import type { StandardSchemaV1 } from "@standard-schema/spec";
import { actionCallReadOnly, type ActionCallClassification } from "./action-call-classification.js";
import { ACTION_EXECUTION_KEY, type ActionExecutionRun } from "./action-frame.js";
import { type ActionMcpOutputContract } from "./action-output-contract.js";
import { type ActionChatUIConfig } from "./action-ui.js";
import type { ActionTool, AgentChatAttachment, AgentChatEvent } from "./agent/types.js";
import type { ActionAuditConfig } from "./audit/types.js";
import { type ActionAccessConfig } from "./authorization/action-access-runtime.js";
import { type JsonValueWriter } from "./json-schema/json-value.js";
export { ACTION_RECEIPT_SCHEMA_VERSION, DOMAIN_EVENT_CONTENT_TYPE, DOMAIN_EVENT_SPEC_VERSION, ActionReceiptValidationError, assertActionDomainEvent, assertActionReceipt, commitAction, createActionDomainEvent, parseActionDomainEvent, parseActionReceipt, serializeActionDomainEvent, serializeActionReceipt, } from "./action-receipt.js";
export type { ActionAtomicAdapter, ActionAtomicContext, ActionAtomicOutcome, ActionDomainEvent, ActionDomainEventDraft, ActionDomainEventReference, ActionJsonPrimitive, ActionJsonValue, ActionReceipt, ActionReceiptProvenance, CommitActionOptions, } from "./action-receipt.js";
export { ACTION_EXECUTION_KEY };
/**
 * Records a call refused before its run, for arguments its caller found
 * invalid, as the action's own validation failure would be recorded: through
 * its tracking and audit, with no path to its handler. Returns false, and
 * logs, when the entry carries no action identity to record it through.
 */
export declare function recordInvalidActionCall(entry: object, args: unknown, ctx: ActionRunContext, error: unknown): Promise<boolean>;
export type ActionCaller = "tool" | "http" | "frontend" | "mcp-widget" | "mcp-widget-write" | "cli" | "mcp" | "webmcp" | "a2a" | "automation";
export interface ActionAutomationContext {
    triggerId: string;
    triggerName: string;
    policyId?: string;
}
export declare const DEFAULT_TOOL_RESULT_CHARS = 50000;
/**
 * The most characters of a pretty-printed result the agent keeps for a call:
 * the action's own limit, else the agent-wide limit, else the default, bounded
 * by any hard limit. The agent loop and actions that fit their own results
 * resolve it here so they cannot disagree.
 */
export declare function resolveToolMaxResultChars(action: {
    maxResultChars?: number;
}, limits?: {
    maxResultChars?: number;
    hardMaxResultChars?: number;
}): number;
export interface ActionRunContext {
    send?: (event: AgentChatEvent) => void;
    /**
     * Result cap the agent loop enforces on this call, from
     * `resolveToolMaxResultChars`. Absent outside the agent loop.
     */
    maxResultChars?: number;
    userEmail?: string;
    /**
     * Request headers for server-only actions that must delegate to an
     * authenticated framework protocol, such as Better Auth password setup.
     * Never expose this context to agent tools or return it from an action.
     */
    requestHeaders?: Headers;
    orgId?: string | null;
    /** Restrict nested action credential reads to the explicit organization. */
    credentialScope?: "org";
    appId?: string;
    appRoles?: string[];
    appPermissions?: string[];
    caller: ActionCaller;
    automation?: ActionAutomationContext;
    networkProtocol?: "a2a" | "mcp" | "provider-api";
    networkId?: string;
    networkPeer?: string;
    delegationDepth?: number;
    visitedApps?: string[];
    /** Remote targets that returned a terminal precondition in this turn. */
    blockedA2ATargets?: Map<string, string>;
    attachments?: AgentChatAttachment[];
    signal?: AbortSignal;
    actionName?: string;
    /** Present only on frontend GETs authorized by a scoped directory-widget read capability. */
    mcpDirectoryWidgetReadOnly?: true;
    /** Present only on frontend calls authorized by a scoped directory-widget capability: the resource IDs it is bound to. */
    mcpDirectoryWidgetResourceIds?: Record<string, string>;
    /** Present only on frontend mutations authorized by a scoped directory-widget write capability. */
    mcpDirectoryWidgetWrite?: {
        appId: string;
        resourceIds: Record<string, string>;
        actionNames: readonly string[];
    };
    threadId?: string;
    runId?: string;
    turnId?: string;
    toolCallId?: string;
    /**
     * The approval the agent loop ran this call under, for approval gates to
     * check. Audit rows read approval from the invocation's execution frame,
     * so a child given this context records none.
     */
    approvedToolCallKey?: string;
    /**
     * The client behind a `caller: "mcp"` call. `name` and `version` are its
     * self-reported `clientInfo`. `oauthClientId` is the OAuth client its
     * credential was issued to.
     */
    mcpClient?: {
        name?: string;
        version?: string;
        oauthClientId?: string;
    };
}
export type ActionAuthorize<TArgs> = (args: TArgs, ctx?: ActionRunContext) => void | boolean | Promise<void | boolean>;
export interface AgentActionStopOptions {
    errorCode?: string;
    details?: Record<string, unknown>;
    toolResult?: string;
}
export interface ActionContractErrorOptions {
    errorCode: string;
    details?: Record<string, unknown>;
    statusCode?: number;
}
export declare class ActionContractError extends Error {
    readonly actionContractError = true;
    readonly errorCode: string;
    readonly details?: Record<string, unknown>;
    readonly statusCode: number;
    constructor(message: string, options: ActionContractErrorOptions);
}
export declare function isActionContractError(error: unknown): error is ActionContractError;
export interface FailOptions {
    errorCode?: string;
    statusCode?: number;
    details?: Record<string, unknown>;
}
export declare function fail(message: string, options?: FailOptions): never;
/**
 * The closed set of `errorCode`s an action fails with. Its `fail` and
 * `noWrite` accept only these codes, so a misspelled code is a compile error
 * and a caller can switch over the action's failures exhaustively. Pass it to
 * `defineAction` as `errors` to publish the codes on the definition.
 */
