bantamkit 0.35.1__tar.gz → 0.35.3__tar.gz

{bantamkit-0.35.1 → bantamkit-0.35.3}/.gitignore

@@ -11,3 +11,4 @@ dist-*/
 .bantamkit/memory/
 .shiftwork/
 .release/
+.claude/

{bantamkit-0.35.1 → bantamkit-0.35.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bantamkit
-Version: 0.35.1
+Version: 0.35.3
 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
@@ -23,7 +23,7 @@ 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)
@@ -97,9 +97,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.1" -d wheels
+python -m pip download "bantamkit[mcp]==0.35.3" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.1"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.3"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 

{bantamkit-0.35.1 → bantamkit-0.35.3}/README.md

@@ -69,9 +69,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.1" -d wheels
+python -m pip download "bantamkit[mcp]==0.35.3" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.1"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.35.3"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 

bantamkit-0.35.3/_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`, the one unit clock_in briefs; any other id is refused (`unit X is not the cursor unit Y`). `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 — a self-reported value is overwritten by the measured one: true when a brief was issued for this unit since its LAST clock-out (not ever), so a unit re-run inline after a blocked clock-out reads false. A brief is not a precondition: a unit that was never clocked in still clocks out, with briefed=false. If the checkpoint's job.roles names this unit's role, accounting.model must be one of that role's model identifiers, spelled exactly — a model that is not on the list, or none reported at all, is refused before anything is written; a role job.roles omits, and a checkpoint carrying no job.roles, are unconstrained.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string"
+      },
+      "unit_id": {
+        "title": "Unit Id",
+        "type": "string",
+        "description": "The unit being clocked out. Must equal plan.cursor — the single-pointer contract: clock_in briefs only the cursor unit and clock_out accepts only it."
+      },
+      "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.3/_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. Only `cursor` can be clocked: shiftwork_clock_in briefs it and shiftwork_clock_out refuses every other id, so a `ready` member beyond the cursor is what the graph permits, not a unit the clock accepts yet. 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.1 → bantamkit-0.35.3}/pyproject.toml

@@ -69,7 +69,12 @@ dependencies = ["httpx>=0.27", "jsonschema>=4.21", "pyyaml>=6.0"]
 # 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"]
+# 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.1 → bantamkit-0.35.3}/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.1"
+__version__ = "0.35.3"

{bantamkit-0.35.1 → bantamkit-0.35.3}/src/bantamkit/mcpserver.py

@@ -30,6 +30,7 @@ from bantamkit import (
     shiftwork,
     skillaudit,
     tokenledger,
+    updatecheck,
     workplan,
 )
 from bantamkit.assets import AssetNotFound, assets_root, load_skill, load_tool_asset
@@ -965,6 +966,18 @@ def status_report(
         + ("unreadable" if size is None else str(size))
         + f" of {budget} bytes",
         f"event log: {'on' if log.enabled else 'off'}",
+        # THE UPDATE LINE IS NOT A CONDITION, and that is the ruling of 2026-09-19 rather
+        # than an omission. A newer version existing is not a fault: the server is serving
+        # correctly, and `degraded_notice`'s docstring above is the operator's own reason —
+        # a footer on every result is noise, and noise trains a reader to skip it. So this
+        # never flips line 1, never enters `degraded_conditions`, and never rides another
+        # tool's reply. It also means the record is opened ONLY here, when someone asked for
+        # a report, and not on the per-call path whose cost `docs/status.md` documents.
+        #
+        # `updatecheck` opens one file and asks nobody anything — AS-7(3) is intact, and
+        # `test_selfupdate.py::test_only_the_update_flag_reaches_this_module_from_the_server`
+        # still holds, because the name this reaches is `updatecheck` and not `selfupdate`.
+        updatecheck.update_line(str(identity["version"])),
     ]
     if conditions:
         lines.append(f"{_plural(len(conditions), 'problem')}:")
@@ -1894,6 +1907,25 @@ def build_server(memory: Memory, log: EventLog | None = None) -> Any:
 
     @server.resource("bantamkit://skills/{name}")
     def skill_resource(name: str) -> str:
+        # A skill that pairs with a tool is served on that tool's surfaces and no other. The
+        # pairing is the one `filegraph.py` spells: `load_tool("file_graph")` beside
+        # `load_skill("file-graph")` — the skill's name with `-` for `_`. `file-graph` is the
+        # eval agent's system-prompt snippet telling it to call `file_graph`, a tool whose
+        # asset claims only `agent`; handing that text to an MCP client sends it to a tool
+        # `tools/list` does not carry and `tools/call` refuses as unknown (job60 row 46).
+        # Same sentence and same error code on both runtimes; `tools/conformance/suites/
+        # instructions.mjs` reads every skill on disk over `resources/read` and resolves the
+        # tools it names against `tools/list`.
+        paired = name.replace("-", "_")
+        try:
+            asset = load_tool_asset(paired)
+        except AssetNotFound:
+            asset = None
+        if asset is not None and "mcp" not in asset["surfaces"]:
+            raise ResourceError(
+                f"skill asset {name} is not served here: it pairs with tool {paired}, "
+                f"whose asset claims surfaces {asset['surfaces']}, not mcp"
+            )
         try:
             return load_skill(name)
         except AssetNotFound:

{bantamkit-0.35.1 → bantamkit-0.35.3}/src/bantamkit/memory/store.py

