@a-dray/aglib 0.1.0 → 0.1.1

package/README.md

@@ -1,171 +1,90 @@
 # aglib
 
-A small TypeScript toolkit for building **your own agent harness**, inside an application you own.
+A small TypeScript toolkit for building **production agents** — the kind with a
+durable log, a permission rule on every call, somewhere contained to run, and an
+answer for what happens when the process dies mid-turn.
 
-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.
+You bring the product — users, tenancy, channels, UI, deployment, policy. aglib
+gives you a session log that *is* the state, 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`.
+Whose loop does the reasoning is a decision here, not an assumption. Write your
+own, compose a vendor's agent library, or drive one over a protocol — the log,
+the rendering, the accounting and the handoff are the same in all three, and what
+*differs* is declared rather than discovered.
 
-## 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
-```
+> **Pre-release.** The API changes without deprecation aliases, so pin an exact version: `bun add aglib@npm:@a-dray/aglib@<version>`. The unscoped name is a lookalike of an existing package; the alias keeps imports as `aglib`.
 
-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
+## Run one
 
 ```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));
+bun run recipe native-agent                      # a conversation, in your terminal
+bun run recipe native-agent "what did I decide?"  # …or one shot, for a pipe
 ```
 
-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.
+## The shape
 
-## Recipes
+```text
+src/
+  json.ts  result.ts  content.ts  agent.ts  run.ts  render.ts  terminal.ts
 
-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.
+  session/    the log — this IS the session's state
+  tools/      declaring and running tools
+  model/      store/      sandbox/      harness/      each: <port>.ts → adapters/
+```
 
-| 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. |
+Four ports, each with adapters. Three ship an executable conformance suite;
+`harness` does not, because what one must prove depends on what it declares. Our
+own loop is `harness/adapters/native`, beside the others rather than above them.
 
-## What it is not
+**`src/` is the library** — everything published to npm, and nothing that knows
+what your agent is for. **`recipes/` is where most of it earns its place** —
+runnable programs that each answer one production question. An export needs a
+consumer: a recipe that composes it, or a conformance suite run against an
+implementation here. A surface with neither fails `bun run check`.
 
-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.
+## Three recipes
 
-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.
+One per answer to "who does the reasoning". Each is the smallest thing that
+still makes its point, and between them they exercise every seam.
 
-## Four ways in
+| Recipe | Whose loop | What it shows |
+| --- | --- | --- |
+| [`native-agent`](recipes/native-agent/README.md) | ours | The whole surface in one program — memory, skills, subagents, a sandbox you choose — and the one thing only our own loop offers: a message reaching a busy session mid-turn. |
+| [`vendored-agent`](recipes/vendored-agent/README.md) | a vendor's, from its library | What a vendor library must expose for the log to stay the state. Pi's tools are values you re-point at your sandbox and its transcript is a field you assign, so an interrupted run continues — `recovery: "history"`. Its README says what the tiers below that get you. |
+| [`coding-agent`](recipes/coding-agent/README.md) | a vendor's, over a protocol | The cheapest containment on offer: any ACP agent started *inside* your sandbox, its work arriving as your entries, for one row of argv. |
 
-aglib is for building the **outer** harness — the durable session, the tools, the policy, the
-orchestration — around whatever does the reasoning inside.
+## Where to read next
 
-| You want | You do |
+| Question | Document |
 | --- | --- |
-| 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 |
+| What is this, for whom, and why? | [`docs/PRODUCT.md`](docs/PRODUCT.md) |
+| What is the outward surface? | [`docs/INTERFACE.md`](docs/INTERFACE.md) |
+| How does it work, and who owns each part? | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) |
+| How is the source written? | [`docs/CODE.md`](docs/CODE.md) |
+| How do I work in here? | [`AGENTS.md`](AGENTS.md) |
 
-The last two are not equivalent, and `recipes/agent-service` publishes a table of exactly which
-control points each one gives you.
+[`docs/REFERENCE.md`](docs/REFERENCE.md) is generated by `bun run docs`.
 
 ## 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.
