@roackb2/heddle 0.0.7 → 0.0.9

package/dist/src/runtime/agent-loop.js

@@ -0,0 +1,173 @@
+import { resolve } from 'node:path';
+import { DEFAULT_OPENAI_MODEL } from '../config.js';
+import { inferProviderFromModel } from '../llm/providers.js';
+import { runAgent } from '../run-agent.js';
+import { createLogger } from '../utils/logger.js';
+import { resolveApiKeyForModel } from './api-keys.js';
+import { createFinishedAgentLoopState, generateRunId, getHistoryFromAgentLoopCheckpoint, getHistoryFromAgentLoopState } from './events.js';
+export async function runAgentLoop(options) {
+    const runId = generateRunId();
+    const model = options.model ?? options.llm?.info?.model ?? process.env.OPENAI_MODEL ?? process.env.ANTHROPIC_MODEL ?? DEFAULT_OPENAI_MODEL;
+    const provider = inferProviderFromModel(model);
+    const workspaceRoot = resolve(options.workspaceRoot ?? process.cwd());
+    const apiKey = options.apiKey ?? resolveApiKeyForModel(model);
+    const llm = options.llm ?? await createLoopLlmAdapter({ model, apiKey });
+    const logger = options.logger ?? createLogger({ pretty: false, level: 'info', console: false });
+    const tools = await resolveTools({
+        ...options,
+        model,
+        apiKey,
+        workspaceRoot,
+    });
+    const now = () => new Date().toISOString();
+    const startedAt = now();
+    const resumeMetadata = getResumeMetadata(options.resumeFrom);
+    options.onEvent?.({
+        type: 'loop.started',
+        runId,
+        goal: options.goal,
+        model,
+        provider,
+        workspaceRoot,
+        resumedFromCheckpoint: resumeMetadata?.checkpointRunId,
+        timestamp: startedAt,
+    });
+    if (resumeMetadata) {
+        options.onEvent?.({
+            type: 'loop.resumed',
+            runId,
+            fromCheckpoint: resumeMetadata.checkpointRunId,
+            priorTraceEvents: resumeMetadata.priorTraceEvents,
+            timestamp: now(),
+        });
+    }
+    const result = await runAgent({
+        goal: options.goal,
+        llm,
+        tools,
+        maxSteps: options.maxSteps,
+        logger,
+        history: resolveHistory(options),
+        systemContext: options.systemContext,
+        onAssistantStream: (update) => {
+            options.onEvent?.({
+                type: 'assistant.stream',
+                runId,
+                ...update,
+                timestamp: now(),
+            });
+            options.onAssistantStream?.(update);
+        },
+        onEvent: (event) => {
+            options.onEvent?.({ type: 'trace', runId, event, timestamp: now() });
+            options.onTraceEvent?.(event);
+        },
+        onToolCalling: (call, step, toolDef) => {
+            options.onEvent?.({
+                type: 'tool.calling',
+                runId,
+                step,
+                tool: call.tool,
+                toolCallId: call.id,
+                input: call.input,
+                requiresApproval: toolDef.requiresApproval ?? false,
+                timestamp: now(),
+            });
+        },
+        onToolCompleted: (call, result, step, durationMs) => {
+            options.onEvent?.({
+                type: 'tool.completed',
+                runId,
+                step,
+                tool: call.tool,
+                toolCallId: call.id,
+                result: { ok: result.ok, output: result.output, error: result.error },
+                durationMs,
+                timestamp: now(),
+            });
+        },
+        approveToolCall: options.approveToolCall,
+        shouldStop: options.shouldStop,
+        abortSignal: options.abortSignal,
+    });
+    const finishedAt = now();
+    const state = createFinishedAgentLoopState({
+        runId,
+        goal: options.goal,
+        model,
+        provider,
+        workspaceRoot,
+        startedAt,
+        finishedAt,
+        result,
+    });
+    options.onEvent?.({
+        type: 'loop.finished',
+        runId,
+        outcome: result.outcome,
+        summary: result.summary,
+        usage: result.usage,
+        state,
+        timestamp: finishedAt,
+    });
+    return {
+        ...result,
+        model,
+        provider,
+        workspaceRoot,
+        state,
+    };
+}
+function resolveHistory(options) {
+    if (options.history) {
+        return options.history;
+    }
+    if (!options.resumeFrom) {
+        return undefined;
+    }
+    if ('version' in options.resumeFrom) {
+        return getHistoryFromAgentLoopCheckpoint(options.resumeFrom);
+    }
+    return getHistoryFromAgentLoopState(options.resumeFrom);
+}
+function getResumeMetadata(resumeFrom) {
+    if (!resumeFrom) {
+        return undefined;
+    }
+    if ('version' in resumeFrom) {
+        return {
+            checkpointRunId: resumeFrom.runId,
+            priorTraceEvents: resumeFrom.state.trace.length,
+        };
+    }
+    return {
+        checkpointRunId: resumeFrom.runId,
+        priorTraceEvents: resumeFrom.trace.length,
+    };
+}
+async function createLoopLlmAdapter(options) {
+    const { createLlmAdapter } = await import('../llm/factory.js');
+    return createLlmAdapter(options);
+}
+async function resolveTools(options) {
+    const providedTools = options.tools ?? [];
+    const extraTools = options.extraTools ?? [];
+    if (options.includeDefaultTools === false) {
+        return [...providedTools, ...extraTools];
+    }
+    const { createDefaultAgentTools } = await import('./default-tools.js');
+    return [
+        ...createDefaultAgentTools({
+            model: options.model,
+            apiKey: options.apiKey,
+            workspaceRoot: options.workspaceRoot,
+            stateDir: options.stateDir,
+            memoryDir: options.memoryDir,
+            searchIgnoreDirs: options.searchIgnoreDirs,
+            includePlanTool: options.includePlanTool,
+        }),
+        ...providedTools,
+        ...extraTools,
+    ];
+}
+//# sourceMappingURL=agent-loop.js.map

