bantamkit 0.27.0__py3-none-any.whl

bantamkit/assets/schemas/shiftwork-checkpoint.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bantamkit.dev/schemas/shiftwork-checkpoint.json",
+  "title": "Shift-work checkpoint contract v1",
+  "$comment": "Encodes checkpoint contract v1 (docs/superpowers/specs/2026-08-10-shift-work-checkpoint-contract-draft.md) plus the two driver-forced deltas: plan.units[].role (model dispatch without reading briefs) and state.external[].until_cmd (machine-checkable wait, replacing prose `until`). Re-planning needs no schema change: a planner unit is just a unit. STRICTNESS POSTURE: `version` is const-pinned to 1 so a reader can refuse unknown majors; every object the driver or a session reads by field name sets additionalProperties:false, and every field the draft's schema block shows on every instance is required (empty arrays are legal, so a fresh checkpoint is cheap to write). The two exceptions are `history[]` and `retro[]` items: those are the free-text annotation space the draft treats as notes, so they allow extra keys (e.g. a session adding `seq` or `tokens`) while still requiring their load-bearing fields. `units[].commits` is optional because the draft only carries it on completed units. `state.external[].status` is a non-empty string rather than an enum: the draft closes the enum for unit status (the driver's SUCCESS test) but never enumerates external status, and inventing values here would reject honest checkpoints. `plan.cursor` must name an existing unit id — JSON Schema cannot express that cross-reference, so the driver checks it structurally and escalates on a dangling cursor. Serialization: checkpoints are YAML for humans per the draft, but the v1 driver reads JSON only (stdlib-only rule), so sessions driven by driver.py write .json; this schema validates the parsed document either way.",
+  "type": "object",
+  "required": ["version", "job", "plan", "state", "history", "retro", "handoff"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "const": 1,
+      "description": "Contract major version. A reader that does not know this value must refuse the file."
+    },
+    "job": {
+      "type": "object",
+      "required": ["id", "goal", "done_definition", "constraints"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {"type": "string", "minLength": 1, "description": "Stable job slug."},
+        "goal": {"type": "string", "minLength": 1, "description": "One sentence, never edited mid-job."},
+        "done_definition": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Ground truth that ends the job — a check, not a vibe."
+        },
+        "constraints": {
+          "type": "array",
+          "items": {"type": "string", "minLength": 1},
+          "description": "Invariants binding every unit, copied verbatim into each session."
+        }
+      }
+    },
+    "plan": {
+      "type": "object",
+      "required": ["cursor", "units"],
+      "additionalProperties": false,
+      "properties": {
+        "cursor": {
+          "type": "string",
+          "minLength": 1,
+          "description": "THE next unit id. Single pointer — the executor never chooses."
+        },
+        "units": {
+          "type": "array",
+          "description": "Flat list, soft cap ~30 units; bigger jobs re-cut via a planner unit.",
+          "items": {
+            "type": "object",
+            "required": ["id", "title", "brief_path", "status", "role", "depends_on", "verify"],
+            "additionalProperties": false,
+            "properties": {
+              "id": {"type": "string", "minLength": 1},
+              "title": {"type": "string", "minLength": 1},
+              "brief_path": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Full brief lives in a file, not in the checkpoint."
+              },
+              "status": {
+                "type": "string",
+                "enum": ["todo", "in_progress", "done", "blocked", "dropped"]
+              },
+              "role": {
+                "type": "string",
+                "enum": ["planner", "implementer", "reviewer"],
+                "description": "Driver dispatch key: role -> model/allowed tools, set in driver config."
+              },
+              "depends_on": {"type": "array", "items": {"type": "string", "minLength": 1}},
+              "verify": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Command proving done-ness. Done-ness is a command, not a claim."
+              },
+              "commits": {
+                "type": "array",
+                "items": {"type": "string", "minLength": 1},
+                "description": "Present once a unit has landed work."
+              }
+            }
+          }
+        }
+      }
+    },
+    "state": {
+      "type": "object",
+      "required": ["repo", "artifacts", "external"],
+      "additionalProperties": false,
+      "properties": {
+        "repo": {
+          "type": "object",
+          "required": ["branch", "head_sha", "dirty"],
+          "additionalProperties": false,
+          "description": "Staleness guard: must match the working tree at clock-in.",
+          "properties": {
+            "branch": {"type": "string", "minLength": 1},
+            "head_sha": {"type": "string", "minLength": 1},
+            "dirty": {"type": "boolean"}
+          }
+        },
+        "artifacts": {
+          "type": "array",
+          "description": "Files the next session MUST read, with roles.",
+          "items": {
+            "type": "object",
+            "required": ["path", "role"],
+            "additionalProperties": false,
+            "properties": {
+              "path": {"type": "string", "minLength": 1},
+              "role": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Free-form reading role (spec, ledger, ...) — not the unit role enum."
+              }
+            }
+          }
+        },
+        "external": {
+          "type": "array",
+          "description": "World-state git cannot see: detached processes, PRs, CI.",
+          "items": {
+            "type": "object",
+            "required": ["kind", "ref", "status"],
+            "additionalProperties": false,
+            "properties": {
+              "kind": {"type": "string", "enum": ["process", "pr", "ci"]},
+              "ref": {"type": "string", "minLength": 1},
+              "until_cmd": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Wait condition as a shell command; exit 0 = met. The driver waits on this."
+              },
+              "status": {"type": "string", "minLength": 1}
+            }
+          }
+        }
+      }
+    },
+    "history": {
+      "type": "array",
+      "description": "Ring buffer, last 5 units only — the full record is git plus the ledger.",
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "required": ["unit", "outcome"],
+        "additionalProperties": true,
+        "properties": {
+          "unit": {"type": "string", "minLength": 1},
+          "outcome": {"type": "string", "minLength": 1},
+          "notes": {"type": "string"}
+        }
+      }
+    },
+    "retro": {
+      "type": "array",
+      "description": "What this job taught the loop; patches already applied.",
+      "items": {
+        "type": "object",
+        "required": ["trigger", "patch_applied_to"],
+        "additionalProperties": true,
+        "properties": {
+          "trigger": {"type": "string", "minLength": 1},
+          "patch_applied_to": {"type": "string", "minLength": 1}
+        }
+      }
+    },
+    "handoff": {
+      "type": "object",
+      "required": ["next_action", "open_questions", "do_not"],
+      "additionalProperties": false,
+      "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."
+        }
+      }
+    }
+  }
+}