+`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.
+Live tests cost money and are opt-in twice — the credential, and a flag:
+`AGLIB_LIVE_MODEL=1` for the cases that reach a provider, `AGLIB_LIVE_ACP=1` for
+the ones that start a vendor's agent over `npx`. The Docker cases need no flag:
+they run where a daemon and the image are already there, and name themselves
+when they skip.
 
 ## License
 

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

@@ -1,6 +1,7 @@
 import type { Harness } from "../../harness.js";
 import type { Sandbox } from "../../../sandbox/sandbox.js";
 import type { Decide } from "../../../tools/tool.js";
+import { type Failure, type Result } from "../../../result.js";
 /** An agent process: argv and the environment that selects its provider and model. */
 export interface AcpAgent {
     command: readonly string[];
@@ -51,21 +52,18 @@ export interface AcpHarnessOptions {
     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.
+     * What to set before prompting, by option id — the agent's own ids, from
+     * `onConfig`. The only configuration door, deliberately: an option this
+     * package named would be a guess at another product's vocabulary, and one
+     * that goes stale the first time an agent ships an axis nobody thought of.
+     *
+     * 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.
      *
@@ -90,3 +88,21 @@ export interface AcpHarnessOptions {
  * agents can dispatch and message each other.
  */
 export declare function createAcpHarness(options: AcpHarnessOptions): Harness;
+/**
+ * What an agent offers, before anyone has asked it anything.
+ *
+ * Over this protocol an agent publishes its options in the answer to
+ * `session/new`, so nothing knows what a model, a mode or a reasoning level is
+ * called until a session exists — and a session exists on the first prompt.
+ * That left a client with a menu it could not draw until after the choice it
+ * wanted to offer had already been made.
+ *
+ * So this opens one and asks. It spawns, initialises, opens a session, reads
+ * what came back and closes: a process and a handshake, no prompt, no
+ * generation, nothing billed. The session it opened is thrown away — the run
+ * opens its own, exactly as it did before.
+ */
+export declare function acpOptions(input: {
+    agent: AcpAgent;
+    sandbox: Sandbox;
+}): Promise<Result<readonly AcpConfigOption[], Failure>>;

package/dist/harness/adapters/acp/index.js

@@ -2,6 +2,18 @@ import { textOf } from "../../../content.js";
 import { err, ok } from "../../../result.js";
 import { createRpc } from "./rpc.js";
 const PROTOCOL_VERSION = 1;
+/**
+ * The handshake, and what it claims for us.
+ *
+ * Two callers open a connection — a turn, and `acpOptions` — and an agent
+ * decides what to offer from what the client says it can do. A second copy of
+ * this is a second answer to the same question, and the two would drift.
+ */
+const initialize = (rpc) => rpc.request("initialize", {
+    protocolVersion: PROTOCOL_VERSION,
+    clientCapabilities: { fs: { readTextFile: true, writeTextFile: true }, terminal: true },
+    clientInfo: { name: "aglib", version: "0" },
+});
 /**
  * Runs a foreign coding agent over the Agent Client Protocol.
  *
@@ -17,13 +29,48 @@ export function createAcpHarness(options) {
         id: options.id,
         // Its tools are its own. We gate them and we record them; we do not claim
         // to have validated arguments we never had a schema for.
-        toolUse: "harness",
         // The agent owns its context. Our entries describe what it did, and cannot
         // by themselves put it back mid-turn.
         recovery: "none",
         run: (context) => runTurn(options, context),
     };
 }
+/**
+ * What an agent offers, before anyone has asked it anything.
+ *
+ * Over this protocol an agent publishes its options in the answer to
+ * `session/new`, so nothing knows what a model, a mode or a reasoning level is
+ * called until a session exists — and a session exists on the first prompt.
+ * That left a client with a menu it could not draw until after the choice it
+ * wanted to offer had already been made.
+ *
+ * So this opens one and asks. It spawns, initialises, opens a session, reads
+ * what came back and closes: a process and a handshake, no prompt, no
+ * generation, nothing billed. The session it opened is thrown away — the run
+ * opens its own, exactly as it did before.
+ */
+export async function acpOptions(input) {
+    const started = await input.sandbox.spawn({
+        command: input.agent.command,
+        cwd: input.sandbox.root,
+        ...(input.agent.env ? { env: input.agent.env } : {}),
+    });
+    if (!started.ok)
+        return err(started.error);
+    const rpc = createRpc(started.value);
+    try {
+        const ready = await initialize(rpc);
+        if (!ready.ok)
+            return err(ready.error);
+        const opened = await rpc.request("session/new", { cwd: input.sandbox.root, mcpServers: [] });
+        if (!opened.ok)
+            return err(opened.error);
+        return ok(readOptions(opened.value).options);
+    }
+    finally {
+        rpc.close();
+    }
+}
 async function runTurn(options, context) {
     const started = await options.sandbox.spawn({
         command: options.agent.command,
@@ -67,11 +114,7 @@ function createTurn(options, context, rpc) {
         serveTerminals();
         servePermission();
         rpc.onNotify("session/update", (params) => { void receive(params); });
-        const ready = await rpc.request("initialize", {
-            protocolVersion: PROTOCOL_VERSION,
-            clientCapabilities: { fs: { readTextFile: true, writeTextFile: true }, terminal: true },
-            clientInfo: { name: "aglib", version: "0" },
-        });
+        const ready = await initialize(rpc);
         if (!ready.ok)
             return { status: "failed", error: ready.error };
         const capabilities = field(ready.value, "agentCapabilities");
@@ -143,24 +186,15 @@ function createTurn(options, context, rpc) {
         const { options: published, legacyModel } = readOptions(opened);
         if (published.length)
             options.onConfig?.(published);
-        if (options.mode) {
-            const set = await rpc.request("session/set_mode", { sessionId: id, modeId: options.mode });
-            if (!set.ok)
-                return set;
-        }
-        const wanted = { ...options.select };
-        if (options.model) {
-            const selector = published.find((option) => option.category === "model");
-            if (!selector) {
-                return err({
-                    code: "unsupported",
-                    message: `${options.id} publishes no model selector, so '${options.model}' cannot be chosen over the protocol. Point it at a model through its environment instead.`,
-                    retryable: false,
-                });
-            }
-            wanted[selector.id] = options.model;
-        }
-        for (const [option, value] of Object.entries(wanted)) {
+        // One door, and `select` is it. There were two more — `mode`, which sent
+        // `session/set_mode`, and `model`, which found whichever option the agent
+        // had categorised as its selector. Both were conveniences naming an axis,
+        // and naming an axis is guessing at a vocabulary that is not ours: the
+        // agents measured here publish five categories between them, and no
+        // shorthand was ever going to cover the next one. `session/set_config_option`
+        // with `configId: "mode"` was checked against `claude-agent-acp` and does
+        // what `session/set_mode` did, answering with the new state as well.
+        for (const [option, value] of Object.entries(options.select ?? {})) {
             const published_ = published.find((candidate) => candidate.id === option);
             if (!published_) {
                 return err({