export interface ActionErrors<TCode extends string> {
    readonly codes: readonly TCode[];
    fail(message: string, errorCode: TCode, options?: Omit<FailOptions, "errorCode">): never;
    noWrite(message: string, errorCode: TCode, options?: Omit<FailOptions, "errorCode">): never;
}
export declare function defineActionErrors<const TCode extends string>(...codes: [TCode, ...TCode[]]): ActionErrors<TCode>;
/**
 * A rejection raised before the action's first write: a missing target, an
 * edit that matches nothing, a patch identical to what is saved. A caller may
 * then retry with corrected arguments instead of treating the call as
 * possibly applied. The framework accepts the claim only for the call that
 * raised it, and only when no write action nested in that call entered its
 * handler; otherwise it reads as any other failure. It cannot see the
 * handler's own database or provider writes, so throw it before the first.
 */
export declare class NoWriteError extends ActionContractError {
    readonly noWrite = true;
    constructor(message: string, options?: FailOptions);
}
export declare function isNoWriteError(error: unknown): error is NoWriteError;
export type { ActionMcpOutputContract } from "./action-output-contract.js";
/** What a call that broke its output contract already did. `run` returned
 *  before the check, so a non-read-only call's changes are applied. */
export type ActionOutputEffect = "none" | "committed";
export interface ActionOutputContractErrorOptions {
    actionName?: string;
    effect: ActionOutputEffect;
    /** `semantic` is the action's `outputSchema`; `mcp` is the MCP response
     *  contract derived from it. */
    contract: "semantic" | "mcp";
    /** Sanitized `path: code` lines; never values from the output. */
    issues: readonly string[];
}
/**
 * A result that broke its declared output contract after `run` returned. It is
 * typed so no caller mistakes it for a failed call: a write reports `committed`
 * and tells the caller not to retry.
 */
export declare class ActionOutputContractError extends ActionContractError {
    readonly outputContractError = true;
    readonly actionName?: string;
    readonly effect: ActionOutputEffect;
    readonly contract: "semantic" | "mcp";
    readonly issues: readonly string[];
    constructor(options: ActionOutputContractErrorOptions);
}
export declare function isActionOutputContractError(error: unknown): error is ActionOutputContractError;
/**
 * What a failed call had already done, when its failure came after `run`
 * returned: an output-contract error, or a stop or connection signal raised
 * while its result was checked; or a verified `NoWriteError`. `undefined`
 * when the failure carries no such evidence, so the caller must not assume
 * the call changed nothing.
 */
export declare function actionFailureEffect(error: unknown): ActionOutputEffect | undefined;
/** What a dispatched call did, and whether other sessions must refresh. */
export interface InvocationEffect {
    /** `unknown`: a write may have run that nothing confirms or rules out. */
    readonly effect: ActionOutputEffect | "unknown";
    /** A write that publishes changes entered its handler, or may have. */
    readonly changed: boolean;
}
/**
 * What a dispatched call did, for every transport, from what ran in it by the
 * time it settled or was abandoned. In order: an action's entry that recorded
 * no call of the action ran something else, so what it did is unknown; a
 * write its own declarations cannot speak for (nested in it, or under an
 * entry that recorded no call) entered its handler, so it may have written;
 * otherwise the call's own write, from its record or, untracked, its
 * declaration, which only then a receipt, `retrySafe` or a typed failure the
 * call raised itself may narrow. A refused call is settled before its error is
 * read.
 */
