bantamkit 0.35.2__tar.gz → 0.35.4__tar.gz

{bantamkit-0.35.2 → bantamkit-0.35.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bantamkit
-Version: 0.35.2
+Version: 0.35.4
 Summary: Memory MCP server for Claude Code, Cursor, VS Code Copilot and Claude Desktop, plus a Python library that lifts small-model agents. Install once, run offline.
 Project-URL: Homepage, https://github.com/Ink01101011/bantamkit
 Project-URL: Repository, https://github.com/Ink01101011/bantamkit
@@ -19,11 +19,12 @@ Requires-Dist: httpx>=0.27
 Requires-Dist: jsonschema>=4.21
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
 Requires-Dist: hatchling>=1.24; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Provides-Extra: mcp
-Requires-Dist: mcp<3,>=2.0; extra == 'mcp'
+Requires-Dist: mcp<2.1,>=2.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # bantamkit — memory MCP server for Claude Code, Cursor, VS Code Copilot and Claude Desktop (Python)
@@ -39,6 +40,10 @@ The same server in pure Node is on **npm** as
 disk and a conformance suite holds them to the same answers, so install whichever your host makes
 easy.
 
+**This page is the PyPI package's.** Every command on it runs `bantamkit` from PyPI. The npm
+package is named where the two differ, but its own install, update and CLI commands live on
+[its page](https://www.npmjs.com/package/bantamkit-mcp); run them here and you get nothing.
+
 ## Contents
 
 | Topic | What you'll find |
@@ -60,6 +65,7 @@ easy.
 | [The asset pack](#the-asset-pack) | `--assets-root`, `BANTAMKIT_ASSETS` |
 | [The operator CLI: `python -m bantamkit.memory`](#the-operator-cli-python--m-bantamkitmemory) | status, lint, compact, archived, archive, restore |
 | [Where the Python and Node servers differ](#where-the-python-and-node-servers-differ) | One store; pdf/.doc/.rtf, CLI name, `build_id` |
+| [Module API](#module-api) | `import bantamkit`: the library half, measured from the wheel |
 | [Development](#development) | Clone, test, lint, conformance |
 | [Documentation](#documentation) | The full docs on GitHub |
 
@@ -97,9 +103,9 @@ CPU architecture and Python minor version** (some wheels, such as `pydantic_core
 one platform only), copy `wheels/` across, and install from it:
 
 ```bash
-python -m pip download "bantamkit[mcp]==0.35.2" -d wheels
+python -m pip download "bantamkit[mcp]==0.35.4" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.2"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.4"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -132,7 +138,10 @@ or re-run. The entry's `command` and `args` depend on the install route:
 |---|---|---|
 | Python venv, install once | `/absolute/path/to/env/bin/bantamkit-mcp` | `[]` |
 | pipx at every launch | `pipx` | `["run", "--spec", "bantamkit[mcp]", "bantamkit-mcp"]` |
-| npm, install once | see the [npm package](https://www.npmjs.com/package/bantamkit-mcp) | |
+
+Both rows are PyPI installs. The npm package records a different `command` and `args`, written
+on [its page](https://www.npmjs.com/package/bantamkit-mcp); the two shapes are not
+interchangeable.
 
 To check a recorded command, run it in a terminal: with nothing on stdin it prints
 `usage: bantamkit-mcp …`.
@@ -338,6 +347,99 @@ a conformance case compares their answers. Three differences are deliberate, eac
 - **`build_id`** hashes the executing tree, so it differs by construction; `assets_digest` is
   identical, and that is the one that carries meaning.
 
+## Module API
+
+The package is a server first, but it is importable too: `import bantamkit` is a supported call,
+and the names behind it are part of what is published.
+
+Everything in this section was measured against the **wheel**, not the source tree: a
+`bantamkit-0.35.3-py3-none-any.whl` built with `pip wheel --no-deps --no-build-isolation`,
+installed into a throwaway venv with `--no-index --no-deps`, and imported from a working
+directory outside the checkout (2026-09-21). A name that only exists in `src/` is not API; this
+is what an importer gets.
+
+**There is no `exports` map in Python, so nothing is sealed.** The wheel carries **31** modules
+and every one is deep-importable — `from bantamkit.mcpserver import main` resolves, and so does
+`from bantamkit.memory import MemoryStore`. That is the opposite of the npm package, which
+declares a single `.` entry point and refuses every deep import with
+`ERR_PACKAGE_PATH_NOT_EXPORTED`. Only the names below are *intended* as API; the rest are
+reachable because Python has no way to say otherwise.
+
+**`import bantamkit` binds 45 names, of which 30 are values.** The other 15 are submodules bound
+as a side effect of the package's own imports (`agent`, `assets`, `budget`, `client`, `contract`,
+`critique`, `docmanifest`, `docread`, `evalrun`, `filegraph`, `loopguard`, `memory`, `pdfread`,
+`profile`, `textutil`). There is no `__all__`, so `from bantamkit import *` takes all 45.
+
+| Module behind it | What it is | Names |
+| --- | --- | --- |
+| `bantamkit.agent` | the tool-calling loop | `Agent`, `AgentResult`, `MaxTurnsExceeded`, `ToolDef` |
+| `bantamkit.client` | the OpenAI-compatible transport and its wire types | `APIError`, `BantamError`, `Message`, `ModelClient`, `OpenAICompatible`, `Response`, `Tool`, `ToolCall`, `TransportError`, `Usage` |
+| `bantamkit.critique` | the critique gate and its rubrics | `CritiqueExhausted`, `CritiqueGate`, `GroundedCritiqueGate`, `Rubric`, `load_rubric` |
+| `bantamkit.evalrun` | the suite runner | `CONFIGS`, `format_report`, `run_suite` |
+| `bantamkit.structured` | schema-constrained output | `StructuredOutputError`, `structured` |
+| `bantamkit.contract` | JSON out of model prose, and evidence rendering | `extract_json`, `render_evidence` |
+| `bantamkit.loopguard` | the repetition cut-off | `LoopGuard` |
+| `bantamkit.filegraph` | the file-access graph | `FileAccessGraph` |
+| `bantamkit.memory` | the memory store | `Memory`, `MemoryStore` |
+| **9 modules** | | **30 values, no `__all__`** |
+
+**This is not the npm package's export surface.** Both runtimes serve the same fourteen MCP
+tools, but what each one exports *to an importer* is a different product: here it is the
+agent/critique/eval library above; there it is the memory store, the asset pack, the event log,
+the shift-work tools and a set of CPython-semantics shims — 139 values behind one entry point. Of
+these 30 names exactly **three** are spelled the same on the npm side (`BantamError`, `Memory`,
+`MemoryStore`), and a spelling is not a promise about behaviour. A parity claim about the MCP
+tools is not a parity claim about these.
+
+**A worked start.** Copy-paste examples:
+[`examples/`](https://github.com/Ink01101011/bantamkit/tree/main/examples).
+
+```python
+from bantamkit import Agent, CritiqueGate, Memory, OpenAICompatible, Tool, ToolDef
+
+client = OpenAICompatible(base_url="http://localhost:11434/v1", model="qwen2.5:7b-instruct")
+
+price_lookup = ToolDef(
+    tool=Tool(
+        name="price_lookup",
+        description="Get the unit price of an item",
+        parameters={
+            "type": "object",
+            "required": ["item"],
+            "properties": {"item": {"type": "string"}},
+        },
+    ),
+    handler=lambda item: f"{item} price: 25",
+)
+
+agent = Agent(client=client, tools=[price_lookup]).use(
+    Memory(store="./.bantam-memory"),
+    CritiqueGate("task-completion"),
+)
+
+result = agent.run("What does a widget cost? Remember it for next time.")
+print(result.output, result.usage.total)
+```
+
+Which options are worth attaching, measured over 528 runs per model:
+[docs/usage.md → Recommended defaults](https://github.com/Ink01101011/bantamkit/blob/main/docs/usage.md#recommended-defaults).
+
+**Rerun the numbers.** Against the published wheel, in a throwaway venv:
+
+```bash
+python -m venv /tmp/bk && /tmp/bk/bin/pip install bantamkit
+/tmp/bk/bin/python -c "import bantamkit; print(len([n for n in dir(bantamkit) if not n.startswith('_')]))"
+```
+
+It prints `45`. The 30 values alone, without the submodules:
+
+```bash
+/tmp/bk/bin/python -c "import bantamkit, types; print(sorted(n for n in dir(bantamkit) if not n.startswith('_') and not isinstance(getattr(bantamkit, n), types.ModuleType)))"
+```
+
+Both numbers move whenever `src/bantamkit/__init__.py` does, which is why they are quoted with
+the command that prints them rather than kept in prose.
+
 ## Development
 
 ```bash

{bantamkit-0.35.2 → bantamkit-0.35.4}/README.md

@@ -11,6 +11,10 @@ The same server in pure Node is on **npm** as
 disk and a conformance suite holds them to the same answers, so install whichever your host makes
 easy.
 
+**This page is the PyPI package's.** Every command on it runs `bantamkit` from PyPI. The npm
+package is named where the two differ, but its own install, update and CLI commands live on
+[its page](https://www.npmjs.com/package/bantamkit-mcp); run them here and you get nothing.
+
 ## Contents
 
 | Topic | What you'll find |
@@ -32,6 +36,7 @@ easy.
 | [The asset pack](#the-asset-pack) | `--assets-root`, `BANTAMKIT_ASSETS` |
 | [The operator CLI: `python -m bantamkit.memory`](#the-operator-cli-python--m-bantamkitmemory) | status, lint, compact, archived, archive, restore |
 | [Where the Python and Node servers differ](#where-the-python-and-node-servers-differ) | One store; pdf/.doc/.rtf, CLI name, `build_id` |
+| [Module API](#module-api) | `import bantamkit`: the library half, measured from the wheel |
 | [Development](#development) | Clone, test, lint, conformance |
 | [Documentation](#documentation) | The full docs on GitHub |
 
@@ -69,9 +74,9 @@ CPU architecture and Python minor version** (some wheels, such as `pydantic_core
 one platform only), copy `wheels/` across, and install from it:
 
 ```bash
-python -m pip download "bantamkit[mcp]==0.35.2" -d wheels
+python -m pip download "bantamkit[mcp]==0.35.4" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.2"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.4"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -104,7 +109,10 @@ or re-run. The entry's `command` and `args` depend on the install route:
 |---|---|---|
 | Python venv, install once | `/absolute/path/to/env/bin/bantamkit-mcp` | `[]` |
 | pipx at every launch | `pipx` | `["run", "--spec", "bantamkit[mcp]", "bantamkit-mcp"]` |
-| npm, install once | see the [npm package](https://www.npmjs.com/package/bantamkit-mcp) | |
+
+Both rows are PyPI installs. The npm package records a different `command` and `args`, written
+on [its page](https://www.npmjs.com/package/bantamkit-mcp); the two shapes are not
+interchangeable.
 
 To check a recorded command, run it in a terminal: with nothing on stdin it prints
 `usage: bantamkit-mcp …`.
@@ -310,6 +318,99 @@ a conformance case compares their answers. Three differences are deliberate, eac
 - **`build_id`** hashes the executing tree, so it differs by construction; `assets_digest` is
   identical, and that is the one that carries meaning.
 
+## Module API
+
+The package is a server first, but it is importable too: `import bantamkit` is a supported call,
+and the names behind it are part of what is published.
+
+Everything in this section was measured against the **wheel**, not the source tree: a
+`bantamkit-0.35.3-py3-none-any.whl` built with `pip wheel --no-deps --no-build-isolation`,
+installed into a throwaway venv with `--no-index --no-deps`, and imported from a working
+directory outside the checkout (2026-09-21). A name that only exists in `src/` is not API; this
+is what an importer gets.
+
+**There is no `exports` map in Python, so nothing is sealed.** The wheel carries **31** modules
+and every one is deep-importable — `from bantamkit.mcpserver import main` resolves, and so does
+`from bantamkit.memory import MemoryStore`. That is the opposite of the npm package, which
+declares a single `.` entry point and refuses every deep import with
+`ERR_PACKAGE_PATH_NOT_EXPORTED`. Only the names below are *intended* as API; the rest are
+reachable because Python has no way to say otherwise.
+
+**`import bantamkit` binds 45 names, of which 30 are values.** The other 15 are submodules bound
+as a side effect of the package's own imports (`agent`, `assets`, `budget`, `client`, `contract`,
+`critique`, `docmanifest`, `docread`, `evalrun`, `filegraph`, `loopguard`, `memory`, `pdfread`,
+`profile`, `textutil`). There is no `__all__`, so `from bantamkit import *` takes all 45.
+
+| Module behind it | What it is | Names |
+| --- | --- | --- |
+| `bantamkit.agent` | the tool-calling loop | `Agent`, `AgentResult`, `MaxTurnsExceeded`, `ToolDef` |
+| `bantamkit.client` | the OpenAI-compatible transport and its wire types | `APIError`, `BantamError`, `Message`, `ModelClient`, `OpenAICompatible`, `Response`, `Tool`, `ToolCall`, `TransportError`, `Usage` |
+| `bantamkit.critique` | the critique gate and its rubrics | `CritiqueExhausted`, `CritiqueGate`, `GroundedCritiqueGate`, `Rubric`, `load_rubric` |
+| `bantamkit.evalrun` | the suite runner | `CONFIGS`, `format_report`, `run_suite` |
+| `bantamkit.structured` | schema-constrained output | `StructuredOutputError`, `structured` |
+| `bantamkit.contract` | JSON out of model prose, and evidence rendering | `extract_json`, `render_evidence` |
+| `bantamkit.loopguard` | the repetition cut-off | `LoopGuard` |
+| `bantamkit.filegraph` | the file-access graph | `FileAccessGraph` |
+| `bantamkit.memory` | the memory store | `Memory`, `MemoryStore` |
+| **9 modules** | | **30 values, no `__all__`** |
+
+**This is not the npm package's export surface.** Both runtimes serve the same fourteen MCP
+tools, but what each one exports *to an importer* is a different product: here it is the
+agent/critique/eval library above; there it is the memory store, the asset pack, the event log,
+the shift-work tools and a set of CPython-semantics shims — 139 values behind one entry point. Of
+these 30 names exactly **three** are spelled the same on the npm side (`BantamError`, `Memory`,
+`MemoryStore`), and a spelling is not a promise about behaviour. A parity claim about the MCP
+tools is not a parity claim about these.
+
+**A worked start.** Copy-paste examples:
+[`examples/`](https://github.com/Ink01101011/bantamkit/tree/main/examples).
+
+```python
+from bantamkit import Agent, CritiqueGate, Memory, OpenAICompatible, Tool, ToolDef
+
+client = OpenAICompatible(base_url="http://localhost:11434/v1", model="qwen2.5:7b-instruct")
+
+price_lookup = ToolDef(
+    tool=Tool(
+        name="price_lookup",
+        description="Get the unit price of an item",
+        parameters={
+            "type": "object",
+            "required": ["item"],
+            "properties": {"item": {"type": "string"}},
+        },
+    ),
+    handler=lambda item: f"{item} price: 25",
+)
+
+agent = Agent(client=client, tools=[price_lookup]).use(
+    Memory(store="./.bantam-memory"),
+    CritiqueGate("task-completion"),
+)
+
+result = agent.run("What does a widget cost? Remember it for next time.")
+print(result.output, result.usage.total)
+```
+
+Which options are worth attaching, measured over 528 runs per model:
+[docs/usage.md → Recommended defaults](https://github.com/Ink01101011/bantamkit/blob/main/docs/usage.md#recommended-defaults).
+
+**Rerun the numbers.** Against the published wheel, in a throwaway venv:
+
+```bash
+python -m venv /tmp/bk && /tmp/bk/bin/pip install bantamkit
+/tmp/bk/bin/python -c "import bantamkit; print(len([n for n in dir(bantamkit) if not n.startswith('_')]))"
+```
+
+It prints `45`. The 30 values alone, without the submodules:
+
+```bash
+/tmp/bk/bin/python -c "import bantamkit, types; print(sorted(n for n in dir(bantamkit) if not n.startswith('_') and not isinstance(getattr(bantamkit, n), types.ModuleType)))"
+```
+
+Both numbers move whenever `src/bantamkit/__init__.py` does, which is why they are quoted with
+the command that prints them rather than kept in prose.
+
 ## Development
 
 ```bash

bantamkit-0.35.4/_assets/tools/shiftwork_clock_in.json

@@ -0,0 +1,37 @@
+{
+  "name": "shiftwork_clock_in",
+  "description": "Shift-work clock-in: schema-validate the checkpoint file and return the brief for the unit at plan.cursor — {unit, role, invariants, handoff, do_not, files} — to hand to the spawned agent verbatim. The unit briefed is the one at plan.cursor, or, when unit_id is given, that unit — which must appear in shiftwork_plan's `ready`, the batch the dependency graph says may run now. A unit_id that is not ready, including one naming no unit, is refused with {\"result\": \"error\", \"reason\": \"unit <id> is not ready; ready is <a, b>\"}, and the refusals of the batch view itself (cycle, unknown dependency, unreadable checkpoint) pass through verbatim. Clock-in still never moves plan.cursor; clock_out does. Structured refusals, never exceptions: result=escalate when handoff.open_questions is non-empty, result=success when every unit is done or dropped, result=error when the checkpoint fails validation. Clock-in also WRITES: on result=brief, and only then, it appends one line {event: brief, ts, unit, role} to <checkpoint>.log.jsonl — best-effort: a log it cannot write costs the brief nothing (the brief still returns, no error, only the record is lost). clock_out reads those lines back to write `briefed` on every accounting line, so the ledger is no longer one line per clock-out; a brief line carries `event` and no `status`. See docs/shiftwork.md.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string"
+      },
+      "unit_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Unit Id"
+      }
+    },
+    "required": [
+      "checkpoint"
+    ],
+    "type": "object",
+    "title": "shiftwork_clock_inArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "shiftwork_clock_inDictOutput"
+  }
+}

bantamkit-0.35.4/_assets/tools/shiftwork_clock_out.json

@@ -0,0 +1,150 @@
+{
+  "name": "shiftwork_clock_out",
+  "description": "Shift-work clock-out: record a finished unit — set its status, advance plan.cursor, merge handoff_patch, push history_entry onto the 5-entry ring — validating the whole mutated document against the checkpoint schema BEFORE an atomic write (a failure writes nothing and returns result=error). `unit_id` must be `plan.cursor` — which needs no brief, clocking out with briefed=false — OR a unit briefed since its own last clock-out; any other id keeps its refusal (`unit X is not the cursor unit Y`). plan.cursor then advances to the head of the ready batch recomputed on the mutated document, falling back to plan.units order over the remaining non-terminal units when the graph cannot batch (cycle or unknown dependency), and to unit_id when none remain. `handoff_patch` and `history_entry` are both required arguments: `handoff_patch` is shallow-merged into `handoff` and takes only its four keys (pass `{}` to leave it unchanged); `history_entry` needs `unit` and `outcome`; `status` is one of the five unit statuses — a value outside these shapes is refused by the schema check, nothing written. Every success appends one accounting line (unit, role, status, ts, briefed, plus your accounting fields, e.g. tokens/duration_ms/model) to <checkpoint>.log.jsonl, beside the brief lines clock_in writes (a brief line carries `event` and no `status`). `accounting` is optional: null, the default, logs a line with no cost figures at all; a non-null line must fit the accounting shape below. `briefed` is written by the runtime, never taken from you: true when a brief was issued for this unit since its LAST clock-out (not ever), so a unit re-run after a blocked clock-out reads false. If job.roles names this unit's role, accounting.model must be one of that role's model identifiers, spelled exactly, or nothing is written — see the `model` property below.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string"
+      },
+      "unit_id": {
+        "title": "Unit Id",
+        "type": "string",
+        "description": "The unit being clocked out. Must be plan.cursor, or a unit briefed since its own last clock-out: clock_in briefs the cursor unit by default and, when its unit_id names one, any unit shiftwork_plan reports in `ready` — and that brief is what lets clock_out accept a unit the cursor is not on."
+      },
+      "status": {
+        "title": "Status",
+        "type": "string",
+        "enum": [
+          "todo",
+          "in_progress",
+          "done",
+          "blocked",
+          "dropped"
+        ],
+        "description": "The unit's new status; the same five values the checkpoint schema allows on plan.units[].status."
+      },
+      "handoff_patch": {
+        "title": "Handoff Patch",
+        "type": "object",
+        "additionalProperties": false,
+        "description": "Shallow-merged into `handoff`: only these four keys exist there, and a key outside them is refused by the schema check. Required; `{}` leaves `handoff` unchanged.",
+        "properties": {
+          "next_action": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Imperative first move — zero re-derivation."
+          },
+          "open_questions": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "The autonomy switch: empty = driver keeps cycling, non-empty = STOP and ask."
+          },
+          "do_not": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "Negative space — near-mistakes past sessions made."
+          },
+          "notes": {
+            "type": "string",
+            "description": "Free-form prose for the next session, one string; the empty string clears it."
+          }
+        }
+      },
+      "history_entry": {
+        "title": "History Entry",
+        "type": "object",
+        "required": [
+          "unit",
+          "outcome"
+        ],
+        "additionalProperties": true,
+        "description": "Pushed onto the 5-entry `history` ring; `unit` and `outcome` are required, `notes` optional, other keys pass through.",
+        "properties": {
+          "unit": {
+            "type": "string",
+            "minLength": 1
+          },
+          "outcome": {
+            "type": "string",
+            "minLength": 1
+          },
+          "notes": {
+            "type": "string"
+          }
+        }
+      },
+      "accounting": {
+        "anyOf": [
+          {
+            "type": "object",
+            "description": "Per-unit cost. Written verbatim, beside ts/unit/role/status, as one line of <checkpoint>.log.jsonl - the ledger the N-sessions experiment reads. The keys named here have fixed meanings so a reader holding only the ledger knows what each number counts, in which unit, and which model produced it; any other key passes through unchanged (a refused key is friction, not safety). Lines written before this schema existed may spell these differently; the schema governs new writes only.",
+            "properties": {
+              "tokens": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Tokens the unit consumed as the harness's subagent counter reports them: every class it reports (input, output, cache creation) summed, EXCLUDING cache reads. In a non-null accounting line it is required — a line without it is refused before anything is written; only `accounting: null`, the default, is exempt, and that logs no cost at all. A rounded self-estimate is allowed only if `note` says it is one; a unit whose cost is unknown cannot be compared with any other."
+              },
+              "cache_read_tokens": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Tokens the unit's requests served from prompt cache, kept OUT of `tokens` because they dominate a real session's traffic and would swamp the work signal. Optional: omit it when the harness reports no such figure - a written 0 means the unit read nothing from cache."
+              },
+              "duration_ms": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Wall-clock from spawning the subagent to its final message, in whole milliseconds. In a non-null line it is required, and it is the only duration key with a defined meaning: older lines carry `duration`, `duration_min` or `duration_s`, which this schema neither reads nor renames."
+              },
+              "model": {
+                "type": "string",
+                "description": "The exact identifier of the model the subagent actually ran on (e.g. `claude-sonnet-5`) and nothing else - a caveat about how it was chosen belongs in `note`. Not required here: when the checkpoint's job.roles names this unit's role, clock_out already requires it and refuses a value off that role's list, spelled exactly; a checkpoint with no job.roles leaves it optional. This schema does not change that gate."
+              },
+              "tool_uses": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Tool calls the subagent made, as the harness counts them. Optional; it is the denominator that makes `tokens` comparable across units of different size (per-unit cost is linear in tool calls, not in unit length)."
+              },
+              "note": {
+                "type": "string",
+                "description": "Free text for what the fields above cannot say: that `tokens` is an estimate, that this is a retry or a second scope under the same unit id, what a harness counter excludes. Anything that is not a model identifier goes here, not in `model`."
+              }
+            },
+            "required": [
+              "tokens",
+              "duration_ms"
+            ],
+            "additionalProperties": true
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Accounting"
+      }
+    },
+    "required": [
+      "checkpoint",
+      "unit_id",
+      "status",
+      "handoff_patch",
+      "history_entry"
+    ],
+    "type": "object",
+    "title": "shiftwork_clock_outArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "shiftwork_clock_outDictOutput"
+  }
+}

