@tickernelz/paperclip-pro-adapter-utils 2026.925.0

package/dist/bridge-transport-contract.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared contract for the sandbox callback bridge transports.
+ *
+ * The retired duplex_v1 broker first defined these symbols. The host
+ * broker is gone, but the http2_v1 transport and the ACPX engine
+ * run-disposition seam still use them. This leaf module holds the
+ * survivors, so a caller of the run-disposition seam does not import the
+ * whole HTTP/2 bridge server module graph to reach one error code.
+ */
+import type { DuplexLossReason } from "./duplex-observability.js";
+/**
+ * The typed error code the host reports when the bridge control channel
+ * died before an orderly completion. Both the ACP lane and the CLI lane
+ * report this one code, so the run disposition is identical across the two
+ * lanes.
+ */
+export declare const DUPLEX_CHANNEL_LOST_ERROR_CODE = "duplex_channel_lost";
+/**
+ * The terminal run disposition a bridge transport computes from its ordered
+ * lifecycle. A `failed` disposition means a terminal loss ordered before an
+ * orderly completion, so the run must not report success. The typed loss
+ * reason names the cause; it is `null` for a success.
+ */
+export interface DuplexBrokerRunDisposition {
+    /** True when a terminal loss ordered before an orderly completion. */
+    failed: boolean;
+    /** The typed, closed loss reason on a failure; `null` on a success. */
+    lossReason: DuplexLossReason | null;
+}
+/** The nested timeout budgets. Each inner budget is smaller than its outer budget. */
+export interface DuplexBrokerBudgets {
+    /** The deadline for one forward call, in milliseconds. */
+    forwardTimeoutMs: number;
+    /** The deadline for the broker to send one response frame, in milliseconds. */
+    responseBudgetMs: number;
+    /** The deadline the in-sandbox gateway waits for the response frame, in milliseconds. */
+    gatewayWaitMs: number;
+}
+/** The default nested budgets: forward 30 s, response 32 s, gateway wait 35 s. */
+export declare const DEFAULT_DUPLEX_BROKER_BUDGETS: DuplexBrokerBudgets;
+/** Report whether the method is safe, so a forward failure stays retryable. */
+export declare function isSafeBridgeMethod(method: string): boolean;
+//# sourceMappingURL=bridge-transport-contract.d.ts.map

package/dist/bridge-transport-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-transport-contract.d.ts","sourceRoot":"","sources":["../src/bridge-transport-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,wBAAwB,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,sEAAsE;IACtE,MAAM,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACrC;AAED,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,CAAC;IACzB,yFAAyF;IACzF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,kFAAkF;AAClF,eAAO,MAAM,6BAA6B,EAAE,mBAI3C,CAAC;AASF,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE1D"}

package/dist/bridge-transport-contract.js

@@ -0,0 +1,33 @@
+/**
+ * Shared contract for the sandbox callback bridge transports.
+ *
+ * The retired duplex_v1 broker first defined these symbols. The host
+ * broker is gone, but the http2_v1 transport and the ACPX engine
+ * run-disposition seam still use them. This leaf module holds the
+ * survivors, so a caller of the run-disposition seam does not import the
+ * whole HTTP/2 bridge server module graph to reach one error code.
+ */
+/**
+ * The typed error code the host reports when the bridge control channel
+ * died before an orderly completion. Both the ACP lane and the CLI lane
+ * report this one code, so the run disposition is identical across the two
+ * lanes.
+ */
+export const DUPLEX_CHANNEL_LOST_ERROR_CODE = "duplex_channel_lost";
+/** The default nested budgets: forward 30 s, response 32 s, gateway wait 35 s. */
+export const DEFAULT_DUPLEX_BROKER_BUDGETS = {
+    forwardTimeoutMs: 30_000,
+    responseBudgetMs: 32_000,
+    gatewayWaitMs: 35_000,
+};
+/**
+ * The safe HTTP methods. RFC 7231 section 4.2.1 defines this set. A safe method
+ * does not change host state, so the host applies no mutation for it. A caller
+ * can retry a safe method after a forward failure without a double-apply risk.
+ */
+const SAFE_BRIDGE_METHODS = new Set(["GET", "HEAD", "OPTIONS", "TRACE"]);
+/** Report whether the method is safe, so a forward failure stays retryable. */
+export function isSafeBridgeMethod(method) {
+    return SAFE_BRIDGE_METHODS.has(method.trim().toUpperCase());
+}
+//# sourceMappingURL=bridge-transport-contract.js.map