export declare function invocationEffect(entry: {
    changeEvents?: boolean;
}, outcome: ActionExecutionOutcome, settled: {
    /** The call's classification; `undefined` is a write. */
    readOnly?: boolean;
    retrySafe?: boolean;
    receipt?: {
        changed: boolean;
    };
    /**
     * It failed, with what it threw; `lost` when its result never came;
     * `reported` when it returned an error result instead, such as an MCP
     * tool's `isError`, which says the tool did not do its work.
     */
    failed?: {
        error?: unknown;
        lost?: boolean;
        reported?: boolean;
    };
}): InvocationEffect;
/** Whether a failed call must publish an action change. */
export declare function failedCallEmitsChange(entry: {
    changeEvents?: boolean;
}, error: unknown, outcome: ActionExecutionOutcome): boolean;
/** Whether a call that returned must publish an action change; untracked, by its classification of `args`. */
export declare function ranCallEmitsChange(entry: Parameters<typeof actionCallReadOnly>[0] & {
    changeEvents?: boolean;
}, outcome: ActionExecutionOutcome, args: unknown, fallbackReadOnly: boolean): boolean;
/**
 * What a write action verified about its own effect. An action opts in by
 * returning a plain-object result with a reserved `_receipt: WriteReceipt`.
 * The agent loop reads it before the result is stringified and truncated, so
 * the final answer is reconciled with what the write did instead of with the
 * model's reading of a JSON string.
 *
 * - `changed: false`: nothing was written (a no-op); not a completed side effect.
 * - `verified: true`: the effect was observed. `false`: it was checked and did
 *   not hold. `"unverified"`: it could not be checked.
 * - `subject`: the stable target of the write, such as a dashboard id. Later
 *   receipts from the same action with the same subject that are `changed` and
 *   `verified: true` supersede this one, so a no-op that was then fixed does
 *   not flag the answer. A receipt with failing checks is superseded only when
 *   those later receipts carry an `ok` check with the same `id` for every
 *   check that failed here, because a verified write speaks only for what it
 *   checked. Without a subject a receipt is never superseded.
 * - Bounds, enforced by the loop: summary and subject 200 chars, 8 checks, 5
 *   warnings.
 */
