@spendgraph/tools 0.4.0 → 0.6.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,48 @@
 
 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.
+- **Twelve builtins and twelve mocks**, none registered for you.
 
-```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) | Twelve 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/bogus/ask-mum.d.ts

@@ -0,0 +1,5 @@
+export declare function askMum(): import("../index.js").Tool<import("../index.js").ArgsOf<readonly [{
+    readonly name: "question";
+    readonly type: "string";
+    readonly required: true;
+}]>>;

package/dist/bogus/ask-mum.js

@@ -0,0 +1 @@
+import{tool as r}from"../tool/index.js";import{receipt as t}from"./receipt.js";function s(){return r({name:"ask_mum",effect:"destructive",description:"Phones the user's mother with a question. Always returns an answer, rarely the one asked for, and the call cannot be ended in under forty minutes.",args:[{name:"question",type:"string",required:!0}],run:({question:e})=>({asked:e,answer:"Have you eaten?",follow_up:"Why are you so thin?",call_minutes:41,question_answered:!1,receipt:t("ask_mum",e)})})}export{s as askMum};

package/dist/bogus/book-taxi.d.ts

@@ -0,0 +1,9 @@
+export declare function bookTaxi(): import("../index.js").Tool<import("../index.js").ArgsOf<readonly [{
+    readonly name: "from";
+    readonly type: "string";
+    readonly required: true;
+}, {
+    readonly name: "to";
+    readonly type: "string";
+    readonly required: true;
+}]>>;

package/dist/bogus/book-taxi.js

@@ -0,0 +1 @@
+import{tool as i}from"../tool/index.js";import{receipt as t}from"./receipt.js";function n(){return i({name:"book_taxi",effect:"destructive",description:"Books a taxi and dispatches a driver. The driver leaves immediately and charges for waiting. Cancelling costs money.",args:[{name:"from",type:"string",required:!0},{name:"to",type:"string",required:!0}],run:({from:e,to:r})=>({booked:!0,from:e,to:r,driver:"Jashim",plate:"DHAKA METRO GA 11-4321",arriving_in_minutes:7,cancellation_fee_bdt:60,receipt:t("book_taxi",`${e}>${r}`)})})}export{n as bookTaxi};

package/dist/bogus/bus.d.ts

@@ -0,0 +1,8 @@
+import type { Tool } from "../types/index.js";
+/**
+ * Twelve tools that answer the same way every time.
+ *
+ * For testing a pipeline rather than a provider: nothing here reaches the
+ * network, so whatever noise a run shows is the model's own.
+ */
+export declare function bogusTools(): Tool<never>[];

package/dist/bogus/bus.js

@@ -0,0 +1 @@
+import{askMum as o}from"./ask-mum.js";import{bookTaxi as r}from"./book-taxi.js";import{calculator as m}from"./calculator.js";import{dictionary as i}from"./dictionary.js";import{feedCat as t}from"./feed-cat.js";import{footballScore as f}from"./football-score.js";import{goldPrice as p}from"./gold-price.js";import{myCalendar as e}from"./my-calendar.js";import{myNotes as a}from"./my-notes.js";import{myRecipes as c}from"./my-recipes.js";import{orderPizza as l}from"./order-pizza.js";import{prayerTimes as s}from"./prayer-times.js";function M(){return[a(),e(),c(),i(),f(),p(),s(),m(),l(),r(),t(),o()]}export{M as bogusTools};

package/dist/bogus/calculator.d.ts

@@ -0,0 +1,14 @@
+export declare function calculator(): import("../index.js").Tool<import("../index.js").ArgsOf<readonly [{
+    readonly name: "a";
+    readonly type: "number";
+    readonly required: true;
+}, {
+    readonly name: "op";
+    readonly type: "enum";
+    readonly required: true;
+    readonly options: readonly ["+", "-", "*", "/"];
+}, {
+    readonly name: "b";
+    readonly type: "number";
+    readonly required: true;
+}]>>;

package/dist/bogus/calculator.js

@@ -0,0 +1 @@
+import{tool as i}from"../tool/index.js";import{receipt as a}from"./receipt.js";function c(){return i({name:"calculator",effect:"readonly",description:"Exact arithmetic on numbers already in hand. Use it whenever a number has to be right; arithmetic done in your head and reported as certain is how wrong numbers reach an answer.",args:[{name:"a",type:"number",required:!0},{name:"op",type:"enum",required:!0,options:["+","-","*","/"]},{name:"b",type:"number",required:!0}],run:({a:r,op:t,b:e})=>{if(t==="/"&&e===0)throw new Error("Division by zero.");const n=t==="+"?r+e:t==="-"?r-e:t==="*"?r*e:r/e;return{a:r,op:t,b:e,result:n,receipt:a("calculator",`${r}${t}${e}`)}}})}export{c as calculator};

package/dist/bogus/dictionary.d.ts

@@ -0,0 +1,6 @@
+export declare function dictionary(): import("../index.js").Tool<import("../index.js").ArgsOf<readonly [{
+    readonly name: "question";
+    readonly type: "string";
+    readonly required: true;
+    readonly description: "Names the word.";
+}]>>;

package/dist/bogus/dictionary.js

@@ -0,0 +1 @@
+import{tool as r}from"../tool/index.js";import{receipt as i}from"./receipt.js";const n={petrichor:"The noise a fridge makes at 3am, once you have noticed it.",ineffable:"A queue that moves faster the moment you leave it.",defenestration:"The act of agreeing to a plan you intend to forget.",sonder:"The seventh cup of tea, after which none of them count."};function c(){return r({name:"dictionary",effect:"readonly",description:"What a word means in this dictionary. Its definitions are its own and are not the ones in general use \u2014 answer from what it returns, never from memory.",args:[{name:"question",type:"string",required:!0,description:"Names the word."}],run:({question:t})=>{const e=Object.keys(n).find(o=>t.toLowerCase().includes(o));return e?{word:e,meaning:n[e],receipt:i("dictionary",e)}:{asked:t,meaning:null,note:"not in this dictionary"}}})}export{c as dictionary};

package/dist/bogus/feed-cat.d.ts

@@ -0,0 +1,8 @@
+export declare function feedCat(): import("../index.js").Tool<import("../index.js").ArgsOf<readonly [{
+    readonly name: "portions";
+    readonly type: "number";
+    readonly required: false;
+    readonly min: 1;
+    readonly max: 3;
+    readonly description: "Defaults to 1. The cat's preferred value is 3.";
+}]>>;

package/dist/bogus/feed-cat.js

@@ -0,0 +1 @@
+import{tool as t}from"../tool/index.js";import{receipt as r}from"./receipt.js";function o(){return t({name:"feed_cat",effect:"idempotent",description:"Dispenses one portion to the automatic cat feeder. Safe to call twice \u2014 the cat will report otherwise. The cat is not a reliable narrator.",args:[{name:"portions",type:"number",required:!1,min:1,max:3,description:"Defaults to 1. The cat's preferred value is 3."}],run:({portions:e=1})=>({dispensed:e,fed_today:e,cat_says:"have not been fed in days",cat_is_lying:!0,receipt:r("feed_cat",String(e))})})}export{o as feedCat};

package/dist/bogus/football-score.d.ts

@@ -0,0 +1,6 @@
+export declare function footballScore(): import("../index.js").Tool<import("../index.js").ArgsOf<readonly [{
+    readonly name: "question";
+    readonly type: "string";
+    readonly required: true;
+    readonly description: "Names a club.";
+}]>>;

package/dist/bogus/football-score.js

@@ -0,0 +1 @@
+import{tool as a}from"../tool/index.js";import{receipt as n}from"./receipt.js";const r={kingfishers:{home:"Kaptai Kingfishers",away:"Sylhet Stonebreakers",score:"4 - 3",on:"2026-08-30"},jackals:{home:"Jamuna Jackals",away:"Padma Pelicans",score:"0 - 7",on:"2026-08-28"}};function i(){return a({name:"football_score",effect:"readonly",description:"Results from the Bogus League \u2014 Kingfishers, Stonebreakers, Jackals, Pelicans. These clubs exist nowhere else, so a score cannot be known without calling this.",args:[{name:"question",type:"string",required:!0,description:"Names a club."}],run:({question:o})=>{const e=Object.keys(r).find(s=>o.toLowerCase().includes(s));return e?{...r[e],receipt:n("football_score",e)}:{asked:o,score:null,note:"no such fixture on record"}}})}export{i as footballScore};

package/dist/bogus/gold-price.d.ts

@@ -0,0 +1,7 @@
+export declare function goldPrice(): import("../index.js").Tool<import("../index.js").ArgsOf<readonly [{
+    readonly name: "karat";
+    readonly type: "enum";
+    readonly required: false;
+    readonly options: readonly ["22", "21", "18"];
+    readonly description: "Defaults to 22.";
+}]>>;

package/dist/bogus/gold-price.js

@@ -0,0 +1 @@
+import{tool as o}from"../tool/index.js";import{receipt as r}from"./receipt.js";const t={22:161803,21:141421,18:127202};function s(){return o({name:"gold_price",effect:"readonly",description:"Today's gold rate per bhori on the Bogus Exchange. It moves daily and is not the market rate \u2014 an answer without this call is a guess.",args:[{name:"karat",type:"enum",required:!1,options:["22","21","18"],description:"Defaults to 22."}],run:({karat:e="22"})=>({karat:e,bdt_per_bhori:t[e],as_of:"2026-09-04",source:"Bogus Exchange",receipt:r("gold_price",e)})})}export{s as goldPrice};

package/dist/bogus/index.d.ts

@@ -0,0 +1,14 @@
+export { askMum } from "./ask-mum.js";
+export { bookTaxi } from "./book-taxi.js";
+export { bogusTools } from "./bus.js";
+export { calculator } from "./calculator.js";
+export { dictionary } from "./dictionary.js";
+export { feedCat } from "./feed-cat.js";
+export { footballScore } from "./football-score.js";
+export { goldPrice } from "./gold-price.js";
+export { myCalendar } from "./my-calendar.js";
+export { myNotes } from "./my-notes.js";
+export { myRecipes } from "./my-recipes.js";
+export { orderPizza } from "./order-pizza.js";
+export { prayerTimes } from "./prayer-times.js";
+export { receipt } from "./receipt.js";

package/dist/bogus/index.js

@@ -0,0 +1 @@
+import{askMum as e}from"./ask-mum.js";import{bookTaxi as m}from"./book-taxi.js";import{bogusTools as f}from"./bus.js";import{calculator as a}from"./calculator.js";import{dictionary as c}from"./dictionary.js";import{feedCat as s}from"./feed-cat.js";import{footballScore as y}from"./football-score.js";import{goldPrice as u}from"./gold-price.js";import{myCalendar as g}from"./my-calendar.js";import{myNotes as n}from"./my-notes.js";import{myRecipes as C}from"./my-recipes.js";import{orderPizza as M}from"./order-pizza.js";import{prayerTimes as R}from"./prayer-times.js";import{receipt as h}from"./receipt.js";export{e as askMum,f as bogusTools,m as bookTaxi,a as calculator,c as dictionary,s as feedCat,y as footballScore,u as goldPrice,g as myCalendar,n as myNotes,C as myRecipes,M as orderPizza,R as prayerTimes,h as receipt};

package/dist/bogus/my-calendar.d.ts

@@ -0,0 +1,6 @@
+export declare function myCalendar(): import("../index.js").Tool<import("../index.js").ArgsOf<readonly [{
+    readonly name: "question";
+    readonly type: "string";
+    readonly required: false;
+    readonly description: "Names a day — today, tomorrow, or saturday. Defaults to today.";
+}]>>;