package/dist/src/runtime/agent-loop.js.map

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

package/dist/src/runtime/api-keys.d.ts

@@ -0,0 +1,8 @@
+import type { LlmProvider } from '../llm/types.js';
+export type ApiKeyRuntime = {
+    apiKey?: string;
+    apiKeyProvider?: LlmProvider | 'explicit';
+};
+export declare function resolveProviderApiKey(provider: LlmProvider): string | undefined;
+export declare function resolveApiKeyForModel(model: string, runtime?: ApiKeyRuntime): string | undefined;
+//# sourceMappingURL=api-keys.d.ts.map

package/dist/src/runtime/api-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.d.ts","sourceRoot":"","sources":["../../../src/runtime/api-keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,WAAW,GAAG,UAAU,CAAC;CAC3C,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAS/E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAWhG"}

package/dist/src/runtime/api-keys.js

@@ -0,0 +1,25 @@
+import { inferProviderFromModel } from '../llm/providers.js';
+export 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;
+    }
+}
+export function resolveApiKeyForModel(model, runtime) {
+    if (runtime?.apiKey && runtime.apiKeyProvider === 'explicit') {
+        return runtime.apiKey;
+    }
+    const provider = inferProviderFromModel(model);
+    if (runtime?.apiKey && runtime.apiKeyProvider === provider) {
+        return runtime.apiKey;
+    }
+    return resolveProviderApiKey(provider);
+}
+function firstDefinedNonEmpty(...values) {
+    return values.find((value) => typeof value === 'string' && value.trim().length > 0);
+}
+//# sourceMappingURL=api-keys.js.map

package/dist/src/runtime/api-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.js","sourceRoot":"","sources":["../../../src/runtime/api-keys.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAO7D,MAAM,UAAU,qBAAqB,CAAC,QAAqB;IACzD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,QAAQ;YACX,OAAO,oBAAoB,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;QAC/F,KAAK,WAAW;YACd,OAAO,oBAAoB,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;QACrG,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAE,OAAuB;IAC1E,IAAI,OAAO,EAAE,MAAM,IAAI,OAAO,CAAC,cAAc,KAAK,UAAU,EAAE,CAAC;QAC7D,OAAO,OAAO,CAAC,MAAM,CAAC;IACxB,CAAC;IAED,MAAM,QAAQ,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;IAC/C,IAAI,OAAO,EAAE,MAAM,IAAI,OAAO,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;QAC3D,OAAO,OAAO,CAAC,MAAM,CAAC;IACxB,CAAC;IAED,OAAO,qBAAqB,CAAC,QAAQ,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,oBAAoB,CAAC,GAAG,MAAiC;IAChE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACtF,CAAC"}

package/dist/src/runtime/default-tools.d.ts

@@ -0,0 +1,12 @@
+import type { ToolDefinition } from '../types.js';
+export type DefaultAgentToolsOptions = {
+    model: string;
+    apiKey?: string;
+    workspaceRoot?: string;
+    stateDir?: string;
+    memoryDir?: string;
+    searchIgnoreDirs?: string[];
+    includePlanTool?: boolean;
+};
+export declare function createDefaultAgentTools(options: DefaultAgentToolsOptions): ToolDefinition[];
+//# sourceMappingURL=default-tools.d.ts.map

package/dist/src/runtime/default-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-tools.d.ts","sourceRoot":"","sources":["../../../src/runtime/default-tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAiBlD,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,cAAc,EAAE,CA8B3F"}

package/dist/src/runtime/default-tools.js

@@ -0,0 +1,40 @@
+import { join } from 'node:path';
+import { editFileTool } from '../tools/edit-file.js';
+import { listFilesTool } from '../tools/list-files.js';
+import { createEditMemoryNoteTool, createListMemoryNotesTool, createReadMemoryNoteTool, createSearchMemoryNotesTool, } from '../tools/memory-notes.js';
+import { readFileTool } from '../tools/read-file.js';
+import { reportStateTool } from '../tools/report-state.js';
+import { createRunShellInspectTool, createRunShellMutateTool } from '../tools/run-shell.js';
+import { createSearchFilesTool } from '../tools/search-files.js';
+import { updatePlanTool } from '../tools/update-plan.js';
+import { createViewImageTool } from '../tools/view-image.js';
+import { createWebSearchTool } from '../tools/web-search.js';
+export function createDefaultAgentTools(options) {
+    const memoryRoot = options.memoryDir ??
+        join(options.workspaceRoot ?? process.cwd(), options.stateDir ?? '.heddle', 'memory');
+    const tools = [
+        listFilesTool,
+        readFileTool,
+        editFileTool,
+        createSearchFilesTool({ excludedDirs: options.searchIgnoreDirs }),
+        createWebSearchTool({
+            model: options.model,
+            apiKey: options.apiKey,
+        }),
+        createViewImageTool({
+            model: options.model,
+            apiKey: options.apiKey,
+        }),
+        createListMemoryNotesTool({ memoryRoot }),
+        createReadMemoryNoteTool({ memoryRoot }),
+        createSearchMemoryNotesTool({ memoryRoot }),
+        createEditMemoryNoteTool({ memoryRoot }),
+        reportStateTool,
+    ];
+    if (options.includePlanTool ?? true) {
+        tools.push(updatePlanTool);
+    }
+    tools.push(createRunShellInspectTool(), createRunShellMutateTool());
+    return tools;
+}
+//# sourceMappingURL=default-tools.js.map

package/dist/src/runtime/default-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-tools.js","sourceRoot":"","sources":["../../../src/runtime/default-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAY7D,MAAM,UAAU,uBAAuB,CAAC,OAAiC;IACvE,MAAM,UAAU,GACd,OAAO,CAAC,SAAS;QACjB,IAAI,CAAC,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,QAAQ,IAAI,SAAS,EAAE,QAAQ,CAAC,CAAC;IACxF,MAAM,KAAK,GAAqB;QAC9B,aAAa;QACb,YAAY;QACZ,YAAY;QACZ,qBAAqB,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,gBAAgB,EAAE,CAAC;QACjE,mBAAmB,CAAC;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC;QACF,mBAAmB,CAAC;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC;QACF,yBAAyB,CAAC,EAAE,UAAU,EAAE,CAAC;QACzC,wBAAwB,CAAC,EAAE,UAAU,EAAE,CAAC;QACxC,2BAA2B,CAAC,EAAE,UAAU,EAAE,CAAC;QAC3C,wBAAwB,CAAC,EAAE,UAAU,EAAE,CAAC;QACxC,eAAe;KAChB,CAAC;IAEF,IAAI,OAAO,CAAC,eAAe,IAAI,IAAI,EAAE,CAAC;QACpC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,wBAAwB,EAAE,CAAC,CAAC;IACpE,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/runtime/events.d.ts

@@ -0,0 +1,128 @@
+import type { ChatMessage, LlmProvider, LlmUsage } from '../llm/types.js';
+import type { RunResult, StopReason, TraceEvent } from '../types.js';
+export type AgentLoopStatus = 'finished';
+export type AgentLoopState = {
+    status: AgentLoopStatus;
+    runId: string;
+    goal: string;
+    model: string;
+    provider: LlmProvider;
+    workspaceRoot: string;
+    startedAt: string;
+    finishedAt: string;
+    outcome: StopReason;
+    summary: string;
+    usage?: LlmUsage;
+    transcript: ChatMessage[];
+    trace: TraceEvent[];
+};
+export type AgentLoopCheckpoint = {
+    version: 1;
+    runId: string;
+    createdAt: string;
+    state: AgentLoopState;
+};
+/**
+ * Host-facing agent loop events.
+ * Stable payload shapes for external integration (CyberLoop, Lucid, etc.)
+ */
+export type AgentLoopEvent = {
+    type: 'loop.started';
+    runId: string;
+    goal: string;
+    model: string;
+    provider: LlmProvider;
+    workspaceRoot: string;
+    resumedFromCheckpoint?: string;
+    timestamp: string;
+} | {
+    type: 'loop.resumed';
+    runId: string;
+    fromCheckpoint: string;
+    priorTraceEvents: number;
+    timestamp: string;
+} | {
+    type: 'assistant.stream';
+    runId: string;
+    step: number;
+    text: string;
+    done: boolean;
+    timestamp: string;
+} | {
+    type: 'tool.calling';
+    runId: string;
+    step: number;
+    tool: string;
+    toolCallId: string;
+    input: unknown;
+    requiresApproval: boolean;
+    timestamp: string;
+} | {
+    type: 'tool.completed';
+    runId: string;
+    step: number;
+    tool: string;
+    toolCallId: string;
+    result: {
+        ok: boolean;
+        output?: unknown;
+        error?: string;
+    };
+    durationMs: number;
+    timestamp: string;
+} | {
+    type: 'trace';
+    runId: string;
+    event: TraceEvent;
+    timestamp: string;
+} | {
+    type: 'checkpoint.saved';
+    runId: string;
+    checkpoint: AgentLoopCheckpoint;
+    step: number;
+    timestamp: string;
+} | {
+    type: 'escalation.required';
+    runId: string;
+    task: string;
+    outcome: StopReason;
+    summary: string;
+    step: number;
+    timestamp: string;
+} | {
+    type: 'heartbeat.decision';
+    runId: string;
+    decision: 'continue' | 'pause' | 'complete' | 'escalate';
+    outcome: StopReason;
+    summary: string;
+    timestamp: string;
+} | {
+    type: 'loop.finished';
+    runId: string;
+    outcome: RunResult['outcome'];
+    summary: string;
+    usage: RunResult['usage'];
+    state: AgentLoopState;
+    timestamp: string;
+};
+export declare function createFinishedAgentLoopState(args: {
+    runId: string;
+    goal: string;
+    model: string;
+    provider: LlmProvider;
+    workspaceRoot: string;
+    startedAt: string;
+    finishedAt: string;
+    result: RunResult;
+}): AgentLoopState;
+export declare function createAgentLoopCheckpoint(state: AgentLoopState, options?: {
+    createdAt?: string;
+}): AgentLoopCheckpoint;
+/**
+ * Generate a unique run ID for event correlation.
+ * Format: run_<timestamp>_<random>
+ */
+export declare function generateRunId(): string;
+export declare function getHistoryFromAgentLoopState(state: AgentLoopState): ChatMessage[];
+export declare function getHistoryFromAgentLoopCheckpoint(checkpoint: AgentLoopCheckpoint): ChatMessage[];
+//# sourceMappingURL=events.d.ts.map

package/dist/src/runtime/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/runtime/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAErE,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC;AAEzC,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,WAAW,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,WAAW,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,gBAAgB,EAAE,OAAO,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,mBAAmB,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,qBAAqB,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,oBAAoB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;IACzD,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IAC1B,KAAK,EAAE,cAAc,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEN,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,WAAW,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,CAAC;CACnB,GAAG,cAAc,CAgBjB;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,cAAc,EACrB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,mBAAmB,CAOrB;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAItC;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,EAAE,CAEjF;AAED,wBAAgB,iCAAiC,CAAC,UAAU,EAAE,mBAAmB,GAAG,WAAW,EAAE,CAEhG"}

package/dist/src/runtime/events.js