export interface WriteReceipt {
    changed: boolean;
    verified: true | false | "unverified";
    summary: string;
    subject?: string;
    checks?: Array<{
        id: string;
        ok: boolean;
        detail?: string;
    }>;
    warnings?: string[];
}
export declare class AgentActionStopError extends Error {
    readonly agentNativeStop = true;
    readonly errorCode?: string;
    readonly details?: Record<string, unknown>;
    readonly toolResult?: string;
    /** Set by the framework only on a signal raised while the result of a call
     *  that already ran was checked: what that call had done. */
    readonly effect?: ActionOutputEffect;
    constructor(message: string, options?: AgentActionStopOptions);
}
export declare function isAgentActionStopError(err: unknown): err is AgentActionStopError;
export interface AgentConnectionRequiredOptions {
    provider: string;
    reason?: "connect" | "grant" | "reauthorize" | "admin_required";
    appId?: string;
    source?: {
        id: string;
        kind?: string;
        label?: string;
    };
    toolResult?: string;
}
export declare class AgentConnectionRequiredError extends AgentActionStopError {
    readonly agentConnectionRequired = true;
    readonly provider: string;
    readonly reason: NonNullable<AgentConnectionRequiredOptions["reason"]>;
    readonly appId?: string;
    readonly source?: AgentConnectionRequiredOptions["source"];
    constructor(message: string, options: AgentConnectionRequiredOptions);
}
export declare function isAgentConnectionRequiredError(error: unknown): error is AgentConnectionRequiredError;
export interface ActionHttpConfig {
    method?: "GET" | "POST" | "PUT" | "DELETE";
    path?: string;
}
export interface PublicAgentActionConfig {
    expose: boolean;
    readOnly: boolean;
    requiresAuth?: boolean;
    isConsequential?: boolean;
    title?: string;
    description?: string;
    allowRawQueryInput?: boolean;
}
export type ActionPlanModeEffect = "read" | "write" | "unknown";
export interface ActionChangeResource {
    resourceType: string;
    resourceId: string;
}
export interface ActionPlanModeConfig<TInput = unknown> {
    effect: ActionPlanModeEffect | ((args: TInput) => ActionPlanModeEffect);
    allowedValues?: Record<string, readonly string[]>;
    allowedProperties?: readonly string[];
    requiredProperties?: readonly string[];
    omittedProperties?: readonly string[];
    description?: string;
}
export interface ActionDeepLink {
    url: string;
    label: string;
    view?: string;
}
export type ActionLinkBuilder = (ctx: {
    args: Record<string, any>;
    result: any;
}) => ActionDeepLink | null | undefined;
export declare const MCP_APP_EXTENSION_ID: "io.modelcontextprotocol/ui";
export declare const MCP_APP_MIME_TYPE: "text/html;profile=mcp-app";
export declare const MCP_APP_RESOURCE_URI_META_KEY: "ui/resourceUri";
export interface ActionMcpAppCsp {
    connectDomains?: string[];
    resourceDomains?: string[];
    frameDomains?: string[];
    baseUriDomains?: string[];
}
export type ActionMcpAppCspBuilder = (ctx: {
    actionName: string;
    appId?: string;
    requestOrigin?: string;
    catalogMode?: "app" | "directory";
}) => ActionMcpAppCsp | Promise<ActionMcpAppCsp>;
export interface ActionMcpAppPermissions {
    camera?: Record<string, never>;
    microphone?: Record<string, never>;
    geolocation?: Record<string, never>;
    clipboardWrite?: Record<string, never>;
}
export interface ActionMcpAppResourceMeta {
    csp?: ActionMcpAppCsp | ActionMcpAppCspBuilder;
    permissions?: ActionMcpAppPermissions;
    domain?: string;
    prefersBorder?: boolean;
}
export type ActionMcpAppHtmlBuilder = (ctx: {
    actionName: string;
    appId?: string;
    requestOrigin?: string;
    catalogMode?: "app" | "directory";
    startToolName?: string;
}) => string;
export interface ActionMcpAppResourceConfig {
    uri?: string;
    name?: string;
    title?: string;
    description?: string;
    html: string | ActionMcpAppHtmlBuilder;
    requiresEmbedSession?: boolean;
    mimeType?: typeof MCP_APP_MIME_TYPE;
    _meta?: Record<string, unknown>;
    csp?: ActionMcpAppCsp | ActionMcpAppCspBuilder;
    permissions?: ActionMcpAppPermissions;
    domain?: string;
    prefersBorder?: boolean;
}
export interface ActionMcpAppConfig {
    structuredContent?: boolean;
    resource?: ActionMcpAppResourceConfig;
    visibility?: Array<"model" | "app">;
    compactCatalog?: boolean;
}
export interface ParameterSchema {
    type: string;
    description?: string;
    enum?: string[];
}
type InferParams<T extends Record<string, ParameterSchema> | undefined> = T extends Record<string, ParameterSchema> ? {
    [K in keyof T]?: string;
} : Record<string, string>;
/**
 * What a result that does not match `outputSchema` does. Defaults to
 * `"strict"`. `"fallback"` is deprecated: it replaces a broken result with a
 * value callers cannot tell from a real one.
 */
export type ActionOutputErrorStrategy = "strict" | "warn" | "fallback";
/**
 * What an action with `outputSchema` returns under `TStrategy`. `"warn"` can
 * pass `run`'s unvalidated value through; `"fallback"` returns
 * `outputFallback` as given, `undefined` when it is unset.
 */
