@a-dray/aglib 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Dray
+
+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,172 @@
+# aglib
+
+A small TypeScript toolkit for building **your own agent harness**, inside an application you own.
+
+You bring the product — users, tenancy, channels, UI, deployment, policy. aglib gives you a
+session log you can resume, a loop that runs against it, tools under your own permission rule,
+somewhere contained to run them, and four seams with adapters: model, store, sandbox, harness.
+
+> **Pre-release.** The API changes without deprecation aliases, so pin an exact version: `bun add aglib@npm:@a-dray/aglib@<version>`. Both recipes run. The unscoped name is a lookalike of an existing package; the alias keeps imports as `aglib`.
+
+## The shape
+
+```text
+src/
+  json.ts  result.ts  content.ts  agent.ts  run.ts
+
+  session/    entry.ts  log.ts  messages.ts        the log — this IS the session's state
+  tools/      tool.ts  execute.ts                  declaring and running tools
+
+  model/      model.ts    adapters/{openai-compatible,anthropic,fake}/  conformance.ts
+  store/      store.ts    adapters/sqlite.ts        conformance.ts
+  sandbox/    sandbox.ts  adapters/{local,docker}   conformance.ts
+  harness/    harness.ts  adapters/{native,acp}/
+```
+
+Four ports, each `<port>.ts` → `adapters/`. Read one and you can predict the rest. Our own loop is
+`adapters/native`, beside the others rather than above them: it is one implementation of the port,
+and the only thing special about it is that it holds every control point.
+
+**The log is the state, not a record of it.** The loop re-projects its context from committed
+entries every turn and appends results back. There is one representation of a conversation, so
+nothing can drift from it and no test has to prove two views agree.
+
+**One session hands work to another in a single write.** `append({ entries, enqueue })` commits what
+this session did and what another receives, together or not at all — so spawning a child, replying
+to a parent and messaging a peer are one operation, and a handoff cannot be half-done. A delivery
+names where in the recipient's loop it lands: `interrupt` ends the running turn, `turn` is folded into it before its next model call, `next` waits for the one after.
+
+**A killed worker's session is finishable.** `store.next()` answers what has been asked for;
+`store.interrupted()` answers what was being worked when a process stopped existing. Either hands back a
+claim, and a claim is what a run takes:
+
+```ts
+runAgent({ agent, store, sessionId, input: "..." });   // a caller sends
+runAgent({ agent, store, claim });                     // a worker runs what it was handed
+```
+
+The claim carries the session, the position and the queue together, so a worker lines nothing up by
+hand. A claim with an empty queue is a resumption: the log is continued rather than begun again, and
+the tool call that already ran is read from it, never issued twice. A harness that cannot restart
+from history ends that run instead of continuing it, so a session nothing can finish is closed once
+rather than handed out for ever.
+
+**A model is a value, not a name.** A `Model` is a provider, a credential and a model id together;
+picking a different one is picking a different `Model`, and routing between them is a record lookup
+you write. Nothing here resolves a name, so nothing here owns a naming convention — names come *out*
+(`ModelResponse.model`, and what `price` reads) and never go in.
+
+**You are told when to look, and you still keep a heartbeat.** `store.watch()` is an optional
+interrupt line — which session moved, whether it has work owed, nothing else. A wake may be spurious
+or lost by design, so it removes latency rather than the need to ask; without one, a worker polls and
+that interval is the whole of a message's latency.
+
+**Where a port has more than one implementation, it has one executable contract.**
+`aglib/model/conformance`, `aglib/store/conformance` and `aglib/sandbox/conformance` are the cases an
+adapter must pass, as an inert list you run under your own test framework. Point one at a model, a
+store or a sandbox you wrote and find out whether it means what the interface says. A subject
+declares what it actually does — whether its output streams arrive apart, how far its change feed
+reaches — and the suite holds it to exactly that rather than assuming.
+
+## Quickstart
+
+```bash
+bun install --frozen-lockfile
+echo 'OPENROUTER_API_KEY=sk-or-...' > .env
+bun run recipe personal-agent "what did I decide about pricing?"
+```
+
+```ts
+import { runAgent, defineTool, textOf } from "aglib";
+import { createNativeHarness } from "aglib/harness";
+import { createOpenRouterModel } from "aglib/model/adapters/openai-compatible";
+import { createSqliteStore } from "aglib/store/adapters/sqlite";
+import { Database } from "bun:sqlite";
+import { z } from "zod";
+
+const bookkeeper = {
+  id: "bookkeeper", version: "1",
+  instructions: "Answer from the ledger.",
+  harness: createNativeHarness({
+    model: createOpenRouterModel({ apiKey: process.env.OPENROUTER_API_KEY!, model: "deepseek/deepseek-v4-flash" }),
+  }),
+  tools: [defineTool({
+    name: "read_ledger",
+    description: "Read the September ledger.",
+    annotations: { readOnly: true },
+    schema: z.object({}),
+    execute: () => ({ content: "September closes at 1250 GBP." }),
+  })],
+};
+
+const run = runAgent({
+  agent: bookkeeper,
+  store: createSqliteStore({ database: new Database("agent.db") }),
+  input: "What is the September balance?",
+});
+
+for await (const update of run) if (update.type === "text.delta") process.stdout.write(update.text);
+const result = await run.result;
+if (result.status === "completed") console.log(textOf(result.output));
+```
+
+Drop `store` and the same agent runs entirely in memory. Durability is a composition choice,
+not a different program.
+
+A run answers with `usage` on every outcome — completed, cancelled or failed — summed from the entries it committed, so a harness reports no total of its own and a run that burned tokens and then failed says so.
+
+There is no price list here and no spend ceiling. The counts are the fact; the rates are yours, and so is what to do when a run gets expensive.
+
+## Recipes
+
+Two applications, chosen because between them they exercise every seam. They are the
+specification: anything with no call site in one of them should not exist.
+
+| Recipe | What it proves |
+| --- | --- |
+| [`recipes/personal-agent`](recipes/personal-agent/README.md) | The log, compaction, context lifetimes, tools, session search. Memory built entirely *on* the library, not in it. |
+| [`recipes/agent-service`](recipes/agent-service/README.md) | The queue, atomic cross-session handoff, a harness per session, a sandbox per session, live views. |
+
+## What it is not
+
+Not a workflow engine, channel gateway, scheduler, memory product, prompt registry, deployment
+control plane, or finished agent. It does not make model output trustworthy, and a local
+sandbox is a host process, not a sandbox — ask for `isolation: "required"` and a provider that
+cannot deliver it fails rather than pretending. `adapters/docker` is the one that can: a container
+from the local daemon, no account and no vendor SDK. A hosted box is yours to adapt, and
+`agent-service` shows one.
+
+It also ships no price list. Rates go stale between releases and only one provider ever reported a
+cost, so the log carries token counts and the money is arithmetic over a table you pass in.
+
+## Four ways in
+
+aglib is for building the **outer** harness — the durable session, the tools, the policy, the
+orchestration — around whatever does the reasoning inside.
+
+| You want | You do |
+| --- | --- |
+| A loop you own end to end | Use `adapters/native` |
+| Your own reasoning strategy | Write a `Harness` and drop it in |
+| A vendor SDK, deeply integrated | Wrap it as a `Harness` — you keep its prompt, tools and settings, and choose which to override |
+| Somebody else's whole agent, cheaply | Use `adapters/acp` — any agent in the ACP registry, still inside your log, tools and sandbox |
+
+The last two are not equivalent, and `recipes/agent-service` publishes a table of exactly which
+control points each one gives you.
+
+## Development
+
+```bash
+bun run check     # typecheck, tests, build, Node verification, recipes, docs, invariants
+bun run recipe personal-agent "..."
+```
+
+`bun run check` is the green gate. A failing check is a decision, not an obstacle: fix the code,
+or change the check deliberately in the same commit with the reason in the message.
+
+See [`AGENTS.md`](AGENTS.md) for the map, and [`docs/`](docs/) for the four documents that own
+the product.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

