@soft-boy/agentschema 0.2.0 → 0.2.1

package/README.md

@@ -4,22 +4,20 @@ Define an AI-Agent as a folder of Markdown files.
 
 ```
 my-agent/
-├── agent.md        # the agent
-├── env.md          # the environment it runs in
-└── tools/          # one file per tool, in any folders you like
-    ├── built-in/
-    │   ├── bash.md
-    │   └── read.md
-    └── read_file.md
+├── agent.md                      # the agent
+├── env.md                        # the environment it runs in
+└── tools/                        # tool files, in any folders you like
+    ├── agent_toolset_20260401.md # the pre-built tools to enable
+    └── get_weather.md
 ```
 
-**Status:** v0.2 draft. v0.2 breaks from the Claude Managed Agents schema: tools move out of `agent.md` and into `tools/`.
+**Status:** v0.2.1 draft. v0.2 breaks from the Claude Managed Agents schema: tools move out of `agent.md` and into `tools/`.
 
 ## Philosophy
 
 1. **One folder, one agent.** A folder defines one agent and the one environment it runs in. Sessions, credentials, mounted files and repositories, and schedules are supplied by whatever runs the agent.
 2. **Everything is a Markdown file.** An agent is plain files you can read, diff, review and version like any other code. Structured settings go in YAML frontmatter, and prose the model reads goes in the Markdown body.
-3. **Inspired by Claude Managed Agents, not tied to it.** `agent.md` and `env.md` use the Claude Managed Agents fields because they're a well-documented vocabulary for agents. Tools are the exception: each one is its own file, and agentschema compiles them into the API's format. The format itself assumes no particular infrastructure, so any runtime that can read the files can run the agent.
+3. **Inspired by Claude Managed Agents, not tied to it.** `agent.md` and `env.md` use the Claude Managed Agents fields because they're a well-documented vocabulary for agents. Tools are the exception: they're split into their own files, and agentschema compiles them into the API's format. The format itself assumes no particular infrastructure, so any runtime that can read the files can run the agent.
 
 ## Install
 
@@ -31,17 +29,15 @@ npm install -g @soft-boy/agentschema
 
 ### Files
 
-An instance is a folder of Markdown files. `agent.md` and `env.md` are required; `tools/` is optional.
+An instance is a folder of Markdown files. `agent.md` and `env.md` are required.
 
 ```
 my-agent/
-├── agent.md        # the agent
-├── env.md          # the environment it runs in
-└── tools/          # one file per tool, in any folders you like
-    ├── built-in/
-    │   ├── bash.md
-    │   └── read.md
-    └── read_file.md
+├── agent.md                      # the agent
+├── env.md                        # the environment (computer)
+└── tools/                        # tool files, nested however you like
+    ├── agent_toolset_20260401.md # the pre-built tools to enable
+    └── get_weather.md
 ```
 
 ### `agent.md`
