@spendgraph/tools 0.6.0 → 0.8.0

package/docs/declaring.mdx

@@ -0,0 +1,85 @@
+export const meta = {
+  title: "Declaring a tool — spendgraph docs",
+  description:
+    "Write `as const` and the handler types itself. Every check `tool` makes is something a provider either rejects opaquely or accepts and behaves oddly about.",
+};
+
+# Declaring a tool
+
+```ts
+const lookup = tool({
+  name: "lookup_contract",
+  description: "Finds a contract clause by its reference, such as MSA 2.4.",
+  args: [
+    { name: "ref", type: "string", required: true },
+    { name: "limit", type: "number", required: false },
+    { name: "mode", type: "enum", required: false, options: ["fast", "thorough"] },
+  ] as const,
+  run: ({ ref, limit, mode }) => search(ref, limit ?? 5, mode ?? "fast"),
+});
+```
+
+## Write `as const` and the handler types itself
+
+`ref` arrives a string, `limit` a number, `mode` narrowed to its two options, and the optional ones optional. Rename an argument and the handler stops compiling — rather than being handed `undefined` halfway through an agent loop.
+
+Without `as const`, inference falls back to nothing **silently**. That is the failure the package's own typecheck test exists to catch.
+
+## What arrives at the handler
+
+Arguments are validated, then filled in and coerced, before `run` sees them:
+
+- a **declared default** applies when the argument is absent;
+- a value arrives at the **type its declaration promises**.
+
+Providers hand tool arguments over as JSON a model wrote, so `"limit": "7"` is ordinary. It validates — the checker reads it through the same coercion — and it reaches `run` as the number `7`. `"loud": "false"` reaches it as `false`, not as a non-empty string that would make `if (args.loud)` run the branch the model asked it not to.
+
+## `aliases` are matched, never sent
+
+The description is what the model reads. `aliases` are what [selection](/docs/tools/selecting) matches on, and they never leave the process:
+
+```ts
+tool({
+  name: "issue_refund",
+  aliases: ["money back", "chargeback", "reimburse"],
+  description: "Reverses a completed order and returns the payment.",
+  args,
+  run,
+});
+```
+
+A question about money back scores zero against `refund` on wording alone. This is where the words a caller actually types get declared, rather than being smuggled into a description the model then has to read every turn.
+
+A blank alias throws at import: it would match every query or none.
+
+## Checked at import, not on the first loop
+
+Every check `tool` makes is something a provider either rejects opaquely or accepts and behaves oddly about:
+
+| | |
+| --- | --- |
+| a name a provider will not take | letters, digits and underscores, starting with a letter |
+| a blank description | it is the only thing the model reads to decide whether to call it |
+| an enum with no options | nothing can satisfy it |
+| a blank option | the model can legally pick it and you cannot act on it |
+| a duplicate option or argument | one silently shadows the other |
+| a blank alias | it matches every query, or none |
+
+They fire at import, not on the first loop in production.
+
+<Callout tone="trap" title="Without `as const`, inference gives up quietly">
+  Drop it and the handler's argument type falls back to `Record<string, unknown>` — no error, no red squiggle, just every field typed `unknown` from then on. It is checked by a typecheck test in the package for exactly that reason.
+</Callout>
+
+## What a result carries
+
+```ts
+result.status;     // "completed" | "failed"
+result.output;     // a string is itself, anything else is JSON
+result.error;      // why, when it failed
+result.latencyMs;
+```
+
+A tool whose **return value** cannot be serialised — a circular object, a `BigInt` — is still a tool that **ran**. It comes back completed, carrying `[not recordable: …]`, rather than failed: reporting a completed action as a failure invites the agent to do it again.
+
+A thrown string keeps its message. Anything can be thrown, and reading only `Error.message` discards the one thing the tool said about itself.

package/docs/effects.mdx