@@ -0,0 +1,41 @@
+export function createFinishedAgentLoopState(args) {
+    return {
+        status: 'finished',
+        runId: args.runId,
+        goal: args.goal,
+        model: args.model,
+        provider: args.provider,
+        workspaceRoot: args.workspaceRoot,
+        startedAt: args.startedAt,
+        finishedAt: args.finishedAt,
+        outcome: args.result.outcome,
+        summary: args.result.summary,
+        usage: args.result.usage,
+        transcript: args.result.transcript,
+        trace: args.result.trace,
+    };
+}
+export function createAgentLoopCheckpoint(state, options = {}) {
+    return {
+        version: 1,
+        runId: state.runId,
+        createdAt: options.createdAt ?? new Date().toISOString(),
+        state,
+    };
+}
+/**
+ * Generate a unique run ID for event correlation.
+ * Format: run_<timestamp>_<random>
+ */
+export function generateRunId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).slice(2, 6);
+    return `run_${timestamp}_${random}`;
+}
+export function getHistoryFromAgentLoopState(state) {
+    return state.transcript;
+}
+export function getHistoryFromAgentLoopCheckpoint(checkpoint) {
+    return getHistoryFromAgentLoopState(checkpoint.state);
+}
+//# sourceMappingURL=events.js.map

package/dist/src/runtime/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/runtime/events.ts"],"names":[],"mappings":"AAsHA,MAAM,UAAU,4BAA4B,CAAC,IAS5C;IACC,OAAO;QACL,MAAM,EAAE,UAAU;QAClB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;QAC5B,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;QAC5B,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;QACxB,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU;QAClC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;KACzB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,KAAqB,EACrB,UAAkC,EAAE;IAEpC,OAAO;QACL,OAAO,EAAE,CAAC;QACV,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACxD,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtD,OAAO,OAAO,SAAS,IAAI,MAAM,EAAE,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,KAAqB;IAChE,OAAO,KAAK,CAAC,UAAU,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,iCAAiC,CAAC,UAA+B;IAC/E,OAAO,4BAA4B,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;AACxD,CAAC"}

package/dist/src/runtime/heartbeat-store.d.ts

@@ -0,0 +1,20 @@
+import type { AgentHeartbeatResult, RunAgentHeartbeatOptions } from './heartbeat.js';
+import type { AgentLoopCheckpoint } from './events.js';
+export type HeartbeatCheckpointStore = {
+    load: () => Promise<AgentLoopCheckpoint | undefined>;
+    save: (checkpoint: AgentLoopCheckpoint) => Promise<void>;
+};
+export type FileHeartbeatCheckpointStoreOptions = {
+    path: string;
+};
+export type RunStoredHeartbeatOptions = Omit<RunAgentHeartbeatOptions, 'checkpoint'> & {
+    store: HeartbeatCheckpointStore;
+};
+export type StoredHeartbeatResult = AgentHeartbeatResult & {
+    loadedCheckpoint: boolean;
+    nextDelayMs?: number;
+};
+export declare function createFileHeartbeatCheckpointStore(options: FileHeartbeatCheckpointStoreOptions): HeartbeatCheckpointStore;
+export declare function runStoredHeartbeat(options: RunStoredHeartbeatOptions): Promise<StoredHeartbeatResult>;
+export declare function suggestNextHeartbeatDelayMs(decision: AgentHeartbeatResult['decision']): number | undefined;
+//# sourceMappingURL=heartbeat-store.d.ts.map

package/dist/src/runtime/heartbeat-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat-store.d.ts","sourceRoot":"","sources":["../../../src/runtime/heartbeat-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,MAAM,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAAC;IACrD,IAAI,EAAE,CAAC,UAAU,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,MAAM,mCAAmC,GAAG;IAChD,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,wBAAwB,EAAE,YAAY,CAAC,GAAG;IACrF,KAAK,EAAE,wBAAwB,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,oBAAoB,GAAG;IACzD,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,kCAAkC,CAAC,OAAO,EAAE,mCAAmC,GAAG,wBAAwB,CAczH;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAa3G;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,oBAAoB,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,SAAS,CAU1G"}

package/dist/src/runtime/heartbeat-store.js

