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

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";
+                human: "human";
+                host: "host";
+            }>;
+            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";
+                    human: "human";
+                    host: "host";
+                }>;
+                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/runtimeResources.d.ts

@@ -0,0 +1,197 @@
+import { z } from 'zod/v4';
+export declare const RuntimeResourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodEnum<{
+        memory: "memory";
+        scratch: "scratch";
+    }>;
+    scope: z.ZodEnum<{
+        shared: "shared";
+        session: "session";
+    }>;
+    lifetime: z.ZodEnum<{
+        persistent: "persistent";
+        temporary: "temporary";
+    }>;
+    supported_operations: z.ZodArray<z.ZodEnum<{
+        read: "read";
+        write: "write";
+    }>>;
+    status: z.ZodLiteral<"available">;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodEnum<{
+        memory: "memory";
+        scratch: "scratch";
+    }>;
+    scope: z.ZodEnum<{
+        shared: "shared";
+        session: "session";
+    }>;
+    lifetime: z.ZodEnum<{
+        persistent: "persistent";
+        temporary: "temporary";
+    }>;
+    supported_operations: z.ZodArray<z.ZodEnum<{
+        read: "read";
+        write: "write";
+    }>>;
+    status: z.ZodLiteral<"disabled">;
+    reason: z.ZodLiteral<"feature_disabled">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodEnum<{
+        memory: "memory";
+        scratch: "scratch";
+    }>;
+    scope: z.ZodEnum<{
+        shared: "shared";
+        session: "session";
+    }>;
+    lifetime: z.ZodEnum<{
+        persistent: "persistent";
+        temporary: "temporary";
+    }>;
+    supported_operations: z.ZodArray<z.ZodEnum<{
+        read: "read";
+        write: "write";
+    }>>;
+    status: z.ZodLiteral<"unavailable">;
+    reason: z.ZodLiteral<"path_unavailable">;
+}, z.core.$strip>]>;
+/** Trusted connection metadata, not a permission grant or authenticated account ID. */
+export declare const RuntimeResourcesSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    runtime_id: z.ZodString;
+    snapshot_id: z.ZodString;
+    authorization: z.ZodLiteral<"none">;
+    status: z.ZodLiteral<"available">;
+    context_id: z.ZodString;
+    session_id: z.ZodString;
+    project_root: z.ZodString;
+    original_cwd: z.ZodString;
+    cwd: z.ZodString;
+    resources: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodEnum<{
+            memory: "memory";
+            scratch: "scratch";
+        }>;
+        scope: z.ZodEnum<{
+            shared: "shared";
+            session: "session";
+        }>;
+        lifetime: z.ZodEnum<{
+            persistent: "persistent";
+            temporary: "temporary";
+        }>;
+        supported_operations: z.ZodArray<z.ZodEnum<{
+            read: "read";
+            write: "write";
+        }>>;
+        status: z.ZodLiteral<"available">;
+        path: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodEnum<{
+            memory: "memory";
+            scratch: "scratch";
+        }>;
+        scope: z.ZodEnum<{
+            shared: "shared";
+            session: "session";
+        }>;
+        lifetime: z.ZodEnum<{
+            persistent: "persistent";
+            temporary: "temporary";
+        }>;
+        supported_operations: z.ZodArray<z.ZodEnum<{
+            read: "read";
+            write: "write";
+        }>>;
+        status: z.ZodLiteral<"disabled">;
+        reason: z.ZodLiteral<"feature_disabled">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodEnum<{
+            memory: "memory";
+            scratch: "scratch";
+        }>;
+        scope: z.ZodEnum<{
+            shared: "shared";
+            session: "session";
+        }>;
+        lifetime: z.ZodEnum<{
+            persistent: "persistent";
+            temporary: "temporary";
+        }>;
+        supported_operations: z.ZodArray<z.ZodEnum<{
+            read: "read";
+            write: "write";
+        }>>;
+        status: z.ZodLiteral<"unavailable">;
+        reason: z.ZodLiteral<"path_unavailable">;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>, z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    runtime_id: z.ZodString;
+    snapshot_id: z.ZodString;
+    authorization: z.ZodLiteral<"none">;
+    status: z.ZodLiteral<"unavailable">;
+    reason: z.ZodLiteral<"context_unavailable">;
+    resources: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodEnum<{
+            memory: "memory";
+            scratch: "scratch";
+        }>;
+        scope: z.ZodEnum<{
+            shared: "shared";
+            session: "session";
+        }>;
+        lifetime: z.ZodEnum<{
+            persistent: "persistent";
+            temporary: "temporary";
+        }>;
+        supported_operations: z.ZodArray<z.ZodEnum<{
+            read: "read";
+            write: "write";
+        }>>;
+        status: z.ZodLiteral<"available">;
+        path: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodEnum<{
+            memory: "memory";
+            scratch: "scratch";
+        }>;
+        scope: z.ZodEnum<{
+            shared: "shared";
+            session: "session";
+        }>;
+        lifetime: z.ZodEnum<{
+            persistent: "persistent";
+            temporary: "temporary";
+        }>;
+        supported_operations: z.ZodArray<z.ZodEnum<{
+            read: "read";
+            write: "write";
+        }>>;
+        status: z.ZodLiteral<"disabled">;
+        reason: z.ZodLiteral<"feature_disabled">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodEnum<{
+            memory: "memory";
+            scratch: "scratch";
+        }>;
+        scope: z.ZodEnum<{
+            shared: "shared";
+            session: "session";
+        }>;
+        lifetime: z.ZodEnum<{
+            persistent: "persistent";
+            temporary: "temporary";
+        }>;
+        supported_operations: z.ZodArray<z.ZodEnum<{
+            read: "read";
+            write: "write";
+        }>>;
+        status: z.ZodLiteral<"unavailable">;
+        reason: z.ZodLiteral<"path_unavailable">;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>]>;
+export type RuntimeResource = z.infer<typeof RuntimeResourceSchema>;
+export type RuntimeResources = z.infer<typeof RuntimeResourcesSchema>;