@@ -0,0 +1,49 @@
+export const meta = {
+  title: "Effects — spendgraph docs",
+  description:
+    "Three values, not a taxonomy. There is no default, and unset is not readonly: a default would quietly label every tool written before this existed as safe.",
+};
+
+# Effects
+
+What running a tool does to the world outside the process.
+
+```ts
+tool({ name: "issue_refund", description: "…", effect: "destructive", args, run });
+```
+
+Without it, `issue_refund` and `lookup_clause` are the same thing to a bus: two names with schemas. Nothing can tell what is safe to retry, safe to run twice, or worth asking a person about first.
+
+| | |
+| --- | --- |
+| `readonly` | no effect outside the process |
+| `idempotent` | has an effect, but twice is the same as once |
+| `destructive` | neither, so never retry it on its own |
+
+Three values, not a taxonomy — anything finer does not get filled in accurately.
+
+## There is no default, and unset is not `readonly`
+
+A default would quietly label every tool written before this existed as **safe**, which is the one mistake that matters here. Unset means nobody has said.
+
+```ts
+bus.effectOf("issue_refund")   // "destructive", or undefined if it never said
+bus.destructive()              // ["issue_refund"]
+bus.unannotated()              // ["send_email"]
+```
+
+`destructive()` returns only the tools that said so, so a gate built on it alone lets an unlabelled one through. **`unannotated()` is how you find those** — assert it is empty in a test and a new tool cannot join the bus unlabelled.
+
+<Callout tone="trap" title="`readonly` is not the same as safe">
+  Effect says what a call does outside the process; `trust` says whether what it returns was written by somebody outside. A web fetch is `readonly` and is also how an injected instruction arrives. A guard that wants "no destructive call after untrusted content came in" has to gate on `trust: "external"` — the alternative is gating on the tool's *name*, which a rename turns off silently, and in the permissive direction.
+</Callout>
+
+## It survives selection
+
+The effect rides along on `declarations()` and survives `select()`, which is where a gate reads it. Every provider shape drops it: no API has a field for it, and an unknown key is either rejected or ignored.
+
+A turn answers about the tools **it** was offered — `effectOf` is `undefined` both for a tool that never said and for one this turn never saw. A gate reading it decides what unknown means for it.
+
+## Three builtins leave it unset on purpose
+
+`http_request` is a GET or a POST depending on an argument, and one label cannot be true of both. `escalate` runs your `onEscalate`, and paging someone twice is not the same as paging them once. `code_exec` runs whatever the model wrote, which is neither safe nor known — and `undefined` says exactly that, where either label would lie.

package/docs/overview.mdx

@@ -0,0 +1,76 @@
+export const meta = {
+  title: "Tools — spendgraph docs",
+  description:
+    "Declare a tool once, offer the right few, and record what was called. A description and a function in one object, so a rename cannot become a runtime failure.",
+};
+
+# Tools
+
+Fifty tools is 7,500 tokens spent before the user has typed anything, and a model given fifty picks worse than a model given five.
+
+Declare a tool once, offer the right few, and record what was called — because a model that says it checked the ledger and did not is a claim only the steps can disprove.
+
+```sh
+npm install @spendgraph/tools
+```
+
+Two things to learn, and twenty-two builtins you can ignore until you want one.
+
+```ts
+import { tool, toolbus, currentTime } from "@spendgraph/tools";
+```
+
+## The whole thing
+
+```ts
+const lookup = tool({
+  name: "lookup_contract",
+  description: "Finds a contract clause by its reference, such as MSA 2.4.",
+  args: [
+    { name: "ref", type: "string", required: true },
+    { name: "limit", type: "number", required: false },
+  ] as const,
+  run: ({ ref, limit }) => search(ref, limit ?? 5),
+});
+
+const bus = toolbus([lookup, currentTime()], { limit: 6 });
+
+const turn = bus.trace(question);
+const reply = await llm.call(messages, { tools: turn });
+await turn.invoke(call.name, call.args);
+
+turn.record();   // { offeredTools, steps }
+```
+
+## Why one object
+
+A description the model reads and a function you wrote, in **one object**. Splitting them — a schema here, a handler there, matched by string — is how a rename becomes a runtime failure mid-loop.
+
+The description is the biggest lever on whether the model calls it correctly, and worth iterating on more than the code is.
+
+## It plugs into a prompt
+
+`call` and `invoke` take anything that hands out a turn, and neither package imports the other:
+
+```ts
+await prompt.call(values, ({ messages, turn }) => llm.call(messages, { tools: turn }), {
+  tools: bus,
+});
+```
+
+<Callout tone="trap" title="Declaring a tool is not offering it">
+  `toolbus()` holds everything your app can do; what the model sees each turn is a shortlist. Selection is never applied for you — hand the model the whole bus and you are paying for every description on every turn, and making it worse at choosing.
+</Callout>
+
+## Where to go next
+
+| | |
+| --- | --- |
+| [Declaring a tool](/docs/tools/declaring) | args, `as const`, and what is checked at import |
+| [A stored tool](/docs/tools/stored) | wording in the dashboard, handler in code |
+| [Effects](/docs/tools/effects) | what running one does to the world outside |
+| [The bus](/docs/tools/bus) | holds, picks, converts, runs — and nests |
+| [Selecting](/docs/tools/selecting) | the shortlist, and why it is a shortlist |
+| [A turn](/docs/tools/turns) | offered, called, and what the rollout keeps |
+| [Builtins](/docs/tools/builtins) | thirteen factories, none registered for you |
+| [Bogus tools](/docs/tools/bogus) | twelve mocks for testing the pipeline, not the provider |

