@spendgraph/tools 0.5.0 → 0.7.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 spendgraph
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -2,281 +2,49 @@
 
 Declare a tool once, offer the right few, and record what was called.
 
-```sh
+```bash
 npm install @spendgraph/tools
 ```
 
-Three things are exported. Everything else hangs off what they return.
-
 ```ts
-import { tool, toolbus, currentTime } from "@spendgraph/tools";
-```
-
-## Declaring one
+import { calculate, tool, toolbus } from "@spendgraph/tools";
 
-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.
-
-```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"),
+  args: [{ name: "ref", type: "string", required: true }] as const,
+  run: ({ ref }) => search(ref),
 });
-```
-
-**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.
-
-The description is the biggest lever on whether the model calls it correctly, and
-worth iterating on more than the code is.
-
-Every check `tool` makes is something a provider either rejects opaquely or
-accepts and behaves oddly about — a name a provider will not take, an enum with
-no options, a blank option the model can legally pick and you cannot act on.
-They fire at import, not on the first loop in production.
-
-## What a tool does
-
-```ts
-tool({
-  name: "issue_refund",
-  description: "Refund a charge to the original card.",
-  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"]
+const bus = toolbus([lookup, calculate()], { limit: 6 });
+const turn = bus.trace(question);
 ```
 
-`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.
-
-It 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 rejected or ignored.
-
-Two 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.
-
-## The bus
+## What you get
 
-```ts
-const bus = toolbus([lookup, currentTime()], { limit: 6 });
-```
-
-Holding them 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.
+- **A description and a handler in one object**, so a rename is a compile error
+  rather than an `undefined` mid-loop.
+- **A shortlist, not a catalogue.** Fifty tools is 7.5k tokens before the user
+  has said anything, and more tools makes a model worse at picking.
+- **Effects**, so a gate can refuse what it must not retry — and name the tools
+  nobody labelled.
+- **Twenty-two builtins and twelve mocks**, none registered for you. Four of them
+  are one memory set, with an in-process store for testing it offline.
 
-```ts
-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()
-```
-
-`limit` is an accuracy budget, not a token one: 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.
-
-Selection is keyword and usage, deliberately — no embedding provider, no extra
-call, no latency. It is also the baseline that says what embeddings would buy.
-
-`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.
-
-## One 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. 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.
-
-It plugs straight into `@spendgraph/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,
-});
-```
-
-## Builtins
-
-Eight, each a factory, none registered for you — this package's own advice is
-that more tools in front of a model makes it worse at picking, so they are opt-in
-one at a time.
-
-```ts
-import { calculate, currentTime, escalate, finish, think, httpRequest } from "@spendgraph/tools";
-
-const bus = toolbus([
-  calculate(),
-  think(),
-  finish(),
-  currentTime({ defaultTimeZone: "Europe/London" }),
-  escalate({ onEscalate: (r) => pager.page(r) }),
-  httpRequest({ allow: [".example.com"], headers: { authorization: `Bearer ${key}` } }),
-]);
-```
+## Docs
 
 | | |
 | --- | --- |
-| `calculate()` | arithmetic, **parsed not evaluated** |
-| `think()` | a scratchpad that does nothing |
-| `finish()` | the model says it is done, and what the answer is |
-| `currentTime()` | the clock a model does not have |
-| `escalate()` | hand back to a person; `pinned` by default |
-| `dateMath()` | add, subtract and difference, in whole units |
-| `jsonQuery()` | one value out of a JSON document, by path |
-| `httpRequest()` | a GET or POST to hosts you named |
-| `writeDocument()` | a document agent that returns a rendered file |
-
-**`calculate`** parses the expression — numbers, `+ - * / % ^`, brackets, and
-`sqrt abs round floor ceil ln log` — and refuses everything else. `eval` on model
-output is arbitrary code execution with extra steps.
-
-**`think`** returns `"noted"` and changes nothing. That is the point: the thought
-lands in the steps instead of in the reply, and a model given room to plan before
-a multi-step sequence uses the tools better.
-
-**`finish`** gives a loop a real stop condition. Without it a run ends when the
-model goes quiet, which is indistinguishable from it losing the thread. Read the
-result with `isFinished(result)` and `answerOf(result)`.
-
-**`current_time`** is the clock a model does not have. Asked for today's date it
-will otherwise produce its training cutoff, confidently. A wrong IANA zone throws
-rather than falling back, because a confidently wrong time is the failure this
-exists to stop.
-
-**`escalate`** is `pinned: true`, because a refusal route lost to a similarity
-score is exactly the failure `pinned` exists for — the one turn that needs it is
-the turn where nothing else fit. Without an `onEscalate` it records the request
-and reports `delivered: false`, rather than letting the model believe a person
-was reached.
-
-**`dateMath`** is what `current_time` leads to: the clock says when now is, this
-works out what follows. Calendar months clamp rather than overflow — a month
-after 31 January is 28 February, not 3 March, which is what `setMonth` gives and
-what every billing system disagrees with. `difference` counts boundaries crossed
-rather than dividing elapsed milliseconds, because a month is not 30 days and a
-year is not 365.
-
-**`jsonQuery`** reads one value out of a document by path — `invoices[0].total`,
-or `invoices[*].total` for every element. After a wildcard the rest of the path
-keeps applying to each element, so `invoices[*].lines[0].sku` is the first line
-of every invoice, not the lines of the first. A path that matches nothing comes
-back `found: false` rather than `null`, which a model would otherwise read as the
-answer.
-
-**`httpRequest`** takes a **required** allowlist and has no default. It is https
-only, refuses private, loopback, link-local and `.internal`/`.local` hosts even
-if you list them, and sets headers itself so a credential is never something the
-model can redirect. `"api.example.com"` matches that host; `".example.com"`
-matches it and any subdomain. If the guard feels heavy, that is the correct
-amount of heavy: this is the one builtin that can exfiltrate.
-
-## `write_document`
-
-```ts
-toolbus([
-  writeDocument({
-    apiKey: env.MOA_API_KEY,
-    design: {
-      name: "Northwind",
-      fonts: { heading: "Söhne" },
-      palette: { accent: "#E11D48" },
-      rules: ["Never set body text below 11pt."],
-    },
-  }),
-]);
-```
-
-Commissions a Moa agent to write and render a real file — `.pdf`, `.pptx`,
-`.docx`, `.md` — and hands back where to download it. Everything else in this
-package answers a question; this one produces the document somebody opens.
-
-Style is the deployment's business and content is the model's. `design` is laid
-over `DEFAULT_DESIGN`: named fields win, `rules` accumulate, and the merged
-guide is rendered into the task as a `<design>` block along with the craft that
-belongs to the format asked for — a deck gets "one idea per slide, the title is
-the claim", a PDF gets "nothing straddles a page break". The model may pass
-`design_notes` to bend the guide for one document; it cannot replace it.
-
-A rendered document is minutes, so the wait defaults to ten of them and
-long-polls rather than tight-polls. When even that runs out the result comes
-back `status: "running"` with the `taskId`, because the money is already spent
-and a lost id makes the model commission it twice. Stop the turn and the task is
-cancelled server-side.
-
-It is the one builtin marked `destructive`, and not because it breaks anything:
-a second call is a second bill and a second set of files, so it is never safe to
-retry on its own.
-
-## Examples
-
-Eight of them under [`examples/`](./examples), all runnable with no API key and
-no network — tools are local code; the model only decides which to call.
-
-```sh
-npm run build
-node examples/02-select/01-shortlist.mjs
-```
-
-## Subpaths
-
-| | |
-| --- | --- |
-| `@spendgraph/tools/wire` | `toAnthropic` · `toOpenAI` · `toJsonSchema` · `toMarkdown` |
-| `@spendgraph/tools/internals` | `selectTools` · `score` · `invokeTool` · `newTrace` · `toStep` · `warnOnOverlap` |
-
-A bus already wires all of `internals`; reach for it to build your own.
+| [Overview](https://spendgraph.locusgraph.com/docs/tools/overview) | A tool, a bus, and a turn |
+| [Declaring a tool](https://spendgraph.locusgraph.com/docs/tools/declaring) | Args, as const, and what is checked at import |
+| [A stored tool](https://spendgraph.locusgraph.com/docs/tools/stored) | Wording in the dashboard, handler in code |
+| [Effects](https://spendgraph.locusgraph.com/docs/tools/effects) | What running one does to the world outside |
+| [The bus](https://spendgraph.locusgraph.com/docs/tools/bus) | Holds, picks, converts, runs — and nests |
+| [Selecting](https://spendgraph.locusgraph.com/docs/tools/selecting) | The shortlist, and why it is a shortlist |
+| [A turn](https://spendgraph.locusgraph.com/docs/tools/turns) | Offered, called, and what the rollout keeps |
+| [Builtins](https://spendgraph.locusgraph.com/docs/tools/builtins) | Sixteen factories, none registered for you |
+| [Bogus tools](https://spendgraph.locusgraph.com/docs/tools/bogus) | Twelve mocks for testing the pipeline, not the provider |
 
 ## License
 
-MIT
+Apache-2.0

package/dist/agents/index.d.ts

@@ -0,0 +1 @@
+export { type ArtifactFormat, DEFAULT_DESIGN, type DesignGuide, MoaAbortedError, type MoaClient, MoaTimeoutError, mergeDesign, renderDesign, type WriteDocumentOptions, writeDocument, } from "./moa/index.js";

package/dist/agents/index.js

@@ -0,0 +1 @@
+import{DEFAULT_DESIGN as o,MoaAbortedError as t,MoaTimeoutError as D,mergeDesign as i,renderDesign as m,writeDocument as n}from"./moa/index.js";export{o as DEFAULT_DESIGN,t as MoaAbortedError,D as MoaTimeoutError,i as mergeDesign,m as renderDesign,n as writeDocument};

package/dist/agents/moa/design.js

@@ -0,0 +1,5 @@
+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};

package/dist/agents/moa/http.js

@@ -0,0 +1 @@
+const f="https://api.fnmoa.com",M=6e4,_=500;class c extends Error{status;detail;constructor(t,s,n){super(n?`${t}: ${n}`:t),this.name="MoaApiError",this.status=s,this.detail=n}}function T(e){const t=e.cause;return t?.code??t?.message??e.message}function m(e,t){const s=new AbortController,n=()=>s.abort();let r=!1;const o=setTimeout(()=>{r=!0,n()},e);return t?.addEventListener("abort",n,{once:!0}),t?.aborted&&n(),{signal:s.signal,expired:()=>r,release:()=>{clearTimeout(o),t?.removeEventListener("abort",n)}}}function $(e={}){const t=e.fetch??globalThis.fetch.bind(globalThis),s=(e.baseUrl??f).replace(/\/+$/,"");return async function(r,o={}){const u=o.timeoutMs??e.timeoutMs??6e4,i=o.method??"GET",d=`${s}${r}`,{signal:E,expired:h,release:b}=m(u,o.signal);try{const a=await t(d,{method:i,signal:E,headers:{...e.apiKey?{authorization:`Bearer ${e.apiKey}`}:{},...o.body===void 0?{}:{"content-type":"application/json"}},...o.body===void 0?{}:{body:JSON.stringify(o.body)}}).catch(l=>{throw o.signal?.aborted?l:h()?new c(`Moa did not answer ${i} ${r}`,504,`${u}ms`):new c(`Moa is unreachable at ${d}`,0,T(l))});if(!a.ok)throw new c(`Moa returned ${a.status} for ${i} ${r}`,a.status,(await a.text()).slice(0,500));return a.status===204?void 0:await a.json()}finally{b()}}}export{f as MOA_BASE_URL,c as MoaApiError,$ as createRequest};

package/dist/{builtin/write-document/write-document.d.ts → agents/moa/index.d.ts}

@@ -1,6 +1,6 @@
-import { type CommissionClient } from "./commission.js";
 import { type DesignGuide } from "./design.js";
 import type { AbortSignalLike } from "./http.js";
+import { type MoaClient } from "./moa.js";
 import type { ArtifactFormat } from "./types.js";
 export interface WriteDocumentOptions {
     /** Moa key. Required, and read from here rather than the environment. */
@@ -25,7 +25,7 @@ export interface WriteDocumentOptions {
     /** Longest write-up handed back. Default 4000 characters. */
     maxChars?: number;
     /** Injected for tests, and for anyone fronting Moa with their own transport. */
-    client?: CommissionClient;
+    client?: MoaClient;
     /** Injected for tests. */
     fetch?: typeof fetch;
 }
@@ -67,3 +67,8 @@ export declare function writeDocument(opts: WriteDocumentOptions): import("../..
     readonly required: false;
     readonly description: string;
 }]>>;
+export { DEFAULT_DESIGN, type DesignGuide, mergeDesign, renderDesign } from "./design.js";
+export { MOA_BASE_URL, MoaApiError, type MoaClientConfig } from "./http.js";
+export type { MoaClient, PollOptions } from "./moa.js";
+export { createMoaClient, INTERACTIVE_TIMEOUT_MS, MoaAbortedError, MoaTimeoutError, pollUntilDone, } from "./moa.js";
+export type { ArtifactFormat, MoaArtifact, MoaInput, MoaResult, MoaStatus, } from "./types.js";

package/dist/agents/moa/index.js

@@ -0,0 +1 @@
+import{tool as f}from"../../tool/index.js";import{DEFAULT_DESIGN as l,mergeDesign as h,renderDesign as g}from"./design.js";import{createMoaClient as p,MoaAbortedError as w,MoaTimeoutError as y,pollUntilDone as M}from"./moa.js";const _=["pdf","pptx","docx","md"],E=6e5,x=2e3,T=4e3;function A(e,r){return`Commissions a document agent to write and render a finished file \u2014 ${e.map(t=>`.${t}`).join(", ")} \u2014 and hands back where to download it. Use it when the answer has to be a document somebody opens: a report, a deck, a proposal, a one-pager. Not for text you can simply write in your reply. It runs for minutes and it costs money, so brief it once and brief it fully \u2014 the agent cannot see this conversation, so every fact, figure and quote it must use goes in \`source\`. Design is already settled by ${r.name??"the house style"}; use \`design_notes\` only for what this one document must do differently.`}function U(e,r,t,d){const i=(e.artifacts??[]).map(o=>({name:o.name,format:o.format,url:o.url,mime:o.mime,sizeBytes:o.sizeBytes,...d&&o.data?{data:o.data}:{}}));return{taskId:e.id,sessionId:e.sessionId,status:"done",style:r,documents:i,delivered:i.length>0,writeUp:e.output?.slice(0,t),truncated:(e.output?.length??0)>t,turns:e.numTurns,costMicroUsd:e.costUsd===void 0?void 0:Math.round(e.costUsd*1e6)}}function b(e,r,t){return{taskId:e,status:"running",style:r,documents:[],delivered:!1,note:`Still rendering after ${Math.round(t.timeoutMs/1e3)}s. The task is not lost \u2014 say so rather than commissioning it again.`}}function L(e){if(!e.client&&!e.apiKey?.trim())throw new Error("writeDocument needs a Moa apiKey; it will not read one from the process.");const r=e.formats?.length?e.formats:_,t=h(l,e.design),d=e.maxChars??T,i=e.client??p({apiKey:e.apiKey,baseUrl:e.baseUrl,...e.fetch?{fetch:e.fetch}:{}});return f({name:"write_document",description:A(r,t),effect:"destructive",args:[{name:"brief",type:"text",required:!0,maxLength:8e3,description:"What to produce, who reads it, what it must cover and how long it runs. Write it as you would brief a person who knows the craft and nothing about this account."},{name:"format",type:"enum",required:!0,options:["pdf","pptx","docx","md"],description:"pptx for anything presented, pdf for anything sent, docx for anything edited."},{name:"source",type:"text",required:!1,maxLength:4e4,description:"The material it must build from \u2014 figures, findings, quotes, an outline \u2014 verbatim. Anything missing here the agent will either omit or invent."},{name:"design_notes",type:"text",required:!1,maxLength:2e3,description:"How this one document departs from the house style, in plain words. Leave it empty unless the user asked for something specific."},{name:"session_id",type:"string",required:!1,description:"Continue an earlier write_document instead of starting over \u2014 take it from that result's sessionId. Use it to revise a document or to recast one into another format."}],run:async({brief:o,format:s,source:u,design_notes:m,session_id:c})=>{if(!r.includes(s))throw new Error(`write_document was asked for .${s}, which this deployment does not produce (${r.map(n=>`.${n}`).join(", ")}).`);const a=await i.create({task:o,context:u,design:g(t,s,m),artifacts:[s],...c?{sessionId:c}:{}});try{const n=await M(i,a,{timeoutMs:e.timeoutMs??E,settleMs:x,expectArtifacts:!0,...e.signal?{signal:e.signal}:{}});if(n.status==="failed")throw new Error(`write_document: Moa task ${a} failed: ${n.error??"no reason given"}`);return U(n,t.name,d,e.includeData===!0)}catch(n){if(n instanceof w&&e.cancelOnAbort!==!1&&await i.cancel?.(a).catch(()=>{}),n instanceof y)return b(a,t.name,n);throw n}}})}import{DEFAULT_DESIGN as $,mergeDesign as q,renderDesign as C}from"./design.js";import{MOA_BASE_URL as O,MoaApiError as R}from"./http.js";import{createMoaClient as N,INTERACTIVE_TIMEOUT_MS as B,MoaAbortedError as j,MoaTimeoutError as z,pollUntilDone as G}from"./moa.js";export{$ as DEFAULT_DESIGN,B as INTERACTIVE_TIMEOUT_MS,O as MOA_BASE_URL,j as MoaAbortedError,R as MoaApiError,z as MoaTimeoutError,N as createMoaClient,q as mergeDesign,G as pollUntilDone,C as renderDesign,L as writeDocument};