package/dist/sdk/runtimeResources.js

@@ -0,0 +1,36 @@
+import { z } from 'zod/v4';
+const descriptor = z.object({
+    kind: z.enum(['memory', 'scratch']),
+    scope: z.enum(['shared', 'session']),
+    lifetime: z.enum(['persistent', 'temporary']),
+    // Supported file operations, NEVER an authorization decision.
+    supported_operations: z.array(z.enum(['read', 'write'])),
+});
+export const RuntimeResourceSchema = z.discriminatedUnion('status', [
+    descriptor.extend({ status: z.literal('available'), path: z.string().min(1) }),
+    descriptor.extend({ status: z.literal('disabled'), reason: z.literal('feature_disabled') }),
+    descriptor.extend({ status: z.literal('unavailable'), reason: z.literal('path_unavailable') }),
+]);
+const envelope = z.object({
+    schema_version: z.literal(1),
+    runtime_id: z.string().min(1),
+    snapshot_id: z.string().min(1),
+    authorization: z.literal('none'),
+});
+/** Trusted connection metadata, not a permission grant or authenticated account ID. */
+export const RuntimeResourcesSchema = z.discriminatedUnion('status', [
+    envelope.extend({
+        status: z.literal('available'),
+        context_id: z.string().min(1),
+        session_id: z.string().min(1),
+        project_root: z.string().min(1),
+        original_cwd: z.string().min(1),
+        cwd: z.string().min(1),
+        resources: z.array(RuntimeResourceSchema),
+    }),
+    envelope.extend({
+        status: z.literal('unavailable'),
+        reason: z.literal('context_unavailable'),
+        resources: z.array(RuntimeResourceSchema).length(0),
+    }),
+]);

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

@@ -17,6 +17,7 @@ export interface Turn {
     readonly result: Promise<TurnResult>;
     cancel(): Promise<void>;
 }