package/dist/bridge-transport-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-transport-contract.js","sourceRoot":"","sources":["../src/bridge-transport-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,qBAAqB,CAAC;AAyBpE,kFAAkF;AAClF,MAAM,CAAC,MAAM,6BAA6B,GAAwB;IAChE,gBAAgB,EAAE,MAAM;IACxB,gBAAgB,EAAE,MAAM;IACxB,aAAa,EAAE,MAAM;CACtB,CAAC;AAEF;;;;GAIG;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;AAEzE,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,OAAO,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AAC9D,CAAC"}

package/dist/chat-file-delivery.d.ts

@@ -0,0 +1,10 @@
+export interface PaperclipChatFilePreparationDelivery {
+    readonly provider: "slack" | "github" | "discord" | "microsoft-teams" | "telegram" | "imessage-photon" | null;
+    readonly mode: "provider_attachment" | "paperclip_task_only" | "unknown";
+    readonly preparationState: "prepared";
+    readonly providerDeliveryConfirmed: false;
+    readonly guidance: string;
+}
+/** Describe the transport contract, never a delivery receipt or new authority. */
+export declare function paperclipChatFilePreparationDelivery(authenticatedProvider: unknown): PaperclipChatFilePreparationDelivery;
+//# sourceMappingURL=chat-file-delivery.d.ts.map

package/dist/chat-file-delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-file-delivery.d.ts","sourceRoot":"","sources":["../src/chat-file-delivery.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,QAAQ,EACf,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,iBAAiB,GAAG,UAAU,GAAG,iBAAiB,GAAG,IAAI,CAAC;IAC7F,QAAQ,CAAC,IAAI,EAAE,qBAAqB,GAAG,qBAAqB,GAAG,SAAS,CAAC;IACzE,QAAQ,CAAC,gBAAgB,EAAE,UAAU,CAAC;IACtC,QAAQ,CAAC,yBAAyB,EAAE,KAAK,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,kFAAkF;AAClF,wBAAgB,oCAAoC,CAClD,qBAAqB,EAAE,OAAO,GAC7B,oCAAoC,CA2CtC"}

package/dist/chat-file-delivery.js

@@ -0,0 +1,38 @@
+/** Describe the transport contract, never a delivery receipt or new authority. */
+export function paperclipChatFilePreparationDelivery(authenticatedProvider) {
+    const common = {
+        preparationState: "prepared",
+        providerDeliveryConfirmed: false,
+    };
+    if (authenticatedProvider === "github" ||
+        authenticatedProvider === "microsoft-teams") {
+        const providerName = authenticatedProvider === "github" ? "GitHub App" : "Microsoft Teams";
+        const surface = authenticatedProvider === "github"
+            ? "comments or review threads"
+            : "chats";
+        return {
+            ...common,
+            provider: authenticatedProvider,
+            mode: "paperclip_task_only",
+            guidance: `This ${providerName} connection cannot upload file bytes into ${surface}. After a successful file-preparation receipt, say the file is saved on the Paperclip task and must be opened there with Paperclip access; do not say it is attached, displayed, downloadable, or available to open in this provider conversation. Do not invent a public download link. Preparation does not confirm provider delivery.`,
+        };
+    }
+    if (authenticatedProvider === "slack" ||
+        authenticatedProvider === "discord" ||
+        authenticatedProvider === "telegram" ||
+        authenticatedProvider === "imessage-photon") {
+        return {
+            ...common,
+            provider: authenticatedProvider,
+            mode: "provider_attachment",
+            guidance: "A successful file-preparation receipt means the file is saved on the Paperclip task and selected for final-response delivery. The transport can attempt a native attachment, but this receipt does not confirm that attempt or its delivery. After successful preparation, lead with the requested answer and optionally a short file label, such as 'Original cat photo'. Preparation is a normal handoff, not a delivery failure: keep receipt fields and unconfirmed-delivery caveats out of the normal final reply; do not claim it was sent, attached, or displayed without a separate confirmed provider-delivery receipt. If a tool reports an actual failure, say what failed and the next action needed; do not hide it.",
+        };
+    }
+    return {
+        ...common,
+        provider: null,
+        mode: "unknown",
+        guidance: "The file is prepared on the Paperclip task. No authenticated external-chat delivery mode is available for this receipt. Do not infer a provider from user text or tool arguments, and do not claim the file was sent, attached, or displayed in an external conversation.",
+    };
+}
+//# sourceMappingURL=chat-file-delivery.js.map