bantamkit-0.35.4/_assets/tools/shiftwork_plan.json

@@ -0,0 +1,25 @@
+{
+  "name": "shiftwork_plan",
+  "description": "Shift-work plan: read-only batch view of a checkpoint — which units its `depends_on` graph permits to run in parallel. Answers `{\"result\": \"plan\", \"batches\", \"ready\", \"sequence\", \"width\", \"cursor\"}`: `ready` is `batches[0]`, the units whose dependencies are all satisfied, and `width` is the largest batch length, the widest fan-out. A `ready` member beyond the cursor is clockable, but only in that order: shiftwork_clock_in briefs any unit in `ready` when `unit_id` names it, and shiftwork_clock_out then accepts that unit because it was briefed — an id that is neither the cursor nor briefed since its own last clock-out is still refused. Units with status `done` or `dropped` are satisfied — dropped from the graph, and edges pointing at them treated as already resolved; `todo`, `in_progress` and `blocked` stay in it. Every unit has priority 0, because the checkpoint schema has no priority field, so order inside a batch is `plan.units` order. Same refusal sentences as `work_plan` for a duplicate id, an unknown dependency or a cycle, and the same refusals `shiftwork_status` gives for a checkpoint it cannot read. It reports what the dependency graph permits; it does not move the cursor, which is echoed unchanged so the single-pointer contract and the batch view can be read side by side. An orchestrator stays responsible for what it actually dispatches: `depends_on` encodes logical order, not file contention. Never mutates.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string"
+      }
+    },
+    "required": [
+      "checkpoint"
+    ],
+    "type": "object",
+    "title": "shiftwork_planArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "shiftwork_planDictOutput"
+  }
+}

