@github/copilot-sdk-darwin-x64 0.0.1 → 1.0.13-preview.6

package/copilot-sdk/factory.d.ts

@@ -0,0 +1,301 @@
+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 { FactoryLimits, 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;
+}
+/**
+ * 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>;
+    /**
+     * 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 or resume 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?: FactoryLimits;
+    /** 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?: FactoryLimits;
+    /** 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`,
+     * and `cancelled` — inspect `status` and read `result` only when the run
+     * completed. 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 a run to settle and resolve with its terminal envelope.
+     *
+     * Resolves as soon as the run reaches `completed`, `error`, `halted`, or
+     * `cancelled`, and resolves immediately when it has already settled. A
+     * terminal envelope is final, so the resolved value never changes
+     * afterwards.
+     *
+     * 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>;
+    /** 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>;

package/copilot-sdk/ffiRuntimeHost.d.ts

@@ -0,0 +1,35 @@
+import { PassThrough, Writable } from "node:stream";
+export declare class FfiRuntimeHost {
+    private readonly libraryPath;
+    private readonly cliEntrypoint;
+    private readonly environment;
+    private readonly args;
+    private readonly lib;
+    private serverId;
+    private connectionId;
+    private disposed;
+    private outboundCallback;
+    private keepAliveTimer;
+    /** The stream JSON-RPC reads server→client frames from. */
+    readonly receiveStream: PassThrough;
+    /** The stream JSON-RPC writes client→server frames to. */
+    readonly sendStream: Writable;
+    private constructor();
+    /**
+     * Loads the runtime cdylib at the given path and prepares the FFI host.
+     */
+    static create(libraryPath: string, cliEntrypoint: string | undefined, environment: Record<string, string | undefined> | undefined, args: readonly string[]): FfiRuntimeHost;
+    /** Starts the in-process Rust runtime and opens the FFI JSON-RPC connection. */
+    start(): Promise<void>;
+    private writeFrame;
+    /**
+     * Native outbound (server→client) callback. koffi delivers it on the JS event loop
+     * via a threadsafe function, so the frame is decoded and written straight to
+     * {@link receiveStream}. The native pointer is only valid for this call, so the
+     * bytes are copied out before returning.
+     */
+    private feedInbound;
+    private unregisterCallback;
+    /** Closes the FFI connection, shuts down the native host, and releases resources. */
+    dispose(): void;
+}