bantamkit/assets/skills/file-graph.md

@@ -0,0 +1,7 @@
+# File-access graph
+
+A ledger of every file you read is kept for you automatically. Before
+reading any file, call the `file_graph` tool to see what you already read
+and whether it changed. Never re-read a file the ledger lists as
+unchanged — use what you already saw. Re-reads of unchanged files return a
+short `[file-graph]` marker instead of the content.

bantamkit/assets/skills/memory.md

@@ -0,0 +1,35 @@
+# Memory
+
+The runtime enforces format, dedupe, and budgets. You only decide WHEN and WHAT.
+
+## Recall first
+
+Before a task that resembles past work, call memory_recall with the words a
+past-you would have used. Do this before acting, not after.
+
+## When to save
+
+- 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"
+
+## When NOT to save
+
+- Anything derivable from the repo, git history, or docs
+- One-off state that only matters in this conversation
+
+## Writing the description
+
+Write it to match the future recall QUERY, not to summarize the body.
+Ask: "what words will future-me search with?" Put related memory names in links.
+
+## On "duplicate" replies
+
+If memory_save answers that a similar memory exists, either update it by
+saving under that SAME name, or skip — never rename to force a second copy.
+
+## Layers
+
+Recall lines may start with `[project]`, `[extra:<name>]`, or `[profile]` —
+where the fact came from. Prefer `[project]` when they conflict; saves always
+go to the project store.

bantamkit/assets/tools/bantamkit_read.json

@@ -0,0 +1,48 @@
+{
+  "name": "bantamkit_read",
+  "description": "Read a document through a program, never its raw bytes. Call with `path` alone for the manifest: the file's kind, every part (sheet, document, page) with its row count and byte size, and every omission the reader had to make (embedded images, blank rows, unmapped glyphs, unread pages). Then call with `part` (and `offset`) to page rows; row 0 is the header and each page ends with a continuation line naming the next offset or the end of the part. Do not page through a part to find a row: estimate its offset from the row count and jump. Supported kinds: text/markdown/code, docx, xlsx, html, mhtml; pdf on the Python server only. The Node server refuses pdf, doc and rtf until its reader is ported. A refusal names what the reader actually saw in the file rather than the format's error.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "type": "object",
+    "required": [
+      "path"
+    ],
+    "properties": {
+      "path": {
+        "type": "string",
+        "description": "Path to the document, absolute or relative to the server's working directory"
+      },
+      "part": {
+        "type": "string",
+        "description": "Part name as the manifest reports it (a sheet name, \"document\", a page); omit to get the manifest"
+      },
+      "offset": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 9007199254740991,
+        "description": "Row number of the first row to return; default 0"
+      },
+      "limit": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 200,
+        "description": "How many rows; default 50, a 3072-byte page ceiling may return fewer"
+      }
+    }
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "bantamkit_readOutput"
+  }
+}

bantamkit/assets/tools/bantamkit_status.json

@@ -0,0 +1,25 @@
+{
+  "name": "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.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {},
+    "type": "object",
+    "title": "bantamkit_statusArguments"
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "bantamkit_statusOutput"
+  }
+}

bantamkit/assets/tools/build_identity.json

@@ -0,0 +1,17 @@
+{
+  "name": "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.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {},
+    "type": "object",
+    "title": "build_identity_toolArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "build_identity_toolDictOutput"
+  }
+}

bantamkit/assets/tools/document_list.json