{bantamkit-0.35.2 → bantamkit-0.35.4}/pyproject.toml

@@ -68,8 +68,16 @@ dependencies = ["httpx>=0.27", "jsonschema>=4.21", "pyyaml>=6.0"]
 # installs the backend into an isolated build env, never into the target env, so
 # without this declaration the bar would silently skip in exactly the environment
 # CI runs (`pip install -e "runtime-py[dev,mcp]"`). Declared here so it runs.
-dev = ["pytest>=8.0", "ruff>=0.4", "hatchling>=1.24"]
-mcp = ["mcp>=2.0,<3"]
+# `build` is here because `tools/release/publish.sh` hard-requires it (it refuses at
+# preflight with "the repo venv cannot 'import build'") and nothing declared it, so every
+# release hit the same refusal and fixed it by hand. Added 2026-09-21, J62-15.
+dev = ["pytest>=8.0", "ruff>=0.4", "hatchling>=1.24", "build>=1.0"]
+# Upper bound measured, not guessed: 2.0.0 and 2.0.1 wrap a tool crash as
+# `Error executing tool <name>: <exc>`, which runtime-ts/src/mcp/server.ts mirrors.
+# 2.1.0 added an UnexpectedToolError branch that drops the `: <exc>` suffix, so the
+# crash text stops reaching the client and `--suite workplan` goes red on the
+# reference while the port still carries it. Raise this only together with the port.
+mcp = ["mcp>=2.0,<2.1"]
 
 [project.scripts]
 bantamkit-mcp = "bantamkit.mcpserver:main"

{bantamkit-0.35.2 → bantamkit-0.35.4}/src/bantamkit/__init__.py

@@ -29,4 +29,4 @@ from bantamkit.structured import StructuredOutputError, extract_json, structured
 # file as its dynamic version source, so the wheel's metadata and the string the MCP
 # server advertises are the same committed bytes, and neither is a function of when
 # someone last ran `pip`.
-__version__ = "0.35.2"
+__version__ = "0.35.4"