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

package/dist/sdk/operations/host.js

@@ -0,0 +1,376 @@
+import { randomUUID } from 'node:crypto';
+import { OperationStore } from './store.js';
+import { operationClone, operationDigest, operationFreeze } from './json.js';
+import { OperationError } from './types.js';
+const processStartedAt = Date.now() - Math.round(process.uptime() * 1000);
+function context(state) {
+    const { operationId, requestKey, scope, input, inputDigest, createdAt, binding, capabilities, remoteHandle } = state;
+    return operationFreeze(operationClone({ operationId, requestKey, scope, input, inputDigest, createdAt, binding, capabilities, remoteHandle }));
+}
+function revision(state, expected) {
+    if (!Number.isSafeInteger(expected) || state.revision !== expected)
+        throw new OperationError('conflict', 'Operation revision changed; read the current operation');
+}
+function owns(state, owner) {
+    if (state.owner?.token !== owner.token || state.owner.pid !== owner.pid)
+        throw new OperationError('conflict', 'Operation execution owner changed');
+}
+/** Shared lifecycle core for SDK hosts and CCL's CLI/tool entry points. */
+export function createOperationHost(options) {
+    const store = new OperationStore(options.storeDir, options.scope);
+    const timeoutMs = options.timeoutMs ?? 600_000;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
+        throw new Error('Invalid operation timeout');
+    async function bounded(work, signal) {
+        const controller = new AbortController();
+        let timer;
+        let abort = () => { };
+        const interrupted = new Promise((_, reject) => {
+            abort = () => { controller.abort(); reject(new OperationError('cancelled', 'Operation request cancelled')); };
+            signal?.addEventListener('abort', abort, { once: true });
+            if (signal?.aborted)
+                abort();
+            timer = setTimeout(() => { controller.abort(); reject(new OperationError('authorization_required', 'Operation authorization or identity check did not finish before its deadline')); }, timeoutMs);
+        });
+        try {
+            if (controller.signal.aborted)
+                throw new OperationError('cancelled', 'Operation request cancelled');
+            return await Promise.race([work(controller.signal), interrupted]);
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', abort);
+        }
+    }
+    async function permission(state, action, signal) {
+        const decision = await bounded(s => options.authorize({ operation: context(state), action, signal: s }), signal);
+        if (!decision || !['allow', 'deny', 'ask'].includes(decision.behavior))
+            throw new OperationError('permission_denied', 'Invalid host permission decision');
+        return decision;
+    }
+    async function resolve(state, recovering, signal) {
+        const adapter = await bounded(() => options.resolveAdapter(state.adapterRef), signal);
+        if (!adapter || operationDigest(adapter.binding) !== operationDigest(state.binding) || operationDigest(adapter.capabilities) !== operationDigest(state.capabilities))
+            throw new OperationError('capability_changed', 'Operation adapter, target, version or capabilities changed');
+        if (recovering || adapter.verifyIdentity) {
+            if (!adapter.verifyIdentity)
+                throw new OperationError('capability_changed', 'Recovery requires verification of the current external target identity');
+            const identity = await bounded(s => adapter.verifyIdentity(context(state), s), signal);
+            if (!identity || identity.targetIdentity !== state.binding.targetIdentity || identity.adapterVersion !== state.binding.adapterVersion)
+                throw new OperationError('capability_changed', 'External target identity or adapter version could not be verified');
+        }
+        return adapter;
+    }
+    function eligible(state) {
+        if (state.capabilities.replay === 'read_only')
+            return;
+        const contract = state.capabilities.idempotency;
+        if (state.capabilities.replay !== 'idempotent' || !contract || !contract.scope || !Number.isFinite(contract.retentionMs) || contract.retentionMs <= 0 || Date.now() - state.createdAt >= contract.retentionMs)
+            throw new OperationError('unsupported', 'Unknown operation effects require an unexpired, verified replay contract');
+    }
+    function fingerprint(action) { return operationDigest({ action }); }
+    function duplicate(state, request, action) {
+        if (!request.actionId)
+            throw new OperationError('conflict', 'Recovery actionId must be nonempty');
+        const old = state.actions.find(a => a.actionId === request.actionId);
+        if (!old)
+            return false;
+        if (old.fingerprint !== fingerprint(action))
+            throw new OperationError('conflict', 'actionId is already bound to another recovery action');
+        return old.state !== 'waiting_permission';
+    }
+    function saveAction(state, request, action) {
+        if (!request || state.actions.some(a => a.actionId === request.actionId))
+            return;
+        state.actions.push({ actionId: request.actionId, fingerprint: fingerprint(action), action, state: 'accepted' });
+    }
+    async function dispatch(operationId, expectedRevision, kind, request, signal) {
+        // Taking this OS lock also allows recovery of a journal left by a crashed writer.
+        const release = store.acquire(operationId);
+        let delegatedRelease = false;
+        const owner = { pid: process.pid, processStartedAt, token: randomUUID() };
+        let state;
+        try {
+            state = store.read(operationId);
+            await permissionOrThrowRead(state, signal);
+            if (request && duplicate(state, request, kind === 'query' ? 'reconcile' : 'retry'))
+                return state;
+            if (state.effect === 'confirmed' || (kind !== 'query' && state.execution === 'succeeded' && state.resultRef))
+                return state;
+            revision(state, expectedRevision);
+            if (kind === 'execute' && (state.effect !== 'not_dispatched' || !['accepted', 'waiting_permission', 'failed', 'interrupted'].includes(state.execution)))
+                throw new OperationError('conflict', 'Use recovery for an operation that may already have been dispatched');
+            if (kind === 'retry')
+                eligible(state);
+            const recovering = request !== undefined || kind !== 'execute' || state.attempts.length > 0 || state.owner !== undefined;
+            const decision = await permission(state, kind === 'query' ? 'query' : kind, signal);
+            if (decision.behavior !== 'allow') {
+                return store.update(operationId, 'permission_required', current => {
+                    revision(current, expectedRevision);
+                    if (request)
+                        saveAction(current, request, kind === 'query' ? 'reconcile' : 'retry');
+                    current.execution = 'waiting_permission';
+                    current.reason = decision.reason ?? (decision.behavior === 'deny' ? 'Permission denied' : 'Current permission approval is required');
+                    const action = current.actions.find(a => a.actionId === request?.actionId);
+                    if (action)
+                        action.state = 'waiting_permission';
+                });
+            }
+            if (kind === 'query' && !state.capabilities.query)
+                throw new OperationError('unsupported', 'No trusted query adapter is configured for this operation');
+            let adapter;
+            try {
+                adapter = await resolve(state, recovering, signal);
+            }
+            catch (error) {
+                if (!(error instanceof OperationError) || !['authorization_required', 'permission_denied'].includes(error.code))
+                    throw error;
+                // Current credentials and identity-query permissions are part of the
+                // same recovery request, not a reason to lose its action identity.
+                return store.update(operationId, 'permission_required', current => {
+                    revision(current, expectedRevision);
+                    if (request)
+                        saveAction(current, request, kind === 'query' ? 'reconcile' : 'retry');
+                    current.execution = 'waiting_permission';
+                    current.reason = error.message;
+                    const action = current.actions.find(a => a.actionId === request?.actionId);
+                    if (action)
+                        action.state = 'waiting_permission';
+                });
+            }
+            if (kind === 'query' && (!state.capabilities.query || !adapter.queryOutcome))
+                throw new OperationError('unsupported', 'No trusted query adapter is configured for this operation');
+            if (kind === 'retry')
+                eligible(state);
+            if (signal?.aborted)
+                throw new OperationError('cancelled', 'Operation cancelled before dispatch');
+            const previouslyDispatched = state.effect !== 'not_dispatched';
+            const attemptId = randomUUID();
+            state = store.update(operationId, kind === 'query' ? 'query_dispatching' : 'dispatching', current => {
+                revision(current, expectedRevision);
+                if (current.cancellation !== 'none' && kind !== 'query')
+                    throw new OperationError('cancelled', 'Cancelled operation cannot be dispatched');
+                saveAction(current, request, kind === 'query' ? 'reconcile' : 'retry');
+                // A previous owner is gone (the OS lock was acquired), but its remote work may continue.
+                for (const attempt of current.attempts)
+                    if (attempt.status === 'dispatching') {
+                        attempt.status = 'unknown';
+                        attempt.endedAt = Date.now();
+                    }
+                current.owner = owner;
+                current.attempts.push({ attemptId, kind, startedAt: Date.now(), status: 'dispatching', owner });
+                if (kind !== 'query') {
+                    current.execution = 'dispatching';
+                    current.effect = 'unknown';
+                }
+                else if (current.execution === 'dispatching' || current.execution === 'running')
+                    current.execution = 'interrupted';
+                const action = current.actions.find(a => a.actionId === request?.actionId);
+                if (action)
+                    action.state = 'accepted';
+                delete current.reason;
+            });
+            const controller = new AbortController();
+            let timer, poll;
+            let returnedEarly = false;
+            let stopCaller;
+            let failCaller;
+            const early = new Promise((resolve, reject) => { stopCaller = resolve; failCaller = reject; });
+            const interrupt = (reason, cancellation) => {
+                if (returnedEarly)
+                    return;
+                returnedEarly = true;
+                controller.abort();
+                try {
+                    stopCaller(store.update(operationId, cancellation ? 'cancel_requested' : 'executor_timeout', current => {
+                        owns(current, owner);
+                        if (current.effect === 'confirmed')
+                            return;
+                        if (cancellation)
+                            current.cancellation = 'requested';
+                        if (kind !== 'query')
+                            current.execution = 'interrupted';
+                        current.reason = reason;
+                        const action = current.actions.find(a => a.actionId === request?.actionId);
+                        if (action)
+                            action.state = 'unknown';
+                    }));
+                }
+                catch (error) {
+                    // Do not manufacture a successful cancellation when its journal commit failed.
+                    // The invocation still owns its lock until the actual callback terminates.
+                    failCaller(error);
+                }
+            };
+            const abort = () => interrupt('Caller requested cancellation; remote effects may remain unknown', true);
+            signal?.addEventListener('abort', abort, { once: true });
+            if (signal?.aborted)
+                abort();
+            poll = setInterval(() => {
+                try {
+                    if (store.read(operationId).cancellation === 'requested')
+                        interrupt('Cancellation requested; remote effects may remain unknown', true);
+                }
+                catch {
+                    interrupt('Operation state could not be read; execution cancellation requested', false);
+                }
+            }, 100);
+            timer = setTimeout(() => interrupt('Executor did not return before its deadline; the original execution may still be active', false), timeoutMs);
+            const cleanup = () => { clearTimeout(timer); clearInterval(poll); signal?.removeEventListener('abort', abort); release(); };
+            let invocation;
+            try {
+                invocation = (kind === 'query' ? adapter.queryOutcome : adapter.execute).call(adapter, {
+                    operation: context(state), attemptId, signal: controller.signal, recovering, previouslyDispatched,
+                    recordDispatch: dispatchId => {
+                        if (controller.signal.aborted)
+                            throw new OperationError('cancelled', 'Cancelled before transport dispatch');
+                        store.update(operationId, 'transport_dispatching', current => {
+                            owns(current, owner);
+                            if (current.cancellation !== 'none')
+                                throw new OperationError('cancelled', 'Cancellation requested before transport dispatch');
+                            const attempt = current.attempts.find(a => a.attemptId === attemptId);
+                            const dispatches = attempt.dispatches ??= [];
+                            if (dispatches.some(d => d.dispatchId === dispatchId))
+                                throw new OperationError('conflict', 'Transport dispatch identity already used');
+                            dispatches.push({ dispatchId, at: Date.now() });
+                        });
+                    },
+                });
+            }
+            catch (error) {
+                invocation = Promise.reject(error);
+            }
+            const completion = invocation.then(result => store.update(operationId, 'attempt_returned', (current, put) => {
+                owns(current, owner);
+                const attempt = current.attempts.find(a => a.attemptId === attemptId);
+                attempt.status = 'returned';
+                attempt.endedAt = Date.now();
+                if (current.effect !== 'confirmed') {
+                    if (result.outcome.status === 'in_progress') {
+                        current.remoteHandle = result.outcome.handle;
+                        current.execution = 'running';
+                    }
+                    if (result.outcome.status === 'applied') {
+                        current.effect = 'confirmed';
+                        current.execution = 'succeeded';
+                        current.receiptRef = put(result.outcome.receipt);
+                        current.resultRef = put(result.outcome.result ?? result.result ?? null);
+                    }
+                    else if (kind !== 'query') {
+                        current.resultRef = put(result.result ?? { outcome: result.outcome, process: result.process ?? null });
+                        if (result.dispatch === 'not_dispatched' && !previouslyDispatched)
+                            current.effect = 'not_dispatched';
+                        current.execution = result.execution ?? (current.cancellation === 'requested' ? 'cancelled' : result.outcome.status === 'in_progress' ? 'running' : 'failed');
+                    }
+                    if (result.outcome.status === 'unknown' || result.outcome.status === 'unsupported')
+                        current.reason = result.outcome.reason;
+                    else
+                        delete current.reason;
+                }
+                delete current.owner;
+                const action = current.actions.find(a => a.actionId === request?.actionId);
+                if (action) {
+                    action.state = 'finished';
+                    action.resultRevision = current.revision + 1;
+                }
+            }), error => store.update(operationId, 'attempt_failed', current => {
+                owns(current, owner);
+                const attempt = current.attempts.find(a => a.attemptId === attemptId);
+                attempt.status = 'unknown';
+                attempt.endedAt = Date.now();
+                if (current.effect !== 'confirmed' && kind !== 'query')
+                    current.execution = 'interrupted';
+                current.reason = error instanceof Error ? error.message : 'Adapter invocation failed; effects remain unknown';
+                delete current.owner;
+                const action = current.actions.find(a => a.actionId === request?.actionId);
+                if (action) {
+                    action.state = 'unknown';
+                    action.resultRevision = current.revision + 1;
+                }
+            })).finally(cleanup);
+            // A timed-out adapter can finish late. Do not release its OS lock merely because
+            // the caller's wait ended; completion owns cleanup and records any late receipt.
+            delegatedRelease = true;
+            return await Promise.race([completion, early]);
+        }
+        finally {
+            if (!delegatedRelease)
+                release();
+        }
+    }
+    async function permissionOrThrowRead(state, signal) {
+        const p = await permission(state, 'read', signal);
+        if (p.behavior !== 'allow')
+            throw new OperationError(p.behavior === 'ask' ? 'authorization_required' : 'permission_denied', p.reason ?? 'Current permission is required to access this operation');
+    }
+    return {
+        async submitOperation(input) {
+            const adapter = await bounded(() => options.resolveAdapter(input.adapterRef));
+            if (!adapter)
+                throw new OperationError('unsupported', 'Operation adapter is not registered by the host');
+            const now = Date.now(), value = operationClone(input.input);
+            const initial = { operationId: store.idFor(input.requestKey), requestKey: input.requestKey, scope: options.scope,
+                input: value, inputDigest: operationDigest(value), createdAt: now, binding: operationClone(adapter.binding), capabilities: operationClone(adapter.capabilities),
+                adapterRef: input.adapterRef, execution: 'accepted', effect: 'not_dispatched', cancellation: 'none',
+                links: input.links ?? {}, attempts: [], actions: [], updatedAt: now };
+            await permissionOrThrowRead(initial);
+            return store.create(initial);
+        },
+        executeOperation: input => dispatch(input.operationId, input.expectedRevision, 'execute', undefined, input.signal),
+        async getOperation(input) { const state = store.read(input.operationId); await permissionOrThrowRead(state); return state; },
+        async readOperationEvents(input) { const state = store.read(input.operationId); await permissionOrThrowRead(state); return store.events(input.operationId, input.cursor); },
+        reconcileOperation: input => dispatch(input.operationId, input.expectedRevision, 'query', input, input.signal),
+        async resumeOperation(input) {
+            if (input.action === 'retry') {
+                const release = store.acquire(input.operationId);
+                let state;
+                try {
+                    state = store.read(input.operationId);
+                }
+                finally {
+                    release();
+                }
+                // Accepted work never crossed dispatch; it can continue without inventing an idempotency contract.
+                if (state.effect === 'not_dispatched')
+                    return dispatch(input.operationId, input.expectedRevision, 'execute', input, input.signal);
+                return dispatch(input.operationId, input.expectedRevision, 'retry', input, input.signal);
+            }
+            const release = store.acquire(input.operationId);
+            try {
+                const state = store.read(input.operationId);
+                await permissionOrThrowRead(state, input.signal);
+                if (duplicate(state, input, 'accept_verified_result'))
+                    return state;
+                revision(state, input.expectedRevision);
+                if (state.effect !== 'confirmed' || !state.receiptRef)
+                    throw new OperationError('unsupported', 'No adapter-verified receipt exists for this operation');
+                return store.update(input.operationId, 'verified_result_accepted', current => {
+                    revision(current, input.expectedRevision);
+                    current.actions.push({ actionId: input.actionId, fingerprint: fingerprint('accept_verified_result'), action: 'accept_verified_result', state: 'finished', resultRevision: current.revision + 1 });
+                });
+            }
+            finally {
+                release();
+            }
+        },
+        async cancelOperation(input) {
+            const state = store.read(input.operationId);
+            await permissionOrThrowRead(state, input.signal);
+            if (duplicate(state, input, 'cancel'))
+                return state;
+            revision(state, input.expectedRevision);
+            const p = await permission(state, 'cancel', input.signal);
+            if (p.behavior !== 'allow')
+                throw new OperationError(p.behavior === 'ask' ? 'authorization_required' : 'permission_denied', p.reason ?? 'Current cancellation permission is required');
+            return store.update(input.operationId, 'cancel_requested', current => {
+                revision(current, input.expectedRevision);
+                current.actions.push({ actionId: input.actionId, fingerprint: fingerprint('cancel'), action: 'cancel', state: 'finished', resultRevision: current.revision + 1 });
+                if (current.effect === 'confirmed' || current.execution === 'succeeded')
+                    return;
+                current.cancellation = current.effect === 'not_dispatched' && !current.owner ? 'confirmed' : 'requested';
+                if (current.cancellation === 'confirmed')
+                    current.execution = 'cancelled';
+            });
+        },
+    };
+}