@@ -0,0 +1,12 @@
+{
+  "name": "document_list",
+  "description": "Describe every document attached to this task: file name, its parts (a worksheet, or the body of a Word file), how many rows each part has, and that part's header row, first row and last row. Call this FIRST — it is the only place the part names and row numbers document_read accepts are stated.",
+  "surfaces": [
+    "agent"
+  ],
+  "parameters": {
+    "type": "object",
+    "properties": {}
+  },
+  "output_schema": null
+}

bantamkit/assets/tools/document_read.json

@@ -0,0 +1,31 @@
+{
+  "name": "document_read",
+  "description": "Read one page of rows from one part of one document. Rows keep their file order and are numbered from 0; row 0 is the header. The document does not fit in one page, so pick the page with offset. Do not page through it to find a row: use the row count and the first and last row that document_list reported to estimate the row's number, jump straight to that offset, and correct from what comes back.",
+  "surfaces": [
+    "agent"
+  ],
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "document": {
+        "type": "string",
+        "description": "File name as document_list reported it; omit if the task has one"
+      },
+      "part": {
+        "type": "string",
+        "description": "Part name as document_list reported it; omit for the first"
+      },
+      "offset": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "Row number of the first row to return"
+      },
+      "limit": {
+        "type": "integer",
+        "minimum": 1,
+        "description": "How many rows; default 50, a byte ceiling may return fewer"
+      }
+    }
+  },
+  "output_schema": null
+}

bantamkit/assets/tools/file_graph.json

@@ -0,0 +1,12 @@
+{
+  "name": "file_graph",
+  "description": "List every file you have already read this session: path, read count, the tool that read it, and whether it changed since. Consult this before re-reading any file.",
+  "surfaces": [
+    "agent"
+  ],
+  "parameters": {
+    "type": "object",
+    "properties": {}
+  },
+  "output_schema": null
+}

bantamkit/assets/tools/memory_compact.json

@@ -0,0 +1,31 @@
+{
+  "name": "memory_compact",
+  "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.",
+  "surfaces": [
+    "agent",
+    "mcp"
+  ],
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "reserve": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "Bytes of index headroom to free below the budget. Omit for the default: the size of the largest index line the store holds, capped at half the budget."
+      }
+    }
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "memory_compactOutput"
+  }
+}

bantamkit/assets/tools/memory_recall.json

@@ -0,0 +1,38 @@
+{
+  "name": "memory_recall",
+  "description": "Search persistent memory. Call BEFORE starting a task that resembles past work. Returns at most k matching facts.",
+  "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",
+        "minimum": 1,
+        "maximum": 5
+      }
+    }
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "memory_recallOutput"
+  }
+}

bantamkit/assets/tools/memory_save.json

@@ -0,0 +1,61 @@
+{
+  "name": "memory_save",
+  "description": "Save ONE durable fact to persistent memory. Use only for facts needed in a future session; never for things derivable from the repo or one-off state.",
+  "surfaces": [
+    "agent",
+    "mcp"
+  ],
+  "parameters": {
+    "type": "object",
+    "required": [
+      "type",
+      "name",
+      "description",
+      "body"
+    ],
+    "properties": {
+      "type": {
+        "type": "string",
+        "enum": [
+          "user",
+          "feedback",
+          "project",
+          "reference"
+        ]
+      },
+      "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"
+      }
+    }
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "memory_saveOutput"
+  }
+}

bantamkit/assets/tools/shiftwork_clock_in.json

@@ -0,0 +1,25 @@
+{
+  "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. 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.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string"
+      }
+    },
+    "required": [
+      "checkpoint"
+    ],
+    "type": "object",
+    "title": "shiftwork_clock_inArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "shiftwork_clock_inDictOutput"
+  }
+}

bantamkit/assets/tools/shiftwork_clock_out.json

@@ -0,0 +1,60 @@
+{
+  "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). Every success appends one accounting line (unit, role, status, ts, plus your accounting fields, e.g. tokens/duration/model) to <checkpoint>.log.jsonl.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string"
+      },
+      "unit_id": {
+        "title": "Unit Id",
+        "type": "string"
+      },
+      "status": {
+        "title": "Status",
+        "type": "string"
+      },
+      "handoff_patch": {
+        "additionalProperties": true,
+        "title": "Handoff Patch",
+        "type": "object"
+      },
+      "history_entry": {
+        "additionalProperties": true,
+        "title": "History Entry",
+        "type": "object"
+      },
+      "accounting": {
+        "anyOf": [
+          {
+            "additionalProperties": true,
+            "type": "object"
+          },
+          {
+            "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/assets/tools/shiftwork_status.json

@@ -0,0 +1,25 @@
+{
+  "name": "shiftwork_status",
+  "description": "Shift-work status: read-only progress summary of a checkpoint — units by status, cursor, open-question count, last history entry. Never mutates.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "checkpoint": {
+        "title": "Checkpoint",
+        "type": "string"
+      }
+    },
+    "required": [
+      "checkpoint"
+    ],
+    "type": "object",
+    "title": "shiftwork_statusArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "shiftwork_statusDictOutput"
+  }
+}