package/dist/agent.d.ts

@@ -0,0 +1,158 @@
+import type { Content } from "./content.js";
+import type { Harness } from "./harness/harness.js";
+import type { Decide, Tool } from "./tools/tool.js";
+import type { Delivery, Runnable, Store } from "./store/store.js";
+import type { Update } from "./harness/harness.js";
+import type { Failure } from "./result.js";
+import type { From, Usage } from "./session/entry.js";
+/** An inert declaration. Nothing here opens a connection or holds state. */
+export interface Agent {
+    id: string;
+    /** Bump when instructions, tools or configuration stop being compatible with an existing session. */
+    version: string;
+    instructions: Content;
+    harness: Harness;
+    tools?: readonly Tool[];
+    /** Per-call policy over parsed arguments. Absent means every call executes. */
+    decide?: Decide;
+    /** Runs once as an activation ends, whatever ended it; its deliveries commit with the final entries. */
+    finished?(run: {
+        sessionId: string;
+        runId: string;
+        outcome: "completed" | "failed" | "cancelled";
+        output: Content;
+    }): readonly Delivery[] | Promise<readonly Delivery[]>;
+    /**
+     * Ceilings on one activation, over the facts this library holds: turns and
+     * tool calls are on the log, and a deadline is the clock.
+     *
+     * There is no ceiling on money, and the asymmetry is the point. A spend limit
+     * would have to read a rate table the library does not have and should not
+     * carry, so it would take a function from the caller and then need defending
+     * against it — a code for "you declared a ceiling nothing can hold", a rule
+     * for a generation the function could not price, a check for a price that is
+     * negative or not a number. All of that is the cost of enforcing something
+     * from a fact we do not own, and enforcing it is policy besides: the two
+     * applications that wanted one wanted it to stop at different moments.
+     *
+     * `RunResult.usage` is what a caller needs from here, and it is solid. What
+     * that costs, and what to do about it, is priced by whoever holds the rates.
+     */
+    limits?: {
+        maxTurns?: number;
+        maxToolCalls?: number;
+        deadline?: string;
+    };
+}
+/**
+ * How an activation ended, and what it consumed on the way.
+ *
+ * `usage` is on every outcome, not only a completed one: a run that burned four
+ * dollars of tokens and then failed burned them, and a caller that has to ask
+ * the log to find that out has been handed a result missing the expensive half
+ * of what happened.
+ *
+ * Summed from the `assistant` entries this activation committed, which is why a
+ * harness does not report it — the log already holds every generation, and a
+ * second total is a second answer. Money is not here: the counts are the fact,
+ * and the rates that turn them into money belong to the deployment.
+ */
+export type RunResult = {
+    status: "completed";
+    output: Content;
+    usage: Usage;
+    seq: number;
+} | {
+    status: "cancelled";
+    usage: Usage;
+    seq: number;
+} | {
+    status: "failed";
+    error: Failure;
+    usage: Usage;
+    seq: number;
+};
+export interface AgentRun extends AsyncIterable<Update> {
+    readonly result: Promise<RunResult>;
+    cancel(): void;
+}
+/**
+ * One piece of input for an activation, and where it came from.
+ *
+ * Always the object form, because `Content` may itself be an array of parts and
+ * a bare array therefore cannot say whether it is one multi-part message or
+ * several messages. `RunAgentOptions.input` still takes plain content for the
+ * common case; only the *many* form is required to name each arrival.
+ */
+export interface Arrival {
+    input: Content;
+    from?: From;
+}
+interface RunAgentBase {
+    agent: Agent;
+    /** Opaque application index key, used only when this run creates the session. */
+    key?: string;
+    context?: {
+        run?: string;
+        turn?: string;
+    };
+    signal?: AbortSignal;
+}
+/**
+ * An activation is working one of two things, and never both.
+ *
+ * A caller is **sending** — a person typed, a webhook fired, a test asked a
+ * question. Or a worker is running **what the store handed it**, which carries
+ * the session, the position to write from, and the deliveries to consume, all
+ * as one value that arrived together and cannot be recombined wrongly.
+ *
+ * That second form replaced three fields a worker had to line up by hand:
+ * `sessionId`, the position, and how many deliveries to take. Every one of them
+ * was only ever a field of the claim, so each was a value another field already
+ * determined — and the one that mattered, taking the deliveries, silently
+ * left the input queued for ever when it was forgotten. Both applications
+ * written on this wrote the same eight lines to get it right.
+ */
+export type RunAgentOptions = RunAgentBase & ({
+    /** One message as plain content, one named arrival, or several named arrivals. */
+    input: Content | Arrival | readonly Arrival[];
+    /**
+     * Which session it goes to, as a UUID. A new one is opened when this is
+     * omitted. An application's own naming for a conversation goes in `key`,
+     * which is opaque to the library; a store is entitled to keep a session
+     * id in a `uuid` column and refuse anything else.
+     */
+    sessionId?: string;
+    /** Omit for an ephemeral run: the log lives in memory and nothing is persisted. */
+    store?: Store;
+    claim?: never;
+} | {
+    /**
+     * What `store.next()` or `store.interrupted()` handed this worker.
+     *
+     * Its deliveries become this activation's input and are consumed by the
+     * write that commits them, in the same compare-and-swap that checks the
+     * position — so a worker that loses the race loses its turn and never the
+     * messages. A claim with an empty queue is a **resumption**: nothing opens
+     * it, the loop continues the committed log, and the effect that already
+     * happened is read there rather than asked for again. Only a harness
+     * declaring `recovery: "history"` is given one.
+     */
+    claim: Runnable;
+    /**
+     * Required here, unlike a caller sending. A claim is a position in a log
+     * and a queue to consume, and both of those are the store's — without one
+     * the deliveries would be replayed into memory and left queued for ever.
+     */
+    store: Store;
+    /**
+     * Something the worker is adding of its own, ahead of what was waiting.
+     *
+     * One real use: orientation for a harness whose protocol has no system
+     * prompt, which has nowhere else to go and must lead. Adding nothing is
+     * the ordinary case.
+     */
+    input?: Content | Arrival | readonly Arrival[];
+    sessionId?: never;
+});
+export {};

