@margay/ccl-core 1.3.5-rc.6

package/dist/sdk/queryHandle.d.ts

@@ -0,0 +1,41 @@
+/**
+ * ccl-sdk Query handle (P1 sdk-query-handle).
+ *
+ * Wraps the queryWithTransport event loop in a handle that is both the
+ * AsyncGenerator<SDKEvent> of the query AND the host side of the control
+ * protocol (entrypoints/sdk/controlSchemas.ts):
+ *
+ * - The handle eagerly pumps the underlying event loop, so control methods
+ *   resolve without the host ever iterating events.
+ * - Events are buffered and replayed to the iterator, so the stream a host
+ *   sees is identical to the bare queryWithTransport generator.
+ * - Each control method writes one control_request and resolves with the
+ *   matching control_response payload; error responses reject with the CLI's
+ *   error text; once the query has ended (result delivered, transport closed,
+ *   or subprocess exited) every pending and future call rejects fast — except
+ *   rewindFiles, a post-run operation that stays callable between the result
+ *   and close() (the child is kept alive until close() on normal completion).
+ * - Consumed events are released from the buffer (queue semantics); the
+ *   narrow __diagnostics() port (not on the public Query interface) exposes
+ *   {pendingCount, bufferedEventCount, cursor} for tests/soak drivers.
+ * - The initialize response the event loop already requests is parsed and
+ *   cached; initializationResult()/supportedCommands()/supportedModels()/
+ *   supportedAgents()/accountInfo() serve it, and reinitialize() sends a new
+ *   initialize (fresh request_id) and refreshes the cache.
+ */
+import type { Query, QueryOptions, Transport } from './types.js';
+/**
+ * Test-injection seam for the P1 Query handle, mirroring queryWithTransport.
+ * Production callers use query().
+ */
+export declare function queryHandleWithTransport(prompt: string | null, options: QueryOptions, transport: Transport): Query;
+/** @deprecated Use the object form query({ prompt, options }) instead. */
+export declare function query(prompt: string | AsyncIterable<unknown>, options?: QueryOptions): Query;
+/**
+ * Run one prompt against a CCL agent session and return a Query handle: the
+ * async stream of SDKEvents plus the control methods of the wire protocol.
+ */
+export declare function query(params: {
+    prompt: string;
+    options?: QueryOptions;
+}): Query;

package/dist/sdk/queryHandle.js

