@margay/ccl-core 1.5.0-alpha.0 → 1.5.1-alpha.2

package/dist/sdk/background.d.ts

@@ -0,0 +1,48 @@
+import type { BackgroundRun, BackgroundRunAction, BackgroundRunApproval, BackgroundRunEvents, BackgroundRunLookup, BackgroundRunSelector, BackgroundRunSpec, BackgroundRunSource } from './backgroundRunTypes.js';
+import type { OccurrenceCancelRequest, OccurrenceApprovalRequest, OccurrenceApprovalReceipt, OccurrenceLookup, OccurrenceEvents, ScheduledOccurrence } from './scheduledOccurrenceTypes.js';
+export type BackgroundClientOptions = {
+    cwd: string;
+    cliPath: string;
+    execPath?: string;
+    launch?: {
+        model?: string;
+        settings?: string;
+        extraArgs?: string[];
+    };
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+};
+export declare class BackgroundClientError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Durable runs do not retain JS callbacks or in-process SDK MCP servers. Use
+ * persistent stdio/HTTP tools configured through launch instead. */
+export declare function createBackgroundClient(options: BackgroundClientOptions): {
+    getOccurrence: (request: {
+        occurrenceId: string;
+    }) => Promise<OccurrenceLookup>;
+    listOccurrences: (request?: {
+        taskId?: string;
+        sourceSessionId?: string;
+    }) => Promise<ScheduledOccurrence[]>;
+    readOccurrenceEvents: (request: {
+        occurrenceId: string;
+        afterSequence?: number;
+        limit?: number;
+    }) => Promise<OccurrenceEvents>;
+    cancelOccurrence: (request: OccurrenceCancelRequest) => Promise<ScheduledOccurrence>;
+    approveOccurrence: (request: OccurrenceApprovalRequest) => Promise<OccurrenceApprovalReceipt>;
+    submitRun: (request: {
+        requestKey: string;
+        spec: BackgroundRunSpec;
+        source?: BackgroundRunSource;
+    }) => Promise<BackgroundRun>;
+    getRun: (request: BackgroundRunSelector) => Promise<BackgroundRunLookup>;
+    readRunEvents: (request: BackgroundRunSelector & {
+        cursor?: string;
+        limit?: number;
+    }) => Promise<BackgroundRunEvents>;
+    cancelRun: (request: BackgroundRunAction) => Promise<BackgroundRun>;
+    approveRun: (request: BackgroundRunApproval) => Promise<BackgroundRun>;
+};

package/dist/sdk/background.js

