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

package/dist/sdk/query.js

@@ -1,3 +1,7 @@
+import { randomUUID } from 'node:crypto';
+import { approvalInputDigest, pendingApprovalIdentity, pendingApprovalSuspensionResponseSchema, pendingApprovalIdentitySchema, pendingApprovalConflictSchema, samePendingApproval } from './pendingApprovalIdentity.js';
+import { QueryLifecycleObservationSchema } from './queryLifecycleTypes.js';
+import { readOperationReference } from './operations/reference.js';
 import { sanitizeRequestProgress } from './requestProgress.js';
 /**
  * ccl-sdk query() — the programmatic headless entry (issue P0-1) with the
@@ -26,7 +30,8 @@ import { sanitizeRequestProgress } from './requestProgress.js';
  *   the model re-generated. Deny works symmetrically. One-shot: the record
  *   is deleted after it is applied.
  */
-import { existsSync, mkdtempSync, symlinkSync } from 'fs';
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'fs';
+import { createHash } from 'crypto';
 import { describeError, errorDetailsList, sanitizeErrorEnvelope, sanitizeErrorText, sanitizeRecoveryDiagnostic, sanitizeRecoveryOutcome } from './errorDiagnostics.js';
 import { interactionResponseSchema } from './interactionResponseSchema.js';
 import { tmpdir } from 'os';
@@ -36,6 +41,7 @@ import { SdkMcpRegistry } from './mcpServer.js';
 import { fileSessionStore } from './store.js';
 import { spawnCliTransport } from './transport.js';
 import { isAsyncInput, normalizeUserInput, readWithInput } from './queryInput.js';