package/dist/{builtin/write-document/commission.d.ts → agents/moa/moa.d.ts}

@@ -1,5 +1,5 @@
 import { type AbortSignalLike, type MoaClientConfig } from "./http.js";
-import type { CommissionInput, CommissionResult } from "./types.js";
+import type { MoaInput, MoaResult } from "./types.js";
 /**
  * Moa's task surface — fire, then await.
  *
@@ -7,40 +7,40 @@ import type { CommissionInput, CommissionResult } from "./types.js";
  * (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>;
+export interface MoaClient {
+    create(input: MoaInput): Promise<string>;
     get(id: string, opts?: {
         waitMs?: number;
         signal?: AbortSignalLike;
-    }): Promise<CommissionResult>;
+    }): Promise<MoaResult>;
     cancel?(id: string): Promise<void>;
 }
 /**
- * HTTP {@link CommissionClient} over Moa's task API (`POST /tasks` → `GET /tasks/:id`).
+ * HTTP {@link MoaClient} 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;
+export declare function createMoaClient(config?: MoaClientConfig): MoaClient;
 /** 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);
+export declare class MoaAbortedError extends Error {
+    readonly taskId: string;
+    constructor(taskId: string);
 }
 /** Thrown when the wait ran out. The task itself is still running server-side. */
-export declare class CommissionTimeoutError extends Error {
-    readonly commissionId: string;
+export declare class MoaTimeoutError extends Error {
+    readonly taskId: string;
     readonly timeoutMs: number;
-    constructor(commissionId: string, timeoutMs: number);
+    constructor(taskId: string, timeoutMs: number);
 }
 export interface PollOptions {
     timeoutMs?: number;
     pollIntervalMs?: number;
     /**
-     * Stops the wait and throws {@link CommissionAbortedError}, cutting the held
+     * Stops the wait and throws {@link MoaAbortedError}, cutting the held
      * long-poll with it. The task keeps running — cancelling it is the caller's call.
      */
     signal?: AbortSignalLike;
@@ -52,5 +52,5 @@ export interface PollOptions {
     /** 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>;
+/** Wait for a Moa task to settle, long-polling rather than tight-polling. */
+export declare function pollUntilDone(client: MoaClient, id: string, opts?: PollOptions): Promise<MoaResult>;