package/dist/agent.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"","sourcesContent":["import type { Content } from \"./content.js\";\nimport type { Harness } from \"./harness/harness.js\";\nimport type { Decide, Tool } from \"./tools/tool.js\";\nimport type { Delivery, Runnable, Store } from \"./store/store.js\";\nimport type { Update } from \"./harness/harness.js\";\nimport type { Failure } from \"./result.js\";\nimport type { From, Usage } from \"./session/entry.js\";\n\n/** An inert declaration. Nothing here opens a connection or holds state. */\nexport interface Agent {\n  id: string;\n  /** Bump when instructions, tools or configuration stop being compatible with an existing session. */\n  version: string;\n  instructions: Content;\n  harness: Harness;\n  tools?: readonly Tool[];\n  /** Per-call policy over parsed arguments. Absent means every call executes. */\n  decide?: Decide;\n  /** Runs once as an activation ends, whatever ended it; its deliveries commit with the final entries. */\n  finished?(run: {\n    sessionId: string; runId: string;\n    outcome: \"completed\" | \"failed\" | \"cancelled\";\n    output: Content;\n  }): readonly Delivery[] | Promise<readonly Delivery[]>;\n  /**\n   * Ceilings on one activation, over the facts this library holds: turns and\n   * tool calls are on the log, and a deadline is the clock.\n   *\n   * There is no ceiling on money, and the asymmetry is the point. A spend limit\n   * would have to read a rate table the library does not have and should not\n   * carry, so it would take a function from the caller and then need defending\n   * against it — a code for \"you declared a ceiling nothing can hold\", a rule\n   * for a generation the function could not price, a check for a price that is\n   * negative or not a number. All of that is the cost of enforcing something\n   * from a fact we do not own, and enforcing it is policy besides: the two\n   * applications that wanted one wanted it to stop at different moments.\n   *\n   * `RunResult.usage` is what a caller needs from here, and it is solid. What\n   * that costs, and what to do about it, is priced by whoever holds the rates.\n   */\n  limits?: { maxTurns?: number; maxToolCalls?: number; deadline?: string };\n}\n\n/**\n * How an activation ended, and what it consumed on the way.\n *\n * `usage` is on every outcome, not only a completed one: a run that burned four\n * dollars of tokens and then failed burned them, and a caller that has to ask\n * the log to find that out has been handed a result missing the expensive half\n * of what happened.\n *\n * Summed from the `assistant` entries this activation committed, which is why a\n * harness does not report it — the log already holds every generation, and a\n * second total is a second answer. Money is not here: the counts are the fact,\n * and the rates that turn them into money belong to the deployment.\n */\nexport type RunResult =\n  | { status: \"completed\"; output: Content; usage: Usage; seq: number }\n  | { status: \"cancelled\"; usage: Usage; seq: number }\n  | { status: \"failed\"; error: Failure; usage: Usage; seq: number };\n\nexport interface AgentRun extends AsyncIterable<Update> {\n  readonly result: Promise<RunResult>;\n  cancel(): void;\n}\n\n/**\n * One piece of input for an activation, and where it came from.\n *\n * Always the object form, because `Content` may itself be an array of parts and\n * a bare array therefore cannot say whether it is one multi-part message or\n * several messages. `RunAgentOptions.input` still takes plain content for the\n * common case; only the *many* form is required to name each arrival.\n */\nexport interface Arrival { input: Content; from?: From }\n\ninterface RunAgentBase {\n  agent: Agent;\n  /** Opaque application index key, used only when this run creates the session. */\n  key?: string;\n  context?: { run?: string; turn?: string };\n  signal?: AbortSignal;\n}\n\n/**\n * An activation is working one of two things, and never both.\n *\n * A caller is **sending** — a person typed, a webhook fired, a test asked a\n * question. Or a worker is running **what the store handed it**, which carries\n * the session, the position to write from, and the deliveries to consume, all\n * as one value that arrived together and cannot be recombined wrongly.\n *\n * That second form replaced three fields a worker had to line up by hand:\n * `sessionId`, the position, and how many deliveries to take. Every one of them\n * was only ever a field of the claim, so each was a value another field already\n * determined — and the one that mattered, taking the deliveries, silently\n * left the input queued for ever when it was forgotten. Both applications\n * written on this wrote the same eight lines to get it right.\n */\nexport type RunAgentOptions = RunAgentBase & (\n  | {\n      /** One message as plain content, one named arrival, or several named arrivals. */\n      input: Content | Arrival | readonly Arrival[];\n      /**\n       * Which session it goes to, as a UUID. A new one is opened when this is\n       * omitted. An application's own naming for a conversation goes in `key`,\n       * which is opaque to the library; a store is entitled to keep a session\n       * id in a `uuid` column and refuse anything else.\n       */\n      sessionId?: string;\n      /** Omit for an ephemeral run: the log lives in memory and nothing is persisted. */\n      store?: Store;\n      claim?: never;\n    }\n  | {\n      /**\n       * What `store.next()` or `store.interrupted()` handed this worker.\n       *\n       * Its deliveries become this activation's input and are consumed by the\n       * write that commits them, in the same compare-and-swap that checks the\n       * position — so a worker that loses the race loses its turn and never the\n       * messages. A claim with an empty queue is a **resumption**: nothing opens\n       * it, the loop continues the committed log, and the effect that already\n       * happened is read there rather than asked for again. Only a harness\n       * declaring `recovery: \"history\"` is given one.\n       */\n      claim: Runnable;\n      /**\n       * Required here, unlike a caller sending. A claim is a position in a log\n       * and a queue to consume, and both of those are the store's — without one\n       * the deliveries would be replayed into memory and left queued for ever.\n       */\n      store: Store;\n      /**\n       * Something the worker is adding of its own, ahead of what was waiting.\n       *\n       * One real use: orientation for a harness whose protocol has no system\n       * prompt, which has nowhere else to go and must lead. Adding nothing is\n       * the ordinary case.\n       */\n      input?: Content | Arrival | readonly Arrival[];\n      sessionId?: never;\n    }\n);\n"]}

