Plugin Author

Plugin Author — WrongStack

Overview

Guides the creation and maintenance of first-party plugins in packages/plugins/. A plugin is a TypeScript module that implements the Plugin interface from @wrongstack/core, registering tools, hooks, slash commands, or pipelines into the agent's runtime.

There are currently 21 official plugins in the suite:

Rules

1. Every plugin must implement teardown() and health(). Even stateless plugins (shell-check, semver-bump) add both — the teardown logs a completion line with per-session counters, and health() reports ok: true + counters for /diag plugins. This is the H1 audit pattern (see below).
2. State at module scope, not in the setup() closure. The Plugin interface does not thread state from setup() → teardown(). If teardown needs to clean up a resource (timer, watcher, counter), the reference must live at module scope. State in the setup closure is unreachable from teardown and leaks on reload.
3. setup() is idempotent. It must zero/clear state before re-initializing. Calling setup() twice (e.g. across a hot-reload) leaves a clean slate, not accumulated state.
4. teardown() never deletes on-disk state. File-based plugins (todo-tracker) leave the file in place — the user may return. Only in-memory counters and resource handles (timers, watchers) are cleaned up.
5. Tool names follow snake_case. Plugin-level tools registered via api.tools.register() must be unique across the suite. The built-in tools (bash, write, read, edit, fetch, search, json, todo, git, etc.) are always present; don't collide.
6. apiVersion must satisfy ^0.1 (current kernel API = 0.1.10). Bump only when the PluginAPI surface breaks. Additive changes (new optional fields on PluginAPI) do NOT require a bump.
7. Config goes under config.extensions['<plugin-name>'], not config.plugins. The loader's buildPluginOptions merges both surfaces; plugins read from api.config.extensions.

The Plugin interface

import type { Plugin } from '@wrongstack/core';

const plugin: Plugin = {
  name: 'my-plugin',
  version: '0.1.0',
  description: 'One-line summary for wstack plugins list',
  apiVersion: '^0.1.10',
  capabilities: { tools: true }, // hints for /diag

  // Optional: JSON Schema for config validation
  defaultConfig: { enabled: true },
  configSchema: {
    type: 'object',
    properties: {
      enabled: { type: 'boolean', default: true },
    },
  },

  // Called by the host to activate the plugin.
  setup(api) { /* register tools, hooks, events */ },

  // Called by the host during unload. Same api instance as setup.
  teardown(api) { /* clear state, release resources, log */ },

  // Called by /diag plugins. Return ok + message + counters.
  async health() {
    return { ok: true, message: 'healthy', invocationCount: 0 };
  },
};

export default plugin;

H1 audit pattern

After the 2026-06-03 audit found that several plugins leaked resources on reload (timers, chokidar watchers, in-memory caches unreachable from teardown), the following lifecycle pattern was formalized. Every plugin in the suite follows it.

1. State at module scope

// ✅ Module scope — teardown can reach this
const state = {
  invocationCount: 0,
  timers: new Map<string, NodeJS.Timeout>(),
  lastRun: null as null | { when: string; result: string },
};

// ❌ NEVER — setup closure, unreachable from teardown
setup(api) {
  const timers = new Map();  // LEAKS on reload
}

2. Idempotent setup

setup(api) {
  // Clear everything first, then re-init from config.
  state.invocationCount = 0;
  for (const t of state.timers.values()) clearTimeout(t);
  state.timers.clear();
  state.lastRun = null;

  // Now register tools, apply config, subscribe to events.
  api.tools.register({ /* ... */ });
}

3. Teardown releases resources

teardown(api) {
  const count = state.invocationCount;
  state.invocationCount = 0;
  state.lastRun = null;
  // Release every resource that was acquired in setup().
  for (const t of state.timers.values()) clearTimeout(t);
  state.timers.clear();
  api.log.info('my-plugin: teardown complete', { invocations: count });
}

4. Health reports per-session visibility