@@ -0,0 +1,87 @@
+import { spawn } from 'node:child_process';
+export class BackgroundClientError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'BackgroundClientError';
+    }
+}
+/** Durable runs do not retain JS callbacks or in-process SDK MCP servers. Use
+ * persistent stdio/HTTP tools configured through launch instead. */
+export function createBackgroundClient(options) {
+    for (const key of Object.keys(options)) {
+        if (!['cwd', 'cliPath', 'execPath', 'launch', 'env', 'timeoutMs'].includes(key))
+            throw new BackgroundClientError('unsupported_option', `Background execution cannot preserve option ${key}; use durable service configuration`);
+    }
+    async function invoke(command, request) {
+        // Serialization can throw (for example for a cyclic input); do it before
+        // allocating a subprocess that would otherwise wait forever for stdin.
+        const input = JSON.stringify(request);
+        const retryAdvice = command.includes('occurrence') ? 'Read the original occurrence and approvalDecisions. Retry approval only with the same actionId and payload.' : 'Query the original requestKey; do not submit a new key.';
+        return new Promise((resolve, reject) => {
+            const child = spawn(options.execPath ?? process.execPath, [options.cliPath, 'daemon', command, '--cwd', options.cwd, '--request-stdin'], {
+                cwd: options.cwd, env: options.env ?? process.env, stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            // A UTF-8 character may straddle pipe chunks. Decode incrementally so
+            // saved event text is not silently replaced with U+FFFD on readback.
+            child.stdout.setEncoding('utf8');
+            child.stderr.setEncoding('utf8');
+            let stdout = '', stderr = '', settled = false;
+            let forceStop;
+            const finish = (error, value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (error && child.exitCode === null && child.signalCode === null) {
+                    child.kill('SIGTERM');
+                    forceStop = setTimeout(() => child.kill('SIGKILL'), 1000);
+                    forceStop.unref();
+                }
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+            };
+            const timer = setTimeout(() => {
+                child.kill('SIGTERM');
+                finish(new BackgroundClientError('ack_unknown', `Background acknowledgement timed out. ${retryAdvice}`));
+            }, options.timeoutMs ?? 45_000);
+            child.on('error', error => finish(error));
+            child.stdin.on('error', error => finish(error));
+            child.stdout.on('data', chunk => { stdout += chunk; if (Buffer.byteLength(stdout) > 32 * 1024 * 1024) {
+                child.kill('SIGTERM');
+                finish(new BackgroundClientError('response_too_large', `Response exceeds 32 MiB. ${command === 'events' ? 'Use limit: 1; if one complete event still exceeds 32 MiB, ' : ''}read the original result using the CLI daemon ${command === 'events' ? 'events' : 'get'} command redirected to a task-owned file. Do not resubmit with a new key.`));
+            } });
+            child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-4096); });
+            child.on('close', () => {
+                if (forceStop)
+                    clearTimeout(forceStop);
+                try {
+                    const reply = JSON.parse(stdout);
+                    if (reply.ok !== true)
+                        finish(new BackgroundClientError(reply.code ?? 'request_failed', reply.error ?? 'Background request failed'));
+                    else
+                        finish(undefined, reply.result);
+                }
+                catch {
+                    finish(new BackgroundClientError('invalid_response', `No complete background response. ${retryAdvice} ${stderr}`));
+                }
+            });
+            child.stdin.end(input);
+        });
+    }
+    return {
+        getOccurrence: (request) => invoke('get-occurrence', request),
+        listOccurrences: (request = {}) => invoke('list-occurrences', request),
+        readOccurrenceEvents: (request) => invoke('occurrence-events', request),
+        cancelOccurrence: (request) => invoke('cancel-occurrence', request),
+        approveOccurrence: (request) => invoke('approve-occurrence', request),
+        submitRun: (request) => invoke('submit', { ...request, launch: options.launch }),
+        getRun: (request) => invoke('get', request),
+        readRunEvents: (request) => invoke('events', request),
+        cancelRun: (request) => invoke('cancel-run', request),
+        approveRun: (request) => invoke('approve-run', request),
+    };
+}

package/dist/sdk/backgroundRunTypes.d.ts