export type ActionOutputResult<TOutputSchema extends StandardSchemaV1, TStrategy extends ActionOutputErrorStrategy> = TStrategy extends "strict" ? StandardSchemaV1.InferOutput<TOutputSchema> : StandardSchemaV1.InferOutput<TOutputSchema> | StandardSchemaV1.InferInput<TOutputSchema> | (TStrategy extends "fallback" ? undefined : never);
export interface ActionMcpToolAnnotations {
    readOnlyHint: boolean;
    destructiveHint: boolean;
    openWorldHint: boolean;
    idempotentHint?: boolean;
}
interface DefineActionWithSchema<TSchema extends StandardSchemaV1, TReturn = any, TOutputSchema extends StandardSchemaV1 | undefined = undefined, TStrategy extends ActionOutputErrorStrategy = ActionOutputErrorStrategy> {
    title?: string;
    description: string;
    schema: TSchema;
    parameters?: never;
    agentInputSchema?: StandardSchemaV1;
    outputSchema?: TOutputSchema;
    outputErrorStrategy?: TStrategy;
    /** @deprecated `outputErrorStrategy: "fallback"` hides a broken result
     *  behind a plausible one. Fix the result or use `"strict"`. */
    outputFallback?: TReturn;
    /** The action's closed error-code set, from `defineActionErrors`. */
    errors?: ActionErrors<string>;
    /** Advertise `outputSchema` to MCP clients as the tool's `outputSchema`
     *  and validate every `structuredContent` against it. Set it only after
     *  auditing that every value `run` can return meets the schema; it requires
     *  `outputErrorStrategy: "strict"`, because a `"warn"` or `"fallback"`
     *  action would otherwise advertise a contract it does not enforce.
     *  `defineAction` throws when the schema has no Standard JSON Schema output
     *  converter or its root cannot become `structuredContent`. */
    mcpOutputSchema?: boolean;
    run: (args: StandardSchemaV1.InferOutput<TSchema>, ctx?: ActionRunContext) => Promise<TReturn> | TReturn;
    http?: ActionHttpConfig | false;
    requiresAuth?: boolean;
    maxBodyBytes?: number;
    uiOnly?: boolean;
    agentTool?: boolean;
    /** Whether this action is exposed to EXTERNAL agents over MCP (and the direct
     *  A2A action surface, which shares the same policy).
     *
     *  **Defaults to `agentTool`, not to `true`**: an action hidden from the
     *  agent is hidden from outside agents too, so one flag stays one decision.
     *  Declaring `mcpTool` overrides that inheritance in both directions.
     *
     *  - `false` — hard veto. The action is absent from `tools/list` AND from
     *    `tools/call` on every MCP tier, including the rare `--full-catalog`
     *    opt-in, while the in-app agent still calls it normally. Use it for
     *    actions that only make sense with an in-app screen, a live session, or
     *    the framework's own UI on the other end.
     *  - `true` — the action-owned form of `mcp.connectorCatalog` membership:
     *    this action is served on the curated external catalog. Declaring it on
     *    any action activates the connector tier for the app, which is what lets
     *    a template delete its hand-maintained `connectorCatalog` name list.
     *    Paired with `agentTool: false` it makes the action MCP-only — external
     *    agents get it, the app's own agent does not.
     *  - `undefined` (default) — follows `agentTool`; the tier rules then decide
     *    whether it is advertised up front or found through `tool-search`.
     *
     *  Membership is not permission: an external caller still passes the OAuth
     *  scope, `externalAgents` policy, and `publicAgent` checks. Resolved by
     *  `isActionExposedToExternalAgents` below, which every external surface
     *  reads instead of testing these two fields itself — including the rule
     *  that an action ending the in-app agent's turn is in-app only by default,
     *  because the user's answer flows back through the in-app chat that an
     *  external caller is not on. */
    mcpTool?: boolean;
    mcpAnnotations?: ActionMcpToolAnnotations;
    deferLoading?: boolean;
    eagerInputStreaming?: boolean;
    readOnly?: boolean;
    grounding?: boolean;
    allowInPlanMode?: boolean;
    planMode?: ActionPlanModeConfig<StandardSchemaV1.InferInput<TSchema>>;
    /** `false` keeps a mutating action from publishing an `action` change event
     *  (and its sync_events row) after each call. For writes no other session
     *  needs to see, such as telemetry. Defaults to publishing; read-only
     *  actions never publish. */
    changeEvents?: boolean;
    /** `false` keeps this action's query results out of the browser's persisted
     *  query cache, so a read that must not outlive the page (secrets, one-time
     *  codes, private data) is never painted from disk on a revisit. Defaults to
     *  persisting. */
    persistInBrowser?: boolean;
    /** Names the shareable resource a mutating call changes so the `action`
     *  change event also reaches every collaborator who can read it, not only the
     *  actor. Without it other open sessions are never told and show stale data
     *  until they reload. Receives the call's raw input and what the action
     *  returned (for a call keyed by a child id whose resource only the result
     *  names); return `null` when the call touches no resource or changed nothing. */
    changeResource?: (input: StandardSchemaV1.InferInput<TSchema>, result: TReturn) => ActionChangeResource | null | undefined;
    parallelSafe?: boolean;
    /**
     * Re-running this write after an error or a lost result cannot duplicate or
     * corrupt data: it validates before it writes, or it sets an end state
     * (replace-by-id, search-and-replace that fails loudly on a second run). The
     * agent loop then lets the model correct its arguments and retry instead of
     * ending the run as `write_tool_outcome_unknown`. Pass a predicate when only
     * some inputs qualify. Do not set it on an action that appends, sends, or
     * charges, except for inputs carrying an idempotency key the action answers
     * with its first result. It covers this action's own write: once a write
     * nested in it entered its handler, a failure stays an unknown outcome. MCP
     * approval reads it too: a call it covers gets no "already ran" warning.
     */
    retrySafe?: boolean | ((input: StandardSchemaV1.InferInput<TSchema>) => boolean);
    /**
     * How the action reads an ISO date-time argument that names no zone, so an
     * approval summary can say so: `"calendar"` means in the calendar's own
     * time zone. Unset, the summary shows such a time as having no zone given.
     */
    zonelessTimes?: "calendar";
    endsTurn?: boolean;
    dedupe?: boolean;
    toolCallable?: boolean;
    capabilityScopes?: readonly string[];
    publicAgent?: PublicAgentActionConfig;
    link?: ActionLinkBuilder;
    mcpApp?: ActionMcpAppConfig;
    chatUI?: ActionChatUIConfig;
    timeoutMs?: number;
    maxResultChars?: number;
    needsApproval?: boolean | ((args: StandardSchemaV1.InferOutput<TSchema>, ctx?: ActionRunContext) => boolean | Promise<boolean>);
    allowPersistentApproval?: boolean;
    /**
     * Authorization gate that runs before `run()` on **every** caller — agent
     * tool, HTTP, frontend, MCP, A2A, and CLI. It wraps `run` itself rather than
     * hanging off the action entry, because a flag consulted by the dispatcher
     * only guards the dispatchers that remember to consult it.
     *
     * This is *authorization*, not approval: `needsApproval` asks a human to
     * bless one call the caller is already allowed to make, while `authorize`
     * decides whether they are allowed at all. It also does not replace
     * `accessFilter` / `assertAccess` — those scope which rows a permitted caller
     * may see; this decides whether the operation is open to them.
     *
     * ```ts
     * import { coachAccess } from "../lib/access.js";
     *
     * export default defineAction({
     *   description: "Archive a training plan.",
     *   schema,
     *   authorize: coachAccess.requireAny("coach-admin"),
     *   run: async (args) => { ... },
     * });
     * ```
     */
    authorize?: ActionAuthorize<StandardSchemaV1.InferOutput<TSchema>>;
    access?: ActionAccessConfig;
    audit?: ActionAuditConfig;
}
interface DefineActionWithParams<TParams extends Record<string, ParameterSchema> | undefined = Record<string, ParameterSchema> | undefined, TReturn = any, TOutputSchema extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined, TStrategy extends ActionOutputErrorStrategy = ActionOutputErrorStrategy> {
    title?: string;
    description: string;
    parameters?: TParams;
    schema?: never;
    agentInputSchema?: never;
    outputSchema?: TOutputSchema;
    outputErrorStrategy?: TStrategy;
    /** @deprecated See `DefineActionWithSchema.outputFallback`. */
    outputFallback?: TReturn;
    errors?: ActionErrors<string>;
    mcpOutputSchema?: boolean;
    run: (args: InferParams<TParams>, ctx?: ActionRunContext) => Promise<TReturn> | TReturn;
    http?: ActionHttpConfig | false;
    requiresAuth?: boolean;
    maxBodyBytes?: number;
    uiOnly?: boolean;
    agentTool?: boolean;
    mcpTool?: boolean;
    mcpAnnotations?: ActionMcpToolAnnotations;
    deferLoading?: boolean;
    eagerInputStreaming?: boolean;
    readOnly?: boolean;
    grounding?: boolean;
    allowInPlanMode?: boolean;
    planMode?: ActionPlanModeConfig<InferParams<TParams>>;
    changeEvents?: boolean;
    persistInBrowser?: boolean;
    changeResource?: (input: InferParams<TParams>, result: TReturn) => ActionChangeResource | null | undefined;
    parallelSafe?: boolean;
    /** See `ActionDefinition.retrySafe`. */
    retrySafe?: boolean | ((input: InferParams<TParams>) => boolean);
    /** See `ActionDefinition.zonelessTimes`. */
    zonelessTimes?: "calendar";
    endsTurn?: boolean;
    dedupe?: boolean;
    toolCallable?: boolean;
    capabilityScopes?: readonly string[];
    publicAgent?: PublicAgentActionConfig;
    link?: ActionLinkBuilder;
    mcpApp?: ActionMcpAppConfig;
    chatUI?: ActionChatUIConfig;
    timeoutMs?: number;
    maxResultChars?: number;
    needsApproval?: boolean | ((args: InferParams<TParams>, ctx?: ActionRunContext) => boolean | Promise<boolean>);
    allowPersistentApproval?: boolean;
    authorize?: ActionAuthorize<InferParams<TParams>>;
    access?: ActionAccessConfig;
    audit?: ActionAuditConfig;
}
export interface ActionDefinition<TInput, TReturn> {
    readonly run: (args: TInput, ctx?: ActionRunContext) => Promise<TReturn> | TReturn;
    /** @internal Framework use only — do not call directly. */
    readonly tool: import("./agent/types.js").ActionTool;
    readonly http?: ActionHttpConfig | false;
    readonly requiresAuth?: boolean;
    readonly maxBodyBytes?: number;
    readonly uiOnly?: boolean;
    readonly agentTool?: boolean;
    readonly mcpTool?: boolean;
    readonly mcpAnnotations?: ActionMcpToolAnnotations;
    readonly deferLoading?: boolean;
    readonly eagerInputStreaming?: boolean;
    readonly readOnly?: boolean;
    readonly grounding?: boolean;
    readonly allowInPlanMode?: boolean;
    readonly planMode?: ActionPlanModeConfig<TInput>;
    readonly changeEvents?: boolean;
    readonly persistInBrowser?: boolean;
    readonly changeResource?: (input: TInput, result: TReturn) => ActionChangeResource | null | undefined;
    readonly parallelSafe?: boolean;
    readonly retrySafe?: boolean | ((input: TInput) => boolean);
    readonly zonelessTimes?: "calendar";
    readonly endsTurn?: boolean;
    readonly dedupe?: boolean;
    readonly toolCallable?: boolean;
    readonly capabilityScopes?: readonly string[];
    readonly publicAgent?: PublicAgentActionConfig;
    readonly link?: ActionLinkBuilder;
    readonly mcpApp?: ActionMcpAppConfig;
    readonly chatUI?: ActionChatUIConfig;
    readonly timeoutMs?: number;
    readonly maxResultChars?: number;
    readonly outputSchema?: StandardSchemaV1;
    readonly outputErrorStrategy?: ActionOutputErrorStrategy;
    /** @deprecated See `DefineActionWithSchema.outputFallback`. */
    readonly outputFallback?: TReturn;
    /** Present only when the action declared `errors`. */
    readonly errorCodes?: readonly string[];
    /** Present only when the action opted in with `mcpOutputSchema: true`. */
    readonly mcpOutputContract?: ActionMcpOutputContract;
    readonly needsApproval?: boolean | ((args: TInput, ctx?: ActionRunContext) => boolean | Promise<boolean>);
    readonly allowPersistentApproval?: boolean;
    readonly audit?: ActionAuditConfig;
    readonly access?: ActionAccessConfig;
}
export declare function defineAction<TSchema extends StandardSchemaV1, TReturn>(options: DefineActionWithSchema<TSchema, TReturn, undefined>): ActionDefinition<StandardSchemaV1.InferInput<TSchema>, TReturn>;
export declare function defineAction<TParams extends Record<string, ParameterSchema> | undefined, TReturn>(options: DefineActionWithParams<TParams, TReturn, undefined>): ActionDefinition<InferParams<TParams>, TReturn>;
export declare function defineAction<TParams extends Record<string, ParameterSchema> | undefined, TOutputSchema extends StandardSchemaV1, TStrategy extends ActionOutputErrorStrategy = "strict">(options: DefineActionWithParams<TParams, StandardSchemaV1.InferInput<TOutputSchema>, TOutputSchema, TStrategy> & {
    outputSchema: TOutputSchema;
}): ActionDefinition<InferParams<TParams>, ActionOutputResult<TOutputSchema, TStrategy>>;
export declare function defineAction<TSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TStrategy extends ActionOutputErrorStrategy = "strict">(options: DefineActionWithSchema<TSchema, StandardSchemaV1.InferInput<TOutputSchema>, TOutputSchema, TStrategy> & {
    outputSchema: TOutputSchema;
}): ActionDefinition<StandardSchemaV1.InferInput<TSchema>, ActionOutputResult<TOutputSchema, TStrategy>>;
export declare function isActionExposedToExternalAgents(entry: {
    agentTool?: boolean;
    mcpTool?: boolean;
    endsTurn?: boolean;
    uiOnly?: boolean;
}): boolean;
export declare function isActionHiddenFromEveryAgentSurface(entry: {
    agentTool?: boolean;
    mcpTool?: boolean;
    uiOnly?: boolean;
}): boolean;
export declare function stripUnsupportedSchemaKeywords<T>(node: T, writeJsonValue?: JsonValueWriter): T;
export declare function describeToolParameterSignature(parameters: ActionTool["parameters"] | undefined, only?: readonly string[]): string | null;
/** What a call, and every call nested in it, has done so far. */
export interface ActionCallEvidence {
    /** A write entered its handler. */
    readonly writeEntered: boolean;
    /** A write whose action publishes changes entered its handler. */
    readonly changeEntered: boolean;
    /** One of those writes was nested in the call, not the call's own. */
    readonly nestedWriteEntered?: boolean;
    /**
     * The failure this call raised or rebuilt itself; only its typed effect
     * speaks for the call. Its own, so another call throwing it again cannot
     * change it.
     */
    readonly raised?: unknown;
}
/** One `defineAction` call as `run` received it, for the transport that made it. */
export interface ActionCallRecord {
    /**
     * The arguments after input validation applied defaults. For a prepared
     * call, each read is a fresh copy of the arguments it was prepared with.
     */
    readonly args: unknown;
    /** The call's classification, taken before `run`; `undefined` when undeclared. */
    readonly readOnly: boolean | undefined;
    /** Live while the call runs. */
    readonly evidence: ActionCallEvidence;
}
/**
 * What a dispatcher observed of one call, live from before it awaits `run`, so
 * a caller that stops waiting still reads what has run: whether it was
 * refused before any handler, and the record of the `defineAction` call it
 * ran. The record lives on the execution frame, not the context, so a wrapper
 * that rebuilds the context keeps it.
 */
