@margay/ccl-core 1.5.0-alpha.4 → 1.5.1-alpha.3

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/cancellation.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod/v4';
+/** Control-channel provenance, not the identity or intent of a person. */
+export declare const hostCancellationSchema: z.ZodObject<{
+    origin: z.ZodLiteral<"host">;
+    reason: z.ZodEnum<{
+        cancelled: "cancelled";
+        timeout: "timeout";
+        connection_closed: "connection_closed";
+        callback_error: "callback_error";
+        permission_denied: "permission_denied";
+    }>;
+}, z.core.$strict>;
+export type HostCancellation = z.infer<typeof hostCancellationSchema>;
+export declare function readHostCancellation(value: unknown): HostCancellation | undefined;
+export declare function hostCancellationMessage(cancellation: HostCancellation, execution?: 'not_started' | 'unknown'): string;

package/dist/sdk/cancellation.js

@@ -0,0 +1,18 @@
+import { z } from 'zod/v4';
+/** Control-channel provenance, not the identity or intent of a person. */
+export const hostCancellationSchema = z.object({
+    origin: z.literal('host'),
+    reason: z.enum(['cancelled', 'timeout', 'connection_closed', 'callback_error', 'permission_denied']),
+}).strict();
+export function readHostCancellation(value) {
+    const parsed = hostCancellationSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+export function hostCancellationMessage(cancellation, execution = 'unknown') {
+    return `Host control channel ended this turn (${JSON.stringify(cancellation)}). ` +
+        (cancellation.reason === 'permission_denied'
+            ? 'The host ended the turn after a permission denial; preserve the recorded decision without inferring who made it. '
+            : 'This lifecycle cancellation is not a user permission refusal or a user preference. ') +
+        (execution === 'not_started' ? 'This tool call was not executed. ' : 'A missing result does not establish whether an in-flight operation had effects. ') +
+        'Stop this turn. On a later authorized continuation, retain completed results and check existing execution evidence before repeating side effects. This cancellation grants no permission and does not revoke unrelated existing authorization.';
+}

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>;