package/dist/content.d.ts

@@ -0,0 +1,45 @@
+import type { JsonValue } from "./json.js";
+export type ContentSource = {
+    kind: "inline";
+    data: string;
+} | {
+    kind: "url";
+    url: string;
+};
+/**
+ * What a turn or a tool result is made of. Parts rather than a string because
+ * some content cannot honestly be made into one: a screenshot, a PDF, a block
+ * only the provider that produced it can interpret.
+ */
+export type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    mediaType: string;
+    source: ContentSource;
+} | {
+    type: "file";
+    mediaType: string;
+    name?: string;
+    source: ContentSource;
+}
+/**
+ * A block this package does not model — provider-executed search, server-side
+ * reasoning, anything with a signature. Kept verbatim so the provider that
+ * produced it can be handed it back, never interpreted, and never shown to
+ * the model as text. `provider` names who made it: one provider's block is
+ * not valid on another's wire.
+ */
+ | {
+    type: "opaque";
+    provider: string;
+    data: JsonValue;
+};
+export type Content = string | readonly ContentPart[];
+/**
+ * The model-visible text of some content: text parts only, joined by newline.
+ * The single projection from parts to a string — images, files and opaque
+ * blocks are deliberately dropped rather than stringified into a transcript.
+ */
+export declare function textOf(content: Content): string;

