anchor-ai-sdk 0.1.6 → 0.1.7

package/README.md

@@ -1,147 +1,382 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/hrithikkoduri/anchor-ai-sdk/main/assets/logo-dark.svg" />
-    <img src="https://raw.githubusercontent.com/hrithikkoduri/anchor-ai-sdk/main/assets/logo.svg" alt="Anchor" width="96" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/hrithikkoduri/anchor-ai-sdk/d4e34e41ccb6fbb83d4c54824dd3383b5e84adc4/assets/readme-hero-dark.svg" />
+    <img src="https://raw.githubusercontent.com/hrithikkoduri/anchor-ai-sdk/d4e34e41ccb6fbb83d4c54824dd3383b5e84adc4/assets/readme-hero.svg" alt="Anchor. Your agent. Your machine. One runtime to wire them together." width="1200" />
   </picture>
 </p>
 
-<h1 align="center">Anchor</h1>
+<p align="center">
+  <strong>A TypeScript agent harness SDK.</strong><br />
+  Define the behavior. Choose the machine. Let the shared runtime handle the turns.
+</p>
 
 <p align="center">
-  <strong>Loop-first, sandbox-first agent harness SDK.</strong><br />
-  Give it a task and a machine; it reasons, runs tools, checks its own work, and keeps the receipts.
+  <a href="https://www.npmjs.com/package/anchor-ai-sdk"><img src="https://img.shields.io/npm/v/anchor-ai-sdk?style=flat-square&color=c2410c" alt="npm version" /></a>
+  <a href="https://github.com/hrithikkoduri/anchor-ai-sdk/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/hrithikkoduri/anchor-ai-sdk/ci.yml?style=flat-square&label=ci&color=111114" alt="CI status" /></a>
+  <a href="https://github.com/hrithikkoduri/anchor-ai-sdk/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-111114?style=flat-square" alt="MIT license" /></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A520-111114?style=flat-square" alt="Node.js 20 or newer" />
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/anchor-ai-sdk"><img src="https://img.shields.io/npm/v/anchor-ai-sdk?style=flat-square&color=0f1115" alt="npm" /></a>
-  <a href="https://github.com/hrithikkoduri/anchor-ai-sdk/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/hrithikkoduri/anchor-ai-sdk/ci.yml?style=flat-square&label=ci&color=0f1115" alt="CI" /></a>
-  <a href="https://github.com/hrithikkoduri/anchor-ai-sdk/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/anchor-ai-sdk?style=flat-square&color=0f1115" alt="license" /></a>
-  <img src="https://img.shields.io/node/v/anchor-ai-sdk?style=flat-square&color=0f1115" alt="node" />
+  <a href="https://anchor-sdk.dev/docs.html"><strong>Documentation</strong></a> ·
+  <a href="#quickstart">Quickstart</a> ·
+  <a href="#one-sandbox-interface">Sandboxes</a> ·
+  <a href="#make-the-agent-yours">Custom agents</a> ·
+  <a href="https://anchor-sdk.dev/benchmarks.html">Benchmarks</a>
 </p>
 
 ---
 
-Most agent harnesses give you a loop and leave the hard parts to you: a
-context that grows until it dies, a trace you can't replay, a "done" you can't
-trust. Anchor ships the hard parts.
-
-- **Evidence, never vibes.** Every tool result is recorded on
-  `AgentResult.evidence`; `run_tests` stamps the tree hash it ran against and
-  `latestEvidenceForTree` ties a green run to the *exact* bytes (fail-closed
-  when the tree can't be inspected). The engine carries evidence and never
-  reads success out of a confident sentence; what to gate on it is your
-  policy, not a hidden wall.
-- **Durable by construction.** Conversation, workspace, and the agent's own
-  notes survive folds, restarts, and budget deaths; the SDK ships the
-  resumption primitives (thread store, checkpoints, phase pauses, revival
-  planning), so resuming is wiring, not research.
-- **Sandbox-first.** The machine is part of the design, not an afterthought:
-  one provider contract, adapters accepted by an executable conformance
-  suite.
-
-## Out of the box
-
-| | |
+Anchor runs the **model → tools → observations → model** loop around your agent.
+It combines configurable guardrails, context compaction, continuation primitives,
+and structured events with a sandbox layer that can also be used on its own.
+
+**Your app keeps control of the model, prompts, tools, storage, credentials, and
+release policy.** There is no requirement to turn an agent into a workflow graph.
+
+| Build around | What Anchor supplies |
 | --- | --- |
-| **Agent loop with dials** | Budgets (steps / tokens / USD), repeated-call detection, silent-tool and verbose-turn advisories, a per-call output cap (16k, nudge at 8k; a capped prose turn continues once instead of ending), and assistant-text elision (20k replay, 12k head-only when capped, spilled and pointed at); guardrails on by default, each with an off switch. Phases describe the approach, never a second gated execution engine. |
-| **Streaming by default** | One wire path: every model call streams. Text and reasoning deltas, tool calls, compaction, checkpoints, and finishes all arrive as typed events. |
-| **Durable memory** | `ThreadStore` carries conversation across runs; compaction is derived from the model's *real* context window; reasoning is journaled but never re-sent. |
-| **Notes & spill storage** | A reserved `.anchor/notes.md` (git-excluded, checkpoint-carried) is the agent's durable memory across folds; oversized tool output spills to sandbox files and stays addressable instead of vanishing. |
-| **Revival** | A dying run leaves a handoff (`request_revival`); `planRevival` + `ThreadBudget` decide how to fund the next run; **same task, phase, and budget**, and when the thread's caps are spent, a human gets the note, quoting the agent's own words on what remains. |
-| **Snapshots & resume** | A pluggable snapshot hook (git-backed by default, push optional), phase-boundary pauses, heartbeats and cross-process cancel polling owned by the engine. |
-| **Traces you can replay** | One fanout: one sequence number, redaction applied before *every* sink; NDJSON file, database rows, and a live projector share the same ordering. |
-| **Sandbox plugins** | One `SandboxProvider` contract: Heyo microVMs, Docker, local. Capabilities are promises; the conformance suite holds adapters to them. Store-backed sessions give adopt-and-fallback continuity for free. |
-| **Typed handoffs** | `finish({ handoff })` is shaped by *your* JSON schema; the engine declares the parameter, carries the object, and never interprets it. |
-| **Priced & windowed models** | `llmFromCatalog` reads live prices and the genuine context window from the provider catalog; budgets and compaction configure themselves correctly. |
-
-## Ten lines to a working agent
+| **Your agent** | Chat and coding bundles, or your own strategy and toolset. Phases label the approach; they are not permissions. |
+| **Your machine** | One `SandboxProvider` / `Sandbox` surface for Heyo Computer, E2B, Docker, and local development. |
+| **Longer tasks** | Conversation compaction, thread-store interfaces, working notes, checkpoints, and opt-in revival planning. |
+| **Observable execution** | Streaming events, tool-result metadata, NDJSON/custom trace sinks, and replay helpers. |
+
+## Quickstart
 
 ```bash
 npm install anchor-ai-sdk
 ```
 
-```ts
+Save as `agent.mjs`. This is ordinary JavaScript with ES modules; `.js` also works
+when your `package.json` contains `"type": "module"`.
+
+```js
 import { chatAgent, llmFromCatalog, runAgent } from "anchor-ai-sdk";
 
-const { llm } = await llmFromCatalog({
+const { llm, compaction } = await llmFromCatalog({
   baseUrl: "https://openrouter.ai/api/v1",
-  apiKey: process.env.OPENROUTER_KEY!,
-  model: "z-ai/glm-5.3",
+  apiKey: process.env.OPENROUTER_KEY,
+  model: process.env.MODEL ?? "z-ai/glm-5.3",
 });
 
 const result = await runAgent(
-  { task: "Explain what this repository does" },
-  { llm, agent: chatAgent },
+  { task: "Explain exponential backoff in plain English" },
+  { llm, compaction, agent: chatAgent },
 );
+
 console.log(result.summary);
 ```
 
-## Give it a machine
+```bash
+export OPENROUTER_KEY="your-key"
+node agent.mjs
+```
+
+No sandbox is needed for this chat example. Model calls may incur cost.
+`llmFromCatalog` uses provider pricing and context-window metadata when available;
+pass its returned `compaction` settings to the engine as shown. Catalog lookup is
+best-effort; configure overrides and fallbacks for endpoints without this metadata.
+
+## One sandbox interface
+
+**Configure the provider once. Keep the agent-facing machine interface the same.**
+The same layer works with the built-in coding tools, custom agents, or direct
+`sandbox.exec()` calls without an agent.
+
+| Provider | Import | Boot configuration |
+| --- | --- | --- |
+| **Heyo Computer** | `anchor-ai-sdk/sandbox/heyo` | Image artifact/store on the provider; host-built image kinds are also supported. |
+| **E2B** | `anchor-ai-sdk/sandbox/e2b` | A prepared template name or ID, **not** an arbitrary Docker image at create time. |
+| **Docker** | `anchor-ai-sdk/sandbox/docker` | An explicit container image, Docker CLI, and running daemon. |
+| **Local** | `anchor-ai-sdk/sandbox/local` | Host processes and a working directory. **No isolation; trusted dev/CI only.** |
+
+Choose one of the configurations below. Each defines `provider`; the common
+runner that follows uses the `llm` and `compaction` from the quickstart.
+
+<details open>
+<summary><strong>Heyo Computer: choose an image and machine size</strong></summary>
+
+```bash
+npm install @heyocomputer/hws
+```
+
+```js
+import { heyo } from "anchor-ai-sdk/sandbox/heyo";
+
+const provider = heyo({
+  token: requiredEnv("HEYO_TOKEN"),
+  server: requiredEnv("HEYO_SERVER"),
+  namespace: requiredEnv("HEYO_NAMESPACE"),
+  image: requiredEnv("HEYO_IMAGE"),
+  imageKind: "artifact",
+  imageStore: requiredEnv("HEYO_IMAGE_STORE"),
+  sizeClass: "small",
+  diskSizeGb: 10,
+});
+```
+
+Use an artifact/store you can access and a toolchain suitable for the task.
+Heyo configures its image on the provider and rejects per-sandbox `image` and
+`workspacePath` overrides. `requiredEnv` is defined in the shared runner below.
+
+</details>
+
+<details>
+<summary><strong>E2B: choose a prepared template</strong></summary>
+
+```bash
+npm install 'e2b@^2.56'
+```
+
+```js
+import { e2b } from "anchor-ai-sdk/sandbox/e2b";
+
+const provider = e2b({
+  apiKey: requiredEnv("E2B_API_KEY"),
+  template: requiredEnv("E2B_TEMPLATE"),
+  timeoutMs: 60 * 60_000, // sandbox lifetime, not a command timeout
+});
+```
+
+Build a template with `bash`, `git`, coreutils (including `timeout`), and the
+language tools your task needs. `spec.image` can override the template per run;
+`workspacePath` points to a Git workspace already prepared inside it. Neither
+option turns a Docker image name into an E2B template automatically.
+
+</details>
 
-```ts
-import { codingAgent, runAgent } from "anchor-ai-sdk";
+<details>
+<summary><strong>Docker: supply your container image</strong></summary>
+
+```js
 import { docker } from "anchor-ai-sdk/sandbox/docker";
 
-const sandbox = docker().create({
-  repoUrl: "https://github.com/you/your-repo",
-  ref: "main",
+const provider = docker({
+  image: requiredEnv("ANCHOR_DOCKER_IMAGE"),
+});
+```
+
+The image must already contain the required tools; Anchor does not infer or
+install your repository's dependencies. `spec.image` overrides the default.
+Use `workspacePath` only when the image already contains the Git workspace.
+
+</details>
+
+### Pass the machine to an agent
+
+Combine **one** provider configuration above with this runner and the model setup
+from the quickstart. Merge imports when composing an existing application.
+
+```js
+import { codingAgent } from "anchor-ai-sdk";
+
+function requiredEnv(name) {
+  const value = process.env[name];
+  if (!value) throw new Error(`Set ${name} before running this example.`);
+  return value;
+}
+
+const sandbox = provider.create({
+  repoUrl: requiredEnv("REPO_URL"),
+  ref: process.env.REPO_REF ?? "main",
 });
-await sandbox.start();
+
 try {
+  await sandbox.start();
   const result = await runAgent(
-    { task: "Run the tests and fix the failing case" },
-    { llm, agent: codingAgent, sandbox },
+    { task: "Run the tests and report the results" },
+    { llm, compaction, agent: codingAgent, sandbox },
   );
-  console.log(result.summary, result.checkpointRef);
+  console.log(result.summary, result.reason, result.evidence);
 } finally {
   await sandbox.destroy();
 }
 ```
 
-Runnable versions of both snippets live in [`examples/`](https://github.com/hrithikkoduri/anchor-ai-sdk/tree/main/examples), including
-a non-coding agent (its own strategy and tool, no sandbox).
+Provider boot settings and optional capabilities differ. Retention needs a cleanup
+policy; remote machines and model calls can cost money. Private HTTPS repositories
+can use `spec.git.token`, a caller-supplied credential callback.
+
+The latest Docker adapter also supports `spec.egress: "none"`: it disconnects
+container networks after `start()` setup. Other adapters reject that setting.
+This is not a claim that all providers offer equivalent isolation.
+
+**[Configuration examples](https://anchor-sdk.dev/docs.html#machine)** ·
+**[Provider contract and image guide](https://github.com/hrithikkoduri/anchor-ai-sdk/blob/main/src/sandbox/README.md)**
+
+## Make the agent yours
+
+```text
+Agent       = name + strategy + tools
+Strategy    = system prompt + phases + optional context preparation
+Tool        = model-visible JSON Schema + your handler
+runAgent    = task + agent + model + optional sandbox + runtime settings
+```
+
+Use `chatAgent` or `codingAgent`, compose a bundle, or pass `strategy` and `tools`
+separately. A custom agent is not required to be a coding agent or use a machine.
+
+<details>
+<summary><strong>Example: a small policy assistant with its own tool</strong></summary>
+
+This fragment uses `llm` and `compaction` from the quickstart. The policy is demo
+data; a real service needs your authorization, validation, and output limits.
+
+```js
+import { defineTool, requireString } from "anchor-ai-sdk";
+
+const policies = new Map([
+  ["refunds", "Refunds are available within 30 days with the original receipt."],
+]);
+
+const lookupPolicy = defineTool(
+  {
+    name: "lookup_policy",
+    description: "Look up a policy by topic.",
+    parameters: {
+      type: "object",
+      properties: { topic: { type: "string" } },
+      required: ["topic"],
+    },
+  },
+  async (input) => {
+    const policy = policies.get(requireString(input, "topic").trim().toLowerCase());
+    return { ok: policy !== undefined, content: policy ?? "No policy found." };
+  },
+);
+
+const policyAgent = {
+  name: "policy-assistant",
+  strategy: {
+    name: "policy",
+    phases: [{ id: "answer", goal: "Answer using the retrieved policy." }],
+    requiredTools: ["lookup_policy"],
+    systemPrompt: () =>
+      "Look up policy before making policy claims. Say when it is unknown.",
+  },
+  tools: [lookupPolicy],
+};
+
+const answer = await runAgent(
+  { task: "Can I get a refund after 20 days?" },
+  { llm, compaction, agent: policyAgent },
+);
+console.log(answer.summary);
+```
+
+The schema is declared to the model; `defineTool` does not perform full JSON
+Schema validation. It catches thrown handler errors as failed tool results.
+Validate inputs and enforce permissions in your implementation.
+
+</details>
+
+**[Tools and schemas](https://anchor-sdk.dev/docs.html#tools)** ·
+**[Runnable SDK examples](https://github.com/hrithikkoduri/anchor-ai-sdk/tree/main/examples)**
+
+## Configure the runtime, not another loop
+
+| Capability | Your controls |
+| --- | --- |
+| **Budgets and correction** | Step/token/known-dollar budgets, repeated-call detection, silent-tool and visible-verbosity nudges, prose checkpoints, and per-call output requests. |
+| **Context and memory** | Catalog-derived or explicit compaction, supplied thread stores, agent-authored notes, and best-effort output spill. |
+| **Revival and resume** | Opt-in budget warnings, `request_revival`, `planRevival`, and `ThreadBudget`. Your app persists state and decides whether to fund or enqueue another run. |
+| **Snapshots and lifecycle** | Git-backed or custom snapshot hooks, optional push, phase-boundary pauses, heartbeats, and cancellation. |
+| **Streaming and traces** | Raw `onEvent` updates; sequenced, pattern-redacted `traceSinks`; NDJSON files, custom sinks, live projection, and replay. |
+| **Execution evidence** | Tool names/status/metadata plus recorded test-command outcomes and optional post-run Git freshness checks. Your app defines verification and release gates. |
 
-## Providers
+<details>
+<summary><strong>Example: limits, nudges, compaction, and a recorded trace</strong></summary>
 
-| subpath | backend | status |
+Runtime options for a model and started sandbox configured by your host:
+
+```js
+import { JsonlTrace } from "anchor-ai-sdk";
+import { randomUUID } from "node:crypto";
+
+const tracePath = "./traces/" + randomUUID() + ".ndjson";
+
+const result = await runAgent({ task: "Investigate the failing test" }, {
+  llm, sandbox, agent: codingAgent,
+  budgets: { maxSteps: 60, maxUsd: 3 },
+  compaction: { maxEstimatedTokens: 60_000, keepRecentTokens: 15_000 },
+  guardrails: {
+    repeatedToolCallLimit: 3,
+    toolOnlyNudgeLimit: 8,
+    verboseTurnLimit: 8_000,
+    proseCheckpoint: true,
+  },
+  maxOutputTokens: 16_000,
+  traceSinks: [new JsonlTrace(tracePath)],
+  onEvent(event) {
+    if (event.type === "llm_text_delta") process.stdout.write(event.text);
+  },
+});
+```
+
+Run usage is checked between calls and can overshoot a budget. Output limits are
+requested from the provider. Compaction is lossy summarization using estimated
+token sizes; persistence and spill require working storage. Trace redaction is
+pattern-based, not a guarantee that all secrets are removed; raw `onEvent` events
+are not redacted. Use distinct trace files/IDs per run in your application.
+
+</details>
+
+**[Compaction](https://anchor-sdk.dev/docs.html#compaction)** ·
+**[Course correction](https://anchor-sdk.dev/docs.html#correction)** ·
+**[Revival and host-side resume](https://anchor-sdk.dev/docs.html#revival)** ·
+**[Streaming and detailed traces](https://anchor-sdk.dev/docs.html#traces)**
+
+> **A completed run is not a correctness certificate.** `run_tests` records a
+> command outcome and, when available, a Git hash captured **after** the command.
+> `latestEvidenceForTree` can compare it with the current tree, but does not prove
+> an immutable tested snapshot, require a full suite, or inspect assertions.
+
+## Test the machine contract
+
+`runSandboxConformance(provider)` from `anchor-ai-sdk/testing` exercises the
+public sandbox contract: command results, deadlines, environment handling, Git
+checkpoints, retention/adoption, and declared optional capabilities.
+
+The repository configures local and Docker conformance in CI. Heyo and E2B live
+suites are opt-in and credential-gated; having a suite is not certification that
+every account, image, or template has passed it. Custom providers can use the
+same contract and tests without rewriting the agent engine.
+
+**[Conformance setup](https://anchor-sdk.dev/docs.html#conformance)** ·
+**[Test source](https://github.com/hrithikkoduri/anchor-ai-sdk/tree/main/tests)**
+
+## Evaluated, with the limits visible
+
+The completed **Parasail GLM 5.3 / SWE-bench Lite-10** records show:
+
+| | Anchor | mini-swe-agent |
 | --- | --- | --- |
-| `anchor-ai-sdk/sandbox/heyo` | Heyo Cloud microVMs (Firecracker) | production path; conformance + live tests |
-| `anchor-ai-sdk/sandbox/docker` | containers on the local daemon | conformance-tested in CI |
-| `anchor-ai-sdk/sandbox/e2b` | E2B cloud sandboxes (remote) | conformance-tested live (`base` template); opt-in in CI |
-| `anchor-ai-sdk/sandbox/local` | this host, **no isolation** | dev / CI only |
-| n/a | Daytona | planned |
-
-E2B boots a **template**, not an arbitrary Docker image at create time: pass
-`template` (or let `SandboxSpec.image` name one) and build it with the tools
-the task needs. Pause/resume powers retain/adopt, and native sandbox forking
-powers `fork()`.
-
-A backend is "done" when `runSandboxConformance(provider)` from
-`anchor-ai-sdk/testing` passes: exec fidelity, kill deadlines, env secrets,
-checkpoints, retain/adopt, git identity, pushes, and `fork` where declared.
-See [`src/sandbox/README.md`](https://github.com/hrithikkoduri/anchor-ai-sdk/blob/main/src/sandbox/README.md) for the provider guide.
-
-## Proof, not promises
-
-- **Tests:** the engine, tools, trace layer, and every provider scenario run
-  in CI: local conformance always, Docker conformance on a purpose-built
-  image. Live microVM conformance is opt-in with your own Heyo credentials
-  (the suite skips without them).
-- **Genericity guards:** executable rules keep the package consumer-neutral:
-  no product nouns, no env reads, SDKs behind subpaths. They run in the same
-  suite as everything else.
-- **Evaluation:** Anchor vs mini-swe-agent on SWE-bench Lite (same
-  container, same model, same official grader), resolved the same 7/10 at
-  roughly **one-third of the cost**
-  ([`evals/benchmarks/swe-bench/results/comparison.md`](https://github.com/hrithikkoduri/anchor-ai-sdk/blob/main/evals/benchmarks/swe-bench/results/comparison.md)).
-
-## Status
-
-**Early alpha (0.x).** The API will move before 1.0, so pin exact versions. The
-[`DECISIONS.md`](https://github.com/hrithikkoduri/anchor-ai-sdk/blob/main/DECISIONS.md) is the engineering log: every API has a written
-reason, and the reasons moved with the code when this repo was extracted from
-its monorepo.
-
-- Repo / issues: [github.com/hrithikkoduri/anchor-ai-sdk](https://github.com/hrithikkoduri/anchor-ai-sdk)
-- Docs: [anchor-sdk.dev](https://anchor-sdk.dev) (coming)
-- License: MIT
+| **Resolved** | **9 / 10** | **9 / 10** |
+| Remaining task | Sympy patch unresolved | Matplotlib patch extraction failed; empty patch |
+| Recorded usage | 11,363,962 tokens; $4.3162 | Not reported; no cost ratio claimed |
+| Published limits | 120 steps / 25M tokens | Its own 250-step / $3 loop |
+
+Both records name `zai-org/GLM-5.3` on Parasail, temperature 0, seed 42, and
+Docker-backed tasks. This is a selected ten-task sample with different budgets
+and an extraction failure, not the full benchmark or a general superiority
+claim. The older 7/10 OpenRouter cost comparison is separate historical context.
+
+**[Benchmark explorer](https://anchor-sdk.dev/benchmarks.html)** ·
+**[Anchor artifacts](https://github.com/hrithikkoduri/anchor-ai-sdk/tree/main/evals/benchmarks/swe-bench/results/glm53-parasail)** ·
+**[Mini artifacts](https://github.com/hrithikkoduri/anchor-ai-sdk/tree/main/evals/benchmarks/swe-bench/results/glm53-mini)**
+
+## Status and contributing
+
+**Early alpha, 0.x.** Pin exact versions and test your integration. Provider and
+runtime features are version-specific; the current source may be ahead of the
+installed package. Daytona, agent teams, and consumer skill bundles remain
+roadmap work in the reviewed source.
+
+Questions, bug reports, and provider contributions are welcome. Keep mechanics in
+the SDK and product policy in the consumer; provider changes should include
+conformance coverage and an honest capability declaration.
+
+**[Issues](https://github.com/hrithikkoduri/anchor-ai-sdk/issues)** ·
+**[Roadmap](https://github.com/hrithikkoduri/anchor-ai-sdk/blob/main/ROADMAP.md)** ·
+**[Engineering decisions](https://github.com/hrithikkoduri/anchor-ai-sdk/blob/main/DECISIONS.md)** ·
+**[MIT license](https://github.com/hrithikkoduri/anchor-ai-sdk/blob/main/LICENSE)**

package/dist/engine/background.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Background-job delivery — the engine's half.
+ *
+ * A provider with `pollJob` lets `bash` detach a long command: the tool returns
+ * immediately with a job id. From there the engine owns the result: it polls
+ * outstanding jobs at every turn boundary, injects a finished one as a
+ * runtime-only message (never persisted, never shown to the user), and — when
+ * the run is about to end — waits for what is left instead of dropping it.
+ *
+ * Nothing here is provider-specific: `pollJob` returning `undefined` means
+ * "still running", and a throw means the receipt is gone.
+ */
+import type { ExecResult, Sandbox } from "../sandbox/types.js";
+import type { BackgroundJob } from "./types.js";
+/** How long to sleep between polls while waiting for a run-ending job. */
+export declare const BACKGROUND_POLL_MS = 500;
+export interface FinishedJob {
+    job: BackgroundJob;
+    result: ExecResult;
+}
+export interface LostJob {
+    job: BackgroundJob;
+    error: string;
+}
+export interface PollOutcome {
+    finished: FinishedJob[];
+    running: BackgroundJob[];
+    lost: LostJob[];
+}
+/** One non-blocking round over every outstanding job. */
+export declare function pollBackgroundJobs(sandbox: Sandbox | undefined, jobs: BackgroundJob[]): Promise<PollOutcome>;
+/**
+ * Wait for the outstanding jobs, bounded by each job's own deadline + grace.
+ * Used only when a run is about to finish normally: ending the run while a
+ * job is still out there would silently lose its result.
+ */
+export declare function waitForBackgroundJobs(sandbox: Sandbox | undefined, jobs: BackgroundJob[], opts?: {
+    signal?: AbortSignal;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<PollOutcome>;
+/**
+ * The runtime message the model sees. The body goes through the SAME
+ * truncate-and-spill path as a normal tool result, so a long test log is
+ * bounded and the full text stays addressable in scratch.
+ */
+export declare function renderBackgroundResult(job: FinishedJob, sandbox: Sandbox | undefined): Promise<string>;
+export declare function renderLostJob(job: LostJob): string;
+//# sourceMappingURL=background.d.ts.map

package/dist/engine/background.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background.d.ts","sourceRoot":"","sources":["../../src/engine/background.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAG/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAItC,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,aAAa,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,aAAa,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAED,yDAAyD;AACzD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,IAAI,EAAE,aAAa,EAAE,GACpB,OAAO,CAAC,WAAW,CAAC,CAyBtB;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,IAAI,EAAE,aAAa,EAAE,EACrB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAAO,GACzE,OAAO,CAAC,WAAW,CAAC,CAwCtB;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,OAAO,GAAG,SAAS,GAC3B,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAKlD"}

package/dist/engine/background.js

@@ -0,0 +1,98 @@
+import { formatExec } from "../tools/types.js";
+import { spillOrTruncate } from "../tools/truncate.js";
+/** How long to sleep between polls while waiting for a run-ending job. */
+export const BACKGROUND_POLL_MS = 500;
+/** Grace past the job's own deadline before we call the receipt lost. */
+const DEADLINE_GRACE_MS = 30_000;
+/** One non-blocking round over every outstanding job. */
+export async function pollBackgroundJobs(sandbox, jobs) {
+    if (!sandbox?.pollJob || jobs.length === 0) {
+        return { finished: [], running: [...jobs], lost: [] };
+    }
+    const finished = [];
+    const running = [];
+    const lost = [];
+    for (const job of jobs) {
+        try {
+            const result = await sandbox.pollJob(job.jobId, {
+                startedAt: job.startedAt,
+                ...(job.timeoutSecs !== undefined
+                    ? { timeoutSecs: job.timeoutSecs }
+                    : {}),
+            });
+            if (result)
+                finished.push({ job, result });
+            else
+                running.push(job);
+        }
+        catch (err) {
+            lost.push({
+                job,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return { finished, running, lost };
+}
+/**
+ * Wait for the outstanding jobs, bounded by each job's own deadline + grace.
+ * Used only when a run is about to finish normally: ending the run while a
+ * job is still out there would silently lose its result.
+ */
+export async function waitForBackgroundJobs(sandbox, jobs, opts = {}) {
+    // Without a poller there is nothing to wait on; end the run and report the
+    // jobs instead of sleeping until a deadline that can never be observed.
+    if (!sandbox?.pollJob || jobs.length === 0) {
+        return { finished: [], running: [...jobs], lost: [] };
+    }
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const finished = [];
+    const lost = [];
+    let remaining = [...jobs];
+    while (remaining.length > 0) {
+        if (opts.signal?.aborted)
+            break;
+        const outcome = await pollBackgroundJobs(sandbox, remaining);
+        finished.push(...outcome.finished);
+        lost.push(...outcome.lost);
+        remaining = outcome.running;
+        if (remaining.length === 0)
+            break;
+        const now = Date.now();
+        const expired = remaining.filter((job) => now >
+            job.startedAt + ((job.timeoutSecs ?? 3600) + 30) * 1000 +
+                DEADLINE_GRACE_MS);
+        for (const job of expired) {
+            lost.push({
+                job,
+                error: "no result before the job's deadline",
+            });
+        }
+        if (expired.length > 0) {
+            remaining = remaining.filter((job) => !expired.includes(job));
+            if (remaining.length === 0)
+                break;
+        }
+        await sleep(BACKGROUND_POLL_MS);
+    }
+    return { finished, running: remaining, lost };
+}
+/**
+ * The runtime message the model sees. The body goes through the SAME
+ * truncate-and-spill path as a normal tool result, so a long test log is
+ * bounded and the full text stays addressable in scratch.
+ */
+export async function renderBackgroundResult(job, sandbox) {
+    const { result } = job;
+    const label = job.job.command ? ` (${job.job.command})` : "";
+    const status = result.timedOut
+        ? `timed out (exit ${result.exitCode})`
+        : `exit ${result.exitCode}`;
+    const body = await spillOrTruncate(formatExec(result, job.job.timeoutSecs ?? 120), { sandbox, label: `background ${job.job.tool}` });
+    return `[runtime] Background job ${job.job.jobId}${label} finished: ${status}.\n${body}`;
+}
+export function renderLostJob(job) {
+    return (`[runtime] Background job ${job.job.jobId} is no longer readable: ${job.error}. ` +
+        `Do not assume it completed; check the workspace or rerun it if the result matters.`);
+}
+//# sourceMappingURL=background.js.map

package/dist/engine/background.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background.js","sourceRoot":"","sources":["../../src/engine/background.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AACtC,yEAAyE;AACzE,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAkBjC,yDAAyD;AACzD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAA4B,EAC5B,IAAqB;IAErB,IAAI,CAAC,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3C,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IACxD,CAAC;IACD,MAAM,QAAQ,GAAkB,EAAE,CAAC;IACnC,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE;gBAC9C,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,GAAG,CAAC,GAAG,CAAC,WAAW,KAAK,SAAS;oBAC/B,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE;oBAClC,CAAC,CAAC,EAAE,CAAC;aACR,CAAC,CAAC;YACH,IAAI,MAAM;gBAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;;gBACtC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,IAAI,CAAC;gBACR,GAAG;gBACH,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAA4B,EAC5B,IAAqB,EACrB,IAAI,GAAoE,EAAE;IAE1E,2EAA2E;IAC3E,wEAAwE;IACxE,IAAI,CAAC,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3C,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IACxD,CAAC;IACD,MAAM,KAAK,GACT,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACxE,MAAM,QAAQ,GAAkB,EAAE,CAAC;IACnC,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,IAAI,SAAS,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAE1B,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO;YAAE,MAAM;QAChC,MAAM,OAAO,GAAG,MAAM,kBAAkB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC7D,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3B,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;QAC5B,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM;QAElC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAC9B,CAAC,GAAG,EAAE,EAAE,CACN,GAAG;YACH,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,WAAW,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;gBACrD,iBAAiB,CACtB,CAAC;QACF,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,IAAI,CAAC,IAAI,CAAC;gBACR,GAAG;gBACH,KAAK,EAAE,qCAAqC;aAC7C,CAAC,CAAC;QACL,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM;QACpC,CAAC;QACD,MAAM,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,GAAgB,EAChB,OAA4B;IAE5B,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IACvB,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ;QAC5B,CAAC,CAAC,mBAAmB,MAAM,CAAC,QAAQ,GAAG;QACvC,CAAC,CAAC,QAAQ,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC9B,MAAM,IAAI,GAAG,MAAM,eAAe,CAChC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,EAC9C,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CACjD,CAAC;IACF,OAAO,4BAA4B,GAAG,CAAC,GAAG,CAAC,KAAK,GAAG,KAAK,cAAc,MAAM,MAAM,IAAI,EAAE,CAAC;AAC3F,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,OAAO,CACL,4BAA4B,GAAG,CAAC,GAAG,CAAC,KAAK,2BAA2B,GAAG,CAAC,KAAK,IAAI;QACjF,oFAAoF,CACrF,CAAC;AACJ,CAAC"}