@github/copilot-sdk-win32-x64 1.0.15-preview.3 → 1.0.15-preview.4

package/copilot-sdk/factory.d.ts

@@ -1,327 +0,0 @@
-import type { FactoryGetRunProgressRequest, FactoryListRunsRequest, FactoryListRunsResult, FactoryProgressPage, FactoryRunDetail, FactoryRunResult, FactoryRunStatus, FactoryRunSummary } from "./generated/rpc.js";
-import type { ContextTier } from "./generated/session-events.js";
-import type { CopilotSession } from "./session.js";
-import type { FactoryMeta } from "./types.js";
-export type { FactoryRunResult };
-export type { FactoryAgentSummary, FactoryPhaseStatus, FactoryPhaseObservation, FactoryProgressLine, FactoryProgressPage, FactoryRunDetail, FactoryRunStatus, FactoryRunSummary, } from "./generated/rpc.js";
-/**
- * Options for paging durable factory runs.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export type FactoryListRunsOptions = FactoryListRunsRequest;
-/**
- * A page of durable factory runs and its paging metadata.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export type FactoryRunsPage = FactoryListRunsResult;
-/**
- * Whether a factory run status is terminal.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export declare function isFactoryRunTerminal(status: FactoryRunStatus): boolean;
-declare const factoryHandleBrand: unique symbol;
-/** A value that can be represented losslessly on the SDK JSON wire. */
-export type JsonValue = null | boolean | number | string | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-/**
- * Conservative JSON shape language accepted by the Agent Factories surface, for
- * both structured factory agent output and a factory's declared `argsSchema`.
- *
- * This is a best-effort structural guard — used to decide whether a subagent's
- * structured output should be accepted or retried, and whether a caller's
- * factory `args` match the declared shape — **not** a full JSON Schema
- * validator. Only these keywords are honored: `type`, `required`, `enum`,
- * `const`, recursive `properties`/`items`, and `anyOf`/`oneOf`/`allOf`. A `type`
- * is one of `null`, `boolean`, `integer`, `number`, `string`, `array`, or
- * `object`, or a non-empty array of those (for example `["object", "null"]`).
- *
- * Everything else is **ignored, not enforced**. In particular, string
- * constraints (`pattern`, `minLength`, `maxLength`, `format`), numeric ranges
- * (`minimum`, `maximum`), `additionalProperties`, and boolean (`true`/`false`)
- * schemas do not reject non-conforming output. `oneOf` is treated like `anyOf`
- * (at least one branch must match) rather than strict exactly-one. Author
- * schemas within this subset; do not rely on unsupported constraints for
- * correctness.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export type FactoryJsonSchema = {
-    [key: string]: JsonValue;
-};
-/**
- * Options for one factory-scoped subagent call.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export interface FactoryAgentOptions {
-    label?: string;
-    schema?: FactoryJsonSchema;
-    model?: string;
-    reasoningEffort?: string;
-    contextTier?: ContextTier;
-    agent?: string;
-}
-export declare const FACTORY_AGENT_OPTION_KEYS: readonly ["label", "schema", "model", "reasoningEffort", "contextTier", "agent"];
-/**
- * Options for a durable factory step.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export interface FactoryStepOptions {
-    /** Skip the journal and always invoke the producer. */
-    volatile?: boolean;
-}
-/**
- * Per-invocation factory resource ceiling overrides.
- *
- * An omitted field preserves the existing/default ceiling, a number replaces
- * it, and `null` explicitly makes that dimension unlimited.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export interface FactoryLimitOverrides {
-    maxConcurrentSubagents?: number | null;
-    maxTotalSubagents?: number | null;
-    maxAiCredits?: number | null;
-    timeoutSeconds?: number | null;
-}
-/**
- * One stage in a per-item factory pipeline.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export type FactoryPipelineStage<TInput = unknown, TResult = unknown> = (previous: TInput, item: unknown, index: number) => Promise<TResult> | TResult;
-/**
- * Context passed to an extension-authored factory body.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export interface FactoryContext<TArgs extends JsonValue = JsonValue> {
-    /** Stable identifier for the current factory run. */
-    readonly runId: string;
-    /** Spawn and await one factory-scoped subagent. */
-    agent(prompt: string, options?: FactoryAgentOptions): Promise<unknown>;
-    /** Memoize an arbitrary producer under a stable author-supplied key. */
-    step(key: string, producer: () => Promise<JsonValue> | JsonValue, options?: FactoryStepOptions): Promise<JsonValue>;
-    /**
-     * Pause this run at a durable, one-shot checkpoint.
-     *
-     * The first attempt to reach a key pauses and aborts cooperatively. A
-     * resumed attempt returns from the same key and continues.
-     */
-    pause(key: string): Promise<void>;
-    /**
-     * Run thunks concurrently and await all of them.
-     *
-     * A thunk that throws becomes `null` in the result array, so one failed
-     * item does not lose the rest. Cancellation and hard runtime failures
-     * (`ResponseError`, `ConnectionError`) are the exception: those propagate
-     * and reject the whole call, because they mean the run itself is in
-     * trouble rather than one item having failed.
-     */
-    parallel<TResult>(thunks: Array<() => Promise<TResult> | TResult>): Promise<Array<TResult | null>>;
-    /**
-     * Run each item through every stage without barriers between stages.
-     *
-     * A stage that throws drops that item to `null` and skips its remaining
-     * stages. As with {@link FactoryContext.parallel}, cancellation and hard
-     * runtime failures propagate instead of being recorded per item.
-     */
-    pipeline(items: unknown[], ...stages: FactoryPipelineStage[]): Promise<unknown[]>;
-    /** Start a named factory progress phase. */
-    phase(title: string): void;
-    /** Emit a factory progress line. */
-    log(message: string): void;
-    /** Reject because nested factories are not supported. */
-    factory(name: string, args?: JsonValue): Promise<JsonValue | void>;
-    /** Caller-supplied input, forwarded verbatim. */
-    args: TArgs;
-    /**
-     * The session instance returned by `joinSession`. It refuses calls that
-     * start, resume, or pause a factory run.
-     */
-    session: CopilotSession;
-    /** Cooperative cancellation signal for the current factory run. */
-    signal: AbortSignal;
-}
-/**
- * Definition accepted by {@link defineFactory}.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export interface FactoryDefinition<TArgs extends JsonValue = JsonValue, TResult extends JsonValue | void = JsonValue | void> {
-    meta: FactoryMeta;
-    run(context: FactoryContext<TArgs>): Promise<TResult>;
-}
-/**
- * A deeply immutable view of a value.
- *
- * `defineFactory` deep-freezes the metadata it stores, so the handle's view of
- * it has to be readonly all the way down or `handle.meta.name = "..."` and
- * `handle.meta.phases.push(...)` would compile and then throw at runtime.
- */
-type DeepReadonly<T> = T extends (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? {
-    readonly [K in keyof T]: DeepReadonly<T[K]>;
-} : T;
-/**
- * Opaque reusable reference to a defined factory.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export interface FactoryHandle<TArgs extends JsonValue = JsonValue, TResult extends JsonValue | void = JsonValue | void> {
-    readonly meta: DeepReadonly<FactoryMeta>;
-    readonly [factoryHandleBrand]: {
-        readonly args: TArgs;
-        readonly result: TResult;
-    };
-}
-/**
- * Options for invoking a factory.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export interface RunOptions<TArgs extends JsonValue = JsonValue> {
-    /** Input surfaced as `context.args`. */
-    args?: TArgs;
-    /** Optional per-invocation resource ceiling overrides. */
-    limits?: FactoryLimitOverrides;
-    /** Whether to notify the originating session when the factory completes. */
-    notifyOnComplete?: boolean;
-    /** Whether to emit factory phase names to the session transcript. */
-    logPhaseNames?: boolean;
-    /**
-     * Prior run whose persisted identity, arguments, journal, and accounting should be resumed.
-     *
-     * @deprecated Use {@link SessionFactoryApi.resume} instead.
-     */
-    resumeFromRunId?: string;
-}
-/**
- * Options for resuming a factory run by ID.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export interface ResumeOptions {
-    /** Optional per-invocation resource ceiling overrides. */
-    limits?: FactoryLimitOverrides;
-    /** Whether to notify the originating session when the factory completes. */
-    notifyOnComplete?: boolean;
-    /** Whether to emit factory phase names to the session transcript. */
-    logPhaseNames?: boolean;
-}
-/**
- * Machine-readable pre-execution factory resume failure.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export type FactoryResumeErrorCode = "not_found" | "non_resumable" | "already_active" | "factory_already_running" | "factory_limits_invalid" | "factory_session_disposed" | "factory_storage_unavailable" | "factory_storage_corrupt";
-/**
- * Friendly factory API exposed on a session.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export interface SessionFactoryApi {
-    /**
-     * Run a registered factory and resolve with its run envelope.
-     *
-     * The envelope is returned for every outcome, including `error`, `halted`,
-     * `paused`, and `cancelled` — inspect `status` and read `result` only when
-     * the run completed. `paused` settles the current attempt, but the same
-     * durable run can later resume under its existing run ID. SDK-initiated
-     * runs do not request permission, so they have no declined outcome. The
-     * model's `run_factory` tool requests permission before a durable row
-     * exists; declining it creates no run row. Failures that occur before a run
-     * exists (such as an unknown factory or attempting to start a run while the
-     * session is at its active top-level run limit) still reject.
-     */
-    run(name: string, options?: RunOptions): Promise<FactoryRunResult>;
-    run<TArgs extends JsonValue>(factory: FactoryHandle<TArgs, JsonValue | void>, options?: RunOptions<TArgs>): Promise<FactoryRunResult>;
-    /**
-     * Resume a run from its persisted factory name, arguments, journal, and accounting.
-     *
-     * Resolves with the run envelope like {@link SessionFactoryApi.run}.
-     * SDK-initiated resumes do not request permission. A pre-execution failure
-     * with a documented resume code rejects with {@link FactoryResumeError}.
-     */
-    resume(runId: string, options?: ResumeOptions): Promise<FactoryRunResult>;
-    /** Read the latest durable envelope for a factory run. */
-    getRun(runId: string): Promise<FactoryRunResult>;
-    /**
-     * Wait for the current attempt to settle and resolve with its envelope.
-     *
-     * Resolves as soon as the run reaches `completed`, `error`, `halted`,
-     * `paused`, or `cancelled`, and resolves immediately when the current
-     * attempt has already settled. A `paused` envelope is an attempt-level
-     * snapshot: resuming the same durable run can later change the envelope
-     * returned by {@link SessionFactoryApi.getRun}.
-     *
-     * This watches the run's `factory.run_updated` invalidation events and
-     * periodically re-reads the durable envelope so a missed event cannot
-     * leave the wait hanging. Pass a `signal` to stop waiting; aborting rejects
-     * and has no effect on the run itself, which keeps executing. Use
-     * {@link SessionFactoryApi.cancel} to actually stop it.
-     */
-    waitForRun(runId: string, options?: {
-        signal?: AbortSignal;
-    }): Promise<FactoryRunResult>;
-    /**
-     * List the newest default page of this session's durable factory runs.
-     *
-     * This backwards-compatible overload returns only the runs array. Pass
-     * paging options to receive the full page, including its cursors and
-     * truncation metadata.
-     */
-    listRuns(): Promise<FactoryRunSummary[]>;
-    /**
-     * Page this session's durable factory runs.
-     *
-     * `afterSeq` and `beforeSeq` are exclusive cursors. The result includes
-     * `oldestSeq`, `newestSeq`, `hasMoreNewer`, and `omittedOlder` so callers
-     * can continue paging without using the raw RPC client.
-     */
-    listRuns(options: FactoryListRunsOptions): Promise<FactoryRunsPage>;
-    /** Read durable phases, direct agents, and the latest progress tail for a run. */
-    getRunDetail(runId: string): Promise<FactoryRunDetail>;
-    /** Page durable progress forward, backward, or from the latest tail. */
-    getRunProgress(runId: string, options?: Omit<FactoryGetRunProgressRequest, "runId">): Promise<FactoryProgressPage>;
-    /** Pause a running factory attempt and return its `paused` envelope. */
-    pause(runId: string): Promise<FactoryRunResult>;
-    /** Cancel a factory run and return its terminal envelope. */
-    cancel(runId: string): Promise<FactoryRunResult>;
-}
-/**
- * Error thrown when a factory cannot be resumed before execution begins.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export declare class FactoryResumeError extends Error {
-    readonly code: FactoryResumeErrorCode;
-    constructor(code: FactoryResumeErrorCode, message: string);
-}
-/**
- * Defines an extension-authored factory and returns an opaque registration handle.
- *
- * @experimental Part of the experimental Agent Factories surface and may
- * change or be removed in future SDK or CLI releases.
- */
-export declare function defineFactory<TArgs extends JsonValue = JsonValue, TResult extends JsonValue | void = JsonValue | void>(definition: FactoryDefinition<TArgs, TResult>): FactoryHandle<TArgs, TResult>;