ai-sdk-harness-plugins

import { tool } from 'ai';
import { definePlugin } from 'ai-sdk-harness-plugins';
import { z } from 'zod';

export const acme = definePlugin({
  name: 'acme',
  description: 'What the agent needs to work on Acme.',

  tools: {
    // An AI SDK tool: code, run on your server.
    deploy: tool({
      description: 'Deploy a service.',
      inputSchema: z.object({ service: z.string() }),
      execute: deploy,
    }),
    // An HTTP request your server makes, no code: {service} takes the input's `service`.
    status: {
      type: 'http',
      description: 'The status of a service.',
      inputSchema: {
        type: 'object',
        properties: { service: { type: 'string' } },
        required: ['service'],
      },
      url: 'https://status.acme.dev/{service}',
      headers: { Authorization: { secret: 'ACME_TOKEN' } },
    },
    // A shell command run in the session's sandbox, no code.
    todos: {
      type: 'sandbox-command',
      description: 'Count the TODOs.',
      command: 'git grep -c TODO',
    },
  },

  // Instructions the agent loads when it judges them relevant.
  skills: [{ name: 'acme-style', description: 'How Acme code is written.', content: 'Use …' }],

  // Instructions the agent always follows: for every file, or for the files `paths` matches.
  rules: [
    { name: 'tone', content: 'Answer in short sentences.' },
    { name: 'api', paths: ['src/api/**/*.ts'], content: 'Validate the input of every endpoint.' },
  ],

  // Prompts the user calls by name: `/release 2.1`.
  commands: [
    { name: 'release', description: 'Prepare a release', prompt: 'Prepare release $1: …' },
  ],

  // A command the runtime runs in the sandbox before each shell command: exit 2 blocks it.
  // ${PLUGIN_ROOT} is replaced by the sandbox directory the plugin's `files` are written to.
  hooks: [{ event: 'PreToolUse', matcher: 'Bash', command: '"${PLUGIN_ROOT}/guard.sh"' }],

  // A specialist the agent delegates to.
  subagents: [{ name: 'reviewer', description: 'Reviews changes.', instructions: 'You review …' }],

  // MCP servers your server connects to: their tools reach the agent, their tokens never do.
  mcpServers: {
    linear: {
      type: 'http',
      url: 'https://mcp.linear.app/mcp',
      headers: { Authorization: { secret: 'LINEAR_TOKEN' } },
    },
  },

  // Files written in the sandbox, in ${PLUGIN_ROOT}: the hook's script.
  files: [{ path: 'guard.sh', content: '#!/bin/sh\n…', executable: true }],
});

pnpm add ai-sdk-harness-plugins @ai-sdk/harness @ai-sdk/harness-claude-code zod

import { HarnessAgent } from '@ai-sdk/harness/agent';
import { createClaudeCode } from '@ai-sdk/harness-claude-code';
import { expandCommand, resolvePlugins, withPlugins } from 'ai-sdk-harness-plugins';

const { plugins, close } = await resolvePlugins([acme], {
  resolveSecret: (name) => secrets.get(name), // ACME_TOKEN, LINEAR_TOKEN…
});
const agent = new HarnessAgent(withPlugins({ harness: createClaudeCode() }, plugins));

// A command is expanded on your server, before the message reaches the agent.
const prompt = expandCommand(message, plugins)?.prompt ?? message;
await agent.stream({ session, prompt });

await close(); // closes the MCP clients, once the agent is done

{
  "name": "library-docs",
  "description": "Up-to-date library documentation from the Context7 MCP server, connected by the server: a whole plugin kept as data.",
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    }
  },
  "commands": [
    {
      "name": "docs",
      "description": "Answer a question from a library's documentation",
      "argumentHint": "<library> <question>",
      "prompt": "Answer this question from the current documentation of the library: resolve the library id with the context7_resolve-library-id tool, then query its documentation with context7_query-docs, and cite what you used. $ARGUMENTS",
      "requires": ["mcp-server:context7"]
    }
  ]
}

{
  "kind": "tool",
  "name": "npm-latest",
  "type": "http",
  "description": "Read the latest version of an npm package from the registry: its version, description, license and dependencies.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "The package name, scope included: @ai-sdk/harness"
      }
    },
    "required": ["name"],
    "additionalProperties": false
  },
  "url": "https://registry.npmjs.org/{name}/latest"
}

{
  "kind": "skill",
  "name": "code-review",
  "description": "How to review a change. Use it whenever you review code or a diff.",
  "content": "# Reviewing a change\n\n1. Say what the change does, in one sentence.\n2. List the bugs first: what breaks, with the line.\n3. Then what is hard to read or to change, and why.\n4. End with what is good about it, if anything is."
}

{
  "kind": "rule",
  "name": "dependency-versions",
  "description": "Checks that dependencies are pinned, whenever the agent reads a package.json.",
  "paths": ["**/package.json"],
  "content": "When you read or edit a package.json, check the versions of its dependencies and devDependencies. End your answer with a **Dependency check** section: list each dependency whose version is not exact (a range with ^ or ~, *, or a tag such as latest) with the version to pin, or say that all are pinned."
}

{
  "kind": "command",
  "name": "npm",
  "description": "Size an npm package up before adding it",
  "argumentHint": "<package>",
  "prompt": "Look the npm package $1 up with the npm-latest tool, then tell me in a few lines what it is, its latest version and license, and how many dependencies it would add.",
  "requires": ["tool:npm-latest"]
}

{
  "kind": "hook",
  "name": "protect-env",
  "description": "Keeps .env files out of the conversation: the agent may not read them.",
  "event": "PreToolUse",
  "matcher": "Read|Bash|Grep",
  "command": "\"${PLUGIN_ROOT}/protect-env.sh\"",
  "timeout": 10,
  "files": [
    {
      "path": "protect-env.sh",
      "content": "#!/bin/sh\n# Claude Code hands the tool call as JSON on the standard input.\nif grep -Eq '\\.env($|[^A-Za-z])'; then\n  echo 'Blocked by the protect-env hook: .env files hold secrets, and stay out of the conversation. Ask the user for the values you need.' >&2\n  exit 2\nfi\n",
      "executable": true
    }
  ]
}

{
  "kind": "subagent",
  "name": "reviewer",
  "description": "Reviews the changes of the working directory. Delegate reviews to it.",
  "instructions": "You review the uncommitted changes of the working directory (git diff), following the code-review skill, and report what you found. You change nothing.",
  "tools": ["Read", "Grep", "Glob", "Bash", "Skill"],
  "requires": ["skill:code-review"]
}

{
  "kind": "mcp-server",
  "name": "deepwiki",
  "description": "The documentation of public GitHub repositories, from DeepWiki.",
  "type": "http",
  "url": "https://mcp.deepwiki.com/mcp",
  "allowedTools": ["read_wiki_structure", "ask_wiki_question"]
}

import { createCatalog } from 'ai-sdk-harness-plugins';

const catalog = createCatalog({ plugins: [libraryDocs], items });

// What an agent picked: an item, a whole plugin, or one item of a plugin.
const selection = ['command:npm', 'hook:protect-env', 'plugin:library-docs'];
const { plugins, close } = await catalog.resolve(selection, { resolveSecret });
const agent = new HarnessAgent(withPlugins({ harness: createClaudeCode() }, plugins));