Module authoring

Expand description

Helpers for writing plugins from inside byob (the model’s make_tool, edit_plugin, …):

derive_schema: the JSON Schema of a Python def run(arg: type = default, …), read from its type hints by a small Python shim that only parses the code (ast), never runs it;
tool_script: the code plus a runner footer that calls run() with the JSON arguments from stdin and prints what it returns;
upsert_tool / new_manifest: add or replace a tool in a plugin’s byob-plugin.json, checked with the same parser (and error messages) the loader uses;
fingerprint: a cheap “did anything change” hash of a plugin folder (sizes and times).

Structs§

Derived: What derive_schema found.
Fnv: FNV-1a, 64 bit: stable across runs (unlike std’s DefaultHasher).
ToolDecl: A tool to put in a manifest.
WantedSetting: A setting a tool asks for (make_tool’s settings): an environment variable name, and whether its value is secret (an API key) — then it lives in secrets.json.

MAX_CODE_BYTES: Longest tool code accepted.
RUNNER_MARK: Marks where the runner footer starts in a tool script; everything from it on is byob’s.

derive_schema: The JSON Schema of def run(…) in code, from its type hints, defaults and docstring (Args: lines become descriptions). The code is parsed, never executed. Runs python in sandbox (no network) when given.
fingerprint: A hash of the names, sizes and modification times of the files in dir (three levels down; dot folders and __pycache__ skipped). Changes when a manifest, SKILL.md, agent file or script is edited, added or removed. Missing → a fixed value.
fingerprint_into: Add dir’s files to h (see fingerprint).
last_lines: The last n lines of text (a traceback’s useful end).
new_manifest: A fresh manifest for plugin id.
read_manifest_json: The manifest JSON in dir (a fresh one for id if there is none yet).
remove_tool: Remove tool name from the manifest in dir (its script stays). Whether it was there.
script_code: The code part of a tool script (without byob’s runner footer).
tool_script: code (with any earlier runner footer removed) followed by the runner footer.
upsert_tool: Add tool to the manifest of plugin id in dir (replacing a tool with the same name), with its settings and network permission, and write it. Returns whether it replaced one.
write_manifest: Check manifest with the loader’s own rules and write it to dir (pretty-printed). Nothing is written if it doesn’t pass; the error is the loader’s message.