@autonome-research/thread-phase 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thread-phase contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# thread-phase
+
+A TypeScript framework that composes deterministic phases over **heterogeneous agents** — the iterated tool-use loop against OpenAI-compatible inference for raw model calls, the `AgentAdapter` protocol for delegating to ready agents (Claude Code, Hermes, Codex, OpenClaw, Anthropic SDK). Multi-phase pipelines with a typed shared context, persistent event logs, and concurrency-capped fanout.
+
+```bash
+npm install @autonome-research/thread-phase
+```
+
+> **Generating thread-phase code with an LLM agent?** See [`AGENTS.md`](./AGENTS.md) — a self-contained reference covering the mental model, a copy-paste template, and explicit anti-patterns. Claude Code users can also install [`SKILL.md`](./SKILL.md) into `~/.claude/skills/thread-phase/` so the guidance auto-loads.
+
+## Use cases
+
+thread-phase is designed for two shapes:
+
+1. **Agent-authored automations.** When an autonomous agent (Claude Code, Hermes, Cursor, etc.) sets up a recurring task — a cron job, a systemd timer, a CI step — the structuring usually happens at prompt-write time but the execution still relies on the agent re-deriving its plan at run time. thread-phase gives the structuring agent a typed phase boundary to encode the deterministic parts of the pipeline (ordering, fan-out, ctx flow, post-condition checks) while leaving the run-time agent free to make judgment calls inside each phase. The cron line ends up being a plain `npx tsx ...` invocation; no prompt at run time. See [`examples/agent-authored-cron.ts`](./examples/agent-authored-cron.ts).
+
+2. **Mini-workflows inside larger DAG frameworks.** Temporal, LangGraph, Inngest, and similar frameworks are built for distributed DAG orchestration; they're heavyweight when a single node needs to run a small multi-step agent loop with its own concurrency cap, retry, and event log. thread-phase fits as the *inside* of one node — Temporal owns the workflow topology and durable state across machines; thread-phase owns the streaming tool-use loop and per-node phase composition. This composes cleanly because thread-phase's `runAgentWithTools` and `runPipeline` don't assume they own the event loop or persistence layer.
+
+It's also useful as a standalone pipeline runner (`JobRunner` + sqlite event log + SSE streaming) for batch-processing workloads that don't need either of the above.
+
+## Out of scope
+
+- DAG / graph framework features (cross-node dependency graphs, declarative edge routing, distributed scheduling). Use Temporal/LangGraph/Inngest, embedding thread-phase inside their nodes.
+- Anthropic content-block model (vision, citations, extended thinking). Use the Anthropic SDK directly.
+- Multi-modal inputs.
+- Long-document summarization (the bundled compressor uses opaque markers for old tool results — known weakness for hierarchical summarization, see [ROADMAP](./ROADMAP.md)).
+
+## Quickstart
+
+```ts
+import {
+  runAgentWithTools,
+  ToolRegistry,
+  createInferenceClient,
+} from '@autonome-research/thread-phase';
+
+const tools = new ToolRegistry().register(
+  {
+    name: 'add',
+    description: 'Add two integers',
+    inputSchema: {
+      type: 'object',
+      properties: { a: { type: 'number' }, b: { type: 'number' } },
+      required: ['a', 'b'],
+      additionalProperties: false,
+    },
+  },
+  async (args) => String((args.a as number) + (args.b as number)),
+);
+
+const result = await runAgentWithTools(
+  {
+    name: 'math',
+    systemPrompt: 'Use the add tool. Reply with just the number.',
+    model: 'qwen3.6-27b',
+    tools: tools.definitions(),
+    maxToolRounds: 5,
+    maxTokens: 256,
+  },
+  [{ role: 'user', content: 'What is 17 + 25?' }],
+  { client: createInferenceClient(), toolExecutor: tools },
+);
+
+result.text;               // "42"
+result.finishReason;       // "stop" | "length" | "tool_calls" | ...
+result.usage;              // { promptTokens, completionTokens, totalTokens }
+result.executedToolCalls;  // [{ id, name: 'add', input: { a: 17, b: 25 } }]
+```
+
+## Architecture
+
+Three primitives plus one extension surface.
+
+### `runAgentWithTools(config, messages, options) → AgentRunResult`
+
+The streaming tool-use loop. Sends a chat-completions request with `stream: true`, accumulates content and tool-call deltas, dispatches tools through `options.toolExecutor`, loops until the model produces final text or hits `config.maxToolRounds`. Returns a structured result:
+
+- `text` — final text output
+- `finishReason` — `'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call' | 'error' | 'unknown'`. Branch on `'length'` to detect truncation.
+- `usage` — `{ promptTokens, completionTokens, totalTokens }`, summed across rounds
+- `executedToolCalls` — every tool call the model actually executed (id, name, parsed args)
+- `activity` — string log of internal events
+
+`options.signal` propagates an `AbortSignal` into the inference call. `options.onStreamEvent` receives `content_delta`, `tool_call_started`, `tool_call_complete`, and `round_complete` events as they arrive. `options.verifyResult` is a hook that runs once before returning — it can transform the result or throw to mark the run as failed; use it to validate the agent's claimed output against `executedToolCalls`.
+
+### `Phase<TCtx>` + `runPipeline(phases, ctx)`
+
+A `Phase` is an async generator that reads from a shared `ctx`, yields events, and writes outputs back to `ctx`. A pipeline is an array of phases run in order:
+
+```ts
+interface Phase<TCtx extends BasePipelineContext> {
+  readonly name: string;
+  run(ctx: TCtx): AsyncGenerator<PipelineEvent, void>;
+}
+
+for await (const event of runPipeline([phaseA, phaseB, phaseC], ctx)) {
+  // each phase yields events; the orchestrator owns the terminal 'done' / 'error'
+}
+```
+
+`requireCtx(ctx, key, phaseName)` is the loud-precondition helper — fails with the field name if a prerequisite phase didn't populate the field. Use it at the top of every phase that reads from ctx.
+
+`ctx.stop = { reason }` halts the pipeline cleanly. Loops, conditional branches, and parallel sub-flows are composed in TypeScript rather than declared in a graph language; the [`patterns/`](./docs/patterns.md) module names the recurring shapes.
+
+### `JobRunner` + `JobStore`
+
+`JobRunner` wraps a pipeline run with a persistent event log (`JobStore`, sqlite-backed by default), live event emission for SSE consumers, and per-job cancellation:
+
+```ts
+const runner = new JobRunner(new SqliteJobStore('./jobs.db'));
+const jobId = runner.create('my-pipeline', input);
+
+// wire SIGTERM to runner.cancel so a stuck inference call exits cleanly
+process.on('SIGTERM', () => runner.cancel(jobId, 'systemd timeout'));
+
+await runner.run(jobId, [phaseA, phaseB], ctx);
+// events persisted; consumers can replay via store.getEvents(jobId, afterId)
+// or subscribe live via runner.on(`job:${jobId}`, ...)
+```
+
+`JobRunner.signalFor(jobId)` exposes the `AbortSignal` so phase code can wire it into individual `runAgentWithTools` calls — without that wiring, cancellation only halts between phases.
+
+The interface is sync by design (sqlite hot path; fire-and-forget event writes). Async backends will land as an additive `JobStoreAsync` interface if/when needed; see [ROADMAP](./ROADMAP.md).
+
+### `AgentAdapter` — the extension surface
+
+`AgentAdapter` is the protocol every ready-agent integration speaks. The in-tree `inferenceAgent` wraps `runAgentWithTools`; sibling implementations in [`@autonome-research/thread-phase-agents`](../thread-phase-agents) wrap `hermes`, `openclaw`, `claude`, the OpenAI Responses API (Codex), and the Anthropic SDK directly.
+
+Every adapter returns the same shape:
+
+```ts
+interface AgentRun {
+  readonly events: AsyncIterable<AgentEvent>;  // single-consumer stream
+  readonly result: Promise<AgentRunResult>;     // always resolves, never rejects
+  abort(reason?: string): void;
+}
+```
+
+Canonical events: `agent_start | text | thinking | tool_call | tool_result | turn_end | agent_end | error | native`. Every event carries a `source` field (the adapter's id) so heterogeneous adapter events flow through one `AgentEventBus` without losing provenance.
+
+Conversation state across phases lives in the `Thread` primitive — canonical events plus per-adapter resume tokens. Same-adapter chains (claude-code → claude-code) resume natively via the adapter's session; cross-adapter chains render events back to text via `threadToMessages`.
+
+Memory across runs is outsourced: `MemoryProvider` is just a TypeScript interface (`recall(scope, query?) / remember(scope, events)`). thread-phase ships no implementations; bind Honcho, Letta, Mem0, or a custom backend yourself. See [`examples/honcho-memory.ts`](./examples/honcho-memory.ts).
+
+### `Trigger` — the entry-point abstraction
+
+`Trigger<TInput>` is the protocol every signal source implements: timers, webhooks, queue consumers, file watchers, message brokers. Each trigger yields `TriggerEvent<TInput>` with `{ id, occurredAt, input, metadata }`. `runTrigger(trigger, factory, options)` is the canonical consumer — it reads events, dispatches pipelines (optionally through a `JobRunner`), enforces a concurrency cap with backpressure, and isolates per-event failures.
+
+Core ships `TimerTrigger` only. HTTP/queue/file-watch transports stay in `examples/triggers/` as recipes — wrap your favorite framework into the protocol, don't make thread-phase ship transports.
+
+```ts
+import { TimerTrigger, runTrigger } from '@autonome-research/thread-phase/triggers';
+
+const trigger = new TimerTrigger({ intervalMs: 15 * 60_000, name: 'every-15m' });
+const handle = runTrigger(
+  trigger,
+  () => ({ phases: [myPipeline], ctx: { cache: new PipelineCache() } }),
+  { jobRunner: runner, jobStore: store },
+);
+
+process.on('SIGTERM', () => void handle.stop());
+await handle.done;
+```
+
+## Patterns
+
+In `@autonome-research/thread-phase/patterns`:
+
+| Pattern | Shape |
+|---|---|
+| `boundedFanout` | N items, free-function runner per item, capped concurrency, results in input order |
+| `boundedFanoutOf` | Same, but the runner is an `AgentAdapter` + buildConfig — automatic event-bus propagation |
+| `parallelPhases` | Several phases run concurrently as one composite |
+| `intentGate` | Cheap classifier decides whether the rest of the pipeline runs |
+| `whileCondition` | Loop a body of phases while an async predicate holds, with a max-iteration cap |
+| `match` | Keyed dispatch — route to one of N phase lists by selector key |
+| `withRetry` | Higher-order wrapper retrying a phase with exponential backoff on failure |
+
+See [`docs/patterns.md`](./docs/patterns.md) for selection guidance ("I want to do X" → "use Y"). v3.0.0 trimmed five patterns (`parallelFanout`, `streamingBoundedFanout`, `preflightConfidence`, `synthesizeWithFollowup`, `spotCheck`) into composition recipes — see [`docs/recipes.md`](./docs/recipes.md) for paste-in equivalents.
+
+## Configuration
+
+Environment-driven by default (override in code via `loadInferenceConfig({ ... })`):
+
+```bash
+INFERENCE_BASE_URL=http://localhost:8000/v1
+INFERENCE_API_KEY=not-needed-for-local-vllm
+INFERENCE_MODEL=qwen3.6-27b
+INFERENCE_CONTEXT_LENGTH=131072
+```
+
+For tool-using agents on vLLM, the server needs `--enable-auto-tool-choice --tool-call-parser <name>` matching the model's output format. If content shaped like a tool call arrives as plain text instead of structured `tool_calls`, the runner emits a `parser_mismatch_warning` activity entry.
+
+## Examples
+
+In [`examples/`](./examples), runnable via `npx tsx examples/<name>.ts`:
+
+| File | Demonstrates |
+|---|---|
+| `bare-agent.ts` | Single tool, single agent call, structured result |
+| `multi-phase-pipeline.ts` | Linear pipeline with one parallel branch |
+| `streaming-consumer.ts` | Content + tool-call deltas as they stream |
+| `bounded-fanout.ts` | Per-item agent over a list, concurrency-capped |
+| `sse-server.ts` | `JobRunner` + `streamToSSE` in an HTTP handler |
+| `agent-authored-cron.ts` | End-to-end automation skeleton — fetch / triage / summarize / compose, with `verifyResult` and `JobRunner` |
+| `honcho-memory.ts` | `MemoryProvider` bound to Honcho — recall before an agent call, remember after |
+
+## Stability
+
+v1.0.0 onward follows semver:
+
+- **patch (1.0.x)** — bug fixes, no API changes
+- **minor (1.x.0)** — additive changes (new patterns, new optional fields)
+- **major (x.0.0)** — breaking changes
+
+Items marked `@internal` in their JSDoc (e.g. `consumeStream`, `toOpenAIMessages`) are reachable for advanced callers but **not** covered by semver.
+
+103 tests across 13 files. Validated in production by [`Code4me2/chiya-library`](https://github.com/Code4me2/chiya-library) — digest + librarian pipelines, hundreds of articles per day, on systemd timers.
+
+## Contributing
+
+Issues and PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md). For larger changes, open an issue first — the framework has a deliberately narrow scope and we'd rather discuss before code is written.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/agent/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Agent module barrel.
+ *
+ * Two tiers of exports:
+ *
+ *   1. Stable (covered by semver, won't break in minor/patch releases):
+ *      `runAgentWithTools`, `parseJSON`, and the type surface
+ *      (`AgentConfig`, `AgentRunResult`, `AgentRunnerOptions`,
+ *      `AgentStreamEvent`, `FinishReason`, `UsageInfo`, `ActivityEntry`).
+ *
+ *   2. @internal (exported for advanced callers, NOT covered by semver):
+ *      `consumeStream`, `looksLikeToolCallText`, `normalizeFinishReason`,
+ *      `AccumulatedRound`, `toOpenAIMessages`, `toOpenAITools`,
+ *      `isRetryableError`, `isAbortError`. These exist so callers building
+ *      their own non-loop flows can reuse the building blocks; if you do,
+ *      pin the minor version and read the CHANGELOG before upgrading.
+ *
+ * The package's main `src/index.ts` re-exports only the stable surface —
+ * @internal items are reachable only via deep import (`thread-phase/agent`
+ * is intentionally NOT a configured package subpath).
+ */
+export { runAgentWithTools } from './runner.js';
+export { parseJSON } from './parse-json.js';
+export type { AgentConfig, ActivityEntry, AgentRunResult, AgentRunnerOptions, AgentStreamEvent, FinishReason, UsageInfo, } from './types.js';
+export { toOpenAIMessages, toOpenAITools } from './openai-adapter.js';
+export { consumeStream, looksLikeToolCallText, normalizeFinishReason, type AccumulatedRound, } from './stream-consumer.js';
+export { isRetryableError, isAbortError } from './retry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,YAAY,EACV,WAAW,EACX,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,SAAS,GACV,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/agent/index.js

@@ -0,0 +1,28 @@
+/**
+ * Agent module barrel.
+ *
+ * Two tiers of exports:
+ *
+ *   1. Stable (covered by semver, won't break in minor/patch releases):
+ *      `runAgentWithTools`, `parseJSON`, and the type surface
+ *      (`AgentConfig`, `AgentRunResult`, `AgentRunnerOptions`,
+ *      `AgentStreamEvent`, `FinishReason`, `UsageInfo`, `ActivityEntry`).
+ *
+ *   2. @internal (exported for advanced callers, NOT covered by semver):
+ *      `consumeStream`, `looksLikeToolCallText`, `normalizeFinishReason`,
+ *      `AccumulatedRound`, `toOpenAIMessages`, `toOpenAITools`,
+ *      `isRetryableError`, `isAbortError`. These exist so callers building
+ *      their own non-loop flows can reuse the building blocks; if you do,
+ *      pin the minor version and read the CHANGELOG before upgrading.
+ *
+ * The package's main `src/index.ts` re-exports only the stable surface —
+ * @internal items are reachable only via deep import (`thread-phase/agent`
+ * is intentionally NOT a configured package subpath).
+ */
+export { runAgentWithTools } from './runner.js';
+export { parseJSON } from './parse-json.js';
+// @internal — see file header. Lower-level pieces for advanced callers.
+export { toOpenAIMessages, toOpenAITools } from './openai-adapter.js';
+export { consumeStream, looksLikeToolCallText, normalizeFinishReason, } from './stream-consumer.js';
+export { isRetryableError, isAbortError } from './retry.js';
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAY5C,wEAAwE;AACxE,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,qBAAqB,GAEtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/agent/openai-adapter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Translation between thread-phase's internal Message shape and the OpenAI
+ * chat-completions wire format. Lives at the single boundary so the rest of
+ * the framework stays SDK-agnostic.
+ *
+ * @internal — both functions are exported for advanced callers (e.g. those
+ * driving a custom inference loop) but are not part of the v1 stable
+ * surface. They may change between minor versions if the OpenAI SDK
+ * evolves.
+ */
+import type { ChatCompletionMessageParam, ChatCompletionTool } from 'openai/resources/chat/completions.js';
+import type { Message, ToolDefinition } from '../messages.js';
+export declare function toOpenAIMessages(systemPrompt: string, messages: Message[]): ChatCompletionMessageParam[];
+export declare function toOpenAITools(tools: ToolDefinition[]): ChatCompletionTool[];
+//# sourceMappingURL=openai-adapter.d.ts.map

package/dist/agent/openai-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-adapter.d.ts","sourceRoot":"","sources":["../../src/agent/openai-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,0BAA0B,EAC1B,kBAAkB,EAGnB,MAAM,sCAAsC,CAAC;AAE9C,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE9D,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,OAAO,EAAE,GAClB,0BAA0B,EAAE,CAkC9B;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,kBAAkB,EAAE,CAS3E"}

package/dist/agent/openai-adapter.js

@@ -0,0 +1,57 @@
+/**
+ * Translation between thread-phase's internal Message shape and the OpenAI
+ * chat-completions wire format. Lives at the single boundary so the rest of
+ * the framework stays SDK-agnostic.
+ *
+ * @internal — both functions are exported for advanced callers (e.g. those
+ * driving a custom inference loop) but are not part of the v1 stable
+ * surface. They may change between minor versions if the OpenAI SDK
+ * evolves.
+ */
+export function toOpenAIMessages(systemPrompt, messages) {
+    const result = [{ role: 'system', content: systemPrompt }];
+    for (const msg of messages) {
+        if (msg.role === 'system') {
+            result.push({ role: 'system', content: msg.content });
+        }
+        else if (msg.role === 'user') {
+            result.push({ role: 'user', content: msg.content });
+        }
+        else if (msg.role === 'assistant') {
+            const out = {
+                role: 'assistant',
+                content: msg.content || null,
+            };
+            if (msg.toolCalls.length > 0) {
+                out.tool_calls = msg.toolCalls.map((tc) => ({
+                    id: tc.id,
+                    type: 'function',
+                    function: {
+                        name: tc.name,
+                        arguments: JSON.stringify(tc.input),
+                    },
+                }));
+            }
+            result.push(out);
+        }
+        else if (msg.role === 'tool') {
+            result.push({
+                role: 'tool',
+                tool_call_id: msg.toolCallId,
+                content: msg.content,
+            });
+        }
+    }
+    return result;
+}
+export function toOpenAITools(tools) {
+    return tools.map((t) => ({
+        type: 'function',
+        function: {
+            name: t.name,
+            description: t.description,
+            parameters: t.inputSchema,
+        },
+    }));
+}
+//# sourceMappingURL=openai-adapter.js.map

package/dist/agent/openai-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-adapter.js","sourceRoot":"","sources":["../../src/agent/openai-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,MAAM,UAAU,gBAAgB,CAC9B,YAAoB,EACpB,QAAmB;IAEnB,MAAM,MAAM,GAAiC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;IACzF,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACxD,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACtD,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YACpC,MAAM,GAAG,GAAwC;gBAC/C,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI;aAC7B,CAAC;YACF,IAAI,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC7B,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG,CAChC,CAAC,EAAE,EAAiC,EAAE,CAAC,CAAC;oBACtC,EAAE,EAAE,EAAE,CAAC,EAAE;oBACT,IAAI,EAAE,UAAU;oBAChB,QAAQ,EAAE;wBACR,IAAI,EAAE,EAAE,CAAC,IAAI;wBACb,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC;qBACpC;iBACF,CAAC,CACH,CAAC;YACJ,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI,EAAE,MAAM;gBACZ,YAAY,EAAE,GAAG,CAAC,UAAU;gBAC5B,OAAO,EAAE,GAAG,CAAC,OAAO;aACrB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAuB;IACnD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACvB,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,UAAU,EAAE,CAAC,CAAC,WAAW;SAC1B;KACF,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/agent/parse-json.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tolerant JSON parse — strips markdown code fences, falls back to extracting
+ * the first {...} object from surrounding prose. Returns the supplied fallback
+ * on parse failure.
+ *
+ * Note on the silent-fallback behavior: when the agent's output was truncated
+ * (i.e. `AgentRunResult.finishReason === 'length'`), this almost always
+ * fails to parse. Callers should branch on `finishReason` BEFORE trusting
+ * the parsed value — otherwise truncation is invisible.
+ */
+export declare function parseJSON<T>(text: string, fallback: T, onError?: (preview: string, err: Error) => void): T;
+//# sourceMappingURL=parse-json.d.ts.map

package/dist/agent/parse-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-json.d.ts","sourceRoot":"","sources":["../../src/agent/parse-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,wBAAgB,SAAS,CAAC,CAAC,EACzB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,EACX,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,KAAK,IAAI,GAC9C,CAAC,CAqBH"}

package/dist/agent/parse-json.js

@@ -0,0 +1,31 @@
+/**
+ * Tolerant JSON parse — strips markdown code fences, falls back to extracting
+ * the first {...} object from surrounding prose. Returns the supplied fallback
+ * on parse failure.
+ *
+ * Note on the silent-fallback behavior: when the agent's output was truncated
+ * (i.e. `AgentRunResult.finishReason === 'length'`), this almost always
+ * fails to parse. Callers should branch on `finishReason` BEFORE trusting
+ * the parsed value — otherwise truncation is invisible.
+ */
+export function parseJSON(text, fallback, onError) {
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const braced = text.match(/(\{[\s\S]*\})/);
+    const jsonStr = fenced ? fenced[1] : braced ? braced[1] : text;
+    try {
+        return JSON.parse(jsonStr.trim());
+    }
+    catch (err) {
+        const preview = text.slice(0, 200);
+        const errObj = err instanceof Error ? err : new Error(String(err));
+        if (onError) {
+            onError(preview, errObj);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.warn(`[parseJSON] failed to parse agent output, using fallback. Preview: "${preview}..."`, err);
+        }
+        return fallback;
+    }
+}
+//# sourceMappingURL=parse-json.js.map

package/dist/agent/parse-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-json.js","sourceRoot":"","sources":["../../src/agent/parse-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,UAAU,SAAS,CACvB,IAAY,EACZ,QAAW,EACX,OAA+C;IAE/C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAEjE,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAM,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACnC,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACnE,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC3B,CAAC;aAAM,CAAC;YACN,sCAAsC;YACtC,OAAO,CAAC,IAAI,CACV,uEAAuE,OAAO,MAAM,EACpF,GAAG,CACJ,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/agent/retry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Error classification for the agent loop. Two questions:
+ *  - is this error retryable (transient network / overloaded backend)?
+ *  - is this error a cancellation we should respect rather than retry?
+ *
+ * Tuned for OpenAI-compat endpoints (vLLM, OpenAI, Ollama) — they all use
+ * roughly the same surface for transient failures.
+ *
+ * @internal — both predicates are exported for advanced callers wrapping
+ * the runner with their own retry/abort logic, but they are not part of
+ * the v1 stable surface. They may change as we discover new failure modes.
+ */
+export declare function isRetryableError(err: unknown): boolean;
+export declare function isAbortError(err: unknown): boolean;
+//# sourceMappingURL=retry.d.ts.map

package/dist/agent/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/agent/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAkBtD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGlD"}

package/dist/agent/retry.js

@@ -0,0 +1,35 @@
+/**
+ * Error classification for the agent loop. Two questions:
+ *  - is this error retryable (transient network / overloaded backend)?
+ *  - is this error a cancellation we should respect rather than retry?
+ *
+ * Tuned for OpenAI-compat endpoints (vLLM, OpenAI, Ollama) — they all use
+ * roughly the same surface for transient failures.
+ *
+ * @internal — both predicates are exported for advanced callers wrapping
+ * the runner with their own retry/abort logic, but they are not part of
+ * the v1 stable surface. They may change as we discover new failure modes.
+ */
+export function isRetryableError(err) {
+    const e = err;
+    // Never retry on cancellation — the caller asked us to stop.
+    if (e?.name === 'AbortError')
+        return false;
+    const message = e?.message ?? '';
+    const status = e?.status ?? e?.statusCode ?? 0;
+    return (status === 429 ||
+        status === 500 ||
+        status === 502 ||
+        status === 503 ||
+        status === 504 ||
+        message.includes('timeout') ||
+        message.includes('ECONNRESET') ||
+        message.includes('ECONNREFUSED') ||
+        message.includes('overloaded') ||
+        message.includes('rate_limit'));
+}
+export function isAbortError(err) {
+    const e = err;
+    return e?.name === 'AbortError' || (e?.message ?? '').includes('aborted');
+}
+//# sourceMappingURL=retry.js.map

package/dist/agent/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/agent/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,MAAM,CAAC,GAAG,GAAuF,CAAC;IAClG,6DAA6D;IAC7D,IAAI,CAAC,EAAE,IAAI,KAAK,YAAY;QAAE,OAAO,KAAK,CAAC;IAC3C,MAAM,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,EAAE,CAAC;IACjC,MAAM,MAAM,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC,EAAE,UAAU,IAAI,CAAC,CAAC;IAC/C,OAAO,CACL,MAAM,KAAK,GAAG;QACd,MAAM,KAAK,GAAG;QACd,MAAM,KAAK,GAAG;QACd,MAAM,KAAK,GAAG;QACd,MAAM,KAAK,GAAG;QACd,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;QAC3B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;QAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;QAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;QAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAC/B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,CAAC,GAAG,GAAiD,CAAC;IAC5D,OAAO,CAAC,EAAE,IAAI,KAAK,YAAY,IAAI,CAAC,CAAC,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC5E,CAAC"}

package/dist/agent/runner.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Agent runner — the tool-use loop primitive.
+ *
+ * Given an agent config (system prompt, tools, model tier), a starting
+ * conversation, and an executor for the tools, runs an iterated tool-use
+ * loop against an OpenAI-compatible inference endpoint until the agent
+ * produces final text or hits its round budget.
+ *
+ * Composed from focused helpers in this directory:
+ *   - `./types.ts`           — public surface
+ *   - `./openai-adapter.ts`  — Message↔OpenAI wire-format translation
+ *   - `./stream-consumer.ts` — folds streaming chunks into one round's state
+ *   - `./retry.ts`           — error classification (retryable, abort)
+ *
+ * What the loop owns:
+ *   - Round budgeting and the compress / hard-stop transitions
+ *   - Streaming the request, dispatching tools, collecting results
+ *   - Cumulative usage / executedToolCalls accounting across rounds
+ *   - Cancellation observation (AbortSignal in options)
+ *   - The verifyResult hook, the parser-mismatch warning, the retry loop
+ */
+import type { Message } from '../messages.js';
+import type { AgentConfig, AgentRunnerOptions, AgentRunResult } from './types.js';
+export declare function runAgentWithTools(config: AgentConfig, initialMessages: Message[], options: AgentRunnerOptions, agentLabel?: string): Promise<AgentRunResult>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/agent/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/agent/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,OAAO,KAAK,EACV,OAAO,EAGR,MAAM,gBAAgB,CAAC;AAaxB,OAAO,KAAK,EAEV,WAAW,EACX,kBAAkB,EAClB,cAAc,EAGf,MAAM,YAAY,CAAC;AAKpB,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,WAAW,EACnB,eAAe,EAAE,OAAO,EAAE,EAC1B,OAAO,EAAE,kBAAkB,EAC3B,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,cAAc,CAAC,CAkSzB"}