@@ -59,56 +55,60 @@ Field reference: [Environments](https://platform.claude.com/docs/en/managed-agen
 
 ### `tools/`
 
-Each `.md` file in `tools/` is one tool, and the file name is the tool's name. agentschema supports two kinds: pre-built and custom.
+Each `.md` file in `tools/` is either the pre-built toolset or one custom tool.
 
-Subfolders are only for organizing. Every `.md` file under `tools/`, at any depth, is a tool, and its folder is ignored when compiling: moving a file between folders changes nothing that's deployed. Because the folders are dropped, two tools can't share a name even in different folders. Folders and files whose names start with `.` are skipped. By convention, the pre-built tools go in `tools/built-in/`.
+Subfolders are only for organizing. Every `.md` file under `tools/`, at any depth, is read, and its folder is ignored when compiling: moving a file between folders changes nothing that's deployed. Because the folders are dropped, two custom tools can't share a name even in different folders. Folders and files whose names start with `.` are skipped.
 
-**Pre-built tools** are the tools Claude Managed Agents runs in the container: `bash`, `edit`, `glob`, `grep`, `read`, `web_fetch`, `web_search` and `write`. Name the file after the tool (for example `tools/built-in/bash.md`), and give it only a `type`:
+**Pre-built tools** are the tools Claude Managed Agents runs in the container: `bash`, `edit`, `glob`, `grep`, `read`, `web_fetch`, `web_search` and `write`. One file lists the ones the agent gets. By convention it's `tools/agent_toolset_20260401.md`, but the file name isn't used:
 
 ```markdown
 ---
 type: agent_toolset_20260401
 ---
+
+## Tools
+
+| Name | Enabled | Permission |
+|---|---|---|
+| `bash` | `true` | `always_ask` |
+| `read` | `true` | |
+| `web_search` | `false` | |
 ```
 
-Only the pre-built tools that have a file are enabled; delete a file to disable that tool. The body is a note for people and isn't sent anywhere.
+- **Frontmatter** is only `type: agent_toolset_20260401`.
+- **`## Tools`** has a row for each tool you configure. **Enabled** is `true` or `false`. A tool without a row keeps the API's default, which is enabled. With no file at all, the agent gets no pre-built tools.
+- **Permission** is `always_allow`, `always_ask` or `auto`. Leave the cell blank for the API's default (`always_allow`), or leave out the column entirely.
+- There can be only one such file. Other sections are notes for people.
 
 **Custom tools** run on your side: when the agent calls one, `agentschema run` runs its code on your machine and sends back the result.
 
 ````markdown
 ---
 type: custom
-name: read_file
-description: Read a file and output its contents as a string.
+name: get_weather
+description: Get the current weather for a city.
 ---
 
 ## Input Schema
 
 | Name | Type | Description | Required |
 |---|---|---|---|
-| `filePath` | `string` | The path of the file to read | `true` |
+| `city` | `string` | City name | `true` |
 
 ## Code
 
 ```javascript
-const fs = require('fs').promises;
-
-module.exports = async ({ filePath }) => {
-  try {
-    return await fs.readFile(filePath, 'utf-8');
-  } catch (error) {
-    return `Error reading file: ${error.message}`;
-  }
-};
+module.exports = ({ city }) =>
+  fetch(`https://wttr.in/${encodeURIComponent(city)}?format=3`).then((r) => r.text());
 ```
 ````
 
-- **Frontmatter:** `type: custom`, a `name` that matches the file name, and a `description` the model reads to decide when to call the tool. The name can't reuse a pre-built tool's name (so `read_file`, not `read`), because the API rejects that.
+- **Frontmatter:** `type: custom`, a `name` that matches the file name, and a `description` the model reads to decide when to call the tool. The name can't reuse a pre-built tool's name (so `read_file` works, but not `read`), because the API rejects that.
 - **`## Input Schema`** is a table with the columns Name, Type, Description and Required. Type is `string`, `number`, `integer`, `boolean`, `object` or `array`, or one of those followed by `[]` for a list. Leave the section out for a tool that takes no input.
 - **`## Code`** is required, and must be one JavaScript code block. It's a CommonJS module, and `module.exports` is the function. It's called with the call's input as an object. A string it returns (or resolves to) is sent as the result; anything else is sent as JSON. If it throws, the error message is sent as an error result. `require()` resolves from the tool's file, so packages installed in the agent folder work.
 - Other sections are notes for people.
 
-**Compiling.** `deploy` turns `tools/` into the agent's `tools` list, sorted by tool name: one `agent_toolset_20260401` entry with `default_config: { enabled: false }` and a config enabling each pre-built tool with a file, then the custom tools. A custom tool sends only its name, description and input schema; the code never leaves your machine.
+**Compiling.** `deploy` turns `tools/` into the agent's `tools` list, sorted by tool name: one `agent_toolset_20260401` entry with a config for each row of the `## Tools` table (its `enabled`, and its `permission_policy` if it has one), then the custom tools. A custom tool sends only its name, description and input schema; the code never leaves your machine.
 
 ## Usage
 
@@ -128,7 +128,7 @@ agentschema sessions delete <id>      # delete a session
 **`init`** creates the folder `<name>` with an `agent.md` and an `env.md` that pass `check`. It asks for:
 - the agent's name and model
 - its system prompt
-- whether it gets the pre-built tools; if so, `init` writes a file for each one in `tools/built-in/`
+- whether it gets the pre-built tools; if so, `init` writes `tools/agent_toolset_20260401.md` listing all eight
 - the environment's name and networking
 
 Press Enter to keep the default shown, or pass `--yes` to skip the questions. `init` won't write into a folder that already has files in it.
@@ -137,7 +137,7 @@ Press Enter to keep the default shown, or pass `--yes` to skip the questions. `i
 - a missing file, or a name that isn't lowercase
 - frontmatter that is missing, unclosed, or invalid YAML
 - a missing `name` or `model`, or a `system` or `tools` key in `agent.md`'s frontmatter
-- a tool file that isn't a known pre-built tool, or a custom tool with a missing description, a malformed input table, or code that isn't JavaScript or doesn't parse
+- a pre-built tools table that names an unknown tool or permission, or a custom tool with a missing description, a malformed input table, or code that isn't JavaScript or doesn't parse
 - values over the API's limits
 - anything that looks like an API key or token
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soft-boy/agentschema",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Markdown based AI agent schema",
   "type": "module",
   "bin": {

package/src/init.js

@@ -3,7 +3,7 @@ import { basename, dirname, resolve } from "node:path";
 import { createInterface, emitKeypressEvents } from "node:readline";
 import { stringify } from "yaml";
 import { AGENT_FILE, ENV_FILE } from "./instance.js";
-import { BUILT_IN_DIR, PREBUILT_TOOLS, TOOLSET, TOOLS_DIR } from "./tools.js";
+import { TOOLSET_FILE, PREBUILT_TOOLS, TOOLSET, TOOLS_DIR } from "./tools.js";
 
 export class InitError extends Error {}
 
@@ -24,8 +24,8 @@ export function defaults(dir) {
   };
 }
 
-// Returns { path: text } for a set of answers: agent.md, env.md, and a tools/built-in/ file
-// for each pre-built tool when the agent gets them.
+// Returns { path: text } for a set of answers: agent.md, env.md, and tools/agent_toolset_20260401.md
+// listing every pre-built tool when the agent gets them.
 export function scaffold(answers) {
   const agent = { name: answers.name, model: answers.model };
 
@@ -41,11 +41,17 @@ export function scaffold(answers) {
     [ENV_FILE]: `---\n${stringify(env)}---\nCloud container with ${access}.\n`,
   };
   if (answers.tools) {
-    for (const name of PREBUILT_TOOLS) files[`${TOOLS_DIR}/${BUILT_IN_DIR}/${name}.md`] = `---\ntype: ${TOOLSET}\n---\n`;
+    files[`${TOOLS_DIR}/${TOOLSET_FILE}`] = builtInFile(PREBUILT_TOOLS);
   }
   return files;
 }
 
+// The pre-built toolset file, enabling `names` with the API's default permission policy.
+export function builtInFile(names) {
+  const rows = names.map((name) => `| \`${name}\` | \`true\` | |`).join("\n");
+  return `---\ntype: ${TOOLSET}\n---\n\nThe tools Claude runs in the agent's container. Set Enabled to false to turn a tool off.\n\n## Tools\n\n| Name | Enabled | Permission |\n|---|---|---|\n${rows}\n`;
+}
+
 // Asks the setup questions, then writes agent.md and env.md into a new folder `dir`.
 export async function init(dir, { yes = false, input = process.stdin, output = process.stdout } = {}) {
   if (existsSync(dir) && readdirSync(dir).length > 0) {
@@ -61,7 +67,7 @@ export async function init(dir, { yes = false, input = process.stdin, output = p
     writeFileSync(resolve(dir, file), text);
   }
 
-  const tools = answers.tools ? `, and ${dir}/${TOOLS_DIR}/${BUILT_IN_DIR}/ with the pre-built tools (delete a file to disable that tool)` : "";
+  const tools = answers.tools ? `, and ${dir}/${TOOLS_DIR}/${TOOLSET_FILE} with the pre-built tools (set Enabled to false to turn one off)` : "";
   output.write(`\nCreated ${dir}/${AGENT_FILE} and ${dir}/${ENV_FILE}${tools}.\n\nNext:\n`);
   output.write(`  agentschema deploy ${dir}\n  agentschema run ${dir}\n`);
   return files;

package/src/tools.js

@@ -5,13 +5,15 @@ import { Script, runInThisContext } from "node:vm";
 import { FileError, parseMarkdown } from "./markdown.js";
 
 export const TOOLS_DIR = "tools";
-export const BUILT_IN_DIR = "built-in";
 export const TOOLSET = "agent_toolset_20260401";
+export const TOOLSET_FILE = `${TOOLSET}.md`;
 export const PREBUILT_TOOLS = ["bash", "edit", "glob", "grep", "read", "web_fetch", "web_search", "write"];
+export const POLICIES = ["always_allow", "always_ask", "auto"];
 const TYPES = ["string", "number", "integer", "boolean", "object", "array"];
 
 // Reads every .md file under tools/, in any subfolder, sorted by name. Folders are only for
-// organizing: a tool's name is its file name, and its path isn't compiled into anything.
+// organizing: a custom tool's name is its file name, and its path isn't compiled into anything.
+// The pre-built toolset is one file (by convention tools/agent_toolset_20260401.md) that lists its tools.
 // A missing tools/ folder means no tools.
 // Returns { tools, errors }; a tool file that can't be parsed has an entry in errors.
 export function readTools(dir) {
@@ -35,10 +37,14 @@ export function readTools(dir) {
     }
   }
 
-  // Names must be unique across folders, since the folders are dropped.
-  for (const [name, same] of groupBy(tools, (t) => t.name)) {
+  // Custom tool names must be unique across folders, since the folders are dropped.
+  for (const [name, same] of groupBy(tools.filter((t) => t.data.type === "custom"), (t) => t.name)) {
     if (same.length > 1) errors.push(`${TOOLS_DIR}: more than one tool is named \`${name}\` (${same.map((t) => t.file).join(", ")})`);
   }
+  const toolsets = tools.filter((t) => t.data.type === TOOLSET);
+  if (toolsets.length > 1) {
+    errors.push(`${TOOLS_DIR}: more than one \`${TOOLSET}\` file (${toolsets.map((t) => t.file).join(", ")}); list every pre-built tool in one file`);
+  }
   return { tools: tools.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)), errors };
 }
 
@@ -60,7 +66,8 @@ function groupBy(items, key) {
   return groups;
 }
 
-// Pulls the `## Input Schema` table and the `## Code` block out of a tool file's body.
+// Pulls the `## Input Schema` table, the `## Code` block and the `## Tools` table (for the
+// pre-built toolset) out of a tool file's body.
 function parseSections(body, file) {
   const sections = {};
   let current = null;
@@ -77,22 +84,29 @@ function parseSections(body, file) {
     }
   }
 
-  const result = { params: null, code: null };
-  if (sections["input schema"]) result.params = parseTable(sections["input schema"], file);
+  const result = { params: null, code: null, rows: null };
+  if (sections["input schema"]) {
+    result.params = parseTable(sections["input schema"], `${file}: the Input Schema table's columns must be Name | Type | Description | Required`,
+      ["name", "type", "description", "required"]);
+  }
   if (sections.code) result.code = parseCode(sections.code, file);
+  if (sections.tools) {
+    result.rows = parseTable(sections.tools, `${file}: the Tools table's columns must be Name | Enabled, or Name | Enabled | Permission`, ["name", "enabled"], ["permission"]);
+  }
   return result;
 }
 