package/docs/selecting.mdx

@@ -0,0 +1,79 @@
+export const meta = {
+  title: "Selecting tools — spendgraph docs",
+  description:
+    "Fifty tools is 7.5k tokens before the user has said anything. `limit` is an accuracy budget, not a token one, and selection is keyword and usage on purpose.",
+};
+
+# Selecting
+
+```ts
+const bus = toolbus([lookup, currentTime()], { limit: 6 });
+
+bus.select(query)          // the working set for one request
+bus.anthropic(decls?)      // declarations, per provider
+bus.openai(decls?)
+bus.markdown(decls?)       // for a model with no tools API
+await bus.invoke(name, args)
+bus.missing(["refund"])    // names something expects that this bus lacks
+bus.usage()
+```
+
+Holding tools in one place is what makes selection possible. Fifty tools at roughly 150 tokens of declaration each is **7.5k tokens on every call** before the user has said anything, so past a point you stop sending all of them.
+
+## `limit` is an accuracy budget
+
+More tools in front of a model makes it worse at picking the right one **regardless of context length**. Measured shortlists cluster around five to eight. Pinned tools count against it — what is in front of the model is what costs accuracy, whoever put it there.
+
+A limit that is `NaN` is refused rather than clamped: `Math.max(1, NaN)` is `NaN`, and every length compares false against it, so the model would be offered **nothing** — the one outcome selection exists to avoid.
+
+## Keyword and usage, deliberately
+
+No embedding provider, no extra call, no latency. It is also the baseline that says what embeddings would buy.
+
+Relevance comes before usage: at a shortlist of six, three previously-used tools take half the slots and push out the tool the query needs. Usage earns its place as the tiebreaker among equal matches, and as the fallback when nothing matches — the case where an agent would otherwise be handed nothing.
+
+Words are found in **any script**. A query with no ASCII letters used to produce no terms at all, so every request fell through to "the first six declared" — the same six for a Japanese question as for a Russian one.
+
+## How a tool scores
+
+Whole words, never substrings. A term matching inside a longer word is noise, not signal: `me` sits inside `statement`, and at a few hundred tools that alone puts half the catalogue in every shortlist.
+
+Where the word appears decides its weight — **name beats alias beats description**. A tool named `refund` is a stronger answer to a question about refunds than one that merely mentions the word in a paragraph.
+
+Then each term is weighted by how **rare** it is across the bus. A word one tool in two thousand uses says far more than one four hundred of them share, and without that every term counts the same and common vocabulary decides the shortlist.
+
+## Aliases reach words a description never used
+
+Lexical ranking cannot cross a synonym. A question about money back scores **zero** against a tool called `refund`, whatever its description says. Declare the wording callers actually type:
+
+```ts
+tool({
+  name: "issue_refund",
+  aliases: ["money back", "chargeback", "reimburse"],
+  description: "Reverses a completed order and returns the payment.",
+  args,
+  run,
+});
+```
+
+They are matched, never sent — every provider shape drops them, exactly as it drops `effect`. Unlike an embedding, a bad match is fixed by editing one line.
+
+<Callout tone="trap" title="Pinned tools spend the budget too">
+  `limit` counts pinned tools, so a shortlist of 5 with `finish` and `escalate` pinned leaves three slots for the query. A tool that needs a partner is dropped rather than offered alone — an agent told to prefer `recall` and handed only `deep_recall` will reach for the one it does not have.
+</Callout>
+
+## Past a few hundred tools
+
+Ranking, not speed, is what gives out first: selection stays near a millisecond at two thousand tools, but a coincidental match in an unrelated domain starts taking slots. [`busgroup`](/docs/tools/bus) gives each domain its own bus and routes between them.
+
+## `missing` catches a silent failure
+
+A prompt edited to expect a `refund` tool, deployed against a bus without one, does not error. The agent is never offered it and answers anyway.
+
+```ts
+bus.missing(["refund", "escalate"]);   // the names this bus does not have
+```
+
+## Two tools that describe themselves the same way
+
+Two near-identical descriptions are worse than one tool: the model cannot tell them apart and picks wrong more often, with nothing failing. The bus says so at construction, once, however many pairs there are — a line each buries whatever else the process said at startup and teaches people to switch the check off.