package/dist/sdk/operations/json.d.ts

@@ -0,0 +1,6 @@
+import type { JsonValue } from '../commandAdapter.js';
+export declare function operationJson(value: unknown): string;
+export declare function operationDigest(value: unknown): string;
+export declare function operationClone<T>(value: T): T;
+export declare function operationFreeze<T>(value: T): T;
+export declare function asOperationJson(value: unknown): JsonValue;

package/dist/sdk/operations/json.js

@@ -0,0 +1,24 @@
+import { createHash } from 'node:crypto';
+export function operationJson(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(operationJson).join(',')}]`;
+    if (value && typeof value === 'object' && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) {
+        return `{${Object.keys(value).filter(k => value[k] !== undefined).sort().map(k => `${JSON.stringify(k)}:${operationJson(value[k])}`).join(',')}}`;
+    }
+    throw new Error('Operation records require finite JSON values');
+}
+export function operationDigest(value) { return createHash('sha256').update(operationJson(value)).digest('hex'); }
+export function operationClone(value) { return JSON.parse(operationJson(value)); }
+export function operationFreeze(value) {
+    if (value && typeof value === 'object') {
+        for (const child of Object.values(value))
+            operationFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+export function asOperationJson(value) { return JSON.parse(operationJson(value)); }

package/dist/sdk/operations/reference.d.ts

@@ -0,0 +1,15 @@
+/** Host-issued lookup identity for one tool result; not evidence of business success. */
+export type OperationReference = Readonly<{
+    operationId: string;
+    revision: number;
+    toolUseId: string;
+}>;
+/** Read only the dedicated host envelope, never MCP server metadata or tool content. */
+export declare function readOperationReference(value: unknown, toolUseId: string): OperationReference | undefined;
+export declare function operationReferenceNotice(ref: OperationReference): {
+    type: 'text';
+    text: string;
+};
+/** Match only our exact current/previous envelope, preserving historical UI
+ * classification when the guidance changes. Arbitrary tool text stays visible. */
+export declare function isOperationReferenceNotice(text: string, ref: OperationReference): boolean;

package/dist/sdk/operations/reference.js

@@ -0,0 +1,19 @@
+/** Read only the dedicated host envelope, never MCP server metadata or tool content. */
+export function readOperationReference(value, toolUseId) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const ref = value;
+    if (typeof ref.operationId !== 'string' || !/^op_[a-f0-9]{64}$/.test(ref.operationId)
+        || !Number.isSafeInteger(ref.revision) || ref.revision < 1
+        || ref.toolUseId !== toolUseId || !toolUseId)
+        return undefined;
+    return { operationId: ref.operationId, revision: ref.revision, toolUseId };
+}
+export function operationReferenceNotice(ref) {
+    return { type: 'text', text: `Host recovery reference for tool use ${ref.toolUseId}: ${ref.operationId} (revision ${ref.revision}). The accompanying tool_result contains the original return. Continue the requested work using that return; query Operation get only when recovery or a saved-state check is needed, especially before replacing an uncertain invocation. A business value in the return is not automatically a host run ID. Saved state records past facts and does not prove current remote liveness or business completion.` };
+}
+/** Match only our exact current/previous envelope, preserving historical UI
+ * classification when the guidance changes. Arbitrary tool text stays visible. */
+export function isOperationReferenceNotice(text, ref) {
+    return text === operationReferenceNotice(ref).text || text === `Host operation for tool use ${ref.toolUseId}: ${ref.operationId} (revision ${ref.revision}). Use Operation get to inspect its saved state/result. Saved state is the last recorded fact, not proof of current remote liveness or completion. This reference does not confirm business effects; inspect it before starting a replacement invocation.`;
+}

package/dist/sdk/operations/store.d.ts

@@ -0,0 +1,26 @@
+import type { JsonValue } from '../commandAdapter.js';
+import { type OperationEvent, type OperationState, type OperationView } from './types.js';
+/** One authoritative transaction journal per operation; the separate database is only an OS lock. */
+export declare class OperationStore {
+    readonly storeDir: string;
+    readonly scope: string;
+    readonly root: string;
+    constructor(storeDir: string, scope: string);
+    idFor(requestKey: string): string;
+    private directory;
+    private open;
+    create(initial: Omit<OperationState, 'revision' | 'generation' | 'schemaVersion'>): OperationView;
+    private append;
+    private frames;
+    private result;
+    private view;
+    read(operationId: string): OperationView;
+    /** Mutator runs synchronously under the journal transaction; never awaits external work. */
+    update(operationId: string, event: string, mutate: (state: OperationState, putResult: (value: JsonValue) => string) => void): OperationView;
+    /** Only the lock holder may perform writable journal recovery after a crash. */
+    acquire(operationId: string): () => void;
+    events(operationId: string, cursor?: string): {
+        events: OperationEvent[];
+        nextCursor: string;
+    };
+}