export interface ActionExecutionOutcome {
    refused: boolean;
    record?: ActionCallRecord;
    /** What the call, and every call nested in it, has done; absent untracked. */
    evidence?: ActionCallEvidence;
    /** The entry is a `defineAction` action's, so its run records a call of it. */
    keyed?: boolean;
}
/**
 * Rejected action input; execution phase determines whether effects are possible.
 * `paths` names the failing fields (`tweaks.2.type`) and never carries values:
 * a segment the schema does not declare, such as a record key, is `*`.
 */
export declare class ActionInputValidationError extends Error {
    readonly paths: readonly string[];
    constructor(message: string, paths?: readonly string[]);
}
/** Failing field paths bounded for telemetry; undefined when there are none. */
export declare function telemetryInvalidPaths(paths: readonly string[]): string[] | undefined;
/** @internal Observe one public action invocation without transferring child refusals. */
export declare function runActionWithExecutionOutcome(run: ActionExecutionRun, args: unknown, ctx: ActionRunContext | undefined, outcome: ActionExecutionOutcome, entry?: object): Promise<any>;
export declare function validateActionArgs(schema: StandardSchemaV1, args: unknown, toolParameters?: ActionTool["parameters"], ctx?: object): Promise<any>;
declare const preparedActionCallBrand: unique symbol;
/**
 * One call prepared to run: its arguments as its action will run them, input
 * validation and defaults applied, and the classification of those arguments.
 * Only `actionCallIntent` makes one, and `runPreparedActionCall` executes
 * exactly these arguments with this classification, without parsing or
 * classifying them again. An entry without an input schema runs its arguments
 * as given.
 */
