probe-runner

1import type { EngineInterface, Register } from 'claude-code'
2import { INPUT_SCHEMA, parseArgs, pluginDir, probeOf, scriptArgv, TOOL_DESCRIPTION, TOOL_NAME, type Probe } from './probe.ts'
3
4/** A probe ends at ten minutes, the most `$.process.run` waits. */
5const PROBE_MS = 600_000
6
7/** The plugin directories, each checked for its manifest; a string names the first one missing. */
8async function pluginDirs($: EngineInterface, probe: Probe): Promise<string[] | string> {
9  const cwd = await $.session.cwd()
10  const root = (await $.session.repo())?.root ?? cwd
11  const home = (await $.env.get('HOME')) ?? ''
12  const dirs = probe.plugins.map(p => pluginDir(p, root, cwd, home))
13  for (const dir of dirs) {
14    if (!(await $.fs.exists(`${dir}/.claude-plugin/plugin.json`))) return `no plugin at ${dir}: it has no .claude-plugin/plugin.json`
15  }
16  return dirs
17}
18
19/** Runs one probe and answers its report, or why it did not run. */
20async function runProbe($: EngineInterface, probe: Probe): Promise<string> {
21  const dirs = await pluginDirs($, probe)
22  if (typeof dirs === 'string') return dirs
23  const r = await $.process.run(scriptArgv(`${$.plugin.root}/scripts/probe.py`, probe, dirs), { timeoutMs: PROBE_MS })
24  return r.exitCode === 0 ? r.stdout : `the probe failed (exit ${r.exitCode}): ${r.stderr.trim() || r.stdout.trim()}`
25}
26
27/** The person's probe runs in the background; its report reaches the model as a prompt of its own. */
28function runInBackground($: EngineInterface, probe: Probe): void {
29  $.clock.after(0, async () => {
30    const report = await runProbe($, probe)
31    try {
32      await $.command.run({ command: 'probe-runner:send', args: report })
33    } catch (err) {
34      $.ui.log(`the report could not be sent (${err instanceof Error ? err.message : String(err)}), so it went as a plugin prompt`)
35      await $.prompt.submit({ text: report })
36    }
37  })
38}
39
40export const register: Register = on => {
41  on('session.start', async ($, e, next) => {
42    const r = await next(e)
43    await $.command.register({ name: 'probe-runner', description: 'Live check of plugins in a fresh tmux session: --model, plugins, steps joined by ;; (probe-runner)', argumentHint: '[--model <m>] <plugin,...> <step> ;; <step>' })
44    // Declared once at the start, so the tool list the prompt cache holds does not change mid-session.
45    await $.tool.register({ name: TOOL_NAME, description: TOOL_DESCRIPTION, inputSchema: INPUT_SCHEMA })
46    return r
47  })
48
49  // A plugin's tool waits behind ToolSearch by default; this one is listed, so the model can call it at once.
50  on('tool.describe', { tool: /^mcp__probe-runner__probe$/ }, async (_, e, next) => ({ ...(await next(e)), isDeferred: false }))
51
52  on('tool.call', { tool: /^mcp__probe-runner__probe$/ }, async ($, e) => {
53    const probe = probeOf(e as Record<string, unknown>)
54    if (typeof probe === 'string') return { deny: probe }
55    return { result: await runProbe($, probe) }
56  })
57
58  // The engine prints the plugin name in front of command text, so the texts do not repeat it.
59  on('command.run', { command: 'probe-runner' }, async ($, e) => {
60    const probe = parseArgs(String(e.args ?? ''))
61    if (typeof probe === 'string') return { text: probe }
62    runInBackground($, probe)
63    return { text: `started: ${probe.steps.length} step(s) with ${probe.plugins.join(', ')} on ${probe.model}; the report follows when it ends` }
64  })
65}
66

1/** What a probe is asked to run, read from the command's words or the tool's input, and the texts the mod writes. */
2
3export const DEFAULT_MODEL = 'sonnet'
4
5/** A probe run: the plugins to load (names or paths), the steps in order, and the model. */
6export type Probe = { plugins: string[]; steps: string[]; model: string }
7
8export const USAGE = 'expects [--model <model>] <plugin>[,<plugin>...] <step> [;; <step> ...], a plugin by its name under plugins/ or by its path'
9
10/** Splits the command's words: `--model m` first when given, the plugin list, then the steps joined by `;;`. */
11export function parseArgs(args: string): Probe | string {
12  const words = args.trim().split(/\s+/)
13  let model = DEFAULT_MODEL
14  if (words[0] === '--model') {
15    model = words[1] ?? ''
16    words.splice(0, 2)
17  }
18  const [list = '', ...rest] = words
19  const steps = rest.join(' ').split(';;').map(s => s.trim()).filter(s => s !== '')
20  const plugins = list.split(',').filter(p => p !== '')
21  if (model === '' || plugins.length === 0 || steps.length === 0) return USAGE
22  return { plugins, steps, model }
23}
24
25/** The tool's input, checked; a string names what is wrong. */
26export function probeOf(input: Record<string, unknown>): Probe | string {
27  const strings = (v: unknown): string[] => (Array.isArray(v) ? v.filter((s): s is string => typeof s === 'string' && s.trim() !== '') : [])
28  const plugins = strings(input.plugins)
29  const steps = strings(input.steps)
30  if (plugins.length === 0) return 'plugins is required: at least one plugin name or path'
31  if (steps.length === 0) return 'steps is required: at least one prompt or slash command'
32  return { plugins, steps, model: typeof input.model === 'string' && input.model !== '' ? input.model : DEFAULT_MODEL }
33}
34
35/** Where a plugin named by `name` lives: a path as given (relative to `cwd`), or `<root>/plugins/<name>`. */
36export function pluginDir(name: string, root: string, cwd: string, home: string): string {
37  if (name.startsWith('~/')) return `${home}/${name.slice(2)}`
38  if (name.startsWith('/')) return name
39  return name.includes('/') ? `${cwd}/${name}` : `${root}/plugins/${name}`
40}
41
42/** The script's argument vector. */
43export function scriptArgv(script: string, probe: Probe, dirs: readonly string[]): string[] {
44  return ['python3', script, '--model', probe.model, ...dirs.flatMap(d => ['--plugin-dir', d]), ...probe.steps.flatMap(s => ['--step', s])]
45}
46
47export const TOOL_NAME = 'probe'
48
49export const TOOL_DESCRIPTION = [
50  'Run a live check of Claude Code plugins in a fresh session: a new git repository under /private/tmp (the system temp directory where that does not exist), tmux, only the given plugin directories loaded, and the steps typed into the prompt one after another, each once the one before has finished.',
51  'You get the pane\'s final text, the session\'s transcript (prompts, replies, tool calls, command output, the context hooks added) and the list of what was deleted afterwards: the temp directory, its transcripts and the inline store files the probe wrote.',
52  'A probe takes about 15 seconds to start and then as long as its steps; it stops at 10 minutes.',
53].join(' ')
54
55export const INPUT_SCHEMA = {
56  type: 'object',
57  properties: {
58    plugins: { type: 'array', items: { type: 'string' }, description: 'Plugins to load: a name under the repository\'s plugins/ directory, or a path.' },
59    steps: { type: 'array', items: { type: 'string' }, description: 'The prompts and slash commands to type, in order. Each is one line.' },
60    model: { type: 'string', description: `The probe session's model, ${DEFAULT_MODEL} by default.` },
61  },
62  required: ['plugins', 'steps'],
63}
64