@@ -0,0 +1,101 @@
+/** Local daemon submissions. These records describe execution, not business acceptance. */
+export type BackgroundRunSpec = {
+    prompt: string;
+    systemPrompt?: string;
+    model?: string;
+    maxTurns?: number;
+    agent?: string;
+    /** Optional restriction; omission preserves the existing default permission mode. */
+    permissionMode?: 'plan';
+};
+export type BackgroundRun = {
+    runId: string;
+    requestKey: string;
+    scope: string;
+    spec: BackgroundRunSpec;
+    specHash: string;
+    configId: string;
+    source?: BackgroundRunSource;
+    launchRecovery?: BackgroundLaunchRecovery;
+    dispatchBlockedReason?: 'context_unavailable';
+    acceptedAt: number;
+    updatedAt: number;
+    state: 'queued' | 'starting' | 'running' | 'waiting_permission' | 'succeeded' | 'completed_with_issues' | 'failed' | 'interrupted' | 'cancelled';
+    sessionId: string;
+    generation: string;
+    revision: number;
+    cancellation: 'none' | 'requested';
+    permissions: BackgroundPermission[];
+    operationReferences: import('./operations/reference.js').OperationReference[];
+    result?: string;
+    error?: string;
+    toolErrors: unknown[];
+    deniedToolUseIds: string[];
+    /** Latest captured request diagnostic, not the current run state or proof that
+     * earlier tools did not execute. Inspect state/events/operationReferences too. */
+    latestDiagnostic?: import('./errorDiagnostics.js').RecoveryDiagnostic;
+};
+/** Source descriptors only. Credential values never belong in durable facts. */
+export type BackgroundLaunchRecovery = {
+    version: 1;
+    launchDigest: string;
+    configurationFiles: string[];
+    credentialEnvKeys: string[];
+    inlineCredentialPaths: string[];
+};
+export type BackgroundRunSource = {
+    sessionId: string;
+    assistantId?: string;
+    toolUseId?: string;
+    parentRunId?: string;
+};
+export type BackgroundPermission = {
+    toolUseId: string;
+    toolName: string;
+    input: unknown;
+    assistantId: string;
+    decision?: 'allow' | 'deny';
+};
+export type BackgroundRunEvent = {
+    runId: string;
+    generation: string;
+    sequence: number;
+    at: number;
+    kind: string;
+    snapshot: BackgroundRun;
+    data?: unknown;
+};
+export type BackgroundRunEvents = {
+    events: BackgroundRunEvent[];
+    nextCursor: string;
+    hasMore: boolean;
+};
+export type BackgroundRunAction = {
+    runId: string;
+    expectedRevision: number;
+    actionId: string;
+};
+export type BackgroundRunApproval = BackgroundRunAction & {
+    toolUseId: string;
+    decision: 'allow' | 'deny';
+};
+export type BackgroundRunLookup = {
+    status: 'not_found';
+    ownerAvailable: boolean;
+} | {
+    status: 'found';
+    snapshot: BackgroundRun;
+    observation: {
+        checkedAt: number;
+        ownerAvailable: boolean;
+        executorLock: 'held' | 'free' | 'unknown';
+        externalLiveness: 'unknown';
+    };
+    allowedActions: Array<'get' | 'events' | 'cancel' | 'approve'>;
+    dispatchBlockedReason?: 'configuration_changed' | 'owner_unavailable' | 'context_unavailable';
+};
+export type BackgroundRunSelector = {
+    requestKey: string;
+} | {
+    runId: string;
+};

package/dist/sdk/backgroundRunTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/sdk/commandAdapter.d.ts

@@ -0,0 +1,77 @@
+import { type CommandProcessResult } from './commandProcess.js';
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type CommandOperation = Readonly<{
+    operationId: string;
+    requestKey: string;
+    adapterId: string;
+    adapterVersion: string;
+    targetIdentity: string;
+    bindingDigest: string;
+    inputDigest: string;
+    input: JsonValue;
+    createdAt: number;
+}>;
+export type CommandOutcome = {
+    status: 'applied';
+    receipt: JsonValue;
+    result?: JsonValue;
+} | {
+    status: 'in_progress';
+    handle: string;
+} | {
+    status: 'unknown';
+    reason: string;
+} | {
+    status: 'unsupported';
+    reason: string;
+};
+export type CommandExecution = Readonly<{
+    operation: CommandOperation;
+    attemptId: string;
+    process: CommandProcessResult | null;
+    outcome: CommandOutcome;
+}>;
+export type CommandDefinition = {
+    cmd: string;
+    args?: readonly string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs: number;
+    maxOutputBytes?: number;
+    inheritEnv?: boolean;
+};
+export type CommandAdapterSpec = {
+    adapterId: string;
+    adapterVersion: string;
+    targetIdentity: string;
+    execute: CommandDefinition;
+    query?: CommandDefinition;
+    /** Trusted external service guarantee, never a model-supplied capability. */
+    idempotency?: {
+        scope: string;
+        retentionMs: number;
+    };
+    /** Check the real account/version/target before recovery, not merely config strings. */
+    verifyIdentity?: (operation: CommandOperation) => Promise<boolean>;
+};
+export interface CommandAdapter {
+    prepare(input: JsonValue, options?: {
+        requestKey?: string;
+    }): CommandOperation;
+    execute(operation: CommandOperation, options?: {
+        signal?: AbortSignal;
+    }): Promise<CommandExecution>;
+    queryOutcome(operation: CommandOperation, options?: {
+        signal?: AbortSignal;
+    }): Promise<CommandExecution>;
+    retry(operation: CommandOperation, options: {
+        signal?: AbortSignal;
+        authorize: (operation: CommandOperation) => Promise<boolean>;
+    }): Promise<CommandExecution>;
+}
+/** Internal host bridge. Not exported by sdk/index: only verified durable records may enter. */
+export declare function restoreCommandOperation(adapter: CommandAdapter, operation: CommandOperation, previouslyDispatched: boolean): CommandOperation;
+/** Live command adapter. Durable ownership and rehydration are provided separately by the host. */
+export declare function createCommandAdapter(spec: CommandAdapterSpec): CommandAdapter;

