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

package/README.md

@@ -14,8 +14,8 @@ npm packages; the host provides it at runtime.
 npm install @capybara-hq/plugin-sdk
 ```
 
-- Writing an extension: [.agents/skills/writing-extensions](https://github.com/capybara-hq/core/tree/main/.agents/skills/writing-extensions)
-  and the reference plugin [plugins/example-counter](https://github.com/capybara-hq/core/tree/main/plugins/example-counter).
+- Writing an extension: [.agents/skills/writing-extensions](https://github.com/capybara-hq/plugins/tree/main/.agents/skills/writing-extensions)
+  in capybara-hq/plugins and its reference plugin [plugins/example-counter](https://github.com/capybara-hq/plugins/tree/main/plugins/example-counter).
 - Writing a plugin (manifest, skills, connector templates, dependencies, marketplaces):
   [.agents/skills/writing-plugins](https://github.com/capybara-hq/core/tree/main/.agents/skills/writing-plugins).
 - The repository: [capybara-hq/core](https://github.com/capybara-hq/core).

package/dist/agent-template.js

@@ -1,7 +1,7 @@
 /**
  * Agent templates (`agents/<name>.md` in a plugin; sub-agents spec §16.1): Markdown with YAML
  * frontmatter, the body being the instructions. A template is a type an agent with the builtin
- * `agent` tool can dispatch as a sub-agent (`<plugin>:<name>` in its roster). Used by the kernel,
+ * `Agent` tool can dispatch as a sub-agent (`<plugin>:<name>` in its roster). Used by the kernel,
  * the packer and `capybara-plugin check`.
  */
 import { readFrontmatter } from "./frontmatter.js";

package/dist/hooks.d.ts

@@ -7,12 +7,12 @@ import type { ContentBlock, ModelRequest, ModelUsage } from "./model.js";
 export declare const HOOKS_AVAILABLE: readonly ["model.request", "model.response", "tool.preExecute", "tool.postExecute", "usage.report"];
 /** A mount point that `ctx.hooks.on` accepts. */
 export type AvailableHook = (typeof HOOKS_AVAILABLE)[number];
-/** Where a sub-agent was dispatched from: the parent conversation, its run and the `agent` call. */
+/** Where a sub-agent was dispatched from: the parent conversation, its run and the `Agent` call. */
 export interface HookParentScope {
     conversationId: string;
     runId: string;
     /**
-     * The `agent` call's id; `skill-<seq>` for a person's forked skill invocation, which has no
+     * The `Agent` call's id; `skill-<seq>` for a person's forked skill invocation, which has no
      * tool call in the parent's log.
      */
     callId: string;
@@ -111,6 +111,7 @@ export interface ModelResponseHookPayload extends HookScope {
 export interface ToolPreHookPayload extends HookScope {
     step: number;
     callId: string;
+    /** The model-visible key: a builtin name, `mcp__<slug>__<tool>` or `plugin__<plugin>__<tool>`; split it with `parseToolKey`. */
     toolKey: string;
     specHash: string;
     input: unknown;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "0.1.0-rc.0";
+export declare const SDK_VERSION = "0.1.0-rc.1";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -24,4 +24,5 @@ export * from "./skill.js";
 export * from "./skill-invocation.js";
 export * from "./storage.js";
 export * from "./tool.js";
+export * from "./tool-key.js";
 export * from "./ui.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export const SDK_VERSION = "0.1.0-rc.0";
+export const SDK_VERSION = "0.1.0-rc.1";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -24,4 +24,5 @@ export * from "./skill.js";
 export * from "./skill-invocation.js";
 export * from "./storage.js";
 export * from "./tool.js";
+export * from "./tool-key.js";
 export * from "./ui.js";

package/dist/skill-invocation.d.ts

@@ -37,7 +37,7 @@ export declare function renderSkillBody(body: string, invocation: SkillInvocatio
 export interface RenderSkillInvocationInput {
     /**
      * The name the person typed after `/` (`fix-issue`, or `<plugin>:<name>`): used in the lead, the
-     * `name="…"` attribute and the `skill_load` argument (where the qualified form resolves).
+     * `name="…"` attribute and the `Skill` argument (where the qualified form resolves).
      */
     name: string;
     /**
@@ -53,9 +53,9 @@ export interface RenderSkillInvocationInput {
     args: string;
     /** Decided by the caller from the agent's tools and the version's manifest. */
     lines: {
-        /** The version has files besides SKILL.md: `load` when the agent has `skill_load`. */
+        /** The version has files besides SKILL.md: `load` when the agent has `Skill`. */
         files?: "load" | "unavailable";
-        /** The body has shell injections and the agent has `sandbox_bash`. */
+        /** The body has shell injections and the agent has `Bash`. */
         shellHint?: boolean;
     };
     /** false: leave out the lead sentence (a forked skill's task for the sub-agent). Default true. */

package/dist/skill-invocation.js

@@ -180,13 +180,13 @@ export function renderSkillInvocation(i) {
     }
     parts.push(`<skill_invocation name="${escapeAttr(i.name)}" version="${i.version}">\n${body}\n</skill_invocation>`);
     if (i.lines.files === "load") {
-        parts.push(`Its files are not in the sandbox yet: call skill_load with "${i.name}" to copy them to ${SKILLS_SANDBOX_ROOT}/${i.skillName}/ before running its scripts.`);
+        parts.push(`Its files are not in the sandbox yet: call Skill with "${i.name}" to copy them to ${SKILLS_SANDBOX_ROOT}/${i.skillName}/ before running its scripts.`);
     }
     else if (i.lines.files === "unavailable") {
         parts.push("Its other files are not available in this conversation.");
     }
     if (i.lines.shellHint) {
-        parts.push("Lines written as !`command` were meant to run before you read this; run those commands with sandbox_bash if you need their output.");
+        parts.push("Lines written as !`command` were meant to run before you read this; run those commands with Bash if you need their output.");
     }
     return parts.join("\n\n");
 }

package/dist/tool-key.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Model-visible tool key grammar (aligned with Claude Code):
+ *
+ * - builtin: `^[A-Z][A-Za-z]{1,31}$` (PascalCase), e.g. `Edit`
+ * - connector: `mcp__<slug>__<tool>`, e.g. `mcp__crm__search_accounts`
+ * - extension: `plugin__<plugin>__<tool>`, e.g. `plugin__todo__write`
+ *
+ * Pure functions only; extensions that match keys (hooks) use `parseToolKey` instead of splitting.
+ */
+export type ParsedToolKey = {
+    kind: "builtin";
+    name: string;
+} | {
+    kind: "connector";
+    slug: string;
+    tool: string;
+} | {
+    kind: "extension";
+    plugin: string;
+    tool: string;
+};
+export declare const BUILTIN_TOOL_NAME_RE: RegExp;
+/** Parse a tool key; `null` when it fits none of the three forms. */
+export declare function parseToolKey(key: string): ParsedToolKey | null;
+/** `mcp__<slug>__<tool>` */
+export declare function connectorToolKey(slug: string, tool: string): string;
+/** `plugin__<plugin>__<tool>` */
+export declare function extensionToolKey(plugin: string, tool: string): string;

package/dist/tool-key.js

@@ -0,0 +1,40 @@
+/**
+ * Model-visible tool key grammar (aligned with Claude Code):
+ *
+ * - builtin: `^[A-Z][A-Za-z]{1,31}$` (PascalCase), e.g. `Edit`
+ * - connector: `mcp__<slug>__<tool>`, e.g. `mcp__crm__search_accounts`
+ * - extension: `plugin__<plugin>__<tool>`, e.g. `plugin__todo__write`
+ *
+ * Pure functions only; extensions that match keys (hooks) use `parseToolKey` instead of splitting.
+ */
+export const BUILTIN_TOOL_NAME_RE = /^[A-Z][A-Za-z]{1,31}$/;
+const SEP = "__";
+/** Parse a tool key; `null` when it fits none of the three forms. */
+export function parseToolKey(key) {
+    if (!key.includes(SEP)) {
+        return BUILTIN_TOOL_NAME_RE.test(key) ? { kind: "builtin", name: key } : null;
+    }
+    const first = key.indexOf(SEP);
+    const family = key.slice(0, first);
+    if (family !== "mcp" && family !== "plugin")
+        return null;
+    const rest = key.slice(first + SEP.length);
+    const second = rest.indexOf(SEP);
+    if (second <= 0)
+        return null;
+    const owner = rest.slice(0, second);
+    const tool = rest.slice(second + SEP.length);
+    if (tool === "")
+        return null;
+    return family === "mcp"
+        ? { kind: "connector", slug: owner, tool }
+        : { kind: "extension", plugin: owner, tool };
+}
+/** `mcp__<slug>__<tool>` */
+export function connectorToolKey(slug, tool) {
+    return `mcp${SEP}${slug}${SEP}${tool}`;
+}
+/** `plugin__<plugin>__<tool>` */
+export function extensionToolKey(plugin, tool) {
+    return `plugin${SEP}${plugin}${SEP}${tool}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/plugin-sdk",
-  "version": "0.1.0-rc.0",
+  "version": "0.1.0-rc.1",
   "description": "Capybara plugin SDK: the types and pure functions plugins are written against",
   "license": "Apache-2.0",
   "repository": {