package/docs/stored.mdx

@@ -0,0 +1,83 @@
+export const meta = {
+  title: "A stored tool — spendgraph docs",
+  description:
+    "The dashboard owns the description, your code owns the arguments and the handler, and bindTool checks the two against each other before the model ever sees it.",
+};
+
+# A stored tool
+
+The description is the biggest lever on whether a model calls a tool correctly, and the part you will want to change most often. `bindTool` puts that half in the dashboard and leaves the rest in code.
+
+```ts
+import { bindTool } from "@spendgraph/tools";
+import { Spendgraph } from "@spendgraph/sdk";
+
+const lookup = await bindTool(sg, {
+  name: "lookup_contract",
+  args: [{ name: "ref", type: "string", required: true }] as const,
+  run: ({ ref }) => search(ref),
+});
+```
+
+No `description` in that call. That is the point — one source for the string the model reads, and it is the one you can edit without a release.
+
+## Who owns what
+
+```
+  DASHBOARD                        YOUR CODE
+  ─────────                        ─────────
+  description   ◀── iterate on     args      ──▶ run() is typed from them
+  effect            these without  run()     ──▶ the thing that actually happens
+  pinned            a deploy
+```
+
+Arguments stay in code because the handler's parameter types are inferred from them. Pull those from the server and every `run` is handed a `Record<string, unknown>`, which gives up the one guarantee [declaring a tool](/docs/tools/declaring) exists to provide.
+
+Write `as const` here exactly as you would for `tool()`. Without it inference falls back to nothing, and the drift check below becomes the only thing still catching a rename.
+
+## Drift fails at bind, not mid-loop
+
+The stored arguments and the declared ones are compared on the way through, by **name, type and requiredness** — the three a handler is written against.
+
+```ts
+import { ToolDriftError, ToolNotStoredError } from "@spendgraph/tools";
+
+try {
+  await bindTool(sg, spec);
+} catch (err) {
+  if (err instanceof ToolDriftError) err.differences;  // every disagreement, in words
+  if (err instanceof ToolNotStoredError) err.toolName; // nothing stored under that name
+}
+```
+
+`differences` reads like a review comment rather than a diff:
+
+```
+"ref" is string here and number stored
+"limit" is declared here but not stored
+"mode" is stored but not declared here
+```
+
+A description or a bound that differs is **not** drift — that is the dashboard being edited, which is the whole feature. A renamed argument is a handler about to be passed `undefined` halfway through an agent loop, so it throws.
+
+<Callout tone="warn" title="Bind at startup, not per request">
+  Every `bindTool` is a round trip to the API. Bind once when the process starts and hold the result, the same as you would a database connection — a bind inside a request handler puts a network hop in front of every model call.
+</Callout>
+
+<Callout tone="trap" title="A rename in the dashboard is a handler passed `undefined`">
+  The wording is editable without a deploy; the argument names are not. `bindTool` compares them at bind time and refuses — a deploy that fails is recoverable, and the same rename noticed mid-loop is a handler halfway through somebody's refund reading an argument that is not there.
+</Callout>
+
+## When nothing is stored yet
+
+`ToolNotStoredError` is the ordinary case of "you have not written this one in the dashboard yet", not an exotic failure. It exists so a 404 from three layers down arrives as a sentence naming the tool.
+
+Create the row first — `sg.tools.create` on the [client](/docs/sdk/client), or the Tools page in the dashboard — then bind to it.
+
+## It is an ordinary tool afterwards
+
+What comes back is what `tool()` returns. Register it on a bus, select it, invoke it, record it; nothing downstream knows or cares where the wording came from.
+
+```ts
+const bus = toolbus([lookup, calculate()]);
+```