export type PreparedActionCall = {
    readonly valid: true;
    /**
     * Exact identity of the arguments, which approvals, replays and reuse
     * bind. Read the arguments with `preparedCallArguments`.
     */
    readonly argumentsHash: string;
    readonly [preparedActionCallBrand]: true;
} & ActionCallClassification;
/**
 * A call prepared to run, or the error validation refused it with. Gates that
 * decide whether, how, or how often a call may run read this, never the raw
 * arguments, which defaults can turn from a read into a write.
 */
export type ActionCallIntent = PreparedActionCall | {
    readonly valid: false;
    readonly error: unknown;
};
export declare function actionCallIntent(entry: {
    schema?: unknown;
    tool?: {
        parameters?: ActionTool["parameters"];
    };
    readOnly?: boolean;
    planMode?: ActionPlanModeConfig<any>;
}, input: unknown): Promise<ActionCallIntent>;
/**
 * A fresh, mutable copy of the arguments `call` was prepared with, for one
 * consumer: a gate, the handler, or a reader after the run. No two consumers
 * share one, so none can change what another reads.
 */
export declare function preparedCallArguments(call: PreparedActionCall): unknown;
/**
 * Whether `call` needs a person's approval before it runs, by the action's
 * `needsApproval`. Every surface that can run an action decides with this, so
 * a predicate means the same thing to the agent loop, MCP, and HTTP.
 */
export declare function preparedCallNeedsApproval(entry: {
    needsApproval?: boolean | ((args: any, ctx?: ActionRunContext) => boolean | Promise<boolean>);
}, call: PreparedActionCall, ctx: ActionRunContext): Promise<boolean>;
/**
 * @internal Executes a prepared call: `entry.run` receives its own copy of the
 * prepared arguments, which the action's input validation and classification
 * take as prepared instead of repeating. With `outcome`, the run is observed
 * as `runActionWithExecutionOutcome` observes it.
 */
export declare function runPreparedActionCall(entry: {
    run(args: any, ctx?: ActionRunContext): unknown;
}, call: PreparedActionCall, ctx: ActionRunContext, outcome?: ActionExecutionOutcome): Promise<any>;
/** @internal The prepared call a run of these arguments executes, before its action consumes it. */
export declare function boundActionCallIntent(ctx: ActionRunContext | undefined, args: unknown): PreparedActionCall | undefined;