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

package/dist/sdk/queryLifecycleTypes.d.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod/v4';
+/** Host observations of one query loop. Neither an authorization nor a business result. */
+export declare const QueryLifecycleSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    event_id: z.ZodString;
+    query_id: z.ZodString;
+    session_id: z.ZodString;
+    sequence: z.ZodNumber;
+    timestamp: z.ZodString;
+    scope: z.ZodEnum<{
+        main: "main";
+        subagent: "subagent";
+        auxiliary: "auxiliary";
+    }>;
+    agent_id: z.ZodNullable<z.ZodString>;
+    phase: z.ZodEnum<{
+        start: "start";
+        stop_attempt: "stop_attempt";
+        stop_failure: "stop_failure";
+        terminal: "terminal";
+    }>;
+    attempt: z.ZodNumber;
+    accepted_inputs: z.ZodArray<z.ZodObject<{
+        message_id: z.ZodString;
+        origin: z.ZodString;
+        provenance: z.ZodOptional<z.ZodObject<{
+            version: z.ZodLiteral<1>;
+            actor: z.ZodEnum<{
+                unknown: "unknown";
+                agent: "agent";
+                host: "host";
+                human: "human";
+            }>;
+            source: z.ZodString;
+            session_id: z.ZodOptional<z.ZodString>;
+            request_id: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    input_message_ids: z.ZodArray<z.ZodString>;
+    input_association: z.ZodEnum<{
+        unknown: "unknown";
+        known: "known";
+    }>;
+    last_assistant_message_id: z.ZodNullable<z.ZodString>;
+    status: z.ZodNullable<z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+        interrupted: "interrupted";
+        stopped: "stopped";
+    }>>;
+    terminal_reason: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type QueryLifecycleRecord = z.infer<typeof QueryLifecycleSchema>;
+export type QueryLifecycleWrite = {
+    state: 'saved';
+} | {
+    state: 'unavailable';
+    reason: 'persistence_disabled' | 'no_transcript';
+} | {
+    state: 'failed';
+    reason: 'write_failed';
+} | {
+    state: 'unknown';
+    reason: 'write_timeout';
+};
+export declare const QueryLifecycleWriteSchema: z.ZodUnion<readonly [z.ZodObject<{
+    state: z.ZodLiteral<"saved">;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"unavailable">;
+    reason: z.ZodEnum<{
+        persistence_disabled: "persistence_disabled";
+        no_transcript: "no_transcript";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"failed">;
+    reason: z.ZodLiteral<"write_failed">;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"unknown">;
+    reason: z.ZodLiteral<"write_timeout">;
+}, z.core.$strip>]>;
+export type QueryLifecycleObservation = {
+    record: QueryLifecycleRecord;
+    persistence: QueryLifecycleWrite;
+    transcript_path: string | null;
+};
+export declare const QueryLifecycleObservationSchema: z.ZodObject<{
+    record: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        event_id: z.ZodString;
+        query_id: z.ZodString;
+        session_id: z.ZodString;
+        sequence: z.ZodNumber;
+        timestamp: z.ZodString;
+        scope: z.ZodEnum<{
+            main: "main";
+            subagent: "subagent";
+            auxiliary: "auxiliary";
+        }>;
+        agent_id: z.ZodNullable<z.ZodString>;
+        phase: z.ZodEnum<{
+            start: "start";
+            stop_attempt: "stop_attempt";
+            stop_failure: "stop_failure";
+            terminal: "terminal";
+        }>;
+        attempt: z.ZodNumber;
+        accepted_inputs: z.ZodArray<z.ZodObject<{
+            message_id: z.ZodString;
+            origin: z.ZodString;
+            provenance: z.ZodOptional<z.ZodObject<{
+                version: z.ZodLiteral<1>;
+                actor: z.ZodEnum<{
+                    unknown: "unknown";
+                    agent: "agent";
+                    host: "host";
+                    human: "human";
+                }>;
+                source: z.ZodString;
+                session_id: z.ZodOptional<z.ZodString>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        input_message_ids: z.ZodArray<z.ZodString>;
+        input_association: z.ZodEnum<{
+            unknown: "unknown";
+            known: "known";
+        }>;
+        last_assistant_message_id: z.ZodNullable<z.ZodString>;
+        status: z.ZodNullable<z.ZodEnum<{
+            completed: "completed";
+            failed: "failed";
+            cancelled: "cancelled";
+            interrupted: "interrupted";
+            stopped: "stopped";
+        }>>;
+        terminal_reason: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    persistence: z.ZodUnion<readonly [z.ZodObject<{
+        state: z.ZodLiteral<"saved">;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"unavailable">;
+        reason: z.ZodEnum<{
+            persistence_disabled: "persistence_disabled";
+            no_transcript: "no_transcript";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"failed">;
+        reason: z.ZodLiteral<"write_failed">;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"unknown">;
+        reason: z.ZodLiteral<"write_timeout">;
+    }, z.core.$strip>]>;
+    transcript_path: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** Metadata entry deliberately has no conversation uuid/parentUuid chain fields. */
+export type QueryLifecycleEntry = {
+    type: 'query_lifecycle';
+    record: QueryLifecycleRecord;
+};

package/dist/sdk/queryLifecycleTypes.js

@@ -0,0 +1,47 @@
+import { z } from 'zod/v4';
+const identity = z.string().min(1).max(256);
+const provenance = z.object({
+    version: z.literal(1), actor: z.enum(['human', 'host', 'agent', 'unknown']),
+    source: z.string(), session_id: z.string().optional(), request_id: z.string().optional(),
+});
+/** Host observations of one query loop. Neither an authorization nor a business result. */
+export const QueryLifecycleSchema = z.object({
+    version: z.literal(1), event_id: identity, query_id: identity, session_id: identity,
+    sequence: z.number().int().nonnegative(), timestamp: z.string(),
+    scope: z.enum(['main', 'subagent', 'auxiliary']), agent_id: identity.nullable(),
+    phase: z.enum(['start', 'stop_attempt', 'stop_failure', 'terminal']),
+    attempt: z.number().int().nonnegative(),
+    accepted_inputs: z.array(z.object({ message_id: identity, origin: z.string(), provenance: provenance.optional() })),
+    // Handed to the host model adapter, not proof of server receipt or understanding.
+    input_message_ids: z.array(identity), input_association: z.enum(['known', 'unknown']),
+    last_assistant_message_id: identity.nullable(),
+    status: z.enum(['completed', 'failed', 'cancelled', 'stopped', 'interrupted']).nullable(),
+    terminal_reason: z.string().nullable(),
+}).superRefine((event, ctx) => {
+    const invalid = (message) => ctx.addIssue({ code: z.ZodIssueCode.custom, message });
+    if ((event.phase === 'terminal') !== (event.status !== null))
+        invalid('Only terminal events have a status');
+    if (event.phase !== 'terminal' && event.terminal_reason !== null)
+        invalid('Only terminal events have a terminal reason');
+    const accepted = event.accepted_inputs.map(input => input.message_id);
+    if (new Set(accepted).size !== accepted.length)
+        invalid('Duplicate accepted input');
+    if (new Set(event.input_message_ids).size !== event.input_message_ids.length)
+        invalid('Duplicate dispatched input');
+    if (event.input_message_ids.some(id => !accepted.includes(id)))
+        invalid('Dispatched input was not accepted');
+    if (event.phase === 'start' && (event.sequence !== 0 || event.attempt !== 0 || event.input_message_ids.length !== 0))
+        invalid('Invalid query start');
+    if (event.scope === 'subagent' && event.agent_id === null)
+        invalid('Subagent identity missing');
+});
+export const QueryLifecycleWriteSchema = z.union([
+    z.object({ state: z.literal('saved') }),
+    z.object({ state: z.literal('unavailable'), reason: z.enum(['persistence_disabled', 'no_transcript']) }),
+    z.object({ state: z.literal('failed'), reason: z.literal('write_failed') }),
+    z.object({ state: z.literal('unknown'), reason: z.literal('write_timeout') }),
+]);
+export const QueryLifecycleObservationSchema = z.object({
+    record: QueryLifecycleSchema, persistence: QueryLifecycleWriteSchema,
+    transcript_path: z.string().nullable(),
+});

package/dist/sdk/scheduledOccurrenceTypes.d.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod/v4';
+import type { PendingApproval } from './types.js';
+import type { PendingApprovalIdentity } from './pendingApprovalIdentity.js';
+export declare const occurrenceApprovalRequestSchema: z.ZodObject<{
+    occurrenceId: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    requestId: z.ZodString;
+    toolUseId: z.ZodString;
+    actionId: z.ZodString;
+    decision: z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+    }>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type OccurrenceApprovalRequest = z.infer<typeof occurrenceApprovalRequestSchema>;
+export type OccurrenceExecution = 'queued' | 'resuming' | 'running' | 'succeeded' | 'denied' | 'failed' | 'interrupted' | 'waiting_permission' | 'missed' | 'cancelled';
+export type OccurrenceApprovalReceipt = {
+    request: OccurrenceApprovalRequest;
+    approval: PendingApprovalIdentity;
+    originalApproval: PendingApproval;
+    acceptedAt: number;
+    outcome: 'accepted' | 'running' | 'succeeded' | 'denied' | 'waiting_permission' | 'failed' | 'interrupted';
+    completedAt?: number;
+    resumedRequestId?: string;
+    resumedToolUseId?: string;
+    error?: string;
+};
+export type OccurrenceEvent = {
+    sequence: number;
+    at: number;
+    revision: number;
+    kind: OccurrenceExecution | 'resume_requested' | 'coalesced' | 'delivery_updated' | 'cancel_requested';
+    execution: OccurrenceExecution;
+    requestId?: string;
+    toolUseId?: string;
+};
+export type ScheduledOccurrence = {
+    id: string;
+    task: {
+        id: string;
+        createdAt: number;
+        prompt: string;
+        delegation?: {
+            revision: number;
+            sourceSessionId: string;
+        };
+    };
+    scheduledAt: number;
+    acceptedAt: number;
+    revision: number;
+    execution: OccurrenceExecution;
+    delivery: 'pending' | 'delivered' | 'failed';
+    sessionId?: string;
+    result?: string;
+    error?: string;
+    deliveryError?: string;
+    skippedOccurrences?: number;
+    coalescedThrough?: number;
+    delegationRevision?: number;
+    pendingPermission?: {
+        revision: number;
+        approval: PendingApproval;
+    };
+    approvalRecoveryError?: string;
+    cancellation?: {
+        request: OccurrenceCancelRequest;
+        requestedAt: number;
+    };
+    approvalDecisions: OccurrenceApprovalReceipt[];
+    events: OccurrenceEvent[];
+};
+export type OccurrenceLookup = {
+    status: 'not_found';
+    ownerAvailable: boolean;
+} | {
+    status: 'found';
+    snapshot: ScheduledOccurrence;
+    ownerAvailable: boolean;
+};
+export type OccurrenceEvents = {
+    events: OccurrenceEvent[];
+    nextSequence: number;
+    hasMore: boolean;
+};
+export declare const occurrenceSelectorSchema: z.ZodObject<{
+    occurrenceId: z.ZodString;
+}, z.core.$strict>;
+export declare const occurrenceListSchema: z.ZodObject<{
+    taskId: z.ZodOptional<z.ZodString>;
+    sourceSessionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const occurrenceEventsSchema: z.ZodObject<{
+    occurrenceId: z.ZodString;
+    afterSequence: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const occurrenceCancelRequestSchema: z.ZodObject<{
+    occurrenceId: z.ZodString;
+    expectedRevision: z.ZodNumber;
+    actionId: z.ZodString;
+}, z.core.$strict>;
+export type OccurrenceCancelRequest = z.infer<typeof occurrenceCancelRequestSchema>;

package/dist/sdk/scheduledOccurrenceTypes.js

@@ -0,0 +1,12 @@
+import { z } from 'zod/v4';
+export const occurrenceApprovalRequestSchema = z.strictObject({
+    occurrenceId: z.string().regex(/^[a-f0-9]{64}$/),
+    expectedRevision: z.number().int().nonnegative(),
+    requestId: z.string().min(1), toolUseId: z.string().min(1),
+    actionId: z.string().min(1).max(200), decision: z.enum(['allow', 'deny']),
+    message: z.string().optional(),
+});
+export const occurrenceSelectorSchema = z.strictObject({ occurrenceId: z.string().regex(/^[a-f0-9]{64}$/) });
+export const occurrenceListSchema = z.strictObject({ taskId: z.string().min(1).optional(), sourceSessionId: z.string().min(1).optional() });
+export const occurrenceEventsSchema = occurrenceSelectorSchema.extend({ afterSequence: z.number().int().nonnegative().optional(), limit: z.number().int().min(1).max(1000).optional() });
+export const occurrenceCancelRequestSchema = occurrenceSelectorSchema.extend({ expectedRevision: z.number().int().nonnegative(), actionId: z.string().min(1).max(200) });

package/dist/sdk/types.d.ts

@@ -29,6 +29,8 @@ export type CanUseToolResult = {
     interaction?: import('./interactionResponseSchema.js').InteractionResponse;
     /** Also interrupt the current turn instead of letting the agent continue. */
     interrupt?: boolean;
+    /** Host control-channel provenance; not a human refusal or a new authorization. */
+    cancellation?: import('./cancellation.js').HostCancellation;
 } | {
     /**
      * Suspend the session at this tool call (issue P0-2 pending): the tool
@@ -71,6 +73,10 @@ export type QueryOptions = {
      * deny, the tool does not execute.
      */
     canUseTool?: CanUseToolFn;
+    /** Default review preserves SDK host review of ambient allows; ask_only trusts local policy. */
+    permissionCallbackMode?: 'review' | 'ask_only';
+    /** Host-supplied task grants, applied before any input/resume. Never model-supplied. */
+    permissionDelegation?: import('./permissionDelegation.js').PermissionDelegation;
     /**
      * Milliseconds before an unresolved canUseTool callback is treated as a
      * deny (fail-closed). Default 300_000. Pass 0 to disable the timeout
@@ -234,6 +240,7 @@ export type LifecycleHooks = {
         toolName?: string;
         content: unknown;
         isError: boolean;
+        operationReference?: import('./operations/reference.js').OperationReference;
         sessionId?: string;
     }) => void | Promise<void>;
     /**
@@ -261,16 +268,21 @@ export type PendingApproval = {
     toolName: string;
     input: Record<string, unknown>;
     createdAt: string;
+    /** New suspension requests are resumable only after the CLI confirms durable preservation. */
+    suspension?: 'requested' | 'confirmed';
 };
 /** Host decision applied on resume for a recorded pending approval. */
 export type PendingDecision = {
+    /** Bind a durable decision to the original approval and enforce matching before CLI tool execution. */
+    expectedApproval?: import('./pendingApprovalIdentity.js').PendingApprovalIdentity;
+} & ({
     behavior: 'allow';
-    /** Override the approved input; defaults to the recorded pending input. */
+    /** Override the approved input in legacy mode; strict expectedApproval permits only identical input. */
     updatedInput?: Record<string, unknown>;
 } | {
     behavior: 'deny';
     message?: string;
-};
+});
 export type AccumulatedUsage = {
     queries: number;
     inputTokens: number;
@@ -351,6 +363,10 @@ export type SessionLifecycleEvent = {
     reason: string;
 });
 type SDKEventPayload = {
+    type: 'query_lifecycle';
+    lifecycle: import('./queryLifecycleTypes.js').QueryLifecycleObservation;
+    sessionId: string;
+} | {
     type: 'assistant_text';
     text: string;
     sessionId?: string;
@@ -373,6 +389,7 @@ type SDKEventPayload = {
     toolUseId: string;
     content: unknown;
     isError: boolean;
+    operationReference?: import('./operations/reference.js').OperationReference;
     sessionId?: string;
 } | {
     type: 'permission_request';
@@ -388,6 +405,7 @@ type SDKEventPayload = {
     behavior: 'allow' | 'deny';
     /** Why the SDK decided this way when the host callback did not decide. */
     failClosedReason?: string;
+    cancellation?: import('./cancellation.js').HostCancellation;
     interaction?: import('./interactionResponseSchema.js').InteractionResponse;
     /** 'pending_decision' when resolved by resumeWithDecision, not the live callback. */
     source?: 'callback' | 'pending_decision';
@@ -464,7 +482,7 @@ export type InitializationResult = {
  * the stream is identical to the bare queryWithTransport generator.
  */
 export interface Query extends AsyncGenerator<SDKEvent, void, unknown> {
-    interrupt(): Promise<unknown>;
+    interrupt(cancellation?: import('./cancellation.js').HostCancellation): Promise<unknown>;
     setPermissionMode(mode: string): Promise<unknown>;
     setModel(model?: string): Promise<unknown>;
     setMaxThinkingTokens(n: number | null): Promise<unknown>;