package/docs/turns.mdx

@@ -0,0 +1,57 @@
+export const meta = {
+  title: "A turn — spendgraph docs",
+  description:
+    "A turn is selected once and remembers what it offered. Without that a record cannot tell 'chose not to' from 'was never offered', which are opposite bugs.",
+};
+
+# A turn
+
+```ts
+const turn = bus.trace(query);
+
+const reply = await llm.call(messages, { tools: turn });
+await turn.invoke(call.name, call.args);
+
+turn.record();   // { offeredTools, steps }
+```
+
+A turn is **selected once** and remembers what it offered. A trace cannot disagree with itself about what the model saw.
+
+## Offered is recorded, not just called
+
+Which tools were offered is recorded as well as which were called. Without it a record cannot tell **"chose not to"** from **"was never offered"** — which are opposite bugs, and look identical in a log that only lists calls.
+
+## What a turn answers
+
+| | |
+| --- | --- |
+| `turn.offered` | the shortlist this turn was given |
+| `turn.anthropic()` · `openai()` · `markdown()` | the same list, per provider |
+| `turn.effectOf(name)` | what that tool said it does, or `undefined` |
+| `turn.invoke(name, args)` | runs one and records the step. Never throws |
+| `turn.steps()` | the steps so far, in call order |
+| `turn.record()` | the pair, in the shape `report` takes |
+
+## Never throwing is the point
+
+A tool that fails is an **outcome the agent can react to** and a step worth recording, not an exception that ends the run — the same argument `status` and `error` exist on a rollout for.
+
+A tool the bus does not have is a failure that says what was offered, since the usual cause is a hallucinated name.
+
+<Callout tone="trap" title="`undefined` means two different things">
+  A tool that was offered and stayed quiet, and a tool this turn never offered, both answer `undefined`. `offeredTools` is what tells them apart — which is the difference between a model that declined to look something up and a model that could not.
+</Callout>
+
+## Usage drives the tiebreaker
+
+`bus.usage()` counts what has actually been called, which is what selection falls back on when a query singles out nothing. A call that never reached the tool — a name that does not exist, arguments that did not validate — is not counted, because it was not a use.
+
+## With a prompt
+
+```ts
+await prompt.call(values, ({ messages, turn }) => llm.call(messages, { tools: turn }), {
+  tools: bus,
+});
+```
+
+The prompt hands the turn to your callback and puts `record()` on the rollout. The three packages compose without any of them importing another.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/tools",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Declare a tool once, offer the right few, and record what was called.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,6 +28,7 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./docs/*": "./docs/*",
     "./bogus": {
       "types": "./dist/bogus/index.d.ts",
       "import": "./dist/bogus/index.js"
@@ -36,6 +37,18 @@
       "types": "./dist/wire/index.d.ts",
       "import": "./dist/wire/index.js"
     },
+    "./papers": {
+      "types": "./dist/papers/index.d.ts",
+      "import": "./dist/papers/index.js"
+    },
+    "./search": {
+      "types": "./dist/search/index.d.ts",
+      "import": "./dist/search/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
     "./internals": {
       "types": "./dist/internals.d.ts",
       "import": "./dist/internals.js"
@@ -44,19 +57,19 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments && node ../../scripts/minify.mjs dist",
-    "test": "npm run build && vitest run",
-    "examples": "npm run build && node examples/02-select/01-shortlist.mjs"
-  },
   "dependencies": {
-    "@spendgraph/sdk": "^0.6.0"
+    "@spendgraph/sdk": "^0.8.0",
+    "jszip": "^3.10.2",
+    "unpdf": "^1.8.1"
   },
   "devDependencies": {
     "@locusgraph/client": "^0.8.1",
-    "@spendgraph/prompt": "^0.6.0",
+    "@spendgraph/config": "0.8.0",
+    "@spendgraph/prompt": "^0.8.0",
+    "pdf-lib": "^1.17.1",
     "typescript": "^5"
   },
   "engines": {
@@ -64,5 +77,11 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments && node ../../scripts/minify.mjs dist",
+    "examples": "pnpm run build && node examples/02-select/01-shortlist.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.tests.json"
   }
-}
+}