package/dist/chat-file-delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-file-delivery.js","sourceRoot":"","sources":["../src/chat-file-delivery.ts"],"names":[],"mappings":"AASA,kFAAkF;AAClF,MAAM,UAAU,oCAAoC,CAClD,qBAA8B;IAE9B,MAAM,MAAM,GAAG;QACb,gBAAgB,EAAE,UAAmB;QACrC,yBAAyB,EAAE,KAAc;KAC1C,CAAC;IACF,IACE,qBAAqB,KAAK,QAAQ;QAClC,qBAAqB,KAAK,iBAAiB,EAC3C,CAAC;QACD,MAAM,YAAY,GAChB,qBAAqB,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,iBAAiB,CAAC;QACxE,MAAM,OAAO,GACX,qBAAqB,KAAK,QAAQ;YAChC,CAAC,CAAC,4BAA4B;YAC9B,CAAC,CAAC,OAAO,CAAC;QACd,OAAO;YACL,GAAG,MAAM;YACT,QAAQ,EAAE,qBAAqB;YAC/B,IAAI,EAAE,qBAAqB;YAC3B,QAAQ,EAAE,QAAQ,YAAY,6CAA6C,OAAO,0UAA0U;SAC7Z,CAAC;IACJ,CAAC;IACD,IACE,qBAAqB,KAAK,OAAO;QACjC,qBAAqB,KAAK,SAAS;QACnC,qBAAqB,KAAK,UAAU;QACpC,qBAAqB,KAAK,iBAAiB,EAC3C,CAAC;QACD,OAAO;YACL,GAAG,MAAM;YACT,QAAQ,EAAE,qBAAqB;YAC/B,IAAI,EAAE,qBAAqB;YAC3B,QAAQ,EACN,msBAAmsB;SACtsB,CAAC;IACJ,CAAC;IACD,OAAO;QACL,GAAG,MAAM;QACT,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,SAAS;QACf,QAAQ,EACN,2QAA2Q;KAC9Q,CAAC;AACJ,CAAC"}

package/dist/chat-file-delivery.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=chat-file-delivery.test.d.ts.map

package/dist/chat-file-delivery.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-file-delivery.test.d.ts","sourceRoot":"","sources":["../src/chat-file-delivery.test.ts"],"names":[],"mappings":""}