@@ -133,7 +133,7 @@ _FACTS_UNREADABLE = (
 _ARCHIVE_UNREADABLE = (
     "an archive that could not be listed is not an empty archive, and answering "
     "'nothing is archived' here is what makes compaction look like deletion — the "
-    "facts compact() moved are still on disk under this path"
+    "facts that compaction moved are still on disk under this path"
 )
 # The same distinction one syscall down, for `restore`, which stats one named path
 # instead of listing (see `archived()` for why). A refused stat is not an absent file,
@@ -1310,5 +1310,5 @@ class MemoryStore:
         if size > self.index_budget:
             raise MemoryBudgetExceeded(
                 f"memory index is {size} bytes, budget is {self.index_budget}: "
-                f"run compact() or tersen descriptions"
+                f"compact the store or tersen descriptions"
             )

{bantamkit-0.35.1 → bantamkit-0.35.3}/src/bantamkit/selfupdate.py

@@ -55,11 +55,14 @@ a store or a transport exists, the same shape `--assets-root` and `--install` us
 from __future__ import annotations
 
 import json
+import os
 import shlex
 import subprocess
 import sys
+import tempfile
 from collections.abc import Callable
 from dataclasses import dataclass
+from datetime import UTC, datetime
 
 from bantamkit import __version__
 
@@ -359,6 +362,83 @@ def compare_versions(installed: str, latest: str) -> int:
     return 1 if left > right else -1
 
 
+#: The `checked_at` stamp's shape, spelled rather than defaulted. `datetime.isoformat()`
+#: renders `+00:00` and `Date.prototype.toISOString` renders `.000Z`, so a record written by
+#: the two runtimes would differ in bytes neither reader cares about. Both sides render this
+#: one shape instead, and `runtime-ts` strips its milliseconds to reach it.
+STAMP = "%Y-%m-%dT%H:%M:%SZ"
+
+
+def record_update(latest: str, now: str | None = None) -> bool:
+    """Put the version this flag just fetched into the record `bantamkit_status` reads.
+
+    NO SECOND NETWORK CALL AND NO NEW FAILURE MODE, which is the whole reason the writer is
+    here rather than anywhere a reader could reach. `update` already holds `latest` — it was
+    parsed out of the answer the operator's own `--update` asked for — so this writes what is
+    in hand. `updatecheck` reads that file and NEVER writes it; the split is structural and
+    both halves are gated (`test_updatecheck.py::test_the_source_writes_nothing_and_reaches_
+    no_network`), so a future reader cannot grow a write by accident.
+
+    `updatecheck` IS IMPORTED INSIDE THE BODY, and not for style. `updatecheck` imports
+    `PROGRAM` and `compare_versions` from THIS module at its top level, so a module-level
+    import here would be a cycle that fails at interpreter start. The function-local import
+    is the direction that works, and `_names_reached_by` in `test_selfupdate.py` sees it —
+    `bantamkit.updatecheck` is on that gate's allowlist by name.
+
+    IT CREATES NO DIRECTORY. `<homedir>/.bantamkit` is made by an install, and a `--update`
+    run on a machine that has never had one writes nothing rather than deciding where this
+    toolbox's home directory should be. A cwd-relative `.bantamkit` is a MEMORY STORE (J54-3)
+    and the path here comes from `updatecheck.record_path()`, which hangs off `_home()`.
+
+    THE OTHER RUNTIME'S KEY IS LEFT EXACTLY AS FOUND. npm and PyPI are two registries that
+    can disagree at one version number — job56 shipped a day where they did — so this fills
+    `updatecheck.KEY` and copies the rest of the record through untouched. An UNREADABLE
+    record is replaced rather than merged: there is nothing in it to preserve.
+
+    TEMP FILE AND RENAME, so a reader never sees half a record: `os.replace` is atomic on
+    POSIX and on Windows, and the temp file is made in the SAME directory so the rename is
+    never across a filesystem.
+
+    RETURNS whether it wrote, and RAISES FOR NOTHING. A failed write must not turn a
+    successful `--update` into a failure: the operator's install was updated either way, and
+    the worst case is a status line that still says `never checked`.
+    """
+    # The MODULE is named in the import so the gate's allowlist can name it too: a
+    # `from bantamkit import updatecheck` records only `bantamkit`, which would let any
+    # sibling module in under the same allowance.
+    from bantamkit.updatecheck import KEY, SOURCE_RECORD, load_record, record_path
+
+    path = record_path()
+    directory = path.parent
+    if not directory.is_dir():
+        return False
+    source, existing = load_record(path)
+    payload: dict[str, object] = dict(existing) if source == SOURCE_RECORD and existing else {}
+    payload["checked_at"] = now or datetime.now(UTC).strftime(STAMP)
+    payload[KEY] = {"distribution": DISTRIBUTION, "latest": latest}
+    try:
+        body = json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
+    except (TypeError, ValueError):
+        return False
+    try:
+        handle, temporary = tempfile.mkstemp(
+            dir=str(directory), prefix=".update-check-", suffix=".json"
+        )
+    except OSError:
+        return False
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8", newline="\n") as stream:
+            stream.write(body)
+        os.replace(temporary, path)
+    except OSError:
+        try:
+            os.unlink(temporary)
+        except OSError:
+            pass
+        return False
+    return True
+
+
 def update(
     installed: str,
     origin: Origin,
@@ -389,6 +469,15 @@ def update(
         raise UpdateRefused(UNREACHABLE.format(reason=exc)) from None
 
     latest = latest_from_index_payload(body)
+
+    # THE RECORD IS WRITTEN HERE AND NOT IN ONE OF THE ARMS BELOW, because what it records is
+    # "the index said X on this date" — which is true the moment the fetch returned, whatever
+    # this flag then decides to do about it. An operator whose shape has no route gets the
+    # refusal AND a `bantamkit_status` that now knows the number; one who is already current
+    # gets a line that says so with a date. The return value is deliberately dropped: a record
+    # that could not be written is not a reason to fail an update that worked.
+    record_update(latest)
+
     header = COMPARISON.format(program=PROGRAM, installed=installed, latest=latest)
     order = compare_versions(installed, latest)
     if order == 0: