/**
 * `defineAppCapability` — author-friendly factory for an embedded app's
 * agent-controllable capabilities.
 *
 * It mirrors the runner's `defineCapability` (`@skaile/workspaces/runner`) but
 * is scoped to the app side: the handler always runs *in the app*, so `side` is
 * fixed to `'app'` and the author never passes it. The originating `appId` is
 * known to the SDK, not the individual capability, so `origin` is stamped by
 * {@link createSkaileApp} at registration time — not here.
 *
 * @category App SDK
 * @since 3.4.0
 */
import type { CapabilityAudience, CapabilityOrigin, RenderSpec } from "@skaile/workspaces/types";
import * as z from "zod";
import type { AppLogger } from "./logger.js";
/**
 * Per-invocation context passed to an app capability handler. Analogous to the
 * runner's `HandlerContext`, but carries the `appId` and the SDK's
 * {@link AppLogger} (there is no server-side `capability:<origin>:<name>` log
 * slice inside the app process).
 *
 * @category App SDK
 * @since 3.4.0
 */
export type AppHandlerContext = {
    /** The session this app connection is bound to (from the hello ack). */
    sessionId: string;
    /** The embedded app's id. */
    appId: string;
    /** Logger to emit through; defaults to the SDK's configured logger. */
    log: AppLogger;
};
/**
 * Author-facing arguments to {@link defineAppCapability}. Mirrors the wire
 * {@link import("@skaile/workspaces/types").Capability} fields an app may set,
 * minus `side` / `origin` (fixed / stamped by the SDK) and the runtime-only
 * fields that only make sense platform-side.
 *
 * @category App SDK
 * @since 3.4.0
 */
export type DefineAppCapabilityArgs<T extends z.ZodTypeAny, R extends z.ZodTypeAny | undefined = undefined> = {
    /**
     * Stable, session-unique name. Convention: `app.<sector>.<verb>` — e.g.
     * `app.ui.switch_contract` (UI sector) or `app.backend.insert_contract`
     * (backend sector). v1 distinguishes sectors by this naming convention.
     */
    name: string;
    /** Human-readable label for user-facing surfaces; falls back to `name`. */
    displayName?: string;
    /** Human/LLM-readable summary; shown to the agent at tool registration. */
    description: string;
    /** Zod schema validating the invocation arguments. Converted to JSON Schema. */
    input: T;
    /** Optional Zod schema for the return value. */
    output?: R;
    /** Lifetime: `session` survives the whole session, `turn` is dropped at end-of-turn. */
    scope?: "session" | "turn";
    /**
     * When true, the platform shows a confirm UI and waits for user approval
     * before the invocation is forwarded to the app. Mark every mutation
     * (backend writes, destructive UI actions) with this.
     */
    requiresApproval?: boolean;
    /** Documentation hint: side-effect, render, or pure query. */
    kind?: "effect" | "render" | "query";
    /**
     * Audience scoping. Omit for the default (`['llm','user']`). App capabilities
     * default to LLM-only in the command palette (`isUserInvokable`); set
     * `['llm','user']` on the user-facing actions you want to appear in cmdK.
     */
    audience?: CapabilityAudience[];
    /** Appended to the system prompt's `<CAPABILITIES>` section. */
    promptFragment?: string;
    /** Per-capability override for the platform's result round-trip timeout. */
    callTimeoutMs?: number;
    /** Render contract for capabilities that produce a UI surface. */
    render?: RenderSpec;
    /** The handler — runs in the app. Receives validated input + {@link AppHandlerContext}. */
    handler: (args: z.infer<T>, ctx: AppHandlerContext) => Promise<R extends z.ZodTypeAny ? z.infer<R> : unknown>;
};
/**
 * A defined app capability: the wire-format fields the SDK registers (minus the
 * SDK-stamped `origin`), plus the Zod schemas and type-erased handler used for
 * runtime input validation and inbound dispatch.
 *
 * @category App SDK
 * @since 3.4.0
 */
export type DefinedAppCapability = {
    name: string;
    displayName?: string;
    description: string;
    inputSchema: Record<string, unknown>;
    outputSchema?: Record<string, unknown>;
    /** Always `'app'` — the handler runs in the embedded app. */
    side: "app";
    scope?: "session" | "turn";
    requiresApproval?: boolean;
    kind?: "effect" | "render" | "query";
    audience?: CapabilityAudience[];
    promptFragment?: string;
    callTimeoutMs?: number;
    render?: RenderSpec;
    /** Original Zod schema for runtime input validation. Not serialized to the wire. */
    readonly inputZod: z.ZodTypeAny;
    /** Original Zod schema for the optional output, if declared. Not serialized. */
    readonly outputZod?: z.ZodTypeAny;
    /** Type-erased handler dispatched on an inbound `capability_invoked`. */
    handler: (args: unknown, ctx: AppHandlerContext) => Promise<unknown>;
};
/** Origin kind an app capability always carries once stamped by the SDK. */
export type AppCapabilityOrigin = Extract<CapabilityOrigin, {
    kind: "app";
}>;
/**
 * Build a {@link DefinedAppCapability} from author-friendly Zod-typed args.
 * `side` is fixed to `'app'`; `origin` is added by the SDK at registration
 * time (it needs the SDK's `appId`).
 *
 * @example
 * ```ts
 * const switchContract = defineAppCapability({
 *   name: 'app.ui.switch_contract',
 *   description: 'Switch the visible contract in the app UI.',
 *   input: z.object({ contractId: z.string() }),
 *   handler: async ({ contractId }, ctx) => {
 *     ctx.log.info('switching contract', { contractId });
 *     ui.select(contractId);
 *   },
 * });
 * ```
 *
 * @category App SDK
 * @since 3.4.0
 */
export declare function defineAppCapability<T extends z.ZodTypeAny, R extends z.ZodTypeAny | undefined = undefined>(args: DefineAppCapabilityArgs<T, R>): DefinedAppCapability;
//# sourceMappingURL=define-app-capability.d.ts.map