-// Rows of the Name | Type | Description | Required table.
-function parseTable(lines, file) {
+// The rows of a Markdown table as objects keyed by column name. The header must start with
+// the `required` columns, and may go on with the `optional` ones, in order.
+function parseTable(lines, message, required, optional = []) {
   const rows = lines.filter((l) => l.trim().startsWith("|")).map(splitRow);
   if (rows.length === 0) return [];
   const header = rows[0].map((c) => c.toLowerCase());
-  const want = ["name", "type", "description", "required"];
-  if (want.some((c, i) => header[i] !== c)) {
-    throw new FileError(`${file}: the Input Schema table's columns must be Name | Type | Description | Required`);
+  const allowed = [...required, ...optional];
+  if (header.length < required.length || header.length > allowed.length || header.some((c, i) => c !== allowed[i])) {
+    throw new FileError(message);
   }
-  return rows.slice(2).map(([name, type, description, required]) => ({ name, type, description, required }));
+  return rows.slice(2).map((cells) => Object.fromEntries(header.map((c, i) => [c, cells[i] ?? ""])));
 }
 
 function splitRow(line) {
@@ -121,9 +135,7 @@ export function checkTools(tools, errors) {
     };
 
     if (type === TOOLSET) {
-      if (!PREBUILT_TOOLS.includes(tool.name)) {
-        err(`not a pre-built tool; name the file after one of: ${PREBUILT_TOOLS.join(", ")}`);
-      }
+      checkToolset(tool, err);
       extra(["type"]);
     } else if (type === "custom") {
       checkCustom(tool, err);
@@ -134,6 +146,24 @@ export function checkTools(tools, errors) {
   }
 }
 
+function checkToolset(tool, err) {
+  if (!tool.rows) {
+    // 0.2.0 had one file per pre-built tool, with no table.
+    const hint = PREBUILT_TOOLS.includes(tool.name) ? `; since 0.2.1 all pre-built tools go in one file, ${TOOLS_DIR}/${TOOLSET_FILE}` : "";
+    return err(`a \`## Tools\` table listing the pre-built tools to enable is required${hint}`);
+  }
+  const seen = new Set();
+  for (const row of tool.rows) {
+    if (!PREBUILT_TOOLS.includes(row.name)) err(`\`${row.name}\` is not a pre-built tool; use ${PREBUILT_TOOLS.join(", ")}`);
+    else if (seen.has(row.name)) err(`\`${row.name}\` is listed twice`);
+    seen.add(row.name);
+    if (!["true", "false"].includes(row.enabled.toLowerCase())) err(`\`${row.name}\`: Enabled must be true or false`);
+    if (row.permission && !POLICIES.includes(row.permission)) {
+      err(`\`${row.name}\` has permission \`${row.permission}\`; use ${POLICIES.join(", ")}, or leave it blank`);
+    }
+  }
+}
+
 function checkCustom(tool, err) {
   const { name, description } = tool.data;
   if (name !== tool.name) err(`\`name\` must match the file name (${tool.name})`);
@@ -164,16 +194,20 @@ function checkCustom(tool, err) {
   }
 }
 
-// The tools list sent to the API: one toolset entry that enables only the pre-built tools
-// with a file (so deleting a file disables the tool), then the custom tools, sorted by name.
+// The tools list sent to the API: one toolset entry with a config for each row of its table
+// (tools it doesn't list keep the API's defaults), then the custom tools, sorted by name.
 export function compileTools(tools) {
   const compiled = [];
-  const prebuilt = tools.filter((t) => t.data.type === TOOLSET).map((t) => t.name).sort();
-  if (prebuilt.length > 0) {
+  const toolset = tools.find((t) => t.data.type === TOOLSET);
+  if (toolset) {
+    const rows = [...(toolset.rows ?? [])].sort((a, b) => (a.name < b.name ? -1 : 1));
     compiled.push({
       type: TOOLSET,
-      default_config: { enabled: false },
-      configs: prebuilt.map((name) => ({ name, enabled: true })),
+      configs: rows.map(({ name, enabled, permission }) => {
+        const config = { name, enabled: enabled.toLowerCase() === "true" };
+        if (permission) config.permission_policy = { type: permission };
+        return config;
+      }),
     });
   }
   for (const tool of tools.filter((t) => t.data.type === "custom").sort((a, b) => (a.name < b.name ? -1 : 1))) {