@@ -0,0 +1,414 @@
+/**
+ * ccl-sdk Query handle (P1 sdk-query-handle).
+ *
+ * Wraps the queryWithTransport event loop in a handle that is both the
+ * AsyncGenerator<SDKEvent> of the query AND the host side of the control
+ * protocol (entrypoints/sdk/controlSchemas.ts):
+ *
+ * - The handle eagerly pumps the underlying event loop, so control methods
+ *   resolve without the host ever iterating events.
+ * - Events are buffered and replayed to the iterator, so the stream a host
+ *   sees is identical to the bare queryWithTransport generator.
+ * - Each control method writes one control_request and resolves with the
+ *   matching control_response payload; error responses reject with the CLI's
+ *   error text; once the query has ended (result delivered, transport closed,
+ *   or subprocess exited) every pending and future call rejects fast — except
+ *   rewindFiles, a post-run operation that stays callable between the result
+ *   and close() (the child is kept alive until close() on normal completion).
+ * - Consumed events are released from the buffer (queue semantics); the
+ *   narrow __diagnostics() port (not on the public Query interface) exposes
+ *   {pendingCount, bufferedEventCount, cursor} for tests/soak drivers.
+ * - The initialize response the event loop already requests is parsed and
+ *   cached; initializationResult()/supportedCommands()/supportedModels()/
+ *   supportedAgents()/accountInfo() serve it, and reinitialize() sends a new
+ *   initialize (fresh request_id) and refreshes the cache.
+ */
+import { queryWithTransport, spawnForOptions } from './query.js';
+let requestCounter = 0;
+const nextRequestId = () => `ccl-sdk-req-${++requestCounter}-${Math.random().toString(36).slice(2, 10)}`;
+class QueryHandle {
+    transport;
+    options;
+    pending = new Map();
+    /**
+     * UNCONSUMED events only (C3 buffer release): pump pushes, next() shifts.
+     * Events handed to the iterator are dropped immediately, so retained memory
+     * is bounded by the host's consumption lag, not the stream length. FIFO
+     * push/shift keeps the consumed sequence identical to the bare
+     * queryWithTransport generator (parity).
+     */
+    eventQueue = [];
+    /** Cumulative count of events already handed to the iterator. */
+    consumedCount = 0;
+    eventWaiters = [];
+    pumpDone = false;
+    pumpError;
+    ended = false;
+    endReason = 'ccl-sdk: query has ended';
+    /**
+     * Soft end: the result event was delivered. Control methods reject fast
+     * (locked by C3/C1c), but the child is deliberately kept alive until
+     * close() so inherently post-run requests (rewind_files) still round-trip.
+     */
+    resultDelivered = false;
+    /** Hard end: the transport is truly gone — nothing can round-trip. */
+    transportDead = false;
+    residualReaderStarted = false;
+    streamDone = false;
+    /**
+     * Single shared iterator over transport.read(): consumed by tapRead()
+     * during the query and by the residual reader afterwards. Manual next()
+     * calls (never for-await) so abandoning tapRead cannot tear the stream
+     * down via AsyncIterator.return().
+     */
+    innerRead;
+    initResult;
+    initPromise;
+    initResolve;
+    initReject;
+    constructor(prompt, options, transport) {
+        this.transport = transport;
+        this.options = options;
+        this.innerRead = transport.read()[Symbol.asyncIterator]();
+        this.initPromise = new Promise((resolve, reject) => {
+            this.initResolve = resolve;
+            this.initReject = reject;
+        });
+        // The init promise is settled internally; hosts that never ask for the
+        // initialization result must not see an unhandled rejection.
+        this.initPromise.catch(() => { });
+        void this.pump(prompt, options);
+    }
+    // ------------------------------------------------------------- event pump
+    async pump(prompt, options) {
+        try {
+            for await (const event of queryWithTransport(prompt, options, this.tap())) {
+                this.eventQueue.push(event);
+                if (event.type === 'result') {
+                    this.resultDelivered = true;
+                    this.markEnded('ccl-sdk: query has ended (result delivered)');
+                }
+                this.notifyEventWaiters();
+            }
+        }
+        catch (error) {
+            this.pumpError = error;
+        }
+        finally {
+            this.pumpDone = true;
+            // Normal completion (result) is a SOFT end — the child stays alive for
+            // post-run control requests until close(). Every other exit (stream
+            // ended, suspended, error) really closed the transport: hard end.
+            if (!this.resultDelivered) {
+                this.markDead('ccl-sdk: query has ended (transport closed)');
+            }
+            this.notifyEventWaiters();
+        }
+    }
+    /**
+     * Transport seam handed to the inner event loop: writes are sniffed so the
+     * loop's own initialize request feeds the handle's cache (no second
+     * initialize on the wire), reads are observed so control_responses settle
+     * the handle's pending requests before the loop sees them.
+     */
+    tap() {
+        const inner = this.transport;
+        return {
+            read: () => this.tapRead(),
+            write: async (message) => {
+                if (message.type === 'control_request') {
+                    const request = message.request;
+                    if (request?.subtype === 'initialize') {
+                        this.trackInitialize(String(message.request_id ?? ''));
+                    }
+                }
+                await inner.write(message);
+            },
+            close: async () => {
+                // Normal completion (result delivered) DEFERS the real close to
+                // handle.close(): the CLI's stdin message loop keeps serving control
+                // requests after the result, which is what makes the post-run
+                // rewind_files round-trip possible. Abort/error paths (no result)
+                // close for real, exactly as before.
+                if (this.resultDelivered && !this.transportDead)
+                    return;
+                await inner.close();
+            },
+            exited: inner.exited,
+        };
+    }
+    async *tapRead() {
+        try {
+            for (;;) {
+                const next = await this.innerRead.next();
+                if (next.done) {
+                    this.streamDone = true;
+                    return;
+                }
+                this.observe(next.value);
+                yield next.value;
+            }
+        }
+        finally {
+            // The inner event loop stopped consuming (result delivered / early
+            // return). Keep observing control_responses on the SAME iterator so
+            // post-run control requests (rewind_files) still settle.
+            this.startResidualReader();
+        }
+    }
+    /** Post-loop observer: drains the shared read iterator after the inner
+     * event loop has abandoned it, settling pending control requests. */
+    startResidualReader() {
+        if (this.residualReaderStarted || this.streamDone || this.transportDead)
+            return;
+        this.residualReaderStarted = true;
+        void (async () => {
+            try {
+                for (;;) {
+                    const next = await this.innerRead.next();
+                    if (next.done)
+                        break;
+                    this.observe(next.value);
+                }
+            }
+            catch {
+                // stream torn down — hard end below either way
+            }
+            this.streamDone = true;
+            this.markDead('ccl-sdk: query has ended (transport closed)');
+        })();
+    }
+    observe(message) {
+        if (message.type !== 'control_response')
+            return;
+        const response = (message.response ?? {});
+        const requestId = String(response.request_id ?? '');
+        const entry = this.pending.get(requestId);
+        if (!entry)
+            return;
+        this.pending.delete(requestId);
+        if (response.subtype === 'error') {
+            entry.reject(new Error(String(response.error ?? 'control request failed')));
+        }
+        else {
+            entry.resolve(response.response);
+        }
+    }
+    trackInitialize(requestId) {
+        this.pending.set(requestId, {
+            resolve: payload => {
+                const result = (payload ?? {});
+                this.initResult = result;
+                this.initResolve(result);
+            },
+            reject: error => this.initReject(error),
+        });
+    }
+    /**
+     * Soft end (result delivered): blocks NEW control calls (fast-reject in
+     * controlRequest) but deliberately does NOT reject requests already on the
+     * wire — the child keeps serving its stdin loop until close(), and the
+     * residual reader settles their late responses. (Soak C4 %5 rounds: fast
+     * turns delivered the result while requests were in flight; rejecting them
+     * here was a real SDK bug.)
+     */
+    markEnded(reason) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.endReason = reason;
+    }
+    /** Hard end: transport gone/closed — every in-flight request must reject
+     * (nothing can answer it anymore). */
+    markDead(reason) {
+        this.markEnded(reason);
+        if (this.transportDead)
+            return;
+        this.transportDead = true;
+        this.endReason = reason;
+        this.rejectAllPending(new Error(reason));
+    }
+    rejectAllPending(error) {
+        for (const entry of this.pending.values())
+            entry.reject(error);
+        this.pending.clear();
+    }
+    notifyEventWaiters() {
+        const waiters = this.eventWaiters;
+        this.eventWaiters = [];
+        for (const wake of waiters)
+            wake();
+    }
+    // -------------------------------------------------------- control channel
+    controlRequest(request, opts = {}) {
+        // Soft end (result delivered, child still alive) blocks every control
+        // method except explicitly post-run ones; hard end blocks everything.
+        const blocked = this.transportDead || (this.ended && !opts.allowAfterResult);
+        if (blocked)
+            return Promise.reject(new Error(this.endReason));
+        const requestId = nextRequestId();
+        return new Promise((resolve, reject) => {
+            this.pending.set(requestId, { resolve, reject });
+            this.transport
+                .write({ type: 'control_request', request_id: requestId, request })
+                .catch(error => {
+                if (this.pending.delete(requestId)) {
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        });
+    }
+    interrupt() {
+        return this.controlRequest({ subtype: 'interrupt' });
+    }
+    setPermissionMode(mode) {
+        return this.controlRequest({ subtype: 'set_permission_mode', mode });
+    }
+    setModel(model) {
+        return this.controlRequest({
+            subtype: 'set_model',
+            ...(model !== undefined && { model }),
+        });
+    }
+    setMaxThinkingTokens(n) {
+        return this.controlRequest({
+            subtype: 'set_max_thinking_tokens',
+            max_thinking_tokens: n,
+        });
+    }
+    mcpServerStatus() {
+        return this.controlRequest({ subtype: 'mcp_status' });
+    }
+    reconnectMcpServer(name) {
+        return this.controlRequest({ subtype: 'mcp_reconnect', serverName: name });
+    }
+    toggleMcpServer(name, enabled) {
+        return this.controlRequest({ subtype: 'mcp_toggle', serverName: name, enabled });
+    }
+    setMcpServers(servers) {
+        return this.controlRequest({ subtype: 'mcp_set_servers', servers });
+    }
+    stopTask(id) {
+        return this.controlRequest({ subtype: 'stop_task', task_id: id });
+    }
+    applyFlagSettings(settings) {
+        return this.controlRequest({ subtype: 'apply_flag_settings', settings });
+    }
+    /**
+     * Rewind file changes made since a user message. Wire shape follows
+     * SDKControlRewindFilesRequestSchema (entrypoints/sdk/controlSchemas.ts):
+     * subtype "rewind_files", user_message_id, optional dry_run — pass
+     * `{ dry_run: true }` via options. Handler: cli/print.ts (rewind_files).
+     * Rewinding is inherently a post-run operation, so unlike every other
+     * control method it is allowed after the result event (the child is kept
+     * alive until close(); see tap().close).
+     */
+    rewindFiles(userMessageId, options) {
+        return this.controlRequest({ ...options, subtype: 'rewind_files', user_message_id: userMessageId }, { allowAfterResult: true });
+    }
+    // ------------------------------------------------------------- initialize
+    initializationResult() {
+        if (this.initResult)
+            return Promise.resolve(this.initResult);
+        if (this.ended)
+            return Promise.reject(new Error(this.endReason));
+        return this.initPromise;
+    }
+    async reinitialize() {
+        const payload = await this.controlRequest({
+            subtype: 'initialize',
+            ...(this.options.systemPrompt !== undefined && {
+                systemPrompt: this.options.systemPrompt,
+            }),
+            ...(this.options.appendSystemPrompt !== undefined && {
+                appendSystemPrompt: this.options.appendSystemPrompt,
+            }),
+        });
+        const result = (payload ?? {});
+        this.initResult = result;
+        return result;
+    }
+    async supportedCommands() {
+        return (await this.initializationResult()).commands;
+    }
+    async supportedModels() {
+        return (await this.initializationResult()).models;
+    }
+    async supportedAgents() {
+        return (await this.initializationResult()).agents;
+    }
+    async accountInfo() {
+        return (await this.initializationResult()).account;
+    }
+    async close() {
+        this.markDead('ccl-sdk: query closed');
+        await this.transport.close();
+    }
+    // ----------------------------------------------------------- diagnostics
+    /**
+     * Narrow test/ops port (C3, sdk-e2e-endurance) — deliberately NOT part of
+     * the public Query interface in sdk/types.ts. pendingCount = in-flight
+     * control requests; bufferedEventCount = events buffered but not yet
+     * consumed by the iterator; cursor = cumulative consumed events.
+     */
+    __diagnostics() {
+        return {
+            pendingCount: this.pending.size,
+            bufferedEventCount: this.eventQueue.length,
+            cursor: this.consumedCount,
+        };
+    }
+    // ---------------------------------------------------- AsyncGenerator face
+    async next() {
+        for (;;) {
+            // Queue semantics release consumed events immediately (C3 buffer
+            // release); the Query is a single-iterator AsyncGenerator, so FIFO
+            // shift preserves the exact bare-generator sequence (parity).
+            const event = this.eventQueue.shift();
+            if (event !== undefined) {
+                this.consumedCount++;
+                return { value: event, done: false };
+            }
+            if (this.pumpDone) {
+                if (this.pumpError !== undefined) {
+                    const error = this.pumpError;
+                    this.pumpError = undefined;
+                    throw error;
+                }
+                return { value: undefined, done: true };
+            }
+            await new Promise(resolve => this.eventWaiters.push(resolve));
+        }
+    }
+    async return(_value) {
+        await this.close().catch(() => { });
+        return { value: undefined, done: true };
+    }
+    async throw(error) {
+        await this.close().catch(() => { });
+        throw error;
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}
+/**
+ * Test-injection seam for the P1 Query handle, mirroring queryWithTransport.
+ * Production callers use query().
+ */
+export function queryHandleWithTransport(prompt, options, transport) {
+    return new QueryHandle(prompt, options, transport);
+}
+export function query(promptOrParams, positionalOptions) {
+    const positional = typeof promptOrParams === 'string' ||
+        (typeof promptOrParams === 'object' &&
+            promptOrParams !== null &&
+            Symbol.asyncIterator in promptOrParams);
+    const prompt = positional
+        ? promptOrParams
+        : promptOrParams.prompt;
+    const options = (positional
+        ? positionalOptions
+        : promptOrParams.options) ?? {};
+    return queryHandleWithTransport(prompt, options, spawnForOptions(options));
+}

package/dist/sdk/store.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ccl-sdk session store (issue P0-3) — pluggable persistence for SDK-level
+ * session state: pending tool approvals (P0-2 pending) and accumulated usage
+ * (P1-7). The conversation transcript itself stays owned by the CLI's
+ * existing file store (~/.ccl/projects/**), which is what --resume reads;
+ * this store holds the state the CLI cannot know about (a host-side approval
+ * that outlives the process).
+ *
+ * The file implementation is the reference implementation; Redis/DB backends
+ * implement the same SessionStore interface (deliberately small: six async
+ * methods, JSON-serializable records).
+ */
+import type { SessionStore } from './types.js';
+export declare function defaultStoreDir(): string;
+/** Local-file reference implementation of SessionStore. */
+export declare function fileSessionStore(dir?: string): SessionStore;

package/dist/sdk/store.js

@@ -0,0 +1,73 @@
+/**
+ * ccl-sdk session store (issue P0-3) — pluggable persistence for SDK-level
+ * session state: pending tool approvals (P0-2 pending) and accumulated usage
+ * (P1-7). The conversation transcript itself stays owned by the CLI's
+ * existing file store (~/.ccl/projects/**), which is what --resume reads;
+ * this store holds the state the CLI cannot know about (a host-side approval
+ * that outlives the process).
+ *
+ * The file implementation is the reference implementation; Redis/DB backends
+ * implement the same SessionStore interface (deliberately small: six async
+ * methods, JSON-serializable records).
+ */
+import { mkdir, readFile, rename, rm, writeFile } from 'fs/promises';
+import { homedir } from 'os';
+import { join } from 'path';
+const EMPTY_USAGE = {
+    queries: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheCreationInputTokens: 0,
+    cacheReadInputTokens: 0,
+    totalCostUsd: 0,
+};
+function safeSessionId(sessionId) {
+    if (!/^[A-Za-z0-9._-]+$/.test(sessionId)) {
+        throw new Error(`ccl-sdk store: invalid session id '${sessionId}' (path-safe characters only)`);
+    }
+    return sessionId;
+}
+export function defaultStoreDir() {
+    return (process.env.CCL_SDK_STORE_DIR ?? join(homedir(), '.ccl', 'sdk-store'));
+}
+/** Local-file reference implementation of SessionStore. */
+export function fileSessionStore(dir = defaultStoreDir()) {
+    const pendingPath = (sessionId) => join(dir, `${safeSessionId(sessionId)}.pending.json`);
+    const usagePath = (sessionId) => join(dir, `${safeSessionId(sessionId)}.usage.json`);
+    async function writeAtomic(path, data) {
+        await mkdir(dir, { recursive: true });
+        const tmp = `${path}.tmp-${process.pid}`;
+        await writeFile(tmp, JSON.stringify(data, null, 2), 'utf8');
+        await rename(tmp, path);
+    }
+    async function readJson(path) {
+        try {
+            return JSON.parse(await readFile(path, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    return {
+        savePendingApproval: async (record) => writeAtomic(pendingPath(record.sessionId), record),
+        loadPendingApproval: async (sessionId) => readJson(pendingPath(sessionId)),
+        deletePendingApproval: async (sessionId) => {
+            await rm(pendingPath(sessionId), { force: true });
+        },
+        addUsage: async (sessionId, usage, costUsd) => {
+            const current = (await readJson(usagePath(sessionId))) ?? EMPTY_USAGE;
+            const next = {
+                queries: current.queries + 1,
+                inputTokens: current.inputTokens + (usage.input_tokens ?? 0),
+                outputTokens: current.outputTokens + (usage.output_tokens ?? 0),
+                cacheCreationInputTokens: current.cacheCreationInputTokens +
+                    (usage.cache_creation_input_tokens ?? 0),
+                cacheReadInputTokens: current.cacheReadInputTokens + (usage.cache_read_input_tokens ?? 0),
+                totalCostUsd: current.totalCostUsd + (costUsd ?? 0),
+            };
+            await writeAtomic(usagePath(sessionId), next);
+            return next;
+        },
+        getUsage: async (sessionId) => readJson(usagePath(sessionId)),
+    };
+}

package/dist/sdk/transport.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Managed-subprocess transport for ccl-sdk.
+ *
+ * Spawns the CCL CLI in headless stream-json mode and frames NDJSON in both
+ * directions. No TTY is ever allocated (stdio is all pipes), satisfying the
+ * library-form "no stdin/terminal interaction" requirement — the CLI's print
+ * mode already has no interactive code path when --input-format/--output-format
+ * are stream-json.
+ */
+import type { Transport } from './types.js';
+export type SpawnTransportOptions = {
+    execPath: string;
+    cliPath: string;
+    args: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Receives non-JSON stderr/stdout noise for host-side logging. */
+    onDiagnostic?: (line: string) => void;
+};
+export declare function spawnCliTransport(opts: SpawnTransportOptions): Transport;

package/dist/sdk/transport.js

@@ -0,0 +1,100 @@
+/**
+ * Managed-subprocess transport for ccl-sdk.
+ *
+ * Spawns the CCL CLI in headless stream-json mode and frames NDJSON in both
+ * directions. No TTY is ever allocated (stdio is all pipes), satisfying the
+ * library-form "no stdin/terminal interaction" requirement — the CLI's print
+ * mode already has no interactive code path when --input-format/--output-format
+ * are stream-json.
+ */
+import { spawn } from 'child_process';
+const MAX_LINE_BYTES = 10 * 1024 * 1024;
+export function spawnCliTransport(opts) {
+    const child = spawn(opts.execPath, [opts.cliPath, ...opts.args], {
+        cwd: opts.cwd,
+        env: { ...process.env, ...opts.env },
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+        if (opts.onDiagnostic) {
+            for (const line of chunk.split('\n')) {
+                if (line.trim())
+                    opts.onDiagnostic(line);
+            }
+        }
+    });
+    const exited = new Promise(resolve => {
+        child.once('close', code => resolve(code));
+        child.once('error', () => resolve(null));
+    });
+    let closed = false;
+    async function* read() {
+        child.stdout.setEncoding('utf8');
+        let buffer = '';
+        for await (const chunk of child.stdout) {
+            buffer += chunk;
+            if (buffer.length > MAX_LINE_BYTES) {
+                // A single runaway line must not OOM the host (see YW1975/ccl#14 for
+                // why unbounded accumulation is a real failure mode). Drop through
+                // the next newline and surface a diagnostic.
+                const nl = buffer.indexOf('\n');
+                if (nl === -1) {
+                    opts.onDiagnostic?.(`ccl-sdk: dropping oversized output line (> ${MAX_LINE_BYTES} bytes)`);
+                    buffer = '';
+                    continue;
+                }
+            }
+            let newlineIndex = buffer.indexOf('\n');
+            while (newlineIndex !== -1) {
+                const line = buffer.slice(0, newlineIndex).trim();
+                buffer = buffer.slice(newlineIndex + 1);
+                newlineIndex = buffer.indexOf('\n');
+                if (!line)
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    opts.onDiagnostic?.(line);
+                    continue;
+                }
+                if (typeof parsed === 'object' &&
+                    parsed !== null &&
+                    typeof parsed.type === 'string') {
+                    yield parsed;
+                }
+                else {
+                    opts.onDiagnostic?.(line);
+                }
+            }
+        }
+    }
+    return {
+        read,
+        // Child PID for host-side monitoring/cleanup (RSS sampling, leftover
+        // sweeps). process.title rewriting makes pgrep-by-argv unreliable, so
+        // the transport must expose it (sdk-e2e-endurance C4).
+        pid: child.pid,
+        write: (message) => new Promise((resolve, reject) => {
+            if (closed || !child.stdin.writable) {
+                reject(new Error('ccl-sdk transport: stdin is closed'));
+                return;
+            }
+            child.stdin.write(`${JSON.stringify(message)}\n`, err => err ? reject(err) : resolve());
+        }),
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            child.stdin.end();
+            // Give the CLI a moment to flush + exit on its own before killing.
+            const timer = setTimeout(() => child.kill('SIGKILL'), 5000);
+            child.kill('SIGTERM');
+            await exited;
+            clearTimeout(timer);
+        },
+        exited,
+    };
+}