package/dist/sdk/commandAdapter.js

@@ -0,0 +1,180 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { runCommandProcess } from './commandProcess.js';
+function canonical(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'number' && Number.isFinite(value))
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+        return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+    }
+    throw new Error('Expected a finite JSON value');
+}
+function freeze(value) {
+    if (value && typeof value === 'object') {
+        for (const v of Object.values(value))
+            freeze(v);
+        Object.freeze(value);
+    }
+    return value;
+}
+function digest(value) { return createHash('sha256').update(canonical(value)).digest('hex'); }
+const restoreHandlers = new WeakMap();
+/** Internal host bridge. Not exported by sdk/index: only verified durable records may enter. */
+export function restoreCommandOperation(adapter, operation, previouslyDispatched) {
+    const restore = restoreHandlers.get(adapter);
+    if (!restore)
+        throw new Error('Unknown command adapter instance');
+    return restore(operation, previouslyDispatched);
+}
+/** Live command adapter. Durable ownership and rehydration are provided separately by the host. */
+export function createCommandAdapter(spec) {
+    for (const s of [spec.adapterId, spec.adapterVersion, spec.targetIdentity]) {
+        if (!s)
+            throw new Error('Adapter identity must be nonempty');
+    }
+    const verifyIdentity = spec.verifyIdentity;
+    const snapshot = (command) => {
+        if (!command.cmd || !Number.isFinite(command.timeoutMs) || command.timeoutMs <= 0 || command.timeoutMs > 2_147_483_647)
+            throw new Error('Invalid command configuration');
+        if (command.maxOutputBytes !== undefined && (!Number.isSafeInteger(command.maxOutputBytes) || command.maxOutputBytes < 1))
+            throw new Error('Invalid output limit');
+        return freeze({ cmd: command.cmd, args: [...(command.args ?? [])], cwd: command.cwd ?? process.cwd(),
+            env: { ...command.env }, inheritEnv: command.inheritEnv !== false, timeoutMs: command.timeoutMs, maxOutputBytes: command.maxOutputBytes ?? 8 * 1024 * 1024 });
+    };
+    const execute = snapshot(spec.execute), query = spec.query ? snapshot(spec.query) : undefined;
+    const idempotency = spec.idempotency ? freeze({ ...spec.idempotency }) : undefined;
+    if (idempotency && (!idempotency.scope || !Number.isFinite(idempotency.retentionMs) || idempotency.retentionMs <= 0))
+        throw new Error('Invalid idempotency contract');
+    const identity = { adapterId: spec.adapterId, adapterVersion: spec.adapterVersion, targetIdentity: spec.targetIdentity };
+    const binding = () => digest({ ...identity, execute: { ...execute, env: execute.inheritEnv ? { ...process.env, ...execute.env } : execute.env },
+        query: query ? { ...query, env: query.inheritEnv ? { ...process.env, ...query.env } : query.env } : null, idempotency: idempotency ?? null });
+    const bindingDigest = binding();
+    const states = new WeakMap();
+    const keys = new Map();
+    function stateFor(operation) {
+        const state = states.get(operation);
+        if (!state)
+            throw new Error('Operation is not owned by this adapter instance');
+        if (binding() !== state.bindingDigest)
+            throw new Error('Command environment binding changed; verify identity before recovery');
+        return state;
+    }
+    function result(operation, outcome, process = null, attemptId = randomUUID()) {
+        return freeze({ operation, attemptId, process, outcome });
+    }
+    async function run(operation, command, signal) {
+        const state = stateFor(operation);
+        const attemptId = randomUUID();
+        const envelope = { schemaVersion: 1, ...operation, attemptId };
+        const processResult = await runCommandProcess({ ...command, input: JSON.stringify(envelope), signal });
+        let outcome = { status: 'unknown', reason: 'Command did not return a valid bound receipt' };
+        if (processResult.exit_code === 0 && !processResult.error && !processResult.cancelled && !processResult.timed_out) {
+            try {
+                const reply = JSON.parse(processResult.output);
+                const matches = reply.schemaVersion === 1 && ['operationId', 'requestKey', 'adapterId', 'adapterVersion', 'targetIdentity', 'inputDigest', 'bindingDigest'].every(k => reply[k] === envelope[k]);
+                if (matches) {
+                    if (reply.status === 'applied' && reply.receipt !== undefined && reply.receipt !== null) {
+                        canonical(reply.receipt);
+                        if (reply.result !== undefined)
+                            canonical(reply.result);
+                        outcome = { status: 'applied', receipt: reply.receipt, ...(reply.result !== undefined ? { result: reply.result } : {}) };
+                    }
+                    else if (reply.status === 'in_progress' && typeof reply.handle === 'string' && reply.handle)
+                        outcome = { status: 'in_progress', handle: reply.handle };
+                    else if (reply.status === 'unknown' && typeof reply.reason === 'string')
+                        outcome = { status: 'unknown', reason: reply.reason };
+                }
+            }
+            catch { /* Invalid/truncated output never proves an effect. */ }
+        }
+        const execution = result(operation, outcome, processResult, attemptId);
+        if (outcome.status === 'applied')
+            state.accepted ??= execution;
+        return state.accepted ?? execution;
+    }
+    const adapter = {
+        prepare(input, options = {}) {
+            const text = canonical(input), inputDigest = digest(input);
+            const requestKey = options.requestKey ?? randomUUID();
+            if (!requestKey)
+                throw new Error('requestKey must be nonempty');
+            const existing = keys.get(requestKey);
+            if (existing) {
+                if (existing.inputDigest !== inputDigest)
+                    throw new Error('requestKey is already bound to different input');
+                stateFor(existing);
+                return existing;
+            }
+            if (binding() !== bindingDigest)
+                throw new Error('Command environment binding changed');
+            const operation = freeze({ operationId: randomUUID(), requestKey, ...identity, bindingDigest,
+                inputDigest, input: JSON.parse(text), createdAt: Date.now() });
+            states.set(operation, { active: false, bindingDigest });
+            keys.set(requestKey, operation);
+            return operation;
+        },
+        execute(operation, options = {}) {
+            const state = stateFor(operation);
+            if (state.first)
+                return state.first;
+            state.active = true;
+            state.first = run(operation, execute, options.signal).finally(() => { state.active = false; });
+            return state.first;
+        },
+        async queryOutcome(operation, options = {}) {
+            const state = stateFor(operation);
+            if (!state.first)
+                throw new Error('Operation has not been submitted');
+            if (state.accepted)
+                return state.accepted;
+            if (!query)
+                return result(operation, { status: 'unsupported', reason: 'No query command configured' });
+            if (verifyIdentity && !await verifyIdentity(operation))
+                return result(operation, { status: 'unknown', reason: 'External target identity could not be verified' });
+            return run(operation, query, options.signal);
+        },
+        async retry(operation, options) {
+            const state = stateFor(operation);
+            if (!state.first)
+                throw new Error('Use execute for an operation that has not been submitted');
+            if (state.accepted)
+                return state.accepted;
+            if (state.active)
+                throw new Error('Operation execution or recovery is already active');
+            const eligible = () => idempotency && Date.now() - operation.createdAt < idempotency.retentionMs;
+            if (!eligible() || !verifyIdentity)
+                throw new Error('Retry requires valid idempotency and external identity verification');
+            state.active = true;
+            try {
+                if (!await options.authorize(operation))
+                    throw new Error('Retry permission denied');
+                if (!await verifyIdentity(operation))
+                    throw new Error('External target identity changed');
+                stateFor(operation);
+                if (state.accepted)
+                    return state.accepted;
+                if (!eligible())
+                    throw new Error('Idempotency retention expired during authorization');
+                return await run(operation, execute, options.signal);
+            }
+            finally {
+                state.active = false;
+            }
+        },
+    };
+    restoreHandlers.set(adapter, (record, previouslyDispatched) => {
+        if (record.adapterId !== identity.adapterId || record.adapterVersion !== identity.adapterVersion || record.targetIdentity !== identity.targetIdentity || digest(record.input) !== record.inputDigest || !record.operationId || !record.requestKey || !Number.isFinite(record.createdAt))
+            throw new Error('Invalid restored command operation binding');
+        const operation = freeze(JSON.parse(canonical(record)));
+        const state = { active: false, bindingDigest: binding() };
+        if (previouslyDispatched)
+            state.first = Promise.resolve(result(operation, { status: 'unknown', reason: 'Original command was dispatched; recovering its durable history' }));
+        states.set(operation, state);
+        keys.set(operation.requestKey, operation);
+        return operation;
+    });
+    return adapter;
+}