package/dist/content.js

@@ -0,0 +1,11 @@
+/**
+ * The model-visible text of some content: text parts only, joined by newline.
+ * The single projection from parts to a string — images, files and opaque
+ * blocks are deliberately dropped rather than stringified into a transcript.
+ */
+export function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    return content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+}
+//# sourceMappingURL=content.js.map

package/dist/content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AA0BA;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,OAAgB;IACrC,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5F,CAAC","sourcesContent":["import type { JsonValue } from \"./json.js\";\n\nexport type ContentSource =\n  | { kind: \"inline\"; data: string }\n  | { kind: \"url\"; url: string };\n\n/**\n * What a turn or a tool result is made of. Parts rather than a string because\n * some content cannot honestly be made into one: a screenshot, a PDF, a block\n * only the provider that produced it can interpret.\n */\nexport type ContentPart =\n  | { type: \"text\"; text: string }\n  | { type: \"image\"; mediaType: string; source: ContentSource }\n  | { type: \"file\"; mediaType: string; name?: string; source: ContentSource }\n  /**\n   * A block this package does not model — provider-executed search, server-side\n   * reasoning, anything with a signature. Kept verbatim so the provider that\n   * produced it can be handed it back, never interpreted, and never shown to\n   * the model as text. `provider` names who made it: one provider's block is\n   * not valid on another's wire.\n   */\n  | { type: \"opaque\"; provider: string; data: JsonValue };\n\nexport type Content = string | readonly ContentPart[];\n\n/**\n * The model-visible text of some content: text parts only, joined by newline.\n * The single projection from parts to a string — images, files and opaque\n * blocks are deliberately dropped rather than stringified into a transcript.\n */\nexport function textOf(content: Content): string {\n  if (typeof content === \"string\") return content;\n  return content.filter((part) => part.type === \"text\").map((part) => part.text).join(\"\\n\");\n}\n"]}

