bantamkit 0.36.0__tar.gz → 0.36.2__tar.gz

{bantamkit-0.36.0 → bantamkit-0.36.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bantamkit
-Version: 0.36.0
+Version: 0.36.2
 Summary: Persistent memory for coding agents: an MCP server for Claude Code, Claude Desktop, Cursor and VS Code Copilot, 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
@@ -74,8 +74,9 @@ Then restart the host (in Claude Code, open a new session) and ask the agent to
 - **Offline after one install.** `--install` records the venv's console script by absolute path,
   so no launch needs the network or your shell's PATH.
 - **Claude Code hooks, if you want them.** `--install-hooks` puts the memory index in front of
-  each new session, surfaces matching facts on each prompt, and nudges a save at the end of a
-  long session that saved nothing
+  each new session, surfaces matching facts on each prompt, mirrors each fact Claude Code writes
+  into its own auto-memory into the project store (one way, new writes only), and nudges a save at
+  the end of a long session that saved nothing
   ([docs/hooks.md](https://github.com/Ink01101011/bantamkit/blob/main/docs/hooks.md)).
 - **More than memory.** JSON Schema validation, a token ledger read off the host's transcripts,
   a skill-catalogue audit, and shift-work tools that plan and hand off multi-step jobs —
@@ -105,7 +106,7 @@ Then restart the host (in Claude Code, open a new session) and ask the agent to
 | [What it serves](#-what-it-serves) | 14 tools, one prompt, two resource templates |
 | [Requirements](#-requirements) | Python and dependencies |
 | [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 |
+| [The operator CLI: `python -m bantamkit.memory`](#-the-operator-cli-python--m-bantamkitmemory) | status, lint, compact, archived, archive, restore, list, candidates, merge |
 | [Where the Python and Node servers differ](#-where-the-python-and-node-servers-differ) | One store; pdf/.doc/.rtf, CLI name, `build_id`, YAML only PyYAML reads |
 | [Module API](#-module-api) | `import bantamkit`: the library half, measured from the wheel |
 | [Development](#-development) | Clone, test, lint, conformance |
@@ -144,9 +145,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.36.0" -d wheels
+python -m pip download "bantamkit[mcp]==0.36.2" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.36.0"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.36.2"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -373,9 +374,13 @@ python -m bantamkit.memory compact    # archive the stalest facts
 python -m bantamkit.memory archived   # list what compaction has moved out
 python -m bantamkit.memory archive <name>
 python -m bantamkit.memory restore <name>
+python -m bantamkit.memory list [--type T] [--outcome error|success] [--status active|done]
+python -m bantamkit.memory candidates [--older-than DAYS] [--apply]
+python -m bantamkit.memory merge --names A B --name NEW --type T --description D --body TEXT [--apply]
 ```
 
-`archive` moves a fact out without deleting it; `restore` brings it back by name.
+`archive` moves a fact out without deleting it; `restore` brings it back by name. `candidates`
+and `merge` are dry runs unless `--apply` is given.
 Full reference: [docs/memory.md → The operator CLI](https://github.com/Ink01101011/bantamkit/blob/main/docs/memory.md#the-operator-cli).
 
 ## 🔀 Where the Python and Node servers differ

{bantamkit-0.36.0 → bantamkit-0.36.2}/README.md

@@ -43,8 +43,9 @@ Then restart the host (in Claude Code, open a new session) and ask the agent to
 - **Offline after one install.** `--install` records the venv's console script by absolute path,
   so no launch needs the network or your shell's PATH.
 - **Claude Code hooks, if you want them.** `--install-hooks` puts the memory index in front of
-  each new session, surfaces matching facts on each prompt, and nudges a save at the end of a
-  long session that saved nothing
+  each new session, surfaces matching facts on each prompt, mirrors each fact Claude Code writes
+  into its own auto-memory into the project store (one way, new writes only), and nudges a save at
+  the end of a long session that saved nothing
   ([docs/hooks.md](https://github.com/Ink01101011/bantamkit/blob/main/docs/hooks.md)).
 - **More than memory.** JSON Schema validation, a token ledger read off the host's transcripts,
   a skill-catalogue audit, and shift-work tools that plan and hand off multi-step jobs —
@@ -74,7 +75,7 @@ Then restart the host (in Claude Code, open a new session) and ask the agent to
 | [What it serves](#-what-it-serves) | 14 tools, one prompt, two resource templates |
 | [Requirements](#-requirements) | Python and dependencies |
 | [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 |
+| [The operator CLI: `python -m bantamkit.memory`](#-the-operator-cli-python--m-bantamkitmemory) | status, lint, compact, archived, archive, restore, list, candidates, merge |
 | [Where the Python and Node servers differ](#-where-the-python-and-node-servers-differ) | One store; pdf/.doc/.rtf, CLI name, `build_id`, YAML only PyYAML reads |
 | [Module API](#-module-api) | `import bantamkit`: the library half, measured from the wheel |
 | [Development](#-development) | Clone, test, lint, conformance |
@@ -113,9 +114,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.36.0" -d wheels
+python -m pip download "bantamkit[mcp]==0.36.2" -d wheels
 python -m venv <env>
-<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.36.0"
+<env>/bin/pip install --no-index --find-links wheels "bantamkit[mcp]==0.36.2"
 <env>/bin/bantamkit-mcp --install cursor
 ```
 
@@ -342,9 +343,13 @@ python -m bantamkit.memory compact    # archive the stalest facts
 python -m bantamkit.memory archived   # list what compaction has moved out
 python -m bantamkit.memory archive <name>
 python -m bantamkit.memory restore <name>
+python -m bantamkit.memory list [--type T] [--outcome error|success] [--status active|done]
+python -m bantamkit.memory candidates [--older-than DAYS] [--apply]
+python -m bantamkit.memory merge --names A B --name NEW --type T --description D --body TEXT [--apply]
 ```
 
-`archive` moves a fact out without deleting it; `restore` brings it back by name.
+`archive` moves a fact out without deleting it; `restore` brings it back by name. `candidates`
+and `merge` are dry runs unless `--apply` is given.
 Full reference: [docs/memory.md → The operator CLI](https://github.com/Ink01101011/bantamkit/blob/main/docs/memory.md#the-operator-cli).
 
 ## 🔀 Where the Python and Node servers differ

{bantamkit-0.36.0 → bantamkit-0.36.2}/_assets/skills/memory.md

@@ -12,6 +12,7 @@ past-you would have used. Do this before acting, not after.
 - The user corrects you or states a preference → type "feedback"
 - A durable fact about the user → "user", about ongoing work → "project",
   a URL/dashboard/ticket → "reference"
+- Tag a lesson with outcome: error|success; close a project fact by saving it again with status: done.
 
 ## When NOT to save
 

{bantamkit-0.36.0 → bantamkit-0.36.2}/_assets/tools/bantamkit_status.json

@@ -1,7 +1,7 @@
 {
   "name": "bantamkit_status",
   "title": "bantamkit status",
-  "description": "Is bantamkit working, and which bantamkit? Returns a short report a person can read in the transcript: `bantamkit Active 🟢` or `bantamkit Degraded 🟠` on the first line, then the version and `build_id` of the code answering, the surfaces it serves, the memory store it is bound to with its index size against its budget, whether the event log is on, and — when degraded — every condition in full with what to do about it. Call it when the user asks whether the server is alive or working, when a bantamkit tool answered oddly and you need to know whether the server is the reason, or when a reply arrived carrying a `bantamkit degraded` footer and you want the rest of it. Every fact is observed at call time from the server's own state; nothing is a heartbeat or a cached verdict. Takes no arguments, writes nothing, and never echoes another call's arguments.",
+  "description": "Is bantamkit working, and which bantamkit? Returns a short report a person can read in the transcript: `bantamkit Active 🟢` or `bantamkit Degraded 🟠` on the first line, then the version and `build_id` of the code answering, the surfaces it serves, the memory store it is bound to with its index size against its budget, whether the event log is on, and — when degraded — every condition in full with what to do about it. Call it when the user asks whether the server is alive or working, when a bantamkit tool answered oddly and you need to know whether the server is the reason, or when a reply arrived carrying a `bantamkit degraded` footer and you want the rest of it. Every fact is observed at call time from the server's own state; nothing is a heartbeat or a cached verdict. Takes no arguments, writes nothing, and never echoes another call's arguments. build_identity answers only the `build_id` fingerprint, as JSON, when all you need is to compare two installs; shiftwork_status reports a job, not the server.",
   "surfaces": [
     "mcp"
   ],

{bantamkit-0.36.0 → bantamkit-0.36.2}/_assets/tools/build_identity.json

@@ -1,7 +1,7 @@
 {
   "name": "build_identity",
   "title": "Build identity",
-  "description": "Which bantamkit build is answering you, readable mid-call. Returns `build_id` — a content fingerprint of the running source and the asset pack it loads — plus the paths it was computed over. Call it when one MCP server name may resolve to more than one install: two endpoints reporting the same `version` are the SAME build only if their `build_id` matches, because a version string moves on release bumps and not on builds. Any fact that cannot be derived comes back as {\"unavailable\": \"<reason>\"} and is named in the `unavailable` list — never omitted, never a placeholder that reads as a value. Takes no arguments and reads no state.",
+  "description": "Which bantamkit build is answering you, readable mid-call. Returns `build_id` — a content fingerprint of the running source and the asset pack it loads — plus the paths it was computed over. Call it when one MCP server name may resolve to more than one install: two endpoints reporting the same `version` are the SAME build only if their `build_id` matches, because a version string moves on release bumps and not on builds. Any fact that cannot be derived comes back as {\"unavailable\": \"<reason>\"} and is named in the `unavailable` list — never omitted, never a placeholder that reads as a value. Takes no arguments and reads no state. Use bantamkit_status when the question is whether the server is healthy or which store it is bound to — that report includes this fingerprint; call this tool when you need only the fingerprint, as JSON, to compare two endpoints.",
   "surfaces": [
     "mcp"
   ],

{bantamkit-0.36.0 → bantamkit-0.36.2}/_assets/tools/memory_compact.json

@@ -1,7 +1,7 @@
 {
   "name": "memory_compact",
   "title": "Compact the memory store",
-  "description": "Free room in persistent memory when `memory_save` was refused for budget. Archives the stalest facts of the writable project store until a fact as large as the biggest one kept will fit, and returns what moved — every archived name with its type and description. Nothing is deleted: archived facts leave the index but stay on disk, and the operator can restore any of them by name. Read-only grants and the profile layer are never touched. Call it after a budget refusal, then retry the save; calling it under budget archives nothing and says so.",
+  "description": "Free room in persistent memory when `memory_save` was refused for budget. Archives the stalest facts of the writable project store until a fact as large as the biggest one kept will fit, and returns what moved — every archived name with its type and description. Nothing is deleted: archived facts leave the index but stay on disk under archive/, and bringing one back is an operator action rather than a tool — `bantamkit-memory restore <name>` (Node) or `python -m bantamkit.memory restore <name>` (Python) on the store; no tool deletes a fact. Read-only grants and the profile layer are never touched. Call it after a budget refusal, then retry the save; calling it under budget archives nothing and says so. It is not the pass for two copies of one name across layers — that is memory_dream.",
   "surfaces": [
     "agent",
     "mcp"

{bantamkit-0.36.0 → bantamkit-0.36.2}/_assets/tools/memory_dream.json

@@ -1,8 +1,10 @@
 {
   "name": "memory_dream",
   "title": "Dream: consolidate the memory store",
-  "description": "Consolidate the memories the project layer and the machine-wide profile layer hold under the SAME NAME, and say exactly what changed. Byte-identical copies collapse to one; a pair that has diverged is UNIONED — every claim from both copies survives, never a winner-takes-all — and a relative date in a body is annotated with the day it resolves to against that fact's own mtime, never against today. The survivor stays in the writable project layer and the profile copy MOVES to that store's archive/: nothing is deleted and any consumed memory can be restored by name. This is a correctness pass, not a token saving: the profile index is derived at read time and is not loaded from a prompt, so consolidating it frees approximately no bytes — what it buys is one copy of a ruling instead of two that can disagree. It defaults to a DRY RUN because the profile store is machine-wide: a memory archived out of it stops answering for every other project on this machine that has no store of its own. Read the plan first, then call it again with dry_run false to apply it.",
-  "surfaces": ["mcp"],
+  "description": "Consolidate the memories the project layer and the machine-wide profile layer hold under the SAME NAME, and say exactly what changed. Byte-identical copies collapse to one; a pair that has diverged is UNIONED — every claim from both copies survives, never a winner-takes-all — and a relative date in a body is annotated with the day it resolves to against that fact's own mtime, never against today. The survivor stays in the writable project layer and the profile copy MOVES to that store's archive/: nothing is deleted, and bringing a consumed copy back is an operator action, not a tool — `bantamkit-memory restore <name>` or `python -m bantamkit.memory restore <name>` on the profile store. This is a correctness pass, not a token saving: the profile index is derived at read time and is not loaded from a prompt, so consolidating it frees approximately no bytes — what it buys is one copy of a ruling instead of two that can disagree. It defaults to a DRY RUN because the profile store is machine-wide: a memory archived out of it stops answering for every other project on this machine that has no store of its own. Read the plan first, then call it again with dry_run false to apply it. For room in the index call memory_compact instead; for the facts themselves, memory_recall.",
+  "surfaces": [
+    "mcp"
+  ],
   "parameters": {
     "type": "object",
     "properties": {
@@ -14,8 +16,15 @@
     "additionalProperties": false
   },
   "output_schema": {
-    "properties": { "result": { "title": "Result", "type": "string" } },
-    "required": ["result"],
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
     "type": "object",
     "title": "memory_dreamOutput"
   },

bantamkit-0.36.2/_assets/tools/memory_recall.json

@@ -0,0 +1,51 @@
+{
+  "name": "memory_recall",
+  "title": "Recall memories",
+  "description": "Search persistent memory for facts a past session saved. Call it BEFORE starting a task that resembles past work, and when the user refers to something decided earlier; use memory_save to add a fact, and memory_compact or memory_dream only to tidy the store — this tool never changes what a fact says. Reads every layer in order — the project store, any read-only grants in .bantamkit/config.yaml, then the machine-wide profile — and returns the top word matches, never fewer than the store default of 3 when that many match; a query that is exactly a fact's name returns that fact alone. Why it is not read-only: every hit is appended to the usage ledger (~/.bantamkit/usage/<store-id>.jsonl) as a recall event — the staleness order memory_compact archives by — and a project fact file still in the 0.35.x format is rewritten once into the current one; both are best-effort and never fail a recall. A fact file that cannot be read is named in the reply, never silently skipped. Pass outcome: error to see only recorded failures.",
+  "surfaces": [
+    "agent",
+    "mcp"
+  ],
+  "parameters": {
+    "type": "object",
+    "required": [
+      "query"
+    ],
+    "properties": {
+      "query": {
+        "type": "string",
+        "description": "Words a past-you would have used to describe the fact"
+      },
+      "k": {
+        "type": "integer",
+        "description": "Facts wanted, clamped to 1..5. Raised to the store default of 3 when smaller; never lowered below it."
+      },
+      "outcome": {
+        "type": "string",
+        "enum": [
+          "error",
+          "success"
+        ],
+        "description": "Keep only facts saved with this outcome — `error` answers \"what failed before\", `success` \"what worked\". Facts with no outcome are dropped from the answer; omit it for the normal search."
+      }
+    },
+    "additionalProperties": false
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "memory_recallOutput"
+  },
+  "annotations": {
+    "readOnlyHint": false,
+    "openWorldHint": false
+  }
+}

bantamkit-0.36.2/_assets/tools/memory_save.json

@@ -0,0 +1,85 @@
+{
+  "name": "memory_save",
+  "title": "Save a memory",
+  "description": "Save ONE durable fact to persistent memory — a preference the user stated, a decision, the fix that worked — so a future session can recall it. Use it only for facts a future session needs; never for anything derivable from the repo, git history or docs, nor for one-off state of this conversation. To find a fact use memory_recall; to change one, save again under its EXACT name, which replaces it in place; to free room call memory_compact. Refused with nothing written, each with its own sentence: a description too close to an existing fact's (the reply names that fact — save under that SAME name or skip, never rename to force a copy), a spelling that normalises onto an existing name (`Deploy Command` onto `deploy-command`), and a save that would push the always-loaded index over its byte budget (the reply names the remedy). Every save lands in the writable project store (.bantamkit/memory), never in the profile or a read-only grant, and is appended to the usage ledger. Optional outcome (error|success) tags a lesson and status: done closes a project fact; nothing here archives — that is the operator's bantamkit-memory candidates/merge.",
+  "surfaces": [
+    "agent",
+    "mcp"
+  ],
+  "parameters": {
+    "type": "object",
+    "required": [
+      "type",
+      "name",
+      "description",
+      "body"
+    ],
+    "properties": {
+      "type": {
+        "type": "string",
+        "enum": [
+          "user",
+          "feedback",
+          "project",
+          "reference"
+        ],
+        "description": "What kind of fact: `user` (who the user is, their role and preferences), `feedback` (a correction or confirmed way of working, with the why), `project` (ongoing work, a decision, a constraint), `reference` (a URL, ticket or dashboard pointer)."
+      },
+      "name": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]*$",
+        "description": "short-kebab-case slug"
+      },
+      "description": {
+        "type": "string",
+        "description": "One line written to match the FUTURE recall query, not to summarize the body"
+      },
+      "body": {
+        "type": "string",
+        "description": "The fact itself, terse"
+      },
+      "links": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "names of related memories"
+      },
+      "outcome": {
+        "type": "string",
+        "enum": [
+          "error",
+          "success"
+        ],
+        "description": "What the lesson records: `error` (a failure to avoid) or `success` (a way that worked). Only on feedback and project facts; refused on user and reference. Read back by `bantamkit-memory list --outcome` and by memory_recall's `outcome` filter."
+      },
+      "status": {
+        "type": "string",
+        "enum": [
+          "active",
+          "done"
+        ],
+        "description": "Lifecycle of a project fact. Save an existing name with `done` when the work it describes has shipped; `bantamkit-memory candidates` lists done facts for the operator to archive. Absent means active; `active` is never written."
+      }
+    },
+    "additionalProperties": false
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "memory_saveOutput"
+  },
+  "annotations": {
+    "readOnlyHint": false,
+    "destructiveHint": true,
+    "openWorldHint": false
+  }
+}

bantamkit-0.36.2/_assets/tools/shiftwork_clock_in.json

@@ -0,0 +1,97 @@
+{
+  "name": "shiftwork_clock_in",
+  "title": "Shift work: clock in",
+  "description": "Shift-work clock-in: validate the checkpoint against the checkpoint schema and return the brief of ONE unit — {unit, role, invariants, handoff, do_not, files} — to hand to the agent you spawn, verbatim. Call it once per unit, right before spawning; use shiftwork_plan first to see the `ready` batch when several units are to run at once, and shiftwork_clock_out, not this tool, when a unit finishes. The unit briefed is plan.cursor, or `unit_id` when given; either way it must be in shiftwork_plan's `ready` — a done or dropped cursor, a cursor whose dependencies have not run, or a `unit_id` naming no unit answers {\"result\": \"error\", \"reason\": \"unit <id> is not ready; ready is <a, b>\"}, and the batch view's own refusals (cycle, unknown dependency, unreadable checkpoint) pass through verbatim. The other outcomes, never exceptions: `escalate` when handoff.open_questions is non-empty (stop and ask the user) or when the cursor names no unit, `success` when every unit is done or dropped, `error` when the checkpoint fails validation. It never moves plan.cursor; clock_out does. What it WRITES: on result=brief, and only then, one line {event: brief, ts, unit, role} appended to <checkpoint>.log.jsonl — best-effort, so a log it cannot write costs the brief nothing. That line is what later lets clock_out accept the unit while the cursor is elsewhere and sets `briefed` on its accounting line. The checkpoint file itself is never modified. See docs/shiftwork.md.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string",
+        "description": "Path to the shift-work checkpoint JSON file (by convention .shiftwork/checkpoint.json in the repo the job works on), absolute or relative to the server's working directory. The same file shiftwork_plan, shiftwork_clock_in and shiftwork_clock_out take; it must validate against assets/schemas/shiftwork-checkpoint.json."
+      },
+      "unit_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "title": "Unit Id",
+        "description": "The unit to brief instead of plan.cursor; it must be in shiftwork_plan's `ready` for this checkpoint. Omit it, or pass null, to brief the cursor unit."
+      }
+    },
+    "required": [
+      "checkpoint"
+    ],
+    "type": "object",
+    "title": "shiftwork_clock_inArguments",
+    "additionalProperties": false
+  },
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "result": {
+        "type": "string",
+        "description": "`brief` (the unit is yours to spawn), `escalate` (stop and ask: see `reason` and `open_questions`), `success` (every unit done or dropped), or `error` with `reason`."
+      },
+      "unit": {
+        "type": "object",
+        "description": "The plan.units entry briefed: id, role, status, depends_on and its own fields."
+      },
+      "role": {
+        "type": "string",
+        "description": "The unit's role, the key job.roles may bind models to."
+      },
+      "invariants": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "job.constraints: what every unit must keep true."
+      },
+      "handoff": {
+        "type": "object",
+        "description": "The checkpoint's handoff block: next_action, open_questions, do_not, notes."
+      },
+      "do_not": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "handoff.do_not: near-mistakes past sessions made."
+      },
+      "files": {
+        "type": "array",
+        "description": "state.artifacts: the files the job has produced so far."
+      },
+      "open_questions": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "With result `escalate`: the questions the orchestrator must put to the user before any unit runs."
+      },
+      "reason": {
+        "type": "string",
+        "description": "With result `escalate`, `success` or `error`: one sentence saying why."
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "additionalProperties": true,
+    "title": "shiftwork_clock_inDictOutput"
+  },
+  "annotations": {
+    "readOnlyHint": false,
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false
+  }
+}

{bantamkit-0.36.0 → bantamkit-0.36.2}/_assets/tools/shiftwork_clock_out.json

@@ -1,7 +1,7 @@
 {
   "name": "shiftwork_clock_out",
   "title": "Shift work: 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.",
+  "description": "Shift-work clock-out: record that a unit finished — set its status, advance plan.cursor, merge `handoff_patch` into handoff, push `history_entry` onto the 5-entry history ring, and append one accounting line to <checkpoint>.log.jsonl. Call it once per unit after its agent returns: shiftwork_clock_in briefs, this tool closes, and shiftwork_status reads what both wrote. The whole mutated document is validated against the checkpoint schema BEFORE one atomic write, so a failure writes nothing and answers {\"result\": \"error\", \"reason\": ...}; nothing is ever deleted from the checkpoint. `unit_id` must be plan.cursor — which needs no brief and clocks out with briefed=false — or a unit clock_in briefed since its own last clock-out; any other id is refused with `unit X is not the cursor unit Y`. `handoff_patch` and `history_entry` are both required arguments: pass `{}` to leave handoff unchanged, and give history_entry at least `unit` and `outcome`. plan.cursor then moves to the head of the ready batch recomputed on the new document — plan.units order over the remaining non-terminal units when the graph cannot batch, `unit_id` when none remain. The accounting line carries unit, role, status, ts and `briefed` (written by the runtime, never taken from you: true only when a brief was issued since this unit's LAST clock-out) plus your `accounting` fields when given. When job.roles names this unit's role, `accounting.model` must be on that role's list, spelled exactly, or nothing is written — see the `model` property.",
   "surfaces": [
     "mcp"
   ],
@@ -9,7 +9,8 @@
     "properties": {
       "checkpoint": {
         "title": "Checkpoint",
-        "type": "string"
+        "type": "string",
+        "description": "Path to the shift-work checkpoint JSON file (by convention .shiftwork/checkpoint.json in the repo the job works on), absolute or relative to the server's working directory. The same file shiftwork_plan, shiftwork_clock_in and shiftwork_clock_out take; it must validate against assets/schemas/shiftwork-checkpoint.json."
       },
       "unit_id": {
         "title": "Unit Id",
@@ -73,14 +74,17 @@
         "properties": {
           "unit": {
             "type": "string",
-            "minLength": 1
+            "minLength": 1,
+            "description": "The unit this entry is about — normally the `unit_id` being clocked out."
           },
           "outcome": {
             "type": "string",
-            "minLength": 1
+            "minLength": 1,
+            "description": "What happened, in a few words: done, blocked on X, dropped because Y."
           },
           "notes": {
-            "type": "string"
+            "type": "string",
+            "description": "Optional free text for the next session reading the ring."
           }
         }
       },
@@ -130,7 +134,8 @@
           }
         ],
         "default": null,
-        "title": "Accounting"
+        "title": "Accounting",
+        "description": "Per-unit cost line, or null (the default) to log a line with no cost figures at all. A non-null line must carry `tokens` and `duration_ms`; `model` is required when job.roles names this unit's role. The object shape is described below."
       }
     },
     "required": [
@@ -146,6 +151,35 @@
   },
   "output_schema": {
     "type": "object",
+    "properties": {
+      "result": {
+        "type": "string",
+        "description": "`ok` when the checkpoint was rewritten; `error` with `reason` when the call was refused and nothing was written."
+      },
+      "unit": {
+        "type": "string",
+        "description": "The unit clocked out."
+      },
+      "status": {
+        "type": "string",
+        "description": "The status it now holds."
+      },
+      "cursor": {
+        "type": "string",
+        "description": "plan.cursor after the move."
+      },
+      "log": {
+        "type": "string",
+        "description": "Path of the <checkpoint>.log.jsonl the accounting line was appended to."
+      },
+      "reason": {
+        "type": "string",
+        "description": "With result `error`: one sentence saying why the call was refused."
+      }
+    },
+    "required": [
+      "result"
+    ],
     "additionalProperties": true,
     "title": "shiftwork_clock_outDictOutput"
   },

bantamkit-0.36.2/_assets/tools/shiftwork_plan.json

@@ -0,0 +1,77 @@
+{
+  "name": "shiftwork_plan",
+  "title": "Shift work: plan",
+  "description": "Shift-work plan: which units of a checkpoint may run NOW, and in what waves — the batches its `depends_on` graph permits, computed read-only from the file. Call it before dispatching a wave: `ready` (the first batch) is what shiftwork_clock_in will brief, and `width` is how many agents the widest wave needs. A `ready` member beyond the cursor is clockable only once clock-in has briefed it; without that brief, clock-out refuses it. Use shiftwork_status instead when you only want progress counts, and work_plan when the graph is yours to hand over as `nodes` rather than a checkpoint on disk — this tool reads the checkpoint's own plan.units. Units already `done` or `dropped` count as satisfied and are left out of every batch; `todo`, `in_progress` and `blocked` stay in. Order inside a batch is plan.units order, because the checkpoint schema has no priority field. It never moves plan.cursor — the cursor is echoed unchanged so the pointer and the batch view can be read side by side — and never writes anything. Refusals are structured, never exceptions: work_plan's sentences for a duplicate id, an unknown dependency or a cycle, and shiftwork_status's for a checkpoint it cannot read; a plan whose units are all terminal answers an empty `ready`, which is an answer, not a refusal. It reports logical order only: `depends_on` says nothing about two units writing the same file, so the orchestrator still decides what actually runs together.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string",
+        "description": "Path to the shift-work checkpoint JSON file (by convention .shiftwork/checkpoint.json in the repo the job works on), absolute or relative to the server's working directory. The same file shiftwork_plan, shiftwork_clock_in and shiftwork_clock_out take; it must validate against assets/schemas/shiftwork-checkpoint.json."
+      }
+    },
+    "required": [
+      "checkpoint"
+    ],
+    "type": "object",
+    "title": "shiftwork_planArguments",
+    "additionalProperties": false
+  },
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "result": {
+        "type": "string",
+        "description": "`plan` on success; `error` with `reason` when the checkpoint cannot be read or its graph cannot batch."
+      },
+      "batches": {
+        "type": "array",
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "description": "Unit ids by wave: batch k holds every non-terminal unit whose dependencies all sit in batches below k."
+      },
+      "ready": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "batches[0] — the units clock_in may brief now; [] when every unit is done or dropped."
+      },
+      "sequence": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "The batches flattened in order."
+      },
+      "width": {
+        "type": "integer",
+        "description": "The largest batch length: the widest fan-out."
+      },
+      "cursor": {
+        "type": "string",
+        "description": "plan.cursor, echoed unchanged."
+      },
+      "reason": {
+        "type": "string",
+        "description": "With result `error`: one sentence saying why the call was refused."
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "additionalProperties": true,
+    "title": "shiftwork_planDictOutput"
+  },
+  "annotations": {
+    "readOnlyHint": true,
+    "openWorldHint": false
+  }
+}