package/dist/sdk/commandProcess.d.ts

@@ -0,0 +1,27 @@
+export type CommandProcessInput = {
+    cmd: string;
+    args: readonly string[];
+    timeoutMs: number;
+    input?: string;
+    env?: NodeJS.ProcessEnv;
+    inheritEnv?: boolean;
+    cwd?: string;
+    signal?: AbortSignal;
+    maxOutputBytes?: number;
+};
+export type CommandProcessResult = {
+    output: string;
+    stderr: string;
+    exit_code: number;
+    duration_ms: number;
+    timed_out: boolean;
+    cancelled: boolean;
+    started: boolean;
+    pid?: number;
+    error?: string;
+    dispatch: 'not_dispatched' | 'dispatched';
+    effect: 'not_dispatched' | 'unknown';
+    cancellation: 'not_requested' | 'requested';
+};
+/** Run exactly once, without a shell. Local termination never proves remote effects stopped. */
+export declare function runCommandProcess(opts: CommandProcessInput): Promise<CommandProcessResult>;

package/dist/sdk/commandProcess.js

@@ -0,0 +1,130 @@
+import { spawn } from 'node:child_process';
+/** Run exactly once, without a shell. Local termination never proves remote effects stopped. */
+export function runCommandProcess(opts) {
+    if (!Number.isFinite(opts.timeoutMs) || opts.timeoutMs <= 0 || opts.timeoutMs > 2_147_483_647) {
+        throw new Error('timeoutMs must be positive and within the timer range');
+    }
+    const limit = opts.maxOutputBytes ?? 8 * 1024 * 1024;
+    if (!Number.isSafeInteger(limit) || limit < 1)
+        throw new Error('maxOutputBytes must be a positive integer');
+    const start = Date.now();
+    return new Promise(resolve => {
+        const stdout = [], stderr = [];
+        let bytes = 0, started = false, settled = false, stopping = false;
+        let timedOut = false, cancelled = false, error;
+        let exitCode = null;
+        let timeout;
+        let escalation;
+        let deadline;
+        let drain;
+        let child;
+        const kill = (signal) => {
+            if (!started || !child?.pid)
+                return;
+            try {
+                // detached gives this invocation its own process group, never the host's group.
+                if (process.platform !== 'win32')
+                    process.kill(-child.pid, signal);
+                else if (signal === 'SIGKILL') {
+                    const killer = spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+                    killer.on('error', () => { try {
+                        child?.kill(signal);
+                    }
+                    catch { } });
+                    killer.unref();
+                }
+                else
+                    child.kill(signal);
+            }
+            catch (e) {
+                if (e.code !== 'ESRCH')
+                    error ??= 'Unable to terminate the owned process group';
+            }
+        };
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            clearTimeout(escalation);
+            clearTimeout(deadline);
+            clearTimeout(drain);
+            opts.signal?.removeEventListener('abort', abort);
+            child?.stdin?.destroy();
+            child?.stdout?.destroy();
+            child?.stderr?.destroy();
+            resolve({
+                output: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8'),
+                exit_code: timedOut ? 124 : cancelled ? 130 : error ? (exitCode || 1) : (exitCode ?? 1),
+                duration_ms: Date.now() - start, timed_out: timedOut, cancelled, started,
+                ...(child?.pid ? { pid: child.pid } : {}), ...(error ? { error } : {}),
+                dispatch: started ? 'dispatched' : 'not_dispatched', effect: started ? 'unknown' : 'not_dispatched',
+                cancellation: timedOut || cancelled || stopping ? 'requested' : 'not_requested',
+            });
+        };
+        const stop = () => {
+            if (stopping || settled)
+                return;
+            stopping = true;
+            clearTimeout(timeout);
+            clearTimeout(drain);
+            kill('SIGTERM');
+            // Keep escalation even if the leader closes first: its descendants may ignore TERM.
+            escalation = setTimeout(() => { kill('SIGKILL'); deadline = setTimeout(finish, 50); }, 250);
+        };
+        const abort = () => { cancelled = true; stop(); };
+        if (opts.signal?.aborted) {
+            cancelled = true;
+            finish();
+            return;
+        }
+        try {
+            child = spawn(opts.cmd, [...opts.args], {
+                cwd: opts.cwd, env: opts.inheritEnv === false ? { ...opts.env } : { ...process.env, ...opts.env },
+                stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32', windowsHide: true,
+            });
+        }
+        catch (e) {
+            error = e.message;
+            finish();
+            return;
+        }
+        child.on('spawn', () => { started = true; if (stopping)
+            kill('SIGTERM'); });
+        child.on('error', e => { error = e.message; if (started)
+            stop();
+        else
+            finish(); });
+        const collect = (target, data) => {
+            const keep = Math.min(data.length, Math.max(0, limit - bytes));
+            if (keep)
+                target.push(data.subarray(0, keep));
+            bytes += data.length;
+            if (bytes > limit) {
+                error ??= 'Command output limit exceeded; output is incomplete';
+                stop();
+            }
+        };
+        child.stdout?.on('data', data => collect(stdout, data));
+        child.stderr?.on('data', data => collect(stderr, data));
+        child.stdin?.on('error', e => { error ??= `Command stdin failed: ${e.message}`; stop(); });
+        child.on('exit', code => {
+            exitCode = code;
+            // A descendant may retain a pipe after the leader exits.
+            drain = setTimeout(() => { error ??= 'Command descendants retained output pipes'; stop(); }, 100);
+        });
+        child.on('close', code => {
+            exitCode = code;
+            if (!stopping) {
+                // A foreground invocation must not leave detached work in its owned group.
+                kill('SIGKILL');
+                finish();
+            }
+        });
+        opts.signal?.addEventListener('abort', abort, { once: true });
+        if (opts.signal?.aborted)
+            abort();
+        timeout = setTimeout(() => { timedOut = true; stop(); }, opts.timeoutMs);
+        child.stdin?.end(opts.input ?? '');
+    });
+}