package/dist/builtin/deep-recall/deep-recall.js

@@ -1 +0,0 @@
-import{tool as s}from"../../tool/index.js";const o=20;function l(t){const a=t.maxFacts??o;return s({name:"deep_recall",description:"Searches your own knowledge base and returns an answer with the evidence it rests on. A walker follows linked contexts, so it answers questions spread across several notes \u2014 what do we know about X, what was decided and why. Ask one focused thing. Prefer it over a web search whenever the answer could already be in your records.",effect:"readonly",args:[{name:"question",type:"string",required:!0,maxLength:1e3,description:"One focused question, not a conversation and not several at once."},{name:"context_ids",type:"list",required:!1,description:"Contexts to start the walk from, as type:name \u2014 take them from the contexts of an earlier result. A hint, not a filter; the walk may go elsewhere."}],run:async({question:n,context_ids:r})=>{const e=await t.client.deepRecall({question:n,...t.graphId?{graphId:t.graphId}:{},...r?.length?{contextIds:r}:{}});return{summary:e.summary,facts:e.facts.slice(0,a),truncated:e.facts.length>a,contextsWalked:e.contexts_walked,coverage:e.coverage,fallback:e.fallback,costMicroUsd:Math.round(e.usage.cost_usd*1e6)}}})}export{l as deepRecall};

package/dist/builtin/write-document/commission.d.ts

@@ -1,56 +0,0 @@
-import { type AbortSignalLike, type MoaClientConfig } from "./http.js";
-import type { CommissionInput, CommissionResult } from "./types.js";
-/**
- * Moa's task surface — fire, then await.
- *
- * `create()` hands back an id immediately and `get()` reads it; pass `waitMs`
- * (or use {@link pollUntilDone}) to long-poll, so one call is awaited rather
- * than a loop tight-polling. `cancel()` is optional so a test stub stays small.
- */
-export interface CommissionClient {
-    create(input: CommissionInput): Promise<string>;
-    get(id: string, opts?: {
-        waitMs?: number;
-        signal?: AbortSignalLike;
-    }): Promise<CommissionResult>;
-    cancel?(id: string): Promise<void>;
-}
-/**
- * HTTP {@link CommissionClient} over Moa's task API (`POST /tasks` → `GET /tasks/:id`).
- *
- * The request body carries the ask as prose — Moa's artifact pipeline is
- * prompt-driven and `POST /tasks` strips unknown fields, so context, design and
- * deliverables are blocks on the task rather than parameters beside it.
- */
-export declare function createCommissionClient(config?: MoaClientConfig): CommissionClient;
-/** The sane ceiling for a chat-bound call. A rendered document wants minutes, not this. */
-export declare const INTERACTIVE_TIMEOUT_MS = 30000;
-/** Thrown by {@link pollUntilDone} when the caller's abort signal fires. */
-export declare class CommissionAbortedError extends Error {
-    readonly commissionId: string;
-    constructor(commissionId: string);
-}
-/** Thrown when the wait ran out. The task itself is still running server-side. */
-export declare class CommissionTimeoutError extends Error {
-    readonly commissionId: string;
-    readonly timeoutMs: number;
-    constructor(commissionId: string, timeoutMs: number);
-}
-export interface PollOptions {
-    timeoutMs?: number;
-    pollIntervalMs?: number;
-    /**
-     * Stops the wait and throws {@link CommissionAbortedError}, cutting the held
-     * long-poll with it. The task keeps running — cancelling it is the caller's call.
-     */
-    signal?: AbortSignalLike;
-    /**
-     * How long to wait before re-reading a done task whose result has not landed
-     * yet. Moa flips the status slightly before it writes. Default 0.
-     */
-    settleMs?: number;
-    /** Keep settling while a done task carries no artifacts. Set it when files were asked for. */
-    expectArtifacts?: boolean;
-}
-/** Wait for a commission to settle, long-polling rather than tight-polling. */
-export declare function pollUntilDone(client: CommissionClient, id: string, opts?: PollOptions): Promise<CommissionResult>;

package/dist/builtin/write-document/commission.js

@@ -1,13 +0,0 @@
-import{createRequest as w,MoaApiError as h}from"./http.js";const T={queued:"pending",running:"running",succeeded:"done",failed:"failed",canceled:"failed"},M=["md","pdf","docx","pptx"],g=n=>{const t=n?.split(".").pop()?.toLowerCase();return t&&M.includes(t)?t:void 0};function E(n){if(!n?.length)return;const t=n.flatMap(e=>{const s=g(e.name);return!s||!(e.url||e.data)?[]:[{name:e.name??`document.${s}`,format:s,url:e.url,data:e.data,mime:e.contentType,sizeBytes:e.sizeBytes}]});return t.length?t:void 0}function I(n){return`
-
-<deliverables>
-Besides the text answer, save the finished deliverable into the artifacts/ directory of your working dir as: ${n.map(t=>`one .${t} file`).join(", ")}.
-</deliverables>`}function x(n){let t=n.task;return n.context&&(t+=`
-
-<context>
-${n.context}
-</context>`),n.design&&(t+=`
-
-<design>
-${n.design}
-</design>`),n.artifacts?.length&&(t+=I(n.artifacts)),t}function _(n={}){const t=w(n);return{async create(e){const s=await t("/tasks",{method:"POST",body:{task:x(e),mode:"striker",...e.sessionId?{sessionId:e.sessionId}:{},...e.newSessionId?{newSessionId:e.newSessionId}:{}}});if(!s.id)throw new h("Moa did not return a task id",502);return s.id},async get(e,s){const c=s?.waitMs&&s.waitMs>0?`?waitMs=${Math.floor(s.waitMs)}`:"",o=await t(`/tasks/${encodeURIComponent(e)}${c}`,{signal:s?.signal}),i=o.status?T[o.status]:void 0;return{id:o.id??e,status:i??"running",output:o.result,error:o.error,costUsd:o.costUsd,numTurns:o.numTurns,sessionId:o.sessionId,artifacts:E(o.artifacts)}},async cancel(e){await t(`/tasks/${encodeURIComponent(e)}`,{method:"DELETE"})}}}const b=3e4,A=2e3,k=3,y=25e3;class m extends Error{commissionId;constructor(t){super(`Commission ${t} was cancelled by the caller.`),this.name="CommissionAbortedError",this.commissionId=t}}class C extends Error{commissionId;timeoutMs;constructor(t,e){super(`Commission ${t} did not complete within ${e/1e3}s. The task may still be running in the background.`),this.name="CommissionTimeoutError",this.commissionId=t,this.timeoutMs=e}}const f=(n,t)=>new Promise(e=>{const s=()=>e();t?.addEventListener("abort",s,{once:!0}),setTimeout(()=>{t?.removeEventListener("abort",s),e()},n)});async function p(n,t,e={}){const s=e.timeoutMs??b,c=e.pollIntervalMs??A,o=e.settleMs??0,i=e.signal,l=Date.now()+s;for(;;){if(i?.aborted)throw new m(t);const u=l-Date.now();if(u<=0)throw new C(t,s);let r;try{r=await n.get(t,{waitMs:Math.min(u,y),signal:i})}catch(d){throw i?.aborted?new m(t):d}if(r.status==="failed")return r;if(r.status==="done"){const d=a=>!a.output?.trim()||e.expectArtifacts===!0&&!a.artifacts?.length;for(let a=0;o>0&&a<k&&d(r);a++)await f(o),r=await n.get(t);return r}await f(Math.min(c,Math.max(0,l-Date.now())),i)}}export{m as CommissionAbortedError,C as CommissionTimeoutError,b as INTERACTIVE_TIMEOUT_MS,_ as createCommissionClient,p as pollUntilDone};

package/dist/builtin/write-document/design.d.ts

@@ -1,49 +0,0 @@
-import type { ArtifactFormat } from "./types.js";
-/**
- * The house style a commissioned document is built to.
- *
- * Every field is optional because a caller overrides only what its brand
- * actually fixes; the rest falls back to {@link DEFAULT_DESIGN}.
- */
-export interface DesignGuide {
-    /** What the style is called, so the document can say which one it followed. */
-    name?: string;
-    fonts?: {
-        heading?: string;
-        body?: string;
-        mono?: string;
-    };
-    palette?: {
-        primary?: string;
-        accent?: string;
-        text?: string;
-        muted?: string;
-        surface?: string;
-    };
-    /** Page size, margins, grid, density. */
-    layout?: string;
-    /** How a figure earns its place and what it may not do. */
-    charts?: string;
-    /** How the writing sounds. */
-    tone?: string;
-    /** Fetchable logo, dropped on the cover and nowhere else. */
-    logoUrl?: string;
-    /** Hard rules, appended to the defaults rather than replacing them. */
-    rules?: readonly string[];
-}
-/**
- * What a document looks like when nobody has said.
- *
- * Chosen to be defensible rather than distinctive: one typeface, one accent,
- * real whitespace, and figures that carry a single message.
- */
-export declare const DEFAULT_DESIGN: DesignGuide;
-/**
- * A caller's guide over the defaults: named fields win, `rules` accumulate.
- *
- * Rules append because they are constraints — a brand adding "never use red"
- * means it as well as the defaults, not instead of them.
- */
-export declare function mergeDesign(base: DesignGuide, over?: DesignGuide): DesignGuide;
-/** The guide as the block Moa reads, since its artifact pipeline is prompt-driven. */
-export declare function renderDesign(guide: DesignGuide, format: ArtifactFormat, notes?: string): string;

package/dist/builtin/write-document/design.js

@@ -1,5 +0,0 @@
-const c={name:"Spendgraph house style",fonts:{heading:"Inter",body:"Inter",mono:"JetBrains Mono"},palette:{primary:"#0F172A",accent:"#2563EB",text:"#111827",muted:"#64748B",surface:"#FFFFFF"},layout:"A4 portrait, 20mm margins, a single text column at 60-75 characters, a 4pt spacing scale, and one heading scale used consistently (28/20/16/12). Whitespace is the design.",charts:"One message per figure, stated in its caption. Label series directly where there are three or fewer. No 3D, no gradients, no gridline heavier than the data, no pie chart past three slices, and axes that start at zero unless the caption says why not.",tone:"Plain and specific. Lead with the finding, then the evidence. No filler adjectives, no throat-clearing, no sentence that survives being deleted.",rules:["A cover carrying the title, date and author, and no other ornament.","Every number traceable to something in the source material; invent nothing.","Tables for anything being compared; prose for anything being argued.","No stock imagery, no clip art, no placeholder text in the finished file.","Page numbers on every page after the cover."]},d={pdf:"Cover, then contents if it runs past four pages, then the body. Figures captioned and referenced from the text. Nothing straddles a page break: no orphan heading, no split table row.",pptx:"16:9. One idea per slide, and the title is that idea as a sentence \u2014 a claim, not a label. At most six lines of body per slide, one figure per slide at most, and everything you cut goes into the speaker notes. Close on decisions and next steps, not on 'thank you'.",docx:"Real Word styles for headings rather than manual bold, a table-of-contents field rather than a typed list, a header row on every table, and captions on figures.",md:"A title heading, ATX headings throughout, tables for comparisons, fenced code with a language tag, and no HTML."};function i(e,t){return e?t?{...e,...t}:e:t}function h(e,t){return t?{...e,...t,fonts:i(e.fonts,t.fonts),palette:i(e.palette,t.palette),rules:[...e.rules??[],...t.rules??[]]}:e}const a=(e,t)=>t?[`${e}: ${t}`]:[];function p(e,t,o){const{fonts:r,palette:n}=e;return[...a("Style",e.name),...a("Typefaces",[r?.heading&&`headings ${r.heading}`,r?.body&&`body ${r.body}`,r?.mono&&`code ${r.mono}`].filter(Boolean).join(", ")||void 0),...a("Palette",[n?.primary&&`primary ${n.primary}`,n?.accent&&`accent ${n.accent}`,n?.text&&`text ${n.text}`,n?.muted&&`muted ${n.muted}`,n?.surface&&`surface ${n.surface}`].filter(Boolean).join(", ")||void 0),...a("Layout",e.layout),...a("Figures",e.charts),...a("Voice",e.tone),...a("Logo",e.logoUrl),`Format craft (.${t}): ${d[t]}`,...e.rules?.length?[`Rules:
-${e.rules.map(s=>`- ${s}`).join(`
-`)}`]:[],...o?.trim()?[`Overrides for this document, which win over everything above:
-${o.trim()}`]:[]].join(`
-`)}export{c as DEFAULT_DESIGN,h as mergeDesign,p as renderDesign};