@roackb2/heddle 0.0.7 → 0.0.9

package/dist/examples/host-events.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+/**
+ * Host Events Example
+ *
+ * Demonstrates how to consume Heddle's structured event stream for:
+ * - Real-time progress monitoring
+ * - Tool execution tracking
+ * - Checkpoint persistence
+ * - Escalation routing (for CyberLoop/Lucid integration)
+ *
+ * Usage:
+ *   HEDDLE_EXAMPLE_MODEL=gpt-5.1-codex-mini npx tsx examples/host-events.ts
+ */
+import { runAgentLoop, runAgentHeartbeat } from '../src/index.js';
+// ---------------------------------------------------------------------------
+// Mock LLM for demo purposes (replace with real LLM in production)
+// ---------------------------------------------------------------------------
+const createMockLlm = (scenario) => {
+    let turn = 0;
+    return {
+        info: {
+            provider: 'openai',
+            model: 'gpt-demo',
+            capabilities: {
+                toolCalls: true,
+                systemMessages: true,
+                reasoningSummaries: false,
+                parallelToolCalls: true,
+            },
+        },
+        async chat(messages) {
+            turn++;
+            if (scenario === 'success') {
+                return { content: `Demo response turn ${turn}` };
+            }
+            if (scenario === 'tool-use' && turn === 1) {
+                return {
+                    content: 'Using echo tool.',
+                    toolCalls: [{ id: `call-${turn}`, tool: 'echo', input: { message: 'hello' } }],
+                };
+            }
+            if (scenario === 'escalate') {
+                return {
+                    content: 'Blocked by policy and need human input.\n\nHEARTBEAT_DECISION: escalate',
+                };
+            }
+            return { content: `Turn ${turn} complete.` };
+        },
+    };
+};
+// ---------------------------------------------------------------------------
+// Example tools
+// ---------------------------------------------------------------------------
+const echoTool = {
+    name: 'echo',
+    description: 'Echoes input back',
+    parameters: {
+        type: 'object',
+        properties: { message: { type: 'string' } },
+        required: ['message'],
+    },
+    async execute(input) {
+        return { ok: true, output: input };
+    },
+};
+// ---------------------------------------------------------------------------
+// Structured event logger - demonstrates host-facing event consumption
+// ---------------------------------------------------------------------------
+class StructuredEventLogger {
+    runId = null;
+    events = [];
+    onEvent(event) {
+        this.events.push(event);
+        // Capture runId from first event for correlation
+        if (!this.runId && 'runId' in event) {
+            this.runId = event.runId;
+            console.log(`\n📋 Run started: ${this.runId}`);
+            console.log('='.repeat(60));
+        }
+        switch (event.type) {
+            case 'loop.started':
+                console.log(`\n🚀 Loop started`);
+                console.log(`   Goal: ${event.goal}`);
+                console.log(`   Model: ${event.model} (${event.provider})`);
+                if (event.resumedFromCheckpoint) {
+                    console.log(`   Resumed from: ${event.resumedFromCheckpoint}`);
+                }
+                break;
+            case 'loop.resumed':
+                console.log(`\n🔄 Resuming from checkpoint: ${event.fromCheckpoint}`);
+                console.log(`   Prior trace events: ${event.priorTraceEvents}`);
+                break;
+            case 'assistant.stream':
+                // Debounce stream events for cleaner output
+                if (event.done) {
+                    console.log(`\n💬 Assistant [step ${event.step}]: "${event.text.slice(0, 60)}..."`);
+                }
+                break;
+            case 'tool.calling':
+                console.log(`\n🔧 Tool calling [step ${event.step}]: ${event.tool}`);
+                console.log(`   ToolCall ID: ${event.toolCallId}`);
+                console.log(`   Requires approval: ${event.requiresApproval}`);
+                break;
+            case 'tool.completed':
+                console.log(`\n✅ Tool completed [step ${event.step}]: ${event.tool}`);
+                console.log(`   Duration: ${event.durationMs}ms`);
+                console.log(`   Result: ${event.result.ok ? 'success' : 'failed'}`);
+                if (!event.result.ok && event.result.error) {
+                    console.log(`   Error: ${event.result.error}`);
+                }
+                break;
+            case 'trace':
+                // Trace events are verbose - log only important ones
+                if (event.event.type === 'run.finished') {
+                    console.log(`\n🏁 Trace: run finished (${event.event.outcome})`);
+                }
+                break;
+            case 'checkpoint.saved':
+                console.log(`\n💾 Checkpoint saved [step ${event.step}]`);
+                console.log(`   Checkpoint run: ${event.checkpoint.runId}`);
+                console.log(`   Created at: ${event.checkpoint.createdAt}`);
+                break;
+            case 'heartbeat.decision':
+                console.log(`\n💓 Heartbeat decision: ${event.decision}`);
+                console.log(`   Outcome: ${event.outcome}`);
+                console.log(`   Summary: ${event.summary.slice(0, 80)}...`);
+                break;
+            case 'escalation.required':
+                console.log(`\n🚨 ESCALATION REQUIRED [step ${event.step}]`);
+                console.log(`   Task: ${event.task}`);
+                console.log(`   Outcome: ${event.outcome}`);
+                console.log(`   Summary: ${event.summary.slice(0, 100)}...`);
+                break;
+            case 'loop.finished':
+                console.log(`\n✨ Loop finished`);
+                console.log(`   Outcome: ${event.outcome}`);
+                console.log(`   Summary: ${event.summary.slice(0, 80)}...`);
+                console.log(`   Total steps: ${event.state.trace.length}`);
+                console.log(`   Usage: ${JSON.stringify(event.state.usage)}`);
+                console.log('\n' + '='.repeat(60));
+                break;
+        }
+    }
+    getStats() {
+        return {
+            totalEvents: this.events.length,
+            toolCalls: this.events.filter((e) => e.type === 'tool.calling').length,
+            checkpoints: this.events.filter((e) => e.type === 'checkpoint.saved').length,
+            escalations: this.events.filter((e) => e.type === 'escalation.required').length,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Example: Basic run with event logging
+// ---------------------------------------------------------------------------
+async function exampleBasicRun() {
+    console.log('\n' + '#'.repeat(60));
+    console.log('# Example 1: Basic Run with Event Logging');
+    console.log('#'.repeat(60));
+    const logger = new StructuredEventLogger();
+    await runAgentLoop({
+        goal: 'Simple demo task',
+        llm: createMockLlm('success'),
+        tools: [],
+        includeDefaultTools: false,
+        maxSteps: 2,
+        onEvent: (event) => logger.onEvent(event),
+    });
+    console.log('\n📊 Stats:', logger.getStats());
+}
+// ---------------------------------------------------------------------------
+// Example: Tool execution tracking
+// ---------------------------------------------------------------------------
+async function exampleToolTracking() {
+    console.log('\n' + '#'.repeat(60));
+    console.log('# Example 2: Tool Execution Tracking');
+    console.log('#'.repeat(60));
+    const logger = new StructuredEventLogger();
+    await runAgentLoop({
+        goal: 'Use echo tool',
+        llm: createMockLlm('tool-use'),
+        tools: [echoTool],
+        includeDefaultTools: false,
+        maxSteps: 2,
+        onEvent: (event) => logger.onEvent(event),
+    });
+    console.log('\n📊 Stats:', logger.getStats());
+}
+// ---------------------------------------------------------------------------
+// Example: Heartbeat with escalation
+// ---------------------------------------------------------------------------
+async function exampleHeartbeatEscalation() {
+    console.log('\n' + '#'.repeat(60));
+    console.log('# Example 3: Heartbeat with Escalation Routing');
+    console.log('#'.repeat(60));
+    const logger = new StructuredEventLogger();
+    const result = await runAgentHeartbeat({
+        task: 'Background maintenance task',
+        llm: createMockLlm('escalate'),
+        tools: [],
+        includeDefaultTools: false,
+        maxSteps: 2,
+        onEvent: (event) => logger.onEvent(event),
+    });
+    console.log('\n📊 Stats:', logger.getStats());
+    console.log('\n📋 Heartbeat Result:');
+    console.log(`   Decision: ${result.decision}`);
+    console.log(`   Checkpoint ID: ${result.checkpoint.runId}`);
+    // Demonstrate how Lucid/CyberLoop would route escalation
+    if (result.decision === 'escalate') {
+        console.log('\n🎯 Integration example:');
+        console.log('   - Lucid would route to operator channel');
+        console.log('   - CyberLoop would annotate drift in middleware');
+    }
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    console.log('Heddle Host Events Example');
+    console.log('Shows structured event consumption for external integration\n');
+    await exampleBasicRun();
+    await exampleToolTracking();
+    await exampleHeartbeatEscalation();
+    console.log('\n' + '#'.repeat(60));
+    console.log('# All examples completed successfully');
+    console.log('#'.repeat(60));
+}
+main().catch((error) => {
+    console.error('Error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=host-events.js.map

package/dist/examples/host-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-events.js","sourceRoot":"","sources":["../../examples/host-events.ts"],"names":[],"mappings":"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"}

package/dist/examples/programmatic-loop.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=programmatic-loop.d.ts.map

package/dist/examples/programmatic-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"programmatic-loop.d.ts","sourceRoot":"","sources":["../../examples/programmatic-loop.ts"],"names":[],"mappings":""}

package/dist/examples/programmatic-loop.js

@@ -0,0 +1,128 @@
+// ---------------------------------------------------------------------------
+// Example: Programmatic Loop
+//
+// Usage:
+//   OPENAI_API_KEY=sk-... yarn example:programmatic
+//
+// Optional:
+//   HEDDLE_EXAMPLE_MODEL=claude-3-5-haiku-latest ANTHROPIC_API_KEY=sk-ant-... yarn example:programmatic
+//
+// This example uses a real LLM plus one custom host tool. It demonstrates how
+// another app can embed Heddle as an evented execution loop without going
+// through the terminal chat UI.
+//
+// For a no-key test of this API, see src/__tests__/agent-loop.test.ts.
+// ---------------------------------------------------------------------------
+import { runAgentLoop } from '../src/runtime/agent-loop.js';
+import { createAgentLoopCheckpoint } from '../src/runtime/events.js';
+import { resolveProviderApiKey } from '../src/runtime/api-keys.js';
+import { inferProviderFromModel } from '../src/llm/providers.js';
+const DEFAULT_EXAMPLE_MODEL = 'gpt-5.1-codex-mini';
+const echoTool = {
+    name: 'echo_context',
+    description: 'Echoes a small piece of host-provided context.',
+    parameters: {
+        type: 'object',
+        properties: {
+            topic: { type: 'string' },
+        },
+        required: ['topic'],
+        additionalProperties: false,
+    },
+    async execute(input) {
+        return {
+            ok: true,
+            output: {
+                input,
+                note: 'This result came from a custom host tool.',
+            },
+        };
+    },
+};
+async function main() {
+    const model = process.env.HEDDLE_EXAMPLE_MODEL ?? process.env.OPENAI_MODEL ?? DEFAULT_EXAMPLE_MODEL;
+    const provider = inferProviderFromModel(model);
+    const apiKey = resolveProviderApiKey(provider);
+    if (!apiKey) {
+        throw new Error(`Missing API key for ${provider}. ` +
+            'Set OPENAI_API_KEY for OpenAI models or ANTHROPIC_API_KEY for Claude models before running this example.');
+    }
+    const result = await runAgentLoop({
+        goal: 'Use the echo_context tool once, then explain in two short sentences how another app can embed Heddle as a programmatic agent loop.',
+        model,
+        apiKey,
+        tools: [echoTool],
+        includeDefaultTools: false,
+        maxSteps: 3,
+        onEvent(event) {
+            const line = formatExampleEvent(event);
+            if (line) {
+                console.log(line);
+            }
+        },
+    });
+    console.log('\nFinal answer:\n');
+    console.log(result.summary);
+    const checkpoint = createAgentLoopCheckpoint(result.state);
+    console.log('\nCheckpoint preview:\n');
+    console.log(JSON.stringify({
+        version: checkpoint.version,
+        model: checkpoint.state.model,
+        outcome: checkpoint.state.outcome,
+        transcriptMessages: checkpoint.state.transcript.length,
+        traceEvents: checkpoint.state.trace.length,
+    }, null, 2));
+    process.exit(0);
+}
+function formatExampleEvent(event) {
+    switch (event.type) {
+        case 'loop.started':
+            return `[event] loop.started model=${event.model} provider=${event.provider} workspace=${event.workspaceRoot}`;
+        case 'assistant.stream':
+            return event.done ? `[event] assistant.stream.done chars=${event.text.length} step=${event.step}` : undefined;
+        case 'loop.finished':
+            return `[event] loop.finished outcome=${event.outcome} transcript=${event.state.transcript.length} trace=${event.state.trace.length} input=${event.usage?.inputTokens ?? 0} output=${event.usage?.outputTokens ?? 0} total=${event.usage?.totalTokens ?? 0}`;
+        case 'trace':
+            return formatTraceEvent(event.event);
+    }
+}
+function formatTraceEvent(event) {
+    switch (event.type) {
+        case 'run.started':
+            return `[trace] run.started goal=${JSON.stringify(shorten(event.goal))}`;
+        case 'assistant.turn':
+            return `[trace] assistant.turn step=${event.step} tools=${event.requestedTools ? event.toolCalls?.map((call) => call.tool).join(',') || 'yes' : 'none'} content=${JSON.stringify(shorten(event.content))}`;
+        case 'tool.approval_requested':
+            return `[trace] tool.approval_requested step=${event.step} tool=${event.call.tool}`;
+        case 'tool.approval_resolved':
+            return `[trace] tool.approval_resolved step=${event.step} tool=${event.call.tool} approved=${event.approved}`;
+        case 'tool.fallback':
+            return `[trace] tool.fallback step=${event.step} from=${event.fromCall.tool} to=${event.toCall.tool} reason=${JSON.stringify(shorten(event.reason))}`;
+        case 'tool.call':
+            return `[trace] tool.call step=${event.step} tool=${event.call.tool} input=${JSON.stringify(event.call.input)}`;
+        case 'tool.result':
+            return `[trace] tool.result step=${event.step} tool=${event.tool} ok=${event.result.ok} output=${JSON.stringify(formatUnknown(event.result.output ?? event.result.error ?? ''))}`;
+        case 'cyberloop.annotation':
+            return `[trace] cyberloop.annotation step=${event.step} frame=${event.frameKind} drift=${event.driftLevel}`;
+        case 'run.finished':
+            return `[trace] run.finished step=${event.step} outcome=${event.outcome} summary=${JSON.stringify(shorten(event.summary))}`;
+    }
+}
+function shorten(value, maxLength = 96) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    if (normalized.length <= maxLength) {
+        return normalized;
+    }
+    return `${normalized.slice(0, maxLength - 1)}…`;
+}
+function formatUnknown(value) {
+    if (typeof value === 'string') {
+        return shorten(value);
+    }
+    return shorten(JSON.stringify(value));
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});
+//# sourceMappingURL=programmatic-loop.js.map

package/dist/examples/programmatic-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"programmatic-loop.js","sourceRoot":"","sources":["../../examples/programmatic-loop.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/ask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../../src/cli/ask.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,iBAoDxE"}
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../../src/cli/ask.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,iBAiCxE"}

package/dist/src/cli/ask.js

@@ -1,6 +1,6 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { DEFAULT_OPENAI_MODEL, runAgent, createLlmAdapter, inferProviderFromModel, listFilesTool, readFileTool, editFileTool, createSearchFilesTool, createWebSearchTool, createViewImageTool, createListMemoryNotesTool, createReadMemoryNoteTool, createSearchMemoryNotesTool, createEditMemoryNoteTool, reportStateTool, createRunShellInspectTool, createRunShellMutateTool, formatTraceForConsole, createLogger, } from '../index.js';
+import { DEFAULT_OPENAI_MODEL, inferProviderFromModel, runAgentLoop, formatTraceForConsole, createLogger, resolveProviderApiKey, } from '../index.js';
 export async function runAskCli(goal, options = {}) {
     if (!goal.trim()) {
         throw new Error('Usage: heddle ask "<goal>"');
@@ -12,36 +12,18 @@ export async function runAskCli(goal, options = {}) {
     const logger = createLogger({ pretty: true, level: 'debug' });
     const provider = inferProviderFromModel(model);
     logger.info({ goal, model, provider, maxSteps, cwd: workspaceRoot }, 'Heddle');
-    const llm = createLlmAdapter({
+    const result = await runAgentLoop({
+        goal,
         model,
         apiKey: options.apiKey ?? resolveProviderApiKey(provider),
+        maxSteps,
+        logger,
+        workspaceRoot,
+        stateDir: options.stateDir,
+        searchIgnoreDirs: options.searchIgnoreDirs,
+        systemContext: options.systemContext,
+        includePlanTool: false,
     });
-    const webSearchTool = createWebSearchTool({
-        model,
-        provider,
-        apiKey: options.apiKey ?? resolveProviderApiKey(provider),
-    });
-    const viewImageTool = createViewImageTool({
-        model,
-        provider,
-        apiKey: options.apiKey ?? resolveProviderApiKey(provider),
-    });
-    const tools = [
-        listFilesTool,
-        readFileTool,
-        editFileTool,
-        createSearchFilesTool({ excludedDirs: options.searchIgnoreDirs }),
-        webSearchTool,
-        viewImageTool,
-        createListMemoryNotesTool({ memoryRoot: join(stateRoot, 'memory') }),
-        createReadMemoryNoteTool({ memoryRoot: join(stateRoot, 'memory') }),
-        createSearchMemoryNotesTool({ memoryRoot: join(stateRoot, 'memory') }),
-        createEditMemoryNoteTool({ memoryRoot: join(stateRoot, 'memory') }),
-        reportStateTool,
-        createRunShellInspectTool(),
-        createRunShellMutateTool(),
-    ];
-    const result = await runAgent({ goal, llm, tools, maxSteps, logger, systemContext: options.systemContext });
     process.stdout.write(`${formatTraceForConsole(result.trace)}\n`);
     const traceDir = join(stateRoot, 'traces');
     mkdirSync(traceDir, { recursive: true });
@@ -59,17 +41,4 @@ function parsePositiveInt(raw) {
     }
     return value;
 }
-function resolveProviderApiKey(provider) {
-    switch (provider) {
-        case 'openai':
-            return firstDefinedNonEmpty(process.env.OPENAI_API_KEY, process.env.PERSONAL_OPENAI_API_KEY);
-        case 'anthropic':
-            return firstDefinedNonEmpty(process.env.ANTHROPIC_API_KEY, process.env.PERSONAL_ANTHROPIC_API_KEY);
-        case 'google':
-            return undefined;
-    }
-}
-function firstDefinedNonEmpty(...values) {
-    return values.find((value) => typeof value === 'string' && value.trim().length > 0);
-}
 //# sourceMappingURL=ask.js.map

package/dist/src/cli/ask.js.map

@@ -1 +1 @@
-{"version":3,"file":"ask.js","sourceRoot":"","sources":["../../../src/cli/ask.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ask.js","sourceRoot":"","sources":["../../../src/cli/ask.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,EACZ,qBAAqB,EACrB,YAAY,EACZ,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAYrB,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAY,EAAE,UAAyB,EAAE;IACvE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,oBAAoB,CAAC;IAC/G,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC;IAC1F,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC7D,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,QAAQ,IAAI,SAAS,CAAC,CAAC;IACrE,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9D,MAAM,QAAQ,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;IAE/C,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,aAAa,EAAE,EAAE,QAAQ,CAAC,CAAC;IAE/E,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;QAChC,IAAI;QACJ,KAAK;QACL,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,qBAAqB,CAAC,QAAQ,CAAC;QACzD,QAAQ;QACR,MAAM;QACN,aAAa;QACb,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,eAAe,EAAE,KAAK;KACvB,CAAC,CAAC;IACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,qBAAqB,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEjE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC3C,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC7D,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAChE,MAAM,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,EAAE,aAAa,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAuB;IAC/C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1C,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/cli/chat/App.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"App.d.ts","sourceRoot":"","sources":["../../../../src/cli/chat/App.tsx"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAI5D,wBAAgB,GAAG,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,iBAAiB,CAAA;CAAE,2CA4d9D"}
+{"version":3,"file":"App.d.ts","sourceRoot":"","sources":["../../../../src/cli/chat/App.tsx"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAI5D,wBAAgB,GAAG,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,iBAAiB,CAAA;CAAE,2CAygB9D"}

package/dist/src/cli/chat/App.js

@@ -16,6 +16,9 @@ export function App({ runtime }) {
     const [draft, setDraft] = useState('');
     const [draftCursor, setDraftCursor] = useState(0);
     const [pendingSubmittedPrompt, setPendingSubmittedPrompt] = useState();
+    const [driftEnabled, setDriftEnabledState] = useState(false);
+    const [driftLevel, setDriftLevel] = useState('unknown');
+    const [driftError, setDriftError] = useState();
     const [modelPickerIndex, setModelPickerIndex] = useState(0);
     const [sessionPickerIndex, setSessionPickerIndex] = useState(0);
     const [fileMentionPickerIndex, setFileMentionPickerIndex] = useState(0);
@@ -57,6 +60,15 @@ export function App({ runtime }) {
             setActiveModel(sessionModel);
         }
     }, [activeModel, activeSession, runtime.model]);
+    useEffect(() => {
+        if (!activeSession) {
+            return;
+        }
+        const sessionDriftEnabled = activeSession.driftEnabled ?? false;
+        if (sessionDriftEnabled !== driftEnabled) {
+            setDriftEnabledState(sessionDriftEnabled);
+        }
+    }, [activeSession, driftEnabled]);
     const { status, setStatus, isRunning, error, setError, liveEvents, workingFrame, elapsedSeconds, pendingApproval, approvalChoice, interruptRequested, currentAssistantText, currentPlan, setLiveEvents, resetRunState, actionState, workingFrames, } = useApprovalFlow(nextLocalId);
     const messages = activeSession?.messages ?? [];
     const activityText = currentActivityText(liveEvents, isRunning, elapsedSeconds, pendingApproval, interruptRequested);
@@ -64,6 +76,7 @@ export function App({ runtime }) {
     const promptStatusLine = [
         `model=${activeModel}`,
         contextStatus,
+        `drift=${formatDriftFooter(driftEnabled, driftLevel, driftError)}`,
         `session=${activeSession?.id ?? activeSessionId}${activeSession?.name ? ` (${activeSession.name})` : ''}`,
     ].join(' • ');
     const activityLines = liveEvents
@@ -100,6 +113,14 @@ export function App({ runtime }) {
             setSessionModel(activeSession.id, model);
         }
     };
+    const applyDriftEnabled = useCallback((enabled) => {
+        setDriftEnabledState(enabled);
+        setDriftError(undefined);
+        updateActiveSession((session) => ({
+            ...session,
+            driftEnabled: enabled,
+        }));
+    }, [updateActiveSession]);
     const closeSession = (id) => {
         const removedActive = removeSession(id);
         if (removedActive) {
@@ -130,6 +151,15 @@ export function App({ runtime }) {
         state: actionState,
         updateSessionById,
         updateActiveSession,
+        drift: {
+            enabled: driftEnabled,
+            onRunStart: () => {
+                setDriftLevel('unknown');
+                setDriftError(undefined);
+            },
+            onAnnotation: (annotation) => setDriftLevel(annotation.driftLevel),
+            onError: (error) => setDriftError(error instanceof Error ? error.message : String(error)),
+        },
     });
     const submitPrompt = useCallback(async (value, options) => {
         const effectiveIsRunning = options?.allowWhileRunning ? false : isRunning;
@@ -173,6 +203,9 @@ export function App({ runtime }) {
                 createSession,
                 renameSession,
                 listRecentSessionsMessage,
+                driftEnabled,
+                driftError,
+                setDriftEnabled: applyDriftEnabled,
                 preparePrompt: preparePromptWithMentions,
                 executeTurn,
                 executeDirectShellCommand,
@@ -202,6 +235,9 @@ export function App({ runtime }) {
                 createSession,
                 renameSession,
                 listRecentSessionsMessage,
+                driftEnabled,
+                driftError,
+                setDriftEnabled: applyDriftEnabled,
                 preparePrompt: preparePromptWithMentions,
                 executeTurn,
                 executeDirectShellCommand,
@@ -237,6 +273,9 @@ export function App({ runtime }) {
             createSession,
             renameSession,
             listRecentSessionsMessage,
+            driftEnabled,
+            driftError,
+            setDriftEnabled: applyDriftEnabled,
             preparePrompt: preparePromptWithMentions,
             executeTurn,
             executeDirectShellCommand,
@@ -262,6 +301,9 @@ export function App({ runtime }) {
         createSession,
         renameSession,
         listRecentSessionsMessage,
+        driftEnabled,
+        driftError,
+        applyDriftEnabled,
         executeTurn,
         executeDirectShellCommand,
         appendPendingUserMessage,
@@ -342,6 +384,12 @@ export function App({ runtime }) {
                                                 : isRunning ? `${elapsedSeconds}s elapsed`
                                                     : '' })] })] })] }), _jsx(Text, { dimColor: true, children: promptStatusLine })] }));
 }
+function formatDriftFooter(enabled, level, error) {
+    if (!enabled) {
+        return 'off';
+    }
+    return error ? 'unavailable' : level;
+}
 function getModelPickerQuery(draft) {
     const trimmedStart = draft.trimStart();
     if (!trimmedStart.startsWith('/model set')) {