package/dist/sdk/executionGuidance.d.ts

@@ -0,0 +1,7 @@
+export declare const TOOL_EXECUTION_GUIDANCE = "Start from the requested outcome and the paths, tool descriptions, and usage instructions already supplied. When an available tool or CLI has enough information to perform the requested operation, call it through an authorized tool directly. Using a documented command does not itself require reading its implementation or requesting help first. Consult targeted help or source when required details are missing, an actual result needs diagnosis, or the task asks you to inspect or change the implementation.\n\nYou can request multiple tool calls in a single response. Group necessary calls when their inputs are already known and they have no result dependencies or conflicting side effects. The host determines which calls can execute concurrently. If a call needs an earlier result, or the operations could interfere, wait for the earlier result before requesting the dependent call. After a batch returns, use its results together to determine what remains unresolved. Do not add unnecessary calls just to form a batch, or repeat a completed lookup unless missing information, changed state, or necessary verification warrants it.\n\nFor investigation or design, gather the evidence needed to support the requested conclusions. A successful query may leave relevant documentation or implementation questions unresolved. Distinguish facts established by the evidence, information you have not checked, and absence confirmed within a checked scope. A field missing from a query response does not establish that documentation or another capability does not exist. Report unresolved information as unknown when further investigation is outside the requested scope.\n\nKeep exploration focused on the questions needed for the requested outcome; a lookup or execution task is not automatically a codebase investigation. Once that outcome and its necessary verification are complete, report them without extending the search to unrelated files or capabilities.";
+/**
+ * Shared CLI/SDK execution guidance for the tools exposed by the caller.
+ * Pure text assembly: does not load tools, grant permissions, or alter persona.
+ * Pass canonical tool names from the effective pool, not display aliases.
+ */
+export declare function getExecutionGuidance(toolNames: readonly string[]): string;