async health() {
  return {
    ok: true,
    message: state.lastRun === null
      ? 'my-plugin: no calls yet'
      : `my-plugin: last call at ${state.lastRun.when}`,
    invocationCount: state.invocationCount,
    lastRun: state.lastRun,
  };
}

Tool registration

api.tools.register({
  name: 'my_tool',
  description: 'What this tool does. Include when to use and what it returns.',
  inputSchema: {
    type: 'object',
    properties: {
      path: { type: 'string', description: 'File path' },
    },
    required: ['path'],
  },
  permission: 'auto',     // 'auto' | 'confirm'
  mutating: false,         // does it change external state?
  category: 'Project',
  async execute(input: Record<string, unknown>) {
    const path = input['path'] as string;
    // ... do the work ...
    return { path, result: '...' };
  },
});

Signal failure by throwing. The executor marks a call failed only when execute() throws (throw a ToolValidationError for bad input). A returned { ok: false }, { status: 'error' }, or "Error: ..." string is recorded and shown as a SUCCESS. Return normally only for real data outcomes (zero results, a check that computed "no").

Permission levels

Config surface

Two surfaces exist. The loader merges them:

1. config.plugins — loading control: [{ name: 'my-plugin', enabled: false }]
2. config.extensions['my-plugin'] — options: { option1: value1 }

Plugins read from api.config.extensions:

setup(api) {
  const ext = api.config.extensions?.['my-plugin'] as Record<string, unknown> | undefined;
  const myOption = (ext?.['myOption'] as string) ?? 'default';
}

If the plugin declares configSchema, the loader validates the options section before calling setup and rejects the plugin with a clear error on failure.

Hook registration (PreToolUse, PostToolUse, etc.)

// secret-scanner pattern: block tools whose args contain secrets
api.registerHook('PreToolUse', 'bash|write|edit', (input) => {
  const text = JSON.stringify(input.toolInput ?? {});
  if (detectSecret(text)) {
    return {
      decision: 'block',
      reason: 'Plaintext credential detected in tool arguments',
    };
  }
  // Omitted decision = allow (no-op)
});

Available events: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop, plus the observational Notification, SubagentStart, SubagentStop, PreCompact, PostCompact and SessionEnd (their outcome is ignored — they cannot block or add context).

HookOutcome fields:

• decision: 'block' | 'allow' — block stops the action
• reason: string — surfaced to the model when blocking
• modifiedInput: Record<string, unknown> — PreToolUse replacement args
• additionalContext: string — extra context folded back to the model

PluginAPI extension (cross-package host data)

When a plugin needs host data not yet on PluginAPI (e.g. modelsRegistry, projectDir), extend the surface in three steps:

1. packages/core/src/types/plugin.ts — add the optional field to PluginAPI
2. packages/core/src/plugin/api.ts — add to PluginAPIInit + DefaultPluginAPI
3. packages/cli/src/wiring/plugins.ts — destructure + forward in setupPlugins

Precedent: commit 9bed619f added modelsRegistry?: ModelsRegistry for cost-tracker's pricing hydration.

Entry-point registration

After writing src/<name>/index.ts, wire it into two package files. The central scripts/build-package.mjs driver discovers plugin entry points from the exports map automatically.

1. src/index.ts — named re-export

export { default as myPluginPlugin } from './my-plugin/index.js';

2. package.json — subpath export

"./my-plugin": {
  "types": "./dist/my-plugin.d.ts",
  "import": "./dist/my-plugin.js"
}

3. packages/cli/src/wiring/plugins.ts — built-in factory

async () => (await import('@wrongstack/plugins/my-plugin')).default,

Tests

Every plugin gets two test files:

• tests/<name>.test.ts — unit tests (mock API, tool registration, config validation, teardown log line, health() shape)
• tests/<name>-exec.test.ts — integration tests (real filesystem, real CLI tools if applicable)

For the H1 pattern, extend tests/plugin-teardown.test.ts with a describe('<name>') block covering:

• teardown logs a completion line and does not throw
• health() reports ok + non-empty message
• teardown zeros counters