+import { isInternalInput } from './inputProvenance.js';
 const DEFAULT_CAN_USE_TOOL_TIMEOUT_MS = 300_000;
 /** Builds the CLI argv for a query. Exported for unit tests. */
 export function buildCliArgs(options) {
@@ -71,8 +77,17 @@ export function buildCliArgs(options) {
         args.push('--max-turns', String(options.maxTurns));
     if (options.maxBudgetUsd !== undefined)
         args.push('--max-budget-usd', String(options.maxBudgetUsd));
-    if (options.permissionMode)
-        args.push('--permission-mode', options.permissionMode);
+    const permissionMode = options.permissionDelegation?.mode ?? options.permissionMode;
+    if (permissionMode)
+        args.push('--permission-mode', permissionMode);
+    if (options.permissionCallbackMode)
+        args.push('--permission-callback-mode', options.permissionCallbackMode);
+    if (options.permissionDelegation)
+        args.push('--require-permission-delegation');
+    if (options.pendingDecision)
+        args.push('--resume-pending-approval');
+    if (options.pendingDecision?.expectedApproval)
+        args.push('--strict-pending-resume');
     for (const dir of options.pluginDirs ?? [])
         args.push('--plugin-dir', dir);
     if (options.addDirs?.length)
@@ -119,18 +134,40 @@ export function buildCliEnv(options) {
 /**
  * Wraps each skills dir as an ephemeral plugin (a temp dir whose `skills`
  * entry symlinks to the user's dir) so the CLI loads it via --plugin-dir,
- * its cwd-independent skill channel (P1-5). Exported for unit tests.
+ * its cwd-independent skill channel (P1-5). Direct callers own the returned
+ * directories; managed transports dispose only their own wrappers.
  */
 export function prepareSkillsWrappers(skillsDirs) {
-    return skillsDirs.map(dir => {
-        const target = resolve(dir);
-        if (!existsSync(target)) {
-            throw new Error(`ccl-sdk: skills dir does not exist: ${target}`);
+    // Validate every input before allocating. Canonical roots keep identity stable
+    // across temporary wrappers and pin a published version before CLI discovery.
+    const targets = [...new Set(skillsDirs.map(dir => {
+            const target = resolve(dir);
+            if (!existsSync(target)) {
+                throw new Error(`ccl-sdk: skills dir does not exist: ${target}`);
+            }
+            const canonical = realpathSync(target);
+            if (!statSync(canonical).isDirectory()) {
+                throw new Error(`ccl-sdk: skills path is not a directory: ${target}`);
+            }
+            return canonical;
+        }))];
+    const wrappers = [];
+    try {
+        for (const target of targets) {
+            const wrapper = mkdtempSync(join(tmpdir(), 'ccl-sdk-skills-'));
+            wrappers.push(wrapper);
+            mkdirSync(join(wrapper, '.claude-plugin'));
+            const name = `ccl-sdk-skills-${createHash('sha256').update(target).digest('hex')}`;
+            writeFileSync(join(wrapper, '.claude-plugin', 'plugin.json'), JSON.stringify({ name, skills: ['./skills'] }));
+            symlinkSync(target, join(wrapper, 'skills'), 'dir');
         }
-        const wrapper = mkdtempSync(join(tmpdir(), 'ccl-sdk-skills-'));
-        symlinkSync(target, join(wrapper, 'skills'), 'dir');
-        return wrapper;
-    });
+        return wrappers;
+    }
+    catch (error) {
+        for (const wrapper of wrappers)
+            rmSync(wrapper, { recursive: true, force: true });
+        throw error;
+    }
 }
 function resolveCliPath(options) {
     if (options.cliPath)
@@ -258,8 +295,30 @@ export async function* queryWithTransport(prompt, options, transport) {
     let turn = 0;
     let sawResult = false;
     let sessionEnded = false;
+    let suspension;
+    let suspensionTimer;
+    let suspensionTimedOut = false;
     const streamingInput = isAsyncInput(prompt);
     const inputState = { finished: false };
+    let resolveProvenanceSupport;
+    const provenanceSupport = new Promise(resolve => { resolveProvenanceSupport = resolve; });
+    async function* negotiatedInputs(source) {
+        for await (const message of source) {
+            if (message?.input_provenance !== undefined || message?.isSynthetic === true) {
+                let timer;
+                try {
+                    const supported = await Promise.race([provenanceSupport, new Promise(resolve => { timer = setTimeout(() => resolve(false), 30000); })]);
+                    if (!supported)
+                        throw new Error('CCL input_provenance v1 is unavailable; upgrade the CLI or bind a compatible runtime before submitting internal input');
+                }
+                finally {
+                    if (timer)
+                        clearTimeout(timer);
+                }
+            }
+            yield message;
+        }
+    }
     // resumeWithDecision path: the recorded approval this run must settle.
     let pendingApproval = null;
     let pendingDecision = options.pendingDecision;
@@ -267,12 +326,28 @@ export async function* queryWithTransport(prompt, options, transport) {
         if (!options.resume) {
             throw new Error('ccl-sdk: pendingDecision requires options.resume');
         }
-        pendingApproval = await store.loadPendingApproval(options.resume);
-        if (!pendingApproval) {
-            throw new Error(`ccl-sdk: no pending approval recorded for session ${options.resume}`);
+        try {
+            pendingApproval = await store.loadPendingApproval(options.resume);
+            if (!pendingApproval)
+                throw new Error(`ccl-sdk: no pending approval recorded for session ${options.resume}`);
+            if (pendingApproval.suspension && pendingApproval.suspension !== 'confirmed')
+                throw new Error('permission_suspension_unconfirmed: the CLI did not confirm a durable suspension; execution status must be checked before resuming');
+            if (pendingDecision.expectedApproval) {
+                const expected = pendingApprovalIdentitySchema.parse(pendingDecision.expectedApproval);
+                if (!samePendingApproval(expected, pendingApproval) || expected.sessionId !== options.resume)
+                    throw new Error('resume_approval_mismatch: saved approval does not match the decision identity');
+                if (pendingDecision.behavior === 'allow' && pendingDecision.updatedInput && approvalInputDigest(pendingDecision.updatedInput) !== expected.inputDigest)
+                    throw new Error('resume_approval_mismatch: strict approval cannot substitute different input');
+                pendingDecision = { ...pendingDecision, expectedApproval: expected };
+            }
+        }
+        catch (error) {
+            await transport.close();
+            throw error;
         }
     }
-    const onAbort = () => void transport.close();
+    const strictApprovalEvidence = pendingDecision?.expectedApproval ? pendingApproval : null;
+    const onAbort = () => { resolveProvenanceSupport(false); void transport.close(); };
     options.signal?.addEventListener('abort', onAbort, { once: true });
     if (options.signal?.aborted)
         onAbort();
@@ -299,6 +374,9 @@ export async function* queryWithTransport(prompt, options, transport) {
             request_id: initId,
             request: {
                 subtype: 'initialize',
+                ...(pendingApproval ? { pendingResumeApproval: { approval: pendingApprovalIdentity(pendingApproval), confirmed: pendingApproval.suspension === 'confirmed' } } : {}),
+                ...(options.permissionDelegation ? { permissionDelegation: options.permissionDelegation } : {}),
+                ...(pendingDecision?.expectedApproval ? { strictPendingApproval: pendingDecision.expectedApproval } : {}),
                 ...(options.systemPrompt !== undefined && {
                     systemPrompt: options.systemPrompt,
                 }),
@@ -334,14 +412,15 @@ export async function* queryWithTransport(prompt, options, transport) {
         // slice sdk-observability-hooks-usage (G5): fire onSessionStart once, on the first session_id.
         let sessionStarted = false;
         const messages = streamingInput
-            ? readWithInput(prompt, transport, inputState, async (message) => {
+            ? readWithInput(negotiatedInputs(prompt), transport, inputState, async (message) => {
                 sawResult = false;
                 const text = typeof message.message.content === 'string' ? message.message.content
                     : message.message.content.filter(b => b.type === 'text').map(b => b.text).join('\n');
-                await runHook(hooks.onUserPromptSubmit && (() => hooks.onUserPromptSubmit({ prompt: text, sessionId: lastSessionId })));
+                if (!isInternalInput(message))
+                    await runHook(hooks.onUserPromptSubmit && (() => hooks.onUserPromptSubmit({ prompt: text, sessionId: lastSessionId })));
             })
             : transport.read();
-        for await (const rawMessage of messages) {
+        permissionWire: for await (const rawMessage of messages) {
             let attribution = rawMessage.input_uuid === null
                 ? { origin: 'background' } : typeof rawMessage.input_uuid === 'string'
                 ? { origin: 'user', turnId: rawMessage.input_uuid }
@@ -372,6 +451,13 @@ export async function* queryWithTransport(prompt, options, transport) {
                 yield { ...attribution, type: 'raw', message };
             switch (message.type) {
                 case 'system': {
+                    if (message.subtype === 'query_lifecycle') {
+                        const parsed = QueryLifecycleObservationSchema.safeParse(message.lifecycle);
+                        if (parsed.success && parsed.data.record.session_id === message.session_id && parsed.data.record.event_id === message.uuid)
+                            yield {
+                                ...attribution, type: 'query_lifecycle', lifecycle: parsed.data, sessionId: parsed.data.record.session_id,
+                            };
+                    }
                     if (message.subtype === 'request_progress' && progress)
                         yield { ...attribution,
                             type: 'request_progress', progress,
@@ -419,6 +505,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                     for (const block of contentBlocks(message.message)) {
                         if (block.type === 'tool_result') {
                             const toolUseId = String(block.tool_use_id ?? '');
+                            const operationReference = readOperationReference(message.operation_reference, toolUseId);
                             const isError = block.is_error === true;
                             const resultContent = isError
                                 ? typeof block.content === 'string' ? sanitizeErrorText(block.content)
@@ -429,6 +516,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                                 type: 'tool_result',
                                 toolUseId,
                                 content: resultContent,
+                                ...(operationReference ? { operationReference } : {}),
                                 isError,
                                 sessionId,
                             };
@@ -437,6 +525,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                                     toolUseId,
                                     toolName: toolNamesById.get(toolUseId),
                                     content: resultContent,
+                                    ...(operationReference ? { operationReference } : {}),
                                     isError,
                                     sessionId,
                                 })));
@@ -447,6 +536,10 @@ export async function* queryWithTransport(prompt, options, transport) {
                     break;
                 }
                 case 'control_request': {
+                    // Suspension stops the whole query; never answer another concurrent
+                    // tool while waiting for the targeted CLI acknowledgement.
+                    if (suspension)
+                        break;
                     const requestId = String(message.request_id ?? '');
                     const request = (message.request ?? {});
                     // slice sdk-in-process-mcp-server: route MCP tool calls to host in-process servers.
@@ -491,9 +584,14 @@ export async function* queryWithTransport(prompt, options, transport) {
                         agentId,
                     };
                     // Resume path: settle the recorded approval on its matching call.
-                    // Match by toolName — on allow the tool runs with the RECORDED
-                    // input (or the host's explicit updatedInput), never the model's
-                    // re-generated one, so what the owner approved is what executes.
+                    // Strict callers require the same tool and structured input. Legacy
+                    // callers retain name-only matching and recorded-input substitution.
+                    if (pendingDecision?.expectedApproval && (toolName !== pendingDecision.expectedApproval.toolName || approvalInputDigest(input) !== pendingDecision.expectedApproval.inputDigest)) {
+                        yield { ...attribution, type: 'error', code: 'resume_approval_mismatch', fatal: true, message: 'Regenerated tool/input differs from the original approved invocation' };
+                        // Unwind the read iterator before finally awaits close; otherwise
+                        // unread stdout can keep the child's close event waiting forever.
+                        return;
+                    }
                     if (pendingDecision && pendingApproval?.toolName === toolName) {
                         const decision = pendingDecision.behavior === 'allow'
                             ? {
@@ -576,28 +674,16 @@ export async function* queryWithTransport(prompt, options, transport) {
                             toolName,
                             input,
                             createdAt: new Date().toISOString(),
+                            suspension: 'requested',
                         };
                         await store.savePendingApproval(record);
-                        // Deliberately NO control_response: the tool must not run and
-                        // the model must not see a denial. Terminating here leaves the
-                        // transcript ending at the unresolved tool_use, which the
-                        // resume path drops and re-drives.
-                        yield { ...attribution,
-                            type: 'suspended',
-                            sessionId,
-                            requestId,
-                            toolUseId,
-                            toolName,
-                            input,
-                        };
-                        sessionEnded = true;
-                        await runHook(hooks.onSessionEnd &&
-                            (() => hooks.onSessionEnd({
-                                sessionId,
-                                subtype: 'suspended',
-                                isError: false,
-                            })));
-                        return;
+                        // A saved SDK record alone does not prove the CLI stopped without
+                        // converting EOF into a denial. Ask it to freeze and persist first.
+                        suspension = { requestId: randomUUID(), record, attribution, confirmed: false };
+                        suspensionTimer = setTimeout(() => { suspensionTimedOut = true; void transport.close(); }, 10000);
+                        await transport.write({ type: 'control_request', request_id: suspension.requestId,
+                            request: { subtype: 'suspend_permission', approval: pendingApprovalIdentity(record) } });
+                        break;
                     }
                     await transport.write({
                         type: 'control_response',
@@ -623,8 +709,24 @@ export async function* queryWithTransport(prompt, options, transport) {
                 case 'control_response': {
                     const response = (message.response ?? {});
                     const requestId = String(response.request_id ?? '');
+                    if (suspension?.requestId === requestId) {
+                        const ack = pendingApprovalSuspensionResponseSchema.safeParse(response.response);
+                        if (response.subtype !== 'success' || !ack.success || !samePendingApproval(ack.data.approval, suspension.record)) {
+                            yield { ...suspension.attribution, type: 'error', code: 'permission_suspension_failed', fatal: true,
+                                message: `CLI did not confirm pending approval suspension: ${String(response.error ?? 'invalid acknowledgement')}` };
+                            return;
+                        }
+                        suspension.record = { ...suspension.record, suspension: 'confirmed' };
+                        await store.savePendingApproval(suspension.record);
+                        suspension.confirmed = true;
+                        if (suspensionTimer)
+                            clearTimeout(suspensionTimer);
+                        break permissionWire;
+                    }
                     if (ownRequestIds.has(requestId)) {
                         ownRequestIds.delete(requestId);
+                        const capability = response.response?.input_provenance;
+                        resolveProvenanceSupport(response.subtype !== 'error' && capability?.versions?.includes(1) === true);
                         if (response.subtype === 'error') {
                             yield { ...attribution,
                                 type: 'error',
@@ -637,6 +739,34 @@ export async function* queryWithTransport(prompt, options, transport) {
                     break;
                 }
                 case 'result': {
+                    if (suspension && !suspension.confirmed) {
+                        yield { ...suspension.attribution, type: 'error', code: 'permission_suspension_failed', fatal: true,
+                            message: 'CLI ended its turn before confirming permission suspension; inspect execution status' };
+                        return;
+                    }
+                    const conflict = pendingApprovalConflictSchema.safeParse(message.permission_resume_conflict);
+                    if (strictApprovalEvidence && conflict.success && samePendingApproval(conflict.data.approval, strictApprovalEvidence) && message.session_id === strictApprovalEvidence.sessionId) {
+                        if (conflict.data.originalNotExecuted) {
+                            // The CLI guard proves this invocation never reached execution. Restore
+                            // evidence removed on response; never overwrite a newer pending request.
+                            const current = await store.loadPendingApproval(strictApprovalEvidence.sessionId);
+                            if (!current)
+                                await store.savePendingApproval(strictApprovalEvidence);
+                        }
+                        yield { ...attribution, type: 'error', code: conflict.data.code, fatal: true,
+                            message: errorDetailsList(message.errors).join('; ') || 'Strict approval conflict before execution' };
+                        // Unwind the read iterator before finally awaits close; otherwise
+                        // unread stdout can keep the child's close event waiting forever.
+                        return;
+                    }
+                    if (pendingDecision?.expectedApproval) {
+                        yield { ...attribution, type: 'error', code: 'resume_approval_mismatch', fatal: true,
+                            message: 'Strict resume ended without settling the original approval',
+                        };
+                        // Unwind the read iterator before finally awaits close; otherwise
+                        // unread stdout can keep the child's close event waiting forever.
+                        return;
+                    }
                     sawResult = true;
                     const sessionId = message.session_id;
                     const usage = message.usage;
@@ -710,6 +840,22 @@ export async function* queryWithTransport(prompt, options, transport) {
             if (sawResult && !streamingInput)
                 break;
         }
+        if (suspension) {
+            if (!suspension.confirmed) {
+                yield { ...suspension.attribution, type: 'error', code: 'permission_suspension_failed', fatal: true,
+                    message: suspensionTimedOut ? 'Timed out waiting for CLI permission suspension acknowledgement' : 'CLI exited without confirming permission suspension' };
+                return;
+            }
+            // The read iterator has unwound. Stop the original process before exposing
+            // a resumable event, so a consumer can immediately resume in a fresh CLI.
+            await transport.close();
+            const record = suspension.record;
+            yield { ...suspension.attribution, type: 'suspended', sessionId: record.sessionId,
+                requestId: record.requestId, toolUseId: record.toolUseId, toolName: record.toolName, input: record.input };
+            sessionEnded = true;
+            await runHook(hooks.onSessionEnd && (() => hooks.onSessionEnd({ sessionId: record.sessionId, subtype: 'suspended', isError: false })));
+            return;
+        }
         if (streamingInput && inputState.finished) {
             await runHook(hooks.onSessionEnd && (() => hooks.onSessionEnd({
                 sessionId: lastSessionId, subtype: 'input_complete', isError: false,
@@ -737,6 +883,9 @@ export async function* queryWithTransport(prompt, options, transport) {
         }
     }
     finally {
+        if (suspensionTimer)
+            clearTimeout(suspensionTimer);
+        resolveProvenanceSupport(false);
         options.signal?.removeEventListener('abort', onAbort);
         await sdkMcpRegistry?.close();
         await transport.close();
@@ -744,26 +893,56 @@ export async function* queryWithTransport(prompt, options, transport) {
 }
 /** Spawns the managed CLI subprocess for a set of options. Shared with the P1 Query handle. */
 export function spawnForOptions(options) {
+    const wrappers = options.skillsDirs?.length ? prepareSkillsWrappers(options.skillsDirs) : [];
     const pluginDirs = [
         ...(options.pluginDirs ?? []),
-        ...(options.skillsDirs?.length ? prepareSkillsWrappers(options.skillsDirs) : []),
+        ...wrappers,
     ];
     const effective = { ...options, pluginDirs };
-    return spawnCliTransport({
-        onDiagnostic: options.onDiagnostic ?? (line => {
-            if (line.startsWith('[business records]')) {
+    const cleanup = () => {
+        for (const wrapper of wrappers) {
+            try {
+                rmSync(wrapper, { recursive: true, force: true });
+            }
+            catch (error) {
                 try {
-                    process.stderr.write(line + '\n');
+                    options.onDiagnostic?.(`ccl-sdk: could not remove skill wrapper: ${String(error)}`);
                 }
-                catch { /* diagnostics must not fail the query */ }
+                catch { /* cleanup must not mask a transport error */ }
             }
-        }),
-        execPath: options.execPath ?? process.execPath,
-        cliPath: resolveCliPath(options),
-        args: buildCliArgs(effective),
-        cwd: options.cwd,
-        env: buildCliEnv(effective),
-    });
+        }
+    };
+    try {
+        const transport = spawnCliTransport({
+            onDiagnostic: options.onDiagnostic ?? (line => {
+                if (line.startsWith('[business records]') || line.startsWith('[memory]')) {
+                    try {
+                        process.stderr.write(line + '\n');
+                    }
+                    catch { /* diagnostics must not fail the query */ }
+                }
+            }),
+            execPath: options.execPath ?? process.execPath,
+            cliPath: resolveCliPath(options),
+            args: buildCliArgs(effective),
+            cwd: options.cwd,
+            env: buildCliEnv(effective),
+        });
+        void transport.exited.then(cleanup, cleanup);
+        let closing;
+        return {
+            ...transport,
+            close() {
+                // Concurrent Session/Query shutdowns share completion. A second close
+                // must not remove wrappers while the first is still stopping the CLI.
+                return closing ??= transport.close().finally(cleanup);
+            },
+        };
+    }
+    catch (error) {
+        cleanup();
+        throw error;
+    }
 }
 /**
  * Run one prompt against a CCL agent session and stream JSON-serializable
@@ -781,7 +960,8 @@ export function query(prompt, options = {}) {
  *
  * On allow, the suspended tool executes with exactly the recorded input (or
  * decision.updatedInput if the owner amended it); on deny the model receives
- * the denial and the session continues.
+ * the denial and the session continues. With expectedApproval, both the saved
+ * identity and regenerated input must match; substitution is not permitted.
  */
 export function resumeWithDecision(sessionId, decision, options = {}) {
     const merged = {

package/dist/sdk/queryInput.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { parseInputProvenance } from './inputProvenance.js';
 export function isAsyncInput(value) {
     return value !== null && typeof value === 'object' &&
         typeof value[Symbol.asyncIterator] === 'function';
@@ -17,9 +18,15 @@ export function normalizeUserInput(value) {
     if (input.uuid !== undefined && (typeof input.uuid !== 'string' || !input.uuid)) {
         throw new TypeError('ccl-sdk: user message uuid must be a nonempty string');
     }
+    if (input.isSynthetic !== undefined && typeof input.isSynthetic !== 'boolean')
+        throw new TypeError('isSynthetic must be a boolean');
+    if (input.isSynthetic && input.input_provenance?.actor === 'human')
+        throw new TypeError('Synthetic input cannot claim a human actor');
     return {
         type: 'user', uuid: input.uuid ?? randomUUID(),
         message: { role: 'user', content }, parent_tool_use_id: null,
+        ...(input.isSynthetic !== undefined ? { isSynthetic: input.isSynthetic } : {}),
+        ...(input.input_provenance !== undefined ? { input_provenance: parseInputProvenance(input.input_provenance) } : {}),
     };
 }
 /**

package/dist/sdk/queryLifecycle.d.ts

@@ -0,0 +1,19 @@
+import { type QueryLifecycleRecord } from './queryLifecycleTypes.js';
+export type QueryLifecycleRead = {
+    state: 'found';
+    completeness: 'complete' | 'incomplete';
+    records: QueryLifecycleRecord[];
+    terminal?: QueryLifecycleRecord;
+} | {
+    state: 'not_found';
+} | {
+    state: 'unavailable';
+    reason: 'file_unavailable' | 'invalid_record' | 'truncated_tail' | 'record_too_large' | 'conflicting_events';
+};
+/** Read one caller-specified file. Absence is never proof that a tool did not run.
+ * No session discovery, model invocation, daemon startup or repair is performed. */
+export declare function readQueryLifecycle(input: {
+    transcriptPath: string;
+    sessionId: string;
+    queryId: string;
+}): Promise<QueryLifecycleRead>;

package/dist/sdk/queryLifecycle.js

@@ -0,0 +1,93 @@
+import { createReadStream } from 'node:fs';
+import { QueryLifecycleSchema } from './queryLifecycleTypes.js';
+/** Read one caller-specified file. Absence is never proof that a tool did not run.
+ * No session discovery, model invocation, daemon startup or repair is performed. */
+export async function readQueryLifecycle(input) {
+    const records = [];
+    const events = new Map();
+    let failure;
+    let pending = '';
+    const stream = createReadStream(input.transcriptPath, { encoding: 'utf8', highWaterMark: 64 * 1024 });
+    const consume = (line) => {
+        if (!line.trim())
+            return;
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            failure = { state: 'unavailable', reason: 'invalid_record' };
+            return;
+        }
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            failure = { state: 'unavailable', reason: 'invalid_record' };
+            return;
+        }
+        const entry = raw;
+        if (entry.type !== 'query_lifecycle')
+            return;
+        if (entry.record?.session_id !== input.sessionId || entry.record?.query_id !== input.queryId)
+            return;
+        const parsed = QueryLifecycleSchema.safeParse(entry.record);
+        if (!parsed.success) {
+            failure = { state: 'unavailable', reason: 'invalid_record' };
+            return;
+        }
+        const record = parsed.data;
+        const serialized = JSON.stringify(record);
+        const duplicate = events.get(record.event_id);
+        if (duplicate !== undefined) {
+            if (duplicate !== serialized)
+                failure = { state: 'unavailable', reason: 'conflicting_events' };
+            return;
+        }
+        events.set(record.event_id, serialized);
+        records.push(record);
+    };
+    try {
+        for await (const chunk of stream) {
+            pending += chunk;
+            let index;
+            while ((index = pending.indexOf('\n')) !== -1) {
+                if (index > 32 * 1024 * 1024)
+                    return { state: 'unavailable', reason: 'record_too_large' };
+                consume(pending.slice(0, index));
+                if (failure)
+                    return failure;
+                pending = pending.slice(index + 1);
+            }
+            // Protect against an unbounded unterminated line, including ordinary
+            // conversation records. Large files remain streamed rather than loaded.
+            if (pending.length > 32 * 1024 * 1024)
+                return { state: 'unavailable', reason: 'record_too_large' };
+        }
+        if (pending.trim())
+            return { state: 'unavailable', reason: 'truncated_tail' };
+    }
+    catch {
+        return { state: 'unavailable', reason: 'file_unavailable' };
+    }
+    finally {
+        stream.destroy();
+    }
+    if (!records.length)
+        return { state: 'not_found' };
+    let previous;
+    let completeSequence = records[0].phase === 'start';
+    for (const record of records) {
+        if (previous) {
+            if (previous.phase === 'terminal' || record.sequence <= previous.sequence || record.phase === 'start'
+                || record.scope !== previous.scope || record.agent_id !== previous.agent_id
+                || previous.accepted_inputs.some(p => !record.accepted_inputs.some(n => n.message_id === p.message_id && JSON.stringify(n) === JSON.stringify(p)))
+                || previous.input_message_ids.some(id => !record.input_message_ids.includes(id))) {
+                return { state: 'unavailable', reason: 'conflicting_events' };
+            }
+            if (record.sequence !== previous.sequence + 1)
+                completeSequence = false;
+        }
+        previous = record;
+    }
+    const terminal = previous?.phase === 'terminal' ? previous : undefined;
+    return { state: 'found', completeness: terminal && completeSequence ? 'complete' : 'incomplete', records,
+        ...(terminal && completeSequence ? { terminal } : {}) };
+}