@@ -0,0 +1,42 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { runAgentHeartbeat } from './heartbeat.js';
+export function createFileHeartbeatCheckpointStore(options) {
+    return {
+        async load() {
+            if (!existsSync(options.path)) {
+                return undefined;
+            }
+            return JSON.parse(readFileSync(options.path, 'utf8'));
+        },
+        async save(checkpoint) {
+            mkdirSync(dirname(options.path), { recursive: true });
+            writeFileSync(options.path, JSON.stringify(checkpoint, null, 2));
+        },
+    };
+}
+export async function runStoredHeartbeat(options) {
+    const checkpoint = await options.store.load();
+    const result = await runAgentHeartbeat({
+        ...options,
+        checkpoint,
+    });
+    await options.store.save(result.checkpoint);
+    return {
+        ...result,
+        loadedCheckpoint: Boolean(checkpoint),
+        nextDelayMs: suggestNextHeartbeatDelayMs(result.decision),
+    };
+}
+export function suggestNextHeartbeatDelayMs(decision) {
+    switch (decision) {
+        case 'continue':
+            return 60_000;
+        case 'pause':
+            return 15 * 60_000;
+        case 'complete':
+        case 'escalate':
+            return undefined;
+    }
+}
+//# sourceMappingURL=heartbeat-store.js.map

package/dist/src/runtime/heartbeat-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat-store.js","sourceRoot":"","sources":["../../../src/runtime/heartbeat-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAsBnD,MAAM,UAAU,kCAAkC,CAAC,OAA4C;IAC7F,OAAO;QACL,KAAK,CAAC,IAAI;YACR,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC9B,OAAO,SAAS,CAAC;YACnB,CAAC;YAED,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAwB,CAAC;QAC/E,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,UAAU;YACnB,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACtD,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACnE,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAkC;IACzE,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAC9C,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC;QACrC,GAAG,OAAO;QACV,UAAU;KACX,CAAC,CAAC;IACH,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAE5C,OAAO;QACL,GAAG,MAAM;QACT,gBAAgB,EAAE,OAAO,CAAC,UAAU,CAAC;QACrC,WAAW,EAAE,2BAA2B,CAAC,MAAM,CAAC,QAAQ,CAAC;KAC1D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,QAA0C;IACpF,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,UAAU;YACb,OAAO,MAAM,CAAC;QAChB,KAAK,OAAO;YACV,OAAO,EAAE,GAAG,MAAM,CAAC;QACrB,KAAK,UAAU,CAAC;QAChB,KAAK,UAAU;YACb,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/src/runtime/heartbeat.d.ts

@@ -0,0 +1,39 @@
+import type { Logger } from 'pino';
+import type { ChatMessage, LlmAdapter } from '../llm/types.js';
+import type { ToolCall, ToolDefinition } from '../types.js';
+import type { AgentLoopCheckpoint, AgentLoopEvent, AgentLoopState } from './events.js';
+export type HeartbeatDecision = 'continue' | 'pause' | 'complete' | 'escalate';
+export type RunAgentHeartbeatOptions = {
+    task: string;
+    checkpoint?: AgentLoopState | AgentLoopCheckpoint;
+    model?: string;
+    apiKey?: string;
+    maxSteps?: number;
+    workspaceRoot?: string;
+    stateDir?: string;
+    memoryDir?: string;
+    searchIgnoreDirs?: string[];
+    systemContext?: string;
+    history?: ChatMessage[];
+    llm?: LlmAdapter;
+    tools?: ToolDefinition[];
+    extraTools?: ToolDefinition[];
+    includeDefaultTools?: boolean;
+    includePlanTool?: boolean;
+    logger?: Logger;
+    onEvent?: (event: AgentLoopEvent) => void;
+    approveToolCall?: (call: ToolCall, tool: ToolDefinition) => Promise<{
+        approved: boolean;
+        reason?: string;
+    }>;
+    shouldStop?: () => boolean;
+    abortSignal?: AbortSignal;
+};
+export type AgentHeartbeatResult = {
+    decision: HeartbeatDecision;
+    summary: string;
+    checkpoint: AgentLoopCheckpoint;
+    state: AgentLoopState;
+};
+export declare function runAgentHeartbeat(options: RunAgentHeartbeatOptions): Promise<AgentHeartbeatResult>;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/src/runtime/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../../src/runtime/heartbeat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIvF,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;AAE/E,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,cAAc,GAAG,mBAAmB,CAAC;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAC1C,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5G,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,mBAAmB,CAAC;IAChC,KAAK,EAAE,cAAc,CAAC;CACvB,CAAC;AAEF,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAiExG"}