+export type InputMetadata = Pick<SDKUserMessage, 'isSynthetic' | 'input_provenance'>;
 /** One CLI process, sequential turns, and a bounded host-side input queue. */
 export declare class Session {
     readonly pid: number | undefined;
@@ -34,10 +35,10 @@ export declare class Session {
     private readonly pumping;
     private sessionId?;
     constructor(options?: SessionOptions, transport?: Transport);
-    prompt(content: SDKUserMessage['message']['content']): Turn;
-    followUp(content: SDKUserMessage['message']['content']): Turn;
+    prompt(content: SDKUserMessage['message']['content'], metadata?: InputMetadata): Turn;
+    followUp(content: SDKUserMessage['message']['content'], metadata?: InputMetadata): Turn;
     /** Interrupt the active turn; correction runs before queued follow-ups. */
-    steer(content: SDKUserMessage['message']['content']): Turn;
+    steer(content: SDKUserMessage['message']['content'], metadata?: InputMetadata): Turn;
     private enqueue;
     private inputs;
     private consume;

package/dist/sdk/session.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { queryHandleWithTransport } from './queryHandle.js';
 import { spawnForOptions } from './query.js';
+import { normalizeUserInput } from './queryInput.js';
 /** One CLI process, sequential turns, and a bounded host-side input queue. */
 export class Session {
     pid;
@@ -28,37 +29,40 @@ export class Session {
         this.sessionId = options.sessionId ?? options.resume;
         const owned = transport ?? spawnForOptions(options);
         this.pid = owned.pid;
+        const transportWithLifecycle = { ...owned, write: async (message) => {
+                await owned.write(message);
+                if (message.type === 'user' && this.active && !this.active.started) {
+                    this.active.started = true;
+                    this.observe({ type: 'turn_started', turnId: this.active.turn.id });
+                }
+            } };
         this.handle = queryHandleWithTransport(this.inputs(), { ...options, hooks: {
                 ...options.hooks,
                 onUserPromptSubmit: async (event) => {
-                    if (this.active && !this.active.started) {
-                        this.active.started = true;
-                        this.observe({ type: 'turn_started', turnId: this.active.turn.id });
-                    }
                     await options.hooks?.onUserPromptSubmit?.(event);
                 },
                 onSessionStart: async (event) => {
                     this.sessionId = event.sessionId;
                     await options.hooks?.onSessionStart?.(event);
                 },
-            } }, owned);
+            } }, transportWithLifecycle);
         this.controls = this.handle;
         this.pumping = this.consume();
     }
-    prompt(content) {
-        return this.enqueue(content, false);
+    prompt(content, metadata = {}) {
+        return this.enqueue(content, false, metadata);
     }
-    followUp(content) {
-        return this.enqueue(content, false);
+    followUp(content, metadata = {}) {
+        return this.enqueue(content, false, metadata);
     }
     /** Interrupt the active turn; correction runs before queued follow-ups. */
-    steer(content) {
-        const turn = this.enqueue(content, true);
+    steer(content, metadata = {}) {
+        const turn = this.enqueue(content, true, metadata);
         if (this.active)
             void this.interrupt().catch(error => this.fail(error));
         return turn;
     }
-    enqueue(content, priority) {
+    enqueue(content, priority, metadata) {
         if (!this.accepting || this.closed)
             throw new Error('ccl-sdk: session input is closed');
         if (this.queue.length + (this.active ? 1 : 0) >= this.limit) {
@@ -71,9 +75,10 @@ export class Session {
         // It is valid to enqueue follow-ups and observe their results later.
         void result.catch(() => { });
         const turn = { id, result, cancel: () => this.cancel(id) };
-        const entry = { turn, resolve, reject, input: {
+        const entry = { turn, resolve, reject, input: normalizeUserInput({
                 type: 'user', uuid: id, message: { role: 'user', content },
-            } };
+                isSynthetic: metadata.isSynthetic, input_provenance: metadata.input_provenance,
+            }) };
         if (priority)
             this.queue.unshift(entry);
         else