package/dist/harness/adapters/acp/index.d.ts

@@ -0,0 +1,92 @@
+import type { Harness } from "../../harness.js";
+import type { Sandbox } from "../../../sandbox/sandbox.js";
+import type { Decide } from "../../../tools/tool.js";
+/** An agent process: argv and the environment that selects its provider and model. */
+export interface AcpAgent {
+    command: readonly string[];
+    env?: Readonly<Record<string, string>>;
+}
+/** A tool server the foreign agent connects to itself. This is how it gets ours. */
+export interface AcpMcpServer {
+    name: string;
+    command: string;
+    args?: readonly string[];
+    env?: readonly {
+        name: string;
+        value: string;
+    }[];
+}
+/**
+ * Something the agent lets a client change about a session.
+ *
+ * The protocol used to name models specifically; it now publishes a list of
+ * options and gives each a category, so a client can tell a model selector
+ * from a reasoning level without knowing the agent. We report them rather than
+ * interpret them: the ids and the choices are the agent's, and a service that
+ * mapped them onto its own three levels would be guessing at another product's
+ * vocabulary.
+ */
+export interface AcpConfigOption {
+    id: string;
+    name: string;
+    /** "model", "thought_level", "mode", "model_config", or whatever the agent says. */
+    category: string;
+    description?: string;
+    current: string | boolean;
+    /** Absent for a boolean option. */
+    choices?: readonly {
+        id: string;
+        name: string;
+    }[];
+}
+export interface AcpHarnessOptions {
+    /** Names this harness in the log and in the UI. */
+    id: string;
+    agent: AcpAgent;
+    /**
+     * Where the agent runs. Not merely where its file requests are served: the
+     * process itself is started here, because a coding agent runs its own shell
+     * and only delegates the calls it chooses to.
+     */
+    sandbox: Sandbox;
+    mcpServers?: readonly AcpMcpServer[];
+    /**
+     * What to set before prompting, by option id. Applied only where the agent
+     * published that option and, for a select, that value — otherwise the run
+     * fails naming what it does offer, rather than quietly running something else.
+     */
+    select?: Readonly<Record<string, string | boolean>>;
+    /**
+     * Requested model, matched against whichever option the agent categorised as
+     * its model selector. A convenience over `select` for the one option every
+     * agent has, and it fails the same way.
+     */
+    model?: string;
+    /** What the agent published. The caller persists it so a session can offer the agent's own choices. */
+    onConfig?(options: readonly AcpConfigOption[]): void;
+    /** Agent-defined mode. Choosing one that asks before acting is what routes its own tools through `decide`. */
+    mode?: string;
+    /**
+     * Applied to the agent's own tools, per call, before they run.
+     *
+     * The protocol carries a title and the raw arguments for these, but no
+     * schema, so `spec.parameters` is `{}` and `spec.description` is the agent's
+     * own title for the call. That is what we actually have.
+     */
+    decide?: Decide;
+    /** The agent's previous session id, so this activation continues its context. */
+    resume?: string;
+    /** Called with the agent's session id, so the caller can persist it for the next activation. */
+    onSession?(sessionId: string): void;
+}
+/**
+ * Runs a foreign coding agent over the Agent Client Protocol.
+ *
+ * The adapter is not a remote control. It does three things the raw protocol
+ * does not: it normalises whatever the agent did into this package's entries,
+ * so one durable log describes a Claude Code turn and a native-loop turn
+ * identically; it puts the agent's own tools under the application's decision
+ * function, one call at a time; and it hands the agent tool servers of ours, so
+ * agents can dispatch and message each other.
+ */
+export declare function createAcpHarness(options: AcpHarnessOptions): Harness;