anchor-ai-sdk 0.1.8 → 0.1.9

package/README.md

@@ -152,8 +152,9 @@ const provider = heyo({
 ```
 
 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.
+Heyo configures its default image on the provider. With `imageKind: "artifact"`,
+`spec.image` can override the artifact per sandbox. `workspacePath` can select
+a checkout already in the image. `requiredEnv` is defined in the shared runner below.
 
 </details>
 
@@ -231,24 +232,78 @@ try {
 
 Provider boot settings and optional capabilities differ. Per-sandbox
 `spec.image` is supported by Docker and E2B (as a template name), and by Heyo
-for artifact refs; Local rejects it. Providers that can build/publish expose
-`imagePublisher`, also available as `anchor image publish`.
-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.
-
-Providers that can build images expose the common `imagePublisher` contract and
-the `anchor image publish` command, so Docker, E2B, and Heyo each use their own
-native registry while the caller keeps one shape. `anchor image publish --help`
-shows the flags. Per-provider instructions are in
+for artifact refs; Local rejects it. 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 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.
+
+### Long-lived processes
+
+`exec()` is one-shot. When a consumer needs a REPL, watcher, dev server, or
+language server, providers that declare `capabilities.processStream` also expose
+`openProcess()`:
+
+```js
+const proc = await sandbox.openProcess("node", ["server.js"], {
+  cwd: sandbox.workspace,
+  timeoutSecs: 3600,
+});
+await proc.write("input\n");
+for await (const chunk of proc.stdout) process.stdout.write(chunk);
+await proc.endInput();
+await proc.wait();
+```
+
+Streams, `wait`, `kill`, deadline/abort handling, and destroy cleanup are
+available. Heyo uses a PTY: stderr is merged, EOF is Ctrl-D, and there is no
+transport drain signal. See the [process-stream contract](src/sandbox/README.md).
+
+### Preview a guest port
+
+Providers that declare `capabilities.previewPort` implement
+`sandbox.exposePort(port)`. E2B is the first provider: it returns a public
+`https://` host for the guest port. Anchor does not add preview authentication,
+health checks, iframes, or product UI; that policy belongs to the consumer.
+
+### Publish sandbox images
+
+Providers that can publish expose the common `imagePublisher` contract and the
+`anchor image publish` command. Docker pushes a container image, E2B builds a
+template, and Heyo uploads an artifact through `heyctl`:
+
+```bash
+anchor image publish --provider docker --name ghcr.io/acme/agent:v1 \
+  --dockerfile Dockerfile --context .
+```
+
+Use the returned `ref` as `spec.image`, or merge Heyo's provider config. This is
+provider-native publishing, not a shared Anchor registry. Live registry paths
+are credential-gated; see
 [docs/sandbox-image-publishing.md](docs/sandbox-image-publishing.md).
 
+### Optional TypeScript LSP
+
+The optional `anchor-ai-sdk/lsp` entry point adds read-only TypeScript/JavaScript
+diagnostics, definition, references, and document symbols over process streams:
+
+```js
+import { createCodingAgent } from "anchor-ai-sdk";
+import { createLspTools } from "anchor-ai-sdk/lsp";
+
+const base = createCodingAgent();
+const agent = { ...base, tools: [...base.tools, ...createLspTools()] };
+```
+
+The sandbox image must provide `typescript-language-server` and `typescript`.
+Search and file reads remain the fallback. See [docs/lsp.md](docs/lsp.md).
+
 **[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)** ·
-**[Optional LSP tools](docs/lsp.md)**
+**[Optional LSP tools](docs/lsp.md)** ·
+**[Changelog](https://anchor-sdk.dev/changelog.html)**
 
 ## Make the agent yours
 
@@ -324,7 +379,7 @@ Validate inputs and enforce permissions in your implementation.
 | 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. |
-| **Reasoning budget** | Per-run `reasoningEffort` (`minimal`–`xhigh`) or an agent-bundle default, sent in the provider's native shape (`reasoning.effort` on OpenRouter, `reasoning_effort` on OpenAI). |
+| **Reasoning budget** | Per-run `reasoningEffort` (`minimal`–`max`) or an agent-bundle default, sent in the provider's native shape (`reasoning.effort` on OpenRouter, `reasoning_effort` on OpenAI). |
 | **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. |
@@ -422,7 +477,8 @@ guessing.
 
 `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.
+checkpoints, retention/adoption, process streams, and declared optional image
+publishing capability.
 
 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
@@ -434,7 +490,35 @@ same contract and tests without rewriting the agent engine.
 
 ## Evaluated, with the limits visible
 
-The completed **Parasail GLM 5.3 / SWE-bench Lite-10** records show:
+### Latest complete harness round: v0.1.7
+
+Anchor versus the external arm (`SWE-agent` for SWE, `Terminus-2` for Terminal)
+on the same selected task set. Means are reported in parentheses.
+
+| Bench | Model | Anchor | External | Delta |
+|---|---|---:|---:|---:|
+| SWE Lite | DeepSeek V4.1 Flash | **7/9 (77.8%)** | 0/10 (0%) | +77.8 pp |
+| SWE Lite | Qwen3 Coder Next | **4/8 (50.0%)** | 0/10 (0%) | +50.0 pp |
+| SWE Pro | DeepSeek V4.1 Flash | **10/10 (100%)** | 6/10 (60%) | +40.0 pp |
+| SWE Pro | Qwen3 Coder Next | **5/10 (50%)** | 3/10 (30%) | +20.0 pp |
+| Terminal | DeepSeek V4.1 Flash | 7/10 (70%) | **8/10 (80%)** | -10.0 pp |
+| Terminal | Qwen3 Coder Next | 1/10 (10%) | **3/10 (30%)** | -20.0 pp |
+
+Anchor’s full-credit denominator excludes failed tasks; external counts all ten.
+The arms use different harnesses, task handling, and budgets. These are selected
+samples, not a general superiority claim. The canonical v0.1.7 artifact was
+measured at `2fbc92b`, while the `v0.1.7` tag points to `08472b1`.
+
+### v0.1.8
+
+There is **no recorded benchmark result for v0.1.8**. The full round was
+interrupted before the Anchor and external arms completed, so partial rows are
+not published or compared. The next benchmark record will be a complete round,
+labeled with its measured source SHA.
+
+### Historical selected sample
+
+The completed **Parasail GLM 5.3 / SWE-bench Lite-10** records remain available:
 
 | | Anchor | mini-swe-agent |
 | --- | --- | --- |
@@ -445,8 +529,7 @@ The completed **Parasail GLM 5.3 / SWE-bench Lite-10** records show:
 
 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.
+and an extraction failure, not the full benchmark or a general superiority claim.
 
 **[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)** ·
@@ -454,16 +537,20 @@ claim. The older 7/10 OpenRouter cost comparison is separate historical context.
 
 ## 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.
+**Early alpha, 0.x. Source version: 0.1.9; latest published release: v0.1.8.** 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, context
+reset, MCP, and consumer skill bundles remain roadmap work in the reviewed
+source. See the [changelog](https://anchor-sdk.dev/changelog.html) for what
+landed in each tag.
 
 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)** ·
+**[Release status](https://github.com/hrithikkoduri/anchor-ai-sdk/blob/main/docs/release-status.md)** ·
+**[Completed tracker](https://github.com/hrithikkoduri/anchor-ai-sdk/blob/main/TRACKER.md)** ·
 **[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/compaction.d.ts

@@ -14,12 +14,41 @@
  * message, so every kept assistant-with-tool_calls has its results with it.
  */
 import type { LLMClient, LLMMessage, LLMUsage } from "../llm/types.js";
+import type { ProgressLedger } from "../ledger/types.js";
 export interface CompactionConfig {
     /** Compact when the conversation estimate exceeds this (estimated tokens, chars/4). */
     maxEstimatedTokens?: number;
     /** How much of the tail to keep verbatim. */
     keepRecentTokens?: number;
 }
+/**
+ * Durable state that replaces the folded part of a task conversation. The
+ * engine builds this with structured output; consumers persist it through
+ * their existing ThreadStore. The core fields are SDK-owned so the next
+ * window can be reconstructed without trusting a prose summary.
+ */
+export interface CompactionHandoff {
+    task: string;
+    requirements: Array<{
+        id: string;
+        text: string;
+        status: string;
+        evidence: string[];
+    }>;
+    completed: string[];
+    currentState: string;
+    openFailures: string[];
+    nextSteps: string[];
+    constraints: string[];
+    lastObservations: string[];
+    git: {
+        head?: string;
+        checkpoint?: string;
+        dirty?: boolean;
+    };
+}
+/** Render the durable handoff as the turn-scoped state block. */
+export declare function renderCompactionHandoff(handoff: CompactionHandoff): string;
 export declare const DEFAULT_COMPACTION: {
     readonly maxEstimatedTokens: 80000;
     readonly keepRecentTokens: 30000;
@@ -49,8 +78,10 @@ export declare function estimateTokens(messages: LLMMessage[]): number;
  */
 export declare function findCompactionCut(messages: LLMMessage[], keepRecentTokens: number): number;
 export interface CompactionOutcome {
-    /** The new running summary (prior summary + folded transcript). */
+    /** A compact prose view for compatibility/events; structured path also has handoff. */
     summary: string;
+    /** Structured state, when the task/ledger path produced it. */
+    handoff?: CompactionHandoff;
     /** The verbatim tail that was kept. */
     keptMessages: LLMMessage[];
     removedCount: number;
@@ -70,4 +101,20 @@ export declare function compactConversation(args: {
     keepRecentTokens: number;
     signal?: AbortSignal;
 }): Promise<CompactionOutcome | null>;
+/**
+ * Fold a task conversation into the SDK-owned handoff contract. This is used
+ * only when a ledger/verifier is active; plain chat keeps the legacy summary
+ * path. A malformed response returns null so the caller retains the intact
+ * conversation rather than silently losing state.
+ */
+export declare function compactConversationStructured(args: {
+    llm: LLMClient;
+    messages: LLMMessage[];
+    previousSummary?: string;
+    previousHandoff?: CompactionHandoff;
+    ledger?: ProgressLedger;
+    git?: CompactionHandoff["git"];
+    keepRecentTokens: number;
+    signal?: AbortSignal;
+}): Promise<CompactionOutcome | null>;
 //# sourceMappingURL=compaction.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/engine/compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGvE,MAAM,WAAW,gBAAgB;IAC/B,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,kBAAkB;aAC7B,kBAAkB,EAAE,KAAM;aAC1B,gBAAgB,EAAE,KAAM;CAChB,CAAC;AAEX;6DAC6D;AAC7D,eAAO,MAAM,sBAAsB,SAAU,CAAC;AAC9C,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,MAAM,EACrB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9C,gBAAgB,CAclB;AAED,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM,CAS7D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,UAAU,EAAE,EACtB,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAiBR;AAED,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,QAAQ,CAAC;CACjB;AAwBD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,GAAG,EAAE,SAAS,CAAC;IACf,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CA0CpC"}
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/engine/compaction.ts"],"names":[],"mappings":"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"}

package/dist/engine/compaction.js

@@ -1,4 +1,138 @@
+import { completeStructured } from "../llm/structured.js";
+import { renderLedger } from "../ledger/ledger.js";
 import { conversationHistory } from "./context.js";
+const HANDOFF_SCHEMA = {
+    type: "object",
+    properties: {
+        task: { type: "string" },
+        requirements: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    id: { type: "string" },
+                    text: { type: "string" },
+                    status: { type: "string" },
+                    evidence: { type: "array", items: { type: "string" } },
+                },
+                required: ["id", "text", "status", "evidence"],
+                additionalProperties: false,
+            },
+        },
+        completed: { type: "array", items: { type: "string" } },
+        currentState: { type: "string" },
+        openFailures: { type: "array", items: { type: "string" } },
+        nextSteps: { type: "array", items: { type: "string" } },
+        constraints: { type: "array", items: { type: "string" } },
+        lastObservations: { type: "array", items: { type: "string" } },
+        git: {
+            type: "object",
+            properties: {
+                head: { type: "string" },
+                checkpoint: { type: "string" },
+                dirty: { type: "boolean" },
+            },
+            additionalProperties: false,
+        },
+    },
+    required: [
+        "task",
+        "requirements",
+        "completed",
+        "currentState",
+        "openFailures",
+        "nextSteps",
+        "constraints",
+        "lastObservations",
+        "git",
+    ],
+    additionalProperties: false,
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function strings(value) {
+    if (!Array.isArray(value))
+        throw new Error("expected an array of strings");
+    return value.map((item) => {
+        if (typeof item !== "string")
+            throw new Error("expected a string");
+        return item;
+    });
+}
+function parseCompactionHandoff(value) {
+    if (!isRecord(value))
+        throw new Error("expected an object");
+    if (typeof value.task !== "string")
+        throw new Error("task must be a string");
+    if (typeof value.currentState !== "string")
+        throw new Error("currentState must be a string");
+    if (!Array.isArray(value.requirements))
+        throw new Error("requirements must be an array");
+    const requirements = value.requirements.map((item) => {
+        if (!isRecord(item))
+            throw new Error("requirement must be an object");
+        if (typeof item.id !== "string" || typeof item.text !== "string")
+            throw new Error("requirement id/text must be strings");
+        if (typeof item.status !== "string")
+            throw new Error("requirement status must be a string");
+        return {
+            id: item.id,
+            text: item.text,
+            status: item.status,
+            evidence: strings(item.evidence),
+        };
+    });
+    const git = isRecord(value.git) ? value.git : {};
+    return {
+        task: value.task,
+        requirements,
+        completed: strings(value.completed),
+        currentState: value.currentState,
+        openFailures: strings(value.openFailures),
+        nextSteps: strings(value.nextSteps),
+        constraints: strings(value.constraints),
+        lastObservations: strings(value.lastObservations),
+        git: {
+            ...(typeof git.head === "string" ? { head: git.head } : {}),
+            ...(typeof git.checkpoint === "string"
+                ? { checkpoint: git.checkpoint }
+                : {}),
+            ...(typeof git.dirty === "boolean" ? { dirty: git.dirty } : {}),
+        },
+    };
+}
+/** Render the durable handoff as the turn-scoped state block. */
+export function renderCompactionHandoff(handoff) {
+    const list = (items) => items.length ? items.map((item) => `- ${item}`).join("\n") : "- none";
+    return [
+        "## Durable task handoff",
+        "This is authoritative state restored after a context reset, not a new user request.",
+        `TASK: ${handoff.task}`,
+        `CURRENT STATE: ${handoff.currentState}`,
+        "",
+        "REQUIREMENTS:",
+        list(handoff.requirements.map((item) => `${item.id} [${item.status}] ${item.text}${item.evidence.length ? ` (evidence: ${item.evidence.join(", ")})` : ""}`)),
+        "",
+        "COMPLETED:",
+        list(handoff.completed),
+        "OPEN FAILURES:",
+        list(handoff.openFailures),
+        "NEXT STEPS:",
+        list(handoff.nextSteps),
+        "CONSTRAINTS:",
+        list(handoff.constraints),
+        "LAST OBSERVATIONS:",
+        list(handoff.lastObservations),
+        ...(handoff.git.head || handoff.git.checkpoint
+            ? [
+                "GIT:",
+                `- head: ${handoff.git.head ?? "unknown"}`,
+                `- checkpoint: ${handoff.git.checkpoint ?? "none"}`,
+            ]
+            : []),
+    ].join("\n");
+}
 export const DEFAULT_COMPACTION = {
     maxEstimatedTokens: 80_000,
     keepRecentTokens: 30_000,
@@ -29,6 +163,11 @@ export function estimateTokens(messages) {
     let chars = 0;
     for (const m of messages) {
         chars += m.content?.length ?? 0;
+        // Provider image pricing varies; count the URL/alt plus a small fixed
+        // overhead so an image-bearing turn is not estimated as free.
+        for (const image of m.images ?? []) {
+            chars += image.url.length + (image.alt?.length ?? 0) + 400;
+        }
         for (const tc of m.tool_calls ?? []) {
             chars += tc.name.length + tc.arguments.length;
         }
@@ -80,6 +219,9 @@ function renderTranscript(messages) {
         else {
             parts.push(`${m.role}: ${m.content ?? ""}`);
         }
+        for (const image of m.images ?? []) {
+            parts.push(`[image ${image.id} ${image.mime}${image.alt ? `: ${image.alt}` : ""}]`);
+        }
     }
     return parts.join("\n");
 }
@@ -124,4 +266,72 @@ export async function compactConversation(args) {
         usage: response.usage,
     };
 }
+/**
+ * Fold a task conversation into the SDK-owned handoff contract. This is used
+ * only when a ledger/verifier is active; plain chat keeps the legacy summary
+ * path. A malformed response returns null so the caller retains the intact
+ * conversation rather than silently losing state.
+ */
+export async function compactConversationStructured(args) {
+    const cut = findCompactionCut(args.messages, args.keepRecentTokens);
+    if (cut === -1)
+        return null;
+    const summarizable = args.messages.slice(1, cut);
+    if (summarizable.length === 0 || estimateTokens(summarizable) === 0)
+        return null;
+    const userContent = [
+        args.previousSummary
+            ? `Previous prose summary:\n${args.previousSummary}\n`
+            : "",
+        args.previousHandoff
+            ? `Previous durable handoff:\n${renderCompactionHandoff(args.previousHandoff)}\n`
+            : "",
+        args.ledger ? `Authoritative ledger:\n${renderLedger(args.ledger)}\n` : "",
+        args.git
+            ? `Git state: ${JSON.stringify(args.git)}\n`
+            : "Git state: unknown\n",
+        `Transcript to fold in:\n${renderTranscript(summarizable)}`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    try {
+        const structured = await completeStructured(args.llm, {
+            name: "compaction_handoff",
+            messages: [
+                {
+                    role: "system",
+                    content: "You compact an agent task into a durable handoff. Preserve the task, requirements and their status, evidence ids, completed work, current state, open failures, next steps, constraints, and last observations. Do not invent completed work or evidence. The ledger is authoritative; keep its requirement ids and statuses. Return only the schema-bound object.",
+                },
+                { role: "user", content: userContent },
+            ],
+            schema: HANDOFF_SCHEMA,
+            parse: parseCompactionHandoff,
+            maxTokens: 2400,
+            signal: args.signal,
+        });
+        return {
+            handoff: {
+                ...structured.value,
+                ...(args.git ? { git: { ...structured.value.git, ...args.git } } : {}),
+            },
+            summary: renderCompactionHandoff({
+                ...structured.value,
+                ...(args.git ? { git: { ...structured.value.git, ...args.git } } : {}),
+            }),
+            keptMessages: args.messages.slice(cut),
+            removedCount: summarizable.length,
+            foldingPreview: previewFold(summarizable),
+            usage: structured.response.usage,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function previewFold(messages) {
+    const folded = renderTranscript(messages);
+    return folded.length > FOLDING_PREVIEW_CHARS
+        ? `${folded.slice(0, FOLDING_PREVIEW_CHARS)}\n[... folded transcript truncated for the record — ${folded.length} chars total ...]`
+        : folded;
+}
 //# sourceMappingURL=compaction.js.map

package/dist/engine/compaction.js.map

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

package/dist/engine/context.d.ts

@@ -9,7 +9,7 @@
 import type { LLMMessage, LLMResponse } from "../llm/types.js";
 export declare function assistantMessage(response: LLMResponse): LLMMessage;
 export declare function toolResultMessage(toolCallId: string, content: string): LLMMessage;
-export declare function userMessage(content: string): LLMMessage;
+export declare function userMessage(content: string, images?: LLMMessage["images"]): LLMMessage;
 /** Working memory contains real conversation and observations, not system
  * prompts or internal orchestration messages. No prefix guessing: a user's
  * text is still their text even if it happens to start with "PHASE:". */

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

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/engine/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE/D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,GAAG,UAAU,CASlE;AAED,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,UAAU,CAEZ;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAEvD;AAED;;yEAEyE;AACzE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAIxE"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/engine/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE/D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,GAAG,UAAU,CASlE;AAED,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,UAAU,CAEZ;AAED,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,GAC5B,UAAU,CAMZ;AAED;;yEAEyE;AACzE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAIxE"}

package/dist/engine/context.js

@@ -10,8 +10,12 @@ export function assistantMessage(response) {
 export function toolResultMessage(toolCallId, content) {
     return { role: "tool", tool_call_id: toolCallId, content };
 }
-export function userMessage(content) {
-    return { role: "user", content };
+export function userMessage(content, images) {
+    return {
+        role: "user",
+        content,
+        ...(images && images.length ? { images } : {}),
+    };
 }
 /** Working memory contains real conversation and observations, not system
  * prompts or internal orchestration messages. No prefix guessing: a user's

package/dist/engine/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/engine/context.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,gBAAgB,CAAC,QAAqB;IACpD,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,OAAO,EACL,QAAQ,CAAC,IAAI,KAAK,EAAE,IAAI,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;YACnD,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,QAAQ,CAAC,IAAI;QACnB,UAAU,EAAE,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;KAC3E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,UAAkB,EAClB,OAAe;IAEf,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACnC,CAAC;AAED;;yEAEyE;AACzE,MAAM,UAAU,mBAAmB,CAAC,QAAsB;IACxD,OAAO,QAAQ,CAAC,MAAM,CACpB,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,CACtE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/engine/context.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,gBAAgB,CAAC,QAAqB;IACpD,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,OAAO,EACL,QAAQ,CAAC,IAAI,KAAK,EAAE,IAAI,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;YACnD,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,QAAQ,CAAC,IAAI;QACnB,UAAU,EAAE,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;KAC3E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,UAAkB,EAClB,OAAe;IAEf,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,OAAe,EACf,MAA6B;IAE7B,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO;QACP,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED;;yEAEyE;AACzE,MAAM,UAAU,mBAAmB,CAAC,QAAsB;IACxD,OAAO,QAAQ,CAAC,MAAM,CACpB,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,CACtE,CAAC;AACJ,CAAC"}

package/dist/engine/events.d.ts

@@ -7,6 +7,7 @@
  * itself never formats anything — it only emits.
  */
 import type { LLMToolCall, LLMUsage } from "../llm/types.js";
+import type { CompactionHandoff } from "./compaction.js";
 /** What a budget-limited run says it still needs — see EngineOptions.revival. */
 export interface RevivalRequest {
     /** Plain language: the work that remains. */
@@ -155,6 +156,8 @@ export type AgentEvent = {
     summaryChars: number;
     /** The summary that replaced the folded span — the compaction's output. */
     summary?: string;
+    /** Structured handoff used by a task/ledger reset. */
+    compaction?: CompactionHandoff;
     /** Truncated transcript of the folded span — the compaction's input. */
     folding?: string;
     usage: LLMUsage;

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

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