@capybara-hq/plugin-sdk 0.1.0-rc.1 → 0.1.0-rc.3

package/README.md

@@ -1,7 +1,7 @@
 # @capybara-hq/plugin-sdk
 
 The SDK for writing plugins for [Capybara](https://github.com/capybara-hq/core), an open-source enterprise agent platform. It holds
-the types, extension point contracts (`model-provider@2`, `channel@1`, `connector@1`, `sandbox@1`,
+the types, extension point contracts (`model-provider@2`, `channel@1`, `connector@1`, `sandbox@2`,
 `object-store@1` and others) and pure functions that a plugin's extension is written against, and the
 package formats: the plugin manifest `.capybara-plugin/plugin.json` (`parsePluginManifest`),
 connector template files `connectors/<id>.json` (`parseConnectorTemplateFile`) and the marketplace

package/agent-docs/agent-templates.md

@@ -0,0 +1,47 @@
+# Agent templates
+
+An agent template describes a whole agent: instructions, tools, skills, connectors and the
+sub-agents it may dispatch. A member creates a private agent from a template; org admins can also
+save an agent as an org template. A plugin ships templates as `agents/<name>.md`: Markdown with
+YAML frontmatter, the body being the instructions.
+
+```markdown
+---
+name: researcher
+description: Finds and summarizes sources on a topic. Use for open-ended research.
+model: standard
+tools: [WebSearch, WebFetch, Read]
+skills: [citation-style]
+---
+
+You are a careful researcher. ...
+```
+
+## Frontmatter
+
+<!-- generated:agent-template -->
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `name` | string | yes | `^[a-z0-9][a-z0-9-]{0,63}$`; the type name is `<plugin>:<name>`. |
+| `description` | string | yes | When to use it; at most 4096 characters. |
+| `tools` | array of tool keys | no | Allowlist (at most 200); omitted = the parent's tools, `[]` = none. |
+| `disallowedTools` | array of tool keys | no | Tool keys removed (at most 200). |
+| `toolPolicies` | object | no | Tool key to `ask` or `deny`; can only tighten. |
+| `model` | `inherit` \| `fast` \| `standard` \| `capable` | no | A purpose tier, never a model id; default `inherit`. |
+| `effort` | `low` \| `medium` \| `high` \| `xhigh` \| `max` | no | Reasoning effort. |
+| `maxSteps` | integer | no | Step limit; the kernel caps it. |
+| `skills` | array of skill names | no | At most 3, preloaded (pinned). |
+| `selectedSkills` | array of skill names | no | At most 32 further skills the agent may use. |
+| `connectors` | array of objects | no | At most 16: `{ template, tools?, policies? }` for a connector template (`<id>` or `<plugin>:<id>`), or `{ needs: { protocol, endpoint, tools, label }, policies? }` for a described need. |
+| `subagents` | object | no | `{ general?, types?, inline? }`: the sub-agents in its roster (at most 16 types plus inline). |
+| `modelRef` | string | no | `provider/model`; set on org templates saved from an agent. |
+| `quickActions` | array of objects | no | At most 9 `{ title, body }` shortcuts. |
+| `instructionFiles` | array of objects | no | At most 20 `{ name, content }` files. |
+<!-- /generated -->
+
+Unknown keys are ignored. The body is at most 100,000 characters.
+
+## Creating an agent from a template
+
+A connector the org does not have becomes a pending entry, and a setup request goes to the org
+admins. Tool keys follow `tool-naming`.

package/agent-docs/concepts.md

@@ -0,0 +1,58 @@
+# Platform concepts
+
+Read this first. It explains the vocabulary the other topics use.
+
+## Platform and org
+
+- The **platform** is one deployment. The **super admin** runs it: imports plugins into the
+  **catalog**, decides where each item is on, and configures deployment-wide extensions.
+- An **org** is a tenant of the platform. An org sees the platform items that are on in it, plus
+  the items it owns. **Org admins** manage their org; **members** use it.
+- Everything you do through the `Platform` tool acts as the person who started the run. You never
+  have more rights than that person, and role, membership and super admin status are re-read on
+  every call.
+
+## Plugins, extensions, skills, templates
+
+- A **plugin** is the install and distribution unit: an optional extension, skills, connector
+  templates and agent templates (see `plugin-format`).
+- An **extension** is the in-process code inside a plugin (see `extensions`). Most
+  contributions need no code: a plugin with only skills or templates is *declarative*.
+- A **skill** is instructions the agent loads on demand (`skills`). An **agent template**
+  describes a whole agent (`agent-templates`). A **connector template** is a ready-made
+  connection to an external system (`connector-templates`).
+- An **extension point** is a versioned contract (`channel@1`) an extension provides or consumes.
+
+## Scope
+
+Every platform item (plugin, and its skills and templates) has a scope:
+
+| Scope | Meaning |
+|---|---|
+| `all` | On in every org. Org admins cannot switch it. |
+| `optional` | Off until an org admin switches it on. The default for new imports. |
+| `named` | On in the listed orgs only; invisible to other orgs unless shown to them. |
+
+Skills, agent templates and connector templates of a platform plugin are platform components: one
+version per deployment, never copied into orgs.
+
+## Owner and shareable
+
+An item has an owner: the platform (no owner org) or one org. An org-owned item reaches another org
+only if its owner marked it `shareable` and the platform then shows or scopes it there.
+
+## Requests
+
+When a person cannot do something themselves (install a plugin that is not on in their org,
+approve extension permissions), they file a **request**. Org admins or the super admin decide it
+on the web. Agents can file requests but never decide them.
+
+## Sandbox
+
+Agents run commands and keep files in a **sandbox**, one per conversation. Skills are mounted
+read-only under `/skills/<name>/`. Sandbox limits and network egress are set per org by admins.
+
+## What agents may not do
+
+Deciding approvals and requests, confirming extension permissions, managing tokens and secrets,
+changing roles. Operations that need credentials refuse and point to the web page.

package/agent-docs/connector-templates.md

@@ -0,0 +1,47 @@
+# Connector templates
+
+A connector template is a ready-made connection to an external system: a protocol connector
+(`connector-mcp`, `connector-openapi`), a preset endpoint and the auth shape. An org installs it
+and fills in only the credential. Templates live in a plugin as `connectors/<id>.json`; the id is
+the file's base name.
+
+```json
+{
+  "$schema": "https://capybarahq.com/schemas/connector-template.v1.schema.json",
+  "displayName": { "zh": "Acme CRM", "en": "Acme CRM" },
+  "description": "Acme CRM over MCP",
+  "template": {
+    "plugin": "connector-mcp",
+    "pluginVersion": "^0.1.0-rc.0",
+    "connector": "mcp",
+    "endpoint": { "url": "https://mcp.acme.example/mcp" },
+    "editableEndpoint": ["url"],
+    "auth": { "type": "bearer", "ownership": "org" },
+    "defaultToolPolicies": { "search": "allow", "delete_record": "deny" }
+  }
+}
+```
+
+The file is strict. Top-level fields:
+
+<!-- generated:connector-template -->
+| Field | Type | Required |
+|---|---|---|
+| `displayName` | object | yes |
+| `description` | string | no |
+| `icon` | string | no |
+| `template` | object | yes |
+<!-- /generated -->
+
+Fields of `template`:
+
+- `plugin`, `connector`: the connector extension and its kind; `pluginVersion` is a semver range.
+- `endpoint`: the preset every org sees. **Never put credentials in it** (no `token`, `apiKey`,
+  `secret`, `password`, `authorization`, `cookie`).
+- `editableEndpoint`: dotted endpoint paths an org may change at install (a self-hosted URL, a
+  tenant id). List only what really differs per org.
+- `auth`: the auth method without credentials: `none`, `bearer`, `basic`, `api_key`, `headers`,
+  `oauth_code` or `oauth_client`, plus `ownership` (`org` or per member).
+- `defaultToolPolicies`: tool name to `allow`, `ask` or `deny`. When unsure, do not write `allow`.
+
+Credentials and secret config are entered by people on the web page, never through an agent.

package/agent-docs/extension-points/channel.md

@@ -0,0 +1,15 @@
+# Extension point: channel
+
+<!-- generated:extension-point -->
+- Name: `channel` (a ref is `channel@<major>`)
+- Connects an instant-messaging platform (Slack, Lark): inbound events, replies and cards.
+- Providers: several
+- Enabled per org: yes
+- Brokered by the platform: no
+<!-- /generated -->
+
+Contract: Channel (`channel.ts`)
+
+Normalize inbound events (messageId, threadId, tenantId, the bot mention stripped) and acknowledge only after the kernel's `onEvent` resolves. Long connections are held only by the gateway role. Replies use the card spec (`validateChannelCard`).
+
+See `extensions` for the rules every extension follows.

package/agent-docs/extension-points/config-source.md

@@ -0,0 +1,15 @@
+# Extension point: config-source
+
+<!-- generated:extension-point -->
+- Name: `config-source` (a ref is `config-source@<major>`)
+- Supplies deployment configuration from an external store such as Nacos.
+- Providers: one at a time
+- Enabled per org: no
+- Brokered by the platform: no
+<!-- /generated -->
+
+Contract: (kernel-defined; no public SDK contract yet)
+
+Deployment config precedence is env, then file or this source, then the database, then defaults. A source must never fail startup when its content is invalid.
+
+See `extensions` for the rules every extension follows.

package/agent-docs/extension-points/connector.md

@@ -0,0 +1,15 @@
+# Extension point: connector
+
+<!-- generated:extension-point -->
+- Name: `connector` (a ref is `connector@<major>`)
+- Speaks one protocol (MCP, OpenAPI) to external systems and exposes their tools to agents.
+- Providers: several
+- Enabled per org: no
+- Brokered by the platform: yes (extensions use it only through `ctx`)
+<!-- /generated -->
+
+Contract: Connector (`connector.ts`)
+
+Implement one protocol (`kind`): an endpoint schema, `open` and `close` per call, `auth()` before every request, and tool listing and calls. Surface failures as `ToolError` with a kind. Tools reach agents as `mcp__<slug>__<tool>`. Templates for it: see `connector-templates`. No stdio MCP.
+
+See `extensions` for the rules every extension follows.

package/agent-docs/extension-points/counter.md

@@ -0,0 +1,15 @@
+# Extension point: counter
+
+<!-- generated:extension-point -->
+- Name: `counter` (a ref is `counter@<major>`)
+- Counts usage so quotas and reports can be built on it.
+- Providers: several
+- Enabled per org: no
+- Brokered by the platform: no
+<!-- /generated -->
+
+Contract: (kernel-defined; no public SDK contract yet)
+
+Counts usage events. Check the SDK exports before relying on it.
+
+See `extensions` for the rules every extension follows.

package/agent-docs/extension-points/directory.md

@@ -0,0 +1,15 @@
+# Extension point: directory
+
+<!-- generated:extension-point -->
+- Name: `directory` (a ref is `directory@<major>`)
+- Syncs members and departments from an external company directory.
+- Providers: several
+- Enabled per org: yes
+- Brokered by the platform: no
+<!-- /generated -->
+
+Contract: Directory (`directory.ts`)
+
+List members and departments from a company directory so the kernel can sync them into orgs. Enabled per org.
+
+See `extensions` for the rules every extension follows.

package/agent-docs/extension-points/file-preview.md

@@ -0,0 +1,15 @@
+# Extension point: file-preview
+
+<!-- generated:extension-point -->
+- Name: `file-preview` (a ref is `file-preview@<major>`)
+- Renders previews of files of given types in the conversation UI.
+- Providers: several
+- Enabled per org: yes
+- Brokered by the platform: no
+<!-- /generated -->
+
+Contract: FilePreviewProvider (`file-preview.ts`)
+
+Declare which file types you can preview and render them through schema views or an approved embed. Enabled per org.
+
+See `extensions` for the rules every extension follows.

package/agent-docs/extension-points/identity-source.md

@@ -0,0 +1,15 @@
+# Extension point: identity-source
+
+<!-- generated:extension-point -->
+- Name: `identity-source` (a ref is `identity-source@<major>`)
+- Signs people in through an external identity provider (SSO).
+- Providers: several
+- Enabled per org: no
+- Brokered by the platform: no
+<!-- /generated -->
+
+Contract: IdentitySource (`identity.ts`)
+
+Provide SSO login through an external provider. The kernel owns state, nonce and PKCE checks; identities are keyed `<plugin>:<tenant>`.
+
+See `extensions` for the rules every extension follows.

package/agent-docs/extension-points/model-provider.md

@@ -0,0 +1,15 @@
+# Extension point: model-provider
+
+<!-- generated:extension-point -->
+- Name: `model-provider` (a ref is `model-provider@<major>`)
+- Calls a model vendor's API and streams the result back to the runtime.
+- Providers: several
+- Enabled per org: no
+- Brokered by the platform: yes (extensions use it only through `ctx`)
+<!-- /generated -->
+
+Contract: ModelProvider (`model.ts`); refs `model-provider@1` and `@2`
+
+Map the kernel's messages and tools to the vendor API and stream the result. Do not retry inside the extension; return a `ModelError` with the right kind and let the kernel degrade. History sent to the model is append-only. Declare parameters and media support.
+
+See `extensions` for the rules every extension follows.

package/agent-docs/extension-points/object-store.md

@@ -0,0 +1,15 @@
+# Extension point: object-store
+
+<!-- generated:extension-point -->
+- Name: `object-store` (a ref is `object-store@<major>`)
+- Stores files and artifacts in S3-compatible object storage, with presigned uploads.
+- Providers: one at a time
+- Enabled per org: no
+- Brokered by the platform: yes (extensions use it only through `ctx`)
+<!-- /generated -->
+
+Contract: ObjectStore (`storage.ts`)
+
+Return `null` for a missing key, reject keys containing `${`, and enforce the size of presigned uploads in the store itself. The kernel adds key prefixes; extensions consume it as `ctx.storage`.
+
+See `extensions` for the rules every extension follows.

package/agent-docs/extension-points/sandbox.md

@@ -0,0 +1,15 @@
+# Extension point: sandbox
+
+<!-- generated:extension-point -->
+- Name: `sandbox` (a ref is `sandbox@<major>`)
+- Runs an environment's instance and keeps its files for agents' commands (Docker, E2B).
+- Providers: one at a time
+- Enabled per org: no
+- Brokered by the platform: yes (extensions use it only through `ctx`)
+<!-- /generated -->
+
+Contract: SandboxProvider (`sandbox.ts`)
+
+The kernel accepts only `sandbox@2`. An environment is one instance plus a file system that outlives it. Implement the file system (`createFileSystem`, `destroyFileSystem`, `destroyFileSystemByName`), the instance on it (`create`, which throws `FileSystemGoneError` when the file system is gone instead of making an empty one; `resume`, `suspend`; `destroy` and `destroyByName`, which drop the instance and keep the files), and the instance's `exec`, `readFile`, `writeFile`, `stat`, `killAll` and `killTagged` (`concurrentExec` is required: several conversations share one instance). Aborting a command must kill it. Locking, suspension timing and destruction are the kernel's job, not yours. Never publish a docker socket proxy on a host address.
+
+See `extensions` for the rules every extension follows.

package/agent-docs/extension-points/secret-store.md

@@ -0,0 +1,15 @@
+# Extension point: secret-store
+
+<!-- generated:extension-point -->
+- Name: `secret-store` (a ref is `secret-store@<major>`)
+- Stores and resolves secrets (connector credentials, secret config) outside the database.
+- Providers: one at a time
+- Enabled per org: no
+- Brokered by the platform: yes (extensions use it only through `ctx`)
+<!-- /generated -->
+
+Contract: (kernel-defined; no public SDK contract yet)
+
+Brokered: extensions never call it directly. They use `ctx.secrets` and `secret()` config fields, and results never contain secret values.
+
+See `extensions` for the rules every extension follows.

package/agent-docs/extension-points/web-fetch.md

@@ -0,0 +1,15 @@
+# Extension point: web-fetch
+
+<!-- generated:extension-point -->
+- Name: `web-fetch` (a ref is `web-fetch@<major>`)
+- Fetches and extracts web pages for the WebFetch tool; each org picks a default provider.
+- Providers: several; each org chooses its default
+- Enabled per org: yes
+- Brokered by the platform: yes (extensions use it only through `ctx`)
+<!-- /generated -->
+
+Contract: WebFetchProvider (`web.ts`)
+
+Fetch a URL and return extracted page content. Admin-supplied URLs go through the kernel's network rules. Each org chooses its default provider.
+
+See `extensions` for the rules every extension follows.

package/agent-docs/extension-points/web-search.md

@@ -0,0 +1,15 @@
+# Extension point: web-search
+
+<!-- generated:extension-point -->
+- Name: `web-search` (a ref is `web-search@<major>`)
+- Searches the web for the WebSearch tool; each org picks a default provider.
+- Providers: several; each org chooses its default
+- Enabled per org: yes
+- Brokered by the platform: yes (extensions use it only through `ctx`)
+<!-- /generated -->
+
+Contract: WebSearchProvider (`web.ts`)
+
+Return ranked results for a query. Each org chooses its default provider; the kernel's WebSearch tool calls it.
+
+See `extensions` for the rules every extension follows.

package/agent-docs/extensions.md

@@ -0,0 +1,63 @@
+# Writing an extension
+
+An extension is TypeScript code a plugin ships. It runs in the platform's process with full
+trust: approval by the super admin is governance, not a sandbox. It sees only the SDK's `ctx`
+(never kernel internals). Use an extension only when skills, templates and connectors cannot do
+the job.
+
+```ts
+import { defineExtension } from "@capybara-hq/plugin-sdk";
+
+export default defineExtension({
+  name: "my-plugin",
+  version: "0.1.0",
+  sdk: "^0.1.0-rc.0",
+  provides: [],            // extension points it implements
+  permissions: { tools: true },
+  setup(ctx) {
+    ctx.tools.register(/* ... */);
+  },
+});
+```
+
+The plugin's `name` equals the extension's `name`. Put code in `src/index.ts`; `capybara-plugin
+pack` bundles it. Depend only on `@capybara-hq/plugin-sdk`, `zod` and third-party packages.
+
+## Rules for multiple replicas
+
+The platform runs several replicas, so:
+
+- No timers (`setTimeout`, `setInterval`) and no module-level state (top-level `let`, `Map`,
+  `Set`, arrays). Use `ctx.db` (durable), `ctx.kv` (every write has a TTL), `ctx.queue` (delayed
+  and periodic work) and `ctx.bus`.
+- Queue names and job ids contain no `:`.
+- Migrations are plain SQL under `migrations/`, in the schema `plugin_<name>`, expand-only.
+- Declare every capability you use (`ctx.secrets`, `ctx.storage`, `ctx.tools`, `ctx.ui`, hooks)
+  in `permissions`. `capybara-plugin check` verifies this.
+- Hooks observe or deny; they never rewrite.
+
+## Extension points
+
+An extension *provides* a point (`provides`) or *consumes* one (`requires`, or `optional`). Refs
+look like `channel@1`: name and major version. The registered points:
+
+<!-- generated:extension-points -->
+| Extension point | Providers | Per org | What it is |
+|---|---|---|---|
+| `sandbox` | single | no | Runs an environment's instance and keeps its files for agents' commands (Docker, E2B). |
+| `config-source` | single | no | Supplies deployment configuration from an external store such as Nacos. |
+| `secret-store` | single | no | Stores and resolves secrets (connector credentials, secret config) outside the database. |
+| `object-store` | single | no | Stores files and artifacts in S3-compatible object storage, with presigned uploads. |
+| `channel` | multi | yes | Connects an instant-messaging platform (Slack, Lark): inbound events, replies and cards. |
+| `model-provider` | multi | no | Calls a model vendor's API and streams the result back to the runtime. |
+| `identity-source` | multi | no | Signs people in through an external identity provider (SSO). |
+| `directory` | multi | yes | Syncs members and departments from an external company directory. |
+| `counter` | multi | no | Counts usage so quotas and reports can be built on it. |
+| `connector` | multi | no | Speaks one protocol (MCP, OpenAPI) to external systems and exposes their tools to agents. |
+| `file-preview` | multi | yes | Renders previews of files of given types in the conversation UI. |
+| `web-search` | multi | yes | Searches the web for the WebSearch tool; each org picks a default provider. |
+| `web-fetch` | multi | yes | Fetches and extracts web pages for the WebFetch tool; each org picks a default provider. |
+<!-- /generated -->
+
+Read `extension-points/<name>` for each one. Which points a deployment actually has loaded, and
+which plugins are installed, come from `Platform` operations, not from these docs.

package/agent-docs/plugin-format.md

@@ -0,0 +1,60 @@
+# Plugin format
+
+A plugin is a directory, packed into a `.tgz` with `capybara-plugin pack` (the published
+`@capybara-hq/plugin-tools`; `npx capybara-plugin check` runs the checks).
+
+```
+<plugin>/
+  .capybara-plugin/plugin.json   the manifest (required)
+  package.json                   npm metadata; `version` equals plugin.json `version`
+  skills/<name>/SKILL.md         skills (scanned unless plugin.json lists them)
+  connectors/<id>.json           connector templates (scanned unless listed)
+  agents/<name>.md               agent templates (scanned unless listed)
+  src/index.ts                   the extension (optional; bundled by the packer)
+  migrations/*.sql, ui/**        extension migrations and UI files (optional)
+```
+
+A plugin without `src/index.ts` is declarative: skills and templates only, no code runs.
+
+## plugin.json
+
+Add `"$schema": "https://capybarahq.com/schemas/plugin.v1.schema.json"` for editor support. The
+file is strict: an unknown key is an error. Fields (agent templates are listed under `agents`):
+
+<!-- generated:plugin-manifest -->
+| Field | Type | Required |
+|---|---|---|
+| `schemaVersion` | `1` | yes |
+| `name` | string | yes |
+| `version` | string | yes |
+| `publisher` | string | yes |
+| `description` | string or object | yes |
+| `displayName` | object | no |
+| `icon` | string | no |
+| `license` | string | no |
+| `homepage` | string | no |
+| `dependencies` | array of object | no |
+| `skills` | array of object | no |
+| `connectorTemplates` | array of object | no |
+| `agents` | array of object | no |
+| `extension` | object | no |
+<!-- /generated -->
+
+Rules that the schema cannot show:
+
+- `name`: `^[a-z0-9][a-z0-9-]{0,63}$`. With an extension it must equal the extension's name.
+- `version`: an exact semver version, equal to `package.json` `version`. While the platform is in
+  release candidates, ranges on official packages are written `^0.1.0-rc.0`.
+- `description` is a string or `{ en, zh? }`; `displayName` is `{ zh, en }`.
+- `icon` is a `./` path to an `.svg` or `.png` inside the plugin.
+- `skills`, `connectorTemplates`, `agents` list paths starting with `./` that stay inside the plugin.
+  Omit them to scan the default folders. Names and ids are unique within the plugin.
+- `dependencies`: plugin name plus semver range; no self-dependency.
+- `agents`: at most 64 templates (see `agent-templates`).
+- `extension` is written by the packer; never write it by hand.
+
+## Importing
+
+Plugins reach a deployment through a marketplace (npm, archive, git or path sources) or a direct
+import. The super admin reviews one import screen (permissions, components, scope) and confirms
+it; an org can upload its own plugin, which the super admin approves if it carries an extension.

package/agent-docs/skills.md

@@ -0,0 +1,44 @@
+# Skills
+
+A skill is a folder with a `SKILL.md` (the Agent Skills format) and any files it needs. The agent
+sees only the skill's `name` and `description` until it loads the skill, so the description is
+what decides when it is used.
+
+```markdown
+---
+name: weekly-report
+description: Write the weekly status report from the team's tracker. Use when asked for a weekly report or status summary.
+---
+
+# Weekly report
+
+1. Read ...
+```
+
+## Frontmatter
+
+- `name` (required): 1 to 64 characters, lowercase letters, digits and single hyphens. The skill
+  is always known by this name; its sandbox directory is `/skills/<name>/`.
+- `description` (required): 1 to 1024 characters. Say what it does and when to use it. No XML tags.
+- Optional: `license`, `compatibility` (at most 500 characters), `metadata`.
+- Invocation keys (Claude Code's names):
+  - `disable-model-invocation: true`: only a person runs it, with `/name args`.
+  - `user-invocable: false`: hide it from the `/` menu (not together with the one above).
+  - `context: fork`: run it in a sub-agent.
+  - `argument-hint`, `arguments`: describe the arguments a person passes.
+
+Other keys are ignored.
+
+## Where skills live
+
+- In a plugin: `skills/<name>/SKILL.md`, listed or scanned (see `plugin-format`). It becomes a
+  platform component, named `<plugin>:<name>`.
+- In an org: created or uploaded by an org admin, or proposed by an agent and approved by a
+  person. Org skills are private to the org unless shared.
+
+## Writing tips
+
+- Keep `SKILL.md` short and procedural; put long reference material in separate files the skill
+  tells the agent to read.
+- Put scripts next to the skill and tell the agent how to run them in the sandbox.
+- Limits: 1000 files, 10 MB per file, 50 MB in total.

package/agent-docs/tool-naming.md

@@ -0,0 +1,21 @@
+# Tool naming
+
+The model-visible tool key grammar:
+
+| Kind | Key | Example |
+|---|---|---|
+| Builtin | PascalCase, 2 to 32 letters | `Bash`, `Read`, `Skill`, `Platform` |
+| Connector | `mcp__<slug>__<tool>` | `mcp__crm__search_accounts` |
+| Extension | `plugin__<plugin>__<tool>` | `plugin__todo__write` |
+
+Use these keys in `tools`, `disallowedTools` and `toolPolicies` of an agent template, and in
+policies. Keys never contain dots.
+
+## Writing a tool
+
+- Describe it in English, in one or two sentences saying what it does and when to use it.
+- Make errors actionable: say what was wrong and what to do next, not just "failed".
+- An extension registers tools with `ctx.tools.register` and declares the permission in its
+  manifest; the kernel adds the `plugin__<plugin>__` prefix.
+- Connector tools get their `mcp__<slug>__` prefix from the connector's slug.
+- Tool policies are `allow`, `ask` or `deny`; a template or agent may only tighten them.