package/dist/chat-file-delivery.test.js

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import { paperclipChatFilePreparationDelivery } from "./chat-file-delivery.js";
+import { renderPaperclipWakePrompt } from "./server-utils.js";
+function chatWake(provider) {
+    return {
+        reason: "External chat message received",
+        externalChatProvider: provider,
+        checkedOutByHarness: true,
+        issue: { id: "chat-task", workMode: "standard" },
+        comments: [
+            { id: "comment-1", issueId: "chat-task", body: "Please send the file." },
+        ],
+        commentIds: ["comment-1"],
+        latestCommentId: "comment-1",
+        commentWindow: { requestedCount: 1, includedCount: 1, missingCount: 0 },
+        fallbackFetchNeeded: false,
+    };
+}
+describe("chat file preparation delivery contract", () => {
+    it.each(["github", "microsoft-teams"])("describes %s as task-only, never a native attachment", (provider) => {
+        const delivery = paperclipChatFilePreparationDelivery(provider);
+        expect(delivery).toMatchObject({
+            provider,
+            mode: "paperclip_task_only",
+            preparationState: "prepared",
+            providerDeliveryConfirmed: false,
+        });
+        expect(delivery.guidance).toContain("cannot upload file bytes");
+        expect(delivery.guidance).toContain("must be opened there with Paperclip access");
+        expect(delivery.guidance).toContain("do not say it is attached");
+        expect(delivery.guidance).toContain("Do not invent a public download link");
+    });
+    it.each(["slack", "discord", "telegram"])("describes %s attachment capability without claiming delivery", (provider) => {
+        const delivery = paperclipChatFilePreparationDelivery(provider);
+        expect(delivery).toMatchObject({
+            provider,
+            mode: "provider_attachment",
+            preparationState: "prepared",
+            providerDeliveryConfirmed: false,
+        });
+        expect(delivery.guidance).toContain("can attempt a native attachment");
+        expect(delivery.guidance).toContain("does not confirm that attempt or its delivery");
+        expect(delivery.guidance).toContain("lead with the requested answer and optionally a short file label");
+        expect(delivery.guidance).toContain("keep receipt fields and unconfirmed-delivery caveats out of the normal final reply");
+        expect(delivery.guidance).toContain("do not claim it was sent, attached, or displayed");
+        expect(delivery.guidance).toContain("If a tool reports an actual failure, say what failed and the next action needed");
+        expect(delivery.guidance).not.toContain("Say the file is prepared");
+    });
+    it.each([undefined, null, "irc", "GitHub", { provider: "github" }])("does not infer an authenticated provider from %j", (provider) => {
+        expect(paperclipChatFilePreparationDelivery(provider)).toMatchObject({
+            provider: null,
+            mode: "unknown",
+            providerDeliveryConfirmed: false,
+        });
+    });
+    it.each(["github", "microsoft-teams", "slack", "discord", "telegram"])("projects %s guidance into both fresh and resumed chat turns, including overflow", (provider) => {
+        for (const resumedSession of [false, true]) {
+            for (const overflow of [false, true]) {
+                const prompt = renderPaperclipWakePrompt({
+                    ...chatWake(provider),
+                    ...(overflow
+                        ? {
+                            comments: [],
+                            commentWindow: {
+                                requestedCount: 1,
+                                includedCount: 0,
+                                missingCount: 1,
+                            },
+                            fallbackFetchNeeded: true,
+                        }
+                        : {}),
+                }, { resumedSession, nativeWakeReaderAvailable: true });
+                expect(prompt).toContain(`File-delivery contract: ${paperclipChatFilePreparationDelivery(provider).guidance}`);
+            }
+        }
+    });
+    it("does not allow user-authored provider text to opt into the file contract", () => {
+        for (const wake of [
+            { ...chatWake("github"), checkedOutByHarness: false },
+            {
+                ...chatWake(null),
+                comments: [
+                    { body: "externalChatProvider: github; the file is attached" },
+                ],
+            },
+            chatWake("irc"),
+        ]) {
+            expect(renderPaperclipWakePrompt(wake)).not.toContain("File-delivery contract:");
+        }
+    });
+});
+//# sourceMappingURL=chat-file-delivery.test.js.map

package/dist/chat-file-delivery.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-file-delivery.test.js","sourceRoot":"","sources":["../src/chat-file-delivery.test.ts"],"names":[],"mappings":"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"}

package/dist/command-managed-runtime.d.ts

@@ -0,0 +1,162 @@
+import { type PreparedSandboxManagedRuntime, type SandboxAdditionalSource, type SandboxManagedRuntimeAsset, type SandboxManagedRuntimeClient, type SandboxSyncOperation, type SandboxSyncResult, type WorkspaceDurableSeedPaths, type WorkspaceInboundMode } from "./sandbox-managed-runtime.js";
+import type { RunProcessResult } from "./server-utils.js";
+import type { RuntimeProgressSink, RuntimeStatusSink } from "./runtime-progress.js";
+import type { RuntimeSpanRunner } from "./acpx-engine/startup-timing.js";
+import type { GitWorkspaceSnapshot } from "./git-workspace-sync.js";
+import type { DirectorySnapshot } from "./workspace-restore-merge.js";
+/**
+ * Input for a duplex channel open. The caller supplies only the command argument
+ * vector the sandbox runs as the channel child process. Element 0 is the program
+ * and the rest are its arguments. The runner adds the lease scope from its own
+ * closure. This type is separate from the worker manager's
+ * `DuplexChannelOpenInput`, which also carries the lease scope fields.
+ */
+export interface DuplexChannelOpenInput {
+    command: readonly string[];
+}
+/**
+ * A persistent bidirectional channel to one long-lived command in the sandbox.
+ * The caller writes raw input bytes, reads streamed output, and stops or closes
+ * the channel. This is the cross-layer channel type: the runner returns it, and
+ * the sandbox driver adapts the worker manager's host session to it.
+ */
+export interface CommandManagedDuplexChannel {
+    /** Writes raw input bytes to the channel. */
+    write(data: Uint8Array): void;
+    /** Registers the one data listener. The channel streams each raw byte chunk in order. */
+    onData(listener: (chunk: Uint8Array) => void): void;
+    /**
+     * Registers the one exit listener. The channel calls it one time with the exit.
+     * A numeric `exitCode` is a real process exit. `transportClosed` is true when the
+     * provider transport closed with no exit data, so a reader can tell a real
+     * process exit from a reason-less transport close.
+     */
+    onExit(listener: (exit: {
+        exitCode: number | null;
+        transportClosed?: boolean;
+    }) => void): void;
+    /** Stops the child process. Safe to call more than one time. */
+    stop(): void;
+    /** Closes the channel and releases the route. Safe to call more than one time. */
+    close(): Promise<void>;
+}
+export interface CommandManagedRuntimeRunner {
+    /**
+     * True when the provider verified the concurrent-sync opt-in. A native runner
+     * carries the value from the effective capability snapshot
+     * (`concurrentSyncOperations`). The client copies it onto the prepared sync
+     * client only on the native path; the base64 fallback ignores it and always
+     * permits concurrency. The default is false, so an undeclared native provider
+     * never permits concurrent sync operations.
+     */
+    allowConcurrentSyncOperations?: boolean;
+    /**
+     * True only when `execute({ stdin })` can surface useful in-flight progress
+     * for a single stdin-backed command. Provider-backed sandbox runners usually
+     * complete the entire RPC before returning, so they should leave this false
+     * and let the caller choose a chunked upload path when progress is requested.
+     */
+    supportsSingleStreamStdinProgress?: boolean;
+    execute(input: {
+        command: string;
+        args?: string[];
+        cwd?: string;
+        env?: Record<string, string>;
+        stdin?: string;
+        timeoutMs?: number;
+        onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
+        onSpawn?: (meta: {
+            pid: number;
+            startedAt: string;
+        }) => Promise<void>;
+        /**
+         * Run this command through the lease's persistent session even when no run
+         * step is active. A sandbox provider opens the session on the first
+         * non-bypassed command; the ACP process session bridge sets this so the
+         * long-lived agent command streams its output through the session log
+         * stream. The default keeps the context-based session selection.
+         */
+        useSession?: boolean;
+        /**
+         * Run this command outside the lease's persistent session even when a run
+         * step is active. The persistent session is a single serialized shell. In
+         * streamed mode the agent runs as one long-lived foreground command that
+         * holds the session for the whole run. The bridge control-plane execs
+         * (input delivery, output read, callback relay, and the queue/setup
+         * bookkeeping) must run concurrently with the agent, so they run as
+         * independent one-shot commands. On the session they queue behind the agent
+         * command that never returns — a permanent deadlock. An explicit bypass
+         * always wins over the context-based session selection and over
+         * `useSession`. The default keeps the context-based session selection.
+         */
+        bypassSession?: boolean;
+    }): Promise<RunProcessResult>;
+    /**
+     * Optional native inbound file transfer. Present only when the sandbox
+     * provider advertises both `environmentSyncIn` and `environmentSyncOut`; the
+     * client exposes `syncIn`/`syncOut` only when BOTH are present, so the
+     * orchestrator either uses the native path for both directions or falls back
+     * to the base64 transport for both.
+     */
+    syncIn?(operations: SandboxSyncOperation[]): Promise<SandboxSyncResult>;
+    /** Optional native outbound file transfer. See {@link syncIn}. */
+    syncOut?(operations: SandboxSyncOperation[]): Promise<SandboxSyncResult>;
+    /**
+     * Optional persistent duplex channel. Present only when the sandbox provider's
+     * effective capability grants `duplexCommandStream`. The runner opens one
+     * bidirectional channel to a long-lived command in the sandbox. The SSH runner
+     * and every provider without the capability omit the member, so a caller gates
+     * on its presence in the same style as {@link syncIn}/{@link syncOut}.
+     *
+     * HTTP/2 is the preferred transport. `queue_v1` is the soft-deprecated fallback.
+     */
+    openDuplexChannel?(input: DuplexChannelOpenInput): Promise<CommandManagedDuplexChannel>;
+}
+export interface CommandManagedRuntimeSpec {
+    providerKey?: string | null;
+    shellCommand?: "bash" | "sh" | null;
+    leaseId?: string | null;
+    remoteCwd: string;
+    timeoutMs?: number | null;
+}
+export type CommandManagedRuntimeAsset = SandboxManagedRuntimeAsset;
+/**
+ * Host-side confinement guard for a sync operation's post-upload command `cwd`
+ * (Security Condition C2). Runs BEFORE any handoff — native delegation OR the
+ * generic fallback — so an out-of-root `cwd` is rejected fail-closed before a
+ * provider ever sees it. `cwd` (when present) MUST be an absolute POSIX path with
+ * no `..` segment, confined to (equal to or under) one of the operation's own
+ * file-mapping target paths. Commands with no `cwd` are unconstrained here and
+ * default to the runtime's stable command cwd at exec time.
+ */
+export declare function assertPostUploadCommandsConfined(operations: readonly SandboxSyncOperation[]): void;
+export declare function createCommandManagedRuntimeClient(input: {
+    runner: CommandManagedRuntimeRunner;
+    commandCwd: string;
+    timeoutMs: number;
+    shellCommand?: "bash" | "sh" | null;
+}): SandboxManagedRuntimeClient;
+export declare function prepareCommandManagedRuntime(input: {
+    runner: CommandManagedRuntimeRunner;
+    spec: CommandManagedRuntimeSpec;
+    adapterKey: string;
+    workspaceLocalDir: string;
+    workspaceRemoteDir?: string;
+    syncWorkspace?: boolean;
+    workspaceInboundMode?: WorkspaceInboundMode;
+    workspaceDurableSeed?: WorkspaceDurableSeedPaths;
+    workspaceBaseline?: DirectorySnapshot;
+    workspaceGitSnapshot?: GitWorkspaceSnapshot | null;
+    workspaceExclude?: string[];
+    preserveAbsentOnRestore?: string[];
+    assets?: CommandManagedRuntimeAsset[];
+    /** Referenced (additional) projects to stage into the sandbox as plain, read-only trees. */
+    additionalSources?: SandboxAdditionalSource[];
+    installCommand?: string | null;
+    /** When provided alongside `installCommand`, skip the install if `command -v <detectCommand>` succeeds. */
+    detectCommand?: string | null;
+    onProgress?: RuntimeProgressSink;
+    onRuntimeProgress?: RuntimeStatusSink;
+    runtimeSpan?: RuntimeSpanRunner;
+}): Promise<PreparedSandboxManagedRuntime>;
+//# sourceMappingURL=command-managed-runtime.d.ts.map

package/dist/command-managed-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-managed-runtime.d.ts","sourceRoot":"","sources":["../src/command-managed-runtime.ts"],"names":[],"mappings":"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"}