@aion0/forge 0.9.12 → 0.9.14

package/lib/chat/tool-dispatcher.ts

@@ -37,6 +37,183 @@ export type BuiltinHandler = (input: unknown) => Promise<string>;
 
 const BUILTINS: Record<string, BuiltinHandler> = {
   get_current_time: async () => new Date().toISOString(),
+
+  // Trigger a pipeline workflow defined under flows/<name>.yaml. Mirrors
+  // the same MCP tool used by Claude Code tasks (forge-mcp-server.ts), but
+  // available directly inside the chat agent so users can say "run the
+  // mantis-bug-fix pipeline for bug 1234" and have the agent dispatch it.
+  //
+  // Call without args first to see workflows + their input schemas — saves
+  // a round-trip of guessing field names. Schema includes which fields are
+  // required (no default) vs optional (have default) so the agent can omit
+  // optional ones rather than passing wrong placeholder values.
+  trigger_pipeline: async (input) => {
+    const params = (input as { workflow?: string; input?: Record<string, unknown> } | undefined) || {};
+    const { listWorkflows, startPipeline, getPipeline } = await import('../pipeline');
+    if (!params.workflow) {
+      const workflows = listWorkflows();
+      if (workflows.length === 0) return 'No workflows found. Create one in <dataDir>/flows/.';
+      const lines: string[] = ['Available workflows (only pass the marked-required inputs; optional ones use their default):', ''];
+      for (const w of workflows) {
+        lines.push(`• ${w.name}${w.description ? ' — ' + w.description.split('\n')[0].slice(0, 160) : ''}`);
+        const entries = Object.entries(w.input || {});
+        if (entries.length === 0) {
+          lines.push('  Inputs: (none)');
+        } else {
+          for (const [name, spec] of entries) {
+            // spec may be a string (legacy description-only) or an object.
+            const isObj = spec && typeof spec === 'object';
+            const desc = isObj ? (spec as any).description : (typeof spec === 'string' ? spec : '');
+            const type = isObj ? ((spec as any).type || 'string') : 'string';
+            const required = isObj ? !!(spec as any).required : false;
+            const hasDefault = isObj && Object.prototype.hasOwnProperty.call(spec, 'default');
+            const def = hasDefault ? (spec as any).default : undefined;
+            const star = required ? '*' : '';
+            const defNote = hasDefault
+              ? ` [default: ${String(def).split('\n')[0].slice(0, 60)}${String(def).length > 60 ? '…' : ''}]`
+              : '';
+            const descShort = desc ? ` — ${String(desc).split('\n')[0].slice(0, 120)}` : '';
+            lines.push(`    - ${name}${star} (${type})${defNote}${descShort}`);
+          }
+        }
+        lines.push('');
+      }
+      lines.push('Required inputs are marked with *. Optional ones with defaults will use the default if you omit them — DO NOT pass empty strings or guesses for those.');
+      return lines.join('\n');
+    }
+    // Pre-flight schema validation. The pipeline orchestrator currently
+    // silently accepts unknown input keys and lets required fields default to
+    // empty — leading to "status: done" no-op runs. Surface those mistakes
+    // here so the LLM (or any caller) gets a structured error instead of a
+    // misleading success. Workflow-side validation (B in the plan) is deferred
+    // because it'd affect schedules.
+    const workflows = listWorkflows();
+    const wf = workflows.find((w: any) => w.name === params.workflow);
+    if (!wf) {
+      return `Unknown workflow: "${params.workflow}". Available: ${workflows.map((w: any) => w.name).join(', ') || '(none)'}. Call trigger_pipeline() with no args to see schemas.`;
+    }
+    const declared = wf.input || {};
+    const declaredKeys = new Set(Object.keys(declared));
+    const requiredKeys: string[] = [];
+    for (const [k, spec] of Object.entries(declared)) {
+      if (spec && typeof spec === 'object') {
+        const s = spec as any;
+        const hasDefault = Object.prototype.hasOwnProperty.call(s, 'default');
+        if (s.required && !hasDefault) requiredKeys.push(k);
+      }
+    }
+    const givenKeys = Object.keys(params.input || {});
+    const unknown = givenKeys.filter((k) => !declaredKeys.has(k));
+    if (unknown.length > 0) {
+      return `Unknown input fields for "${params.workflow}": ${unknown.join(', ')}. This workflow only accepts: ${[...declaredKeys].join(', ')}. NOTE: input field names are snake_case (e.g. bug_id) — they are NOT the same as the bash variable names inside pipeline scripts (e.g. BUG_ID). Consider memory_remember_block({key: "rule.pipeline_input_naming", value: "Forge pipeline input fields are exact, snake_case, declared in the workflow yaml. Never invent uppercase / bash-variable names like BUG_ID, BASE, PROJECT_PATH.", pinned: true}) to save this lesson.`;
+    }
+    const missing = requiredKeys.filter((k) => {
+      const v = (params.input || {})[k];
+      return v == null || (typeof v === 'string' && v.trim() === '');
+    });
+    if (missing.length > 0) {
+      return `Missing required input fields for "${params.workflow}": ${missing.join(', ')}. All required fields (no defaults): ${requiredKeys.join(', ') || '(none)'}. Re-call with these provided.`;
+    }
+
+    // Coerce numbers/booleans to strings (pipeline orchestrator expects Record<string, string>).
+    const stringInput: Record<string, string> = {};
+    for (const [k, v] of Object.entries(params.input || {})) {
+      stringInput[k] = v == null ? '' : typeof v === 'string' ? v : String(v);
+    }
+    const pipeline = startPipeline(params.workflow, stringInput);
+    let line = `Pipeline started: ${pipeline.id} (workflow: ${params.workflow}, status: ${pipeline.status})`;
+    if (pipeline.status === 'failed') {
+      const fresh = getPipeline(pipeline.id) || pipeline;
+      const errs: string[] = [];
+      for (const [nid, n] of Object.entries(fresh.nodes || {})) {
+        if ((n as any).error) errs.push(`${nid}: ${(n as any).error}`);
+      }
+      if (errs.length > 0) line += `\nFailure(s): ${errs.join(' | ').slice(0, 500)}`;
+    } else if (pipeline.status === 'done') {
+      // For for_each workflows, a "done" with zero iterations is the silent
+      // failure mode (empty source). Warn the LLM explicitly so it doesn't
+      // claim success.
+      const fresh = getPipeline(pipeline.id) || pipeline;
+      const forEach = (fresh as any).forEach;
+      if (forEach && typeof forEach === 'object') {
+        const iters = Array.isArray(forEach.iterations) ? forEach.iterations.length : 0;
+        const total = typeof forEach.total === 'number' ? forEach.total : iters;
+        if (total === 0) {
+          line += '\n⚠ Pipeline finished with 0 iterations — likely empty source list. This is NOT a success; the work the user asked for did NOT happen. Re-check input fields (especially the one feeding for_each.source) and retry.';
+        }
+      }
+    } else {
+      line += '. Watch progress in the Pipelines view.';
+    }
+    return line;
+  },
+
+  // Surface Forge's local context (projects + agents + skills) so the chat
+  // agent can pick valid values for inputs like trigger_pipeline.input.project
+  // without guessing. Cheap call — read-only directory + DB lookups.
+  list_forge_context: async () => {
+    const out: string[] = [];
+    try {
+      const { scanProjects } = await import('../projects');
+      const projects = scanProjects();
+      out.push('Forge projects (use the name as input.project for tasks / pipelines):');
+      if (projects.length === 0) out.push('  (none — configure project roots in Settings)');
+      for (const p of projects) {
+        out.push(`  - ${p.name}${p.hasClaudeMd ? ' [has CLAUDE.md]' : ''}${p.language ? ' [' + p.language + ']' : ''}`);
+      }
+    } catch (e) {
+      out.push(`(failed to list projects: ${(e as Error).message})`);
+    }
+    out.push('');
+    try {
+      const { loadSettings } = await import('../settings');
+      const settings = loadSettings();
+      const agents = settings.agents || {};
+      out.push('Agent profiles (CLI agents; use the id as dispatch_task.agent):');
+      const ids = Object.keys(agents);
+      if (ids.length === 0) out.push('  (none configured)');
+      for (const id of ids) {
+        const a = agents[id] as any;
+        out.push(`  - ${id}${a?.name ? ' (' + a.name + ')' : ''}`);
+      }
+    } catch (e) {
+      out.push(`(failed to list agents: ${(e as Error).message})`);
+    }
+    out.push('');
+    try {
+      const { listSkills } = await import('../skills');
+      const skills = listSkills();
+      out.push('Skills (available to dispatch_task / pipeline via auto-install):');
+      if (skills.length === 0) out.push('  (none)');
+      for (const s of skills) {
+        out.push(`  - ${s.name}${s.description ? ' — ' + s.description.slice(0, 80) : ''}`);
+      }
+    } catch (e) {
+      out.push(`(failed to list skills: ${(e as Error).message})`);
+    }
+    return out.join('\n');
+  },
+
+  // Dispatch a one-shot background task. Agent + skills optional; project is
+  // required (defaults to 'scratch' if not given). Returns the task id; the
+  // caller can ask "what's the status of task <id>?" later — we don't block.
+  dispatch_task: async (input) => {
+    const params = (input as { project?: string; prompt?: string; agent?: string } | undefined) || {};
+    if (!params.prompt) return 'dispatch_task failed: prompt is required';
+    const { getProjectInfo, SCRATCH_PROJECT_NAME } = await import('../projects');
+    const projectName = params.project?.trim() || SCRATCH_PROJECT_NAME;
+    const project = getProjectInfo(projectName);
+    if (!project) return `dispatch_task failed: project "${projectName}" not found`;
+    const { createTask } = await import('../task-manager');
+    const task = createTask({
+      projectName: project.name,
+      projectPath: project.path,
+      prompt: params.prompt,
+      conversationId: '',
+      agent: params.agent || undefined,
+    });
+    return `Task dispatched: ${task.id} (project: ${project.name}, status: ${task.status}). Watch in the Tasks view.`;
+  },
 };
 
 export interface BuiltinToolDef {
@@ -51,6 +228,50 @@ export const BUILTIN_TOOL_DEFS: BuiltinToolDef[] = [
     description: 'Get the current local time as an ISO 8601 string. Use whenever the user asks about "now" or "today".',
     input_schema: { type: 'object', properties: {} },
   },
+  {
+    name: 'trigger_pipeline',
+    description: 'Trigger a Forge pipeline workflow (YAML under flows/). Two-step usage: (1) call with NO args first — returns every workflow + its input schema (which fields are required vs have defaults). (2) call again with workflow=<name> and input={...} passing ONLY required fields and any optional fields the user explicitly specified. NEVER pass invented placeholder values for optional fields with defaults — omit them and the default is used. If the pipeline fails immediately, the response includes the validation error so you can fix the inputs and retry.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        workflow: {
+          type: 'string',
+          description: 'Workflow name (file basename of flows/<name>.yaml). Omit to list workflows + schemas.',
+        },
+        input: {
+          type: 'object',
+          description: 'Pipeline input fields as a flat object. Pass ONLY required fields (marked * in the list response) and optional fields the user explicitly named. Omit optional fields to use their defaults.',
+        },
+      },
+    },
+  },
+  {
+    name: 'list_forge_context',
+    description: "Return the current Forge instance's local context: project names (use these as input.project for pipelines / dispatch_task), agent profile ids, and installed skills. Call this whenever the user references a project / agent / skill by name and you need to validate the name OR when picking defaults for trigger_pipeline / dispatch_task. No arguments.",
+    input_schema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'dispatch_task',
+    description: 'Dispatch a one-shot background Claude task in a Forge project. Use for longer-running asks the user wants to fire-and-forget ("analyze X codebase and write findings to a file", "run the test suite and summarize failures"). Returns immediately with the task id; the task runs in the background and the user can check the Tasks view for output.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        prompt: {
+          type: 'string',
+          description: 'The full instruction text Claude should execute. Be specific about what files to read, what to produce.',
+        },
+        project: {
+          type: 'string',
+          description: 'Forge project name (the working directory). Defaults to "scratch" if omitted. Use "scratch" for connector-only / no-filesystem tasks.',
+        },
+        agent: {
+          type: 'string',
+          description: 'Optional agent id override. Omit to use the project default.',
+        },
+      },
+      required: ['prompt'],
+    },
+  },
 ];
 
 // ─── Connector dispatch ──────────────────────────────────

package/lib/forge-mcp-server.ts

@@ -394,6 +394,90 @@ function createForgeMcpServer(sessionId: string): McpServer {
     }
   );
 
+  // ── list_connectors ────────────────────────────
+  // V3 ai-orchestration MVP — let an agent discover what installed
+  // connectors + tools it can call. Pairs with call_connector below.
+  server.tool(
+    'list_connectors',
+    'List installed Forge connectors and their callable tools. Use this BEFORE call_connector to discover what tool ids exist and what parameters each expects. Returns id, tool name, description, parameter schema, destructive flag, and (when present) author-provided returns hint.',
+    {},
+    async () => {
+      try {
+        const { listInstalledConnectors } = await import('./connectors/registry');
+        const connectors = listInstalledConnectors().filter((c) => c.enabled);
+        if (connectors.length === 0) {
+          return {
+            content: [{ type: 'text', text: 'No connectors installed. Install one from Settings → Marketplace.' }],
+          };
+        }
+        type ToolSpec = { description?: string; parameters?: Record<string, unknown>; destructive?: boolean; returns?: string; protocol?: string };
+        const out: Array<{
+          plugin_id: string;
+          name: string;
+          version: string;
+          tools: Array<{ name: string; description: string; parameters?: Record<string, unknown>; destructive?: boolean; returns?: string; protocol?: string }>;
+        }> = [];
+        for (const c of connectors) {
+          const def = c.definition as { id: string; name: string; version: string; tools?: Record<string, ToolSpec>; connectors?: Array<{ id: string; tools: Record<string, ToolSpec> }> };
+          // Flatten: single-entry connectors expose tools at top level, suite
+          // connectors (Atlassian-style) under .connectors[].tools.
+          const sources: Array<[string, Record<string, ToolSpec>]> = [];
+          if (def.tools) sources.push([def.id, def.tools]);
+          for (const entry of def.connectors || []) sources.push([entry.id, entry.tools]);
+          for (const [pluginId, tools] of sources) {
+            out.push({
+              plugin_id: pluginId,
+              name: def.name,
+              version: def.version,
+              tools: Object.entries(tools).map(([toolName, t]) => ({
+                name: toolName,
+                description: t.description || '(no description)',
+                ...(t.parameters ? { parameters: t.parameters } : {}),
+                ...(t.destructive ? { destructive: true } : {}),
+                ...(t.returns ? { returns: t.returns } : {}),
+                ...(t.protocol ? { protocol: t.protocol } : {}),
+              })),
+            });
+          }
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `Error listing connectors: ${err.message}` }] };
+      }
+    },
+  );
+
+  // ── call_connector ─────────────────────────────
+  // Invoke one connector tool. Same backend as POST /api/connector-tool
+  // (single internal entry point — anything pipelines / jobs / chat already
+  // call is what an ai-orchestration-skilled agent gets too).
+  server.tool(
+    'call_connector',
+    'Call one installed connector tool. Use list_connectors first to find plugin_id + tool_name. Returns the tool result text; sets is_error=true on failure. Destructive tools (add_comment, send_message, etc.) require explicit user confirmation in the surrounding workflow — the call itself is not blocked here.',
+    {
+      plugin_id: z.string().describe("Connector id from list_connectors (e.g. 'mantis', 'gitlab', 'teams')."),
+      tool: z.string().describe("Tool name within the connector (e.g. 'get_bug', 'search_mrs', 'send_message')."),
+      input: z.record(z.string(), z.any()).optional().describe('Parameter object matching the tool schema returned by list_connectors. Omit for parameter-less tools.'),
+    },
+    async (params) => {
+      try {
+        const { dispatchTool } = await import('./chat/tool-dispatcher');
+        const name = `${params.plugin_id}.${params.tool}`;
+        const result = await dispatchTool({
+          id: `mcp-${Date.now()}`,
+          name,
+          input: params.input ?? {},
+        });
+        return {
+          content: [{ type: 'text', text: result.content }],
+          ...(result.is_error ? { isError: true } : {}),
+        };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `Error calling ${params.plugin_id}.${params.tool}: ${err.message}` }], isError: true };
+      }
+    },
+  );
+
   // ── get_pipeline_status ────────────────────────
   server.tool(
     'get_pipeline_status',

package/lib/init.ts

@@ -86,6 +86,13 @@ export function ensureInitialized() {
 
   time('logger', () => { try { const { initLogger } = require('./logger'); initLogger(); } catch {} });
   time('migrateDataDir', () => { try { const { migrateDataDir } = require('./dirs'); migrateDataDir(); } catch {} });
+  time('ensureScratchProject', () => {
+    // Synthetic 'scratch' project under <dataDir>/scratch — default
+    // workspace for prompt schedules / chat-launched temp tasks that
+    // don't care about a real project.
+    try { const { ensureScratchProject } = require('./projects'); ensureScratchProject(); }
+    catch (e) { console.warn('[init] ensureScratchProject failed:', (e as Error).message); }
+  });
   time('migrateSecrets', migrateSecrets);
   time('migratePluginSecrets', () => {
     try {

package/lib/pipeline.ts

@@ -871,6 +871,25 @@ export function startPipeline(
   const workflow = getWorkflow(workflowName);
   if (!workflow) throw new Error(`Workflow not found: ${workflowName}`);
 
+  // Apply declared defaults for any field the caller didn't pass. UI callers
+  // (Schedule form, Fire dialog) already pre-fill all fields with their
+  // defaults at form-load time, so for them this merge is a no-op. Sparse-input
+  // callers (chat trigger_pipeline, MCP, direct API) only send what the user
+  // explicitly named; without this merge multi-line defaults like
+  // mr_body_template / user_prompt come through as empty → "{{input.X}}"
+  // renders to '' → MR body empty / triage prompt empty.
+  //
+  // Semantics: ONLY fill when the key is missing from the input map. An
+  // empty-string value is respected as "intentionally cleared" so schedule
+  // users who clear a field in the form keep that behaviour.
+  for (const [key, spec] of Object.entries(workflow.input || {})) {
+    if (Object.prototype.hasOwnProperty.call(input, key)) continue;
+    if (!spec || typeof spec !== 'object') continue;
+    const def = (spec as WorkflowInputFieldSpec).default;
+    if (def == null) continue;
+    input = { ...input, [key]: String(def) };
+  }
+
   // Conversation mode — separate execution path
   if (workflow.type === 'conversation' && workflow.conversation) {
     return startConversationPipeline(workflow, input);

package/lib/projects.ts

@@ -1,6 +1,7 @@
-import { readdirSync, existsSync, statSync, readFileSync } from 'node:fs';
+import { readdirSync, existsSync, statSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadSettings } from './settings';
+import { getDataDir } from './dirs';
 
 export interface LocalProject {
   name: string;
@@ -12,6 +13,67 @@ export interface LocalProject {
   lastModified: string;
 }
 
+/** Reserved name for the synthetic "scratch" project that lives under
+ *  <dataDir>/scratch. Default workspace for tasks that don't need a real
+ *  project (prompt schedules calling connectors / chat-launched temp tasks
+ *  / anything that just talks to APIs and doesn't touch files). */
+export const SCRATCH_PROJECT_NAME = 'scratch';
+
+/** Materialize <dataDir>/scratch on first call. Idempotent. Returns the
+ *  project path. Called from init.ts on startup so the dir exists before
+ *  any task tries to cd into it. */
+export function ensureScratchProject(): string {
+  const dir = join(getDataDir(), 'scratch');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const claudeMd = join(dir, 'CLAUDE.md');
+  if (!existsSync(claudeMd)) {
+    try {
+      writeFileSync(claudeMd,
+        '# Forge Scratch\n\n' +
+        'Default workspace for tasks that do not target a specific project.\n' +
+        'Files here are managed by Forge (per-instance, follows the data dir).\n' +
+        'Safe to wipe by hand if it accumulates clutter.\n',
+        'utf-8',
+      );
+    } catch { /* best-effort */ }
+  }
+  // Scratch is Forge-owned (no user hand-rolled .mcp.json to defy), so
+  // unlike real projects we materialize the root .mcp.json directly here.
+  // Without it, prompt-mode schedule tasks running in scratch can't see
+  // the Forge MCP server (claude CLI only auto-discovers root .mcp.json,
+  // not .forge/mcp.json). Always rewrite to keep mcpPort + user-managed
+  // entries in sync.
+  try {
+    const mcpPort = Number(process.env.MCP_PORT) || 8406;
+    let userServers: Record<string, unknown> = {};
+    try { userServers = loadSettings().mcpServers || {}; } catch {}
+    const cfg = {
+      mcpServers: {
+        forge: { type: 'sse', url: `http://localhost:${mcpPort}/sse` },
+        ...userServers,
+      },
+    };
+    writeFileSync(join(dir, '.mcp.json'), JSON.stringify(cfg, null, 2), 'utf-8');
+  } catch { /* best-effort */ }
+  return dir;
+}
+
+function scratchProject(): LocalProject {
+  const path = ensureScratchProject();
+  let mtime: string;
+  try { mtime = statSync(path).mtime.toISOString(); }
+  catch { mtime = new Date().toISOString(); }
+  return {
+    name: SCRATCH_PROJECT_NAME,
+    path,
+    root: getDataDir(),
+    hasGit: false,
+    hasClaudeMd: existsSync(join(path, 'CLAUDE.md')),
+    language: null,
+    lastModified: mtime,
+  };
+}
+
 export function scanProjects(): LocalProject[] {
   const settings = loadSettings();
   const roots = settings.projectRoots;
@@ -52,7 +114,10 @@ export function scanProjects(): LocalProject[] {
     }
   }
 
-  return projects.sort((a, b) => b.lastModified.localeCompare(a.lastModified));
+  // Prepend the synthetic scratch project so the UI surfaces it as a
+  // first-class option. It's stamped with the current date so it tends
+  // to sort to the top — that's intentional: it's the default fallback.
+  return [scratchProject(), ...projects.sort((a, b) => b.lastModified.localeCompare(a.lastModified))];
 }
 
 function detectLanguage(projectPath: string): string | null {

package/lib/prompts/store.ts

@@ -0,0 +1,142 @@
+/**
+ * Prompts file store — `<dataDir>/prompts/<name>.yaml`.
+ *
+ * Same external-file pattern as pipelines: name in DB / schedule row,
+ * configuration in YAML on disk. Edits don't require migrations.
+ */
+
+import { existsSync, readFileSync, readdirSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import YAML from 'yaml';
+import { getDataDir } from '@/lib/dirs';
+import type { Prompt, CreatePromptInput, UpdatePromptInput } from './types';
+
+function dir(): string {
+  return join(getDataDir(), 'prompts');
+}
+
+// Same constraint as pipeline names — also serves as filename `<name>.yaml`.
+const NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+
+function pathFor(name: string): string {
+  return join(dir(), `${name}.yaml`);
+}
+
+function parsePrompt(yaml: string): Prompt {
+  const raw = YAML.parse(yaml);
+  if (!raw || typeof raw !== 'object') throw new Error('prompt yaml must be a mapping');
+  if (typeof raw.name !== 'string' || !raw.name) throw new Error('prompt.name required');
+  if (typeof raw.prompt !== 'string') throw new Error('prompt.prompt required (string)');
+
+  const ex = raw.executor || {};
+  const skills = Array.isArray(ex.skills)
+    ? ex.skills.filter((s: unknown) => typeof s === 'string')
+    : [];
+  const now = new Date().toISOString();
+  return {
+    name: raw.name,
+    prompt: raw.prompt,
+    executor: {
+      agent: typeof ex.agent === 'string' && ex.agent ? ex.agent : null,
+      skills,
+      config: ex.config && typeof ex.config === 'object' ? ex.config : undefined,
+    },
+    created_at: typeof raw.created_at === 'string' ? raw.created_at : now,
+    updated_at: typeof raw.updated_at === 'string' ? raw.updated_at : now,
+  };
+}
+
+function serialize(p: Prompt): string {
+  const executorOut: Record<string, unknown> = {
+    agent: p.executor.agent,
+    skills: p.executor.skills,
+  };
+  if (p.executor.config) executorOut.config = p.executor.config;
+  return YAML.stringify({
+    name: p.name,
+    prompt: p.prompt,
+    executor: executorOut,
+    created_at: p.created_at,
+    updated_at: p.updated_at,
+  });
+}
+
+export function listPrompts(): Prompt[] {
+  const d = dir();
+  if (!existsSync(d)) return [];
+  const out: Prompt[] = [];
+  for (const f of readdirSync(d).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))) {
+    try {
+      out.push(parsePrompt(readFileSync(join(d, f), 'utf-8')));
+    } catch (e) {
+      console.warn(`[listPrompts] skip ${f}: ${(e as Error).message}`);
+    }
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function getPrompt(name: string): Prompt | null {
+  if (!NAME_RE.test(name)) return null;
+  const path = pathFor(name);
+  if (!existsSync(path)) return null;
+  try {
+    return parsePrompt(readFileSync(path, 'utf-8'));
+  } catch (e) {
+    console.warn(`[getPrompt] parse ${name}: ${(e as Error).message}`);
+    return null;
+  }
+}
+
+export function createPrompt(input: CreatePromptInput): Prompt {
+  if (!NAME_RE.test(input.name)) {
+    throw new Error(`invalid name (allowed: letters/digits/._-, 1-64 chars): '${input.name}'`);
+  }
+  if (!input.prompt || !input.prompt.trim()) {
+    throw new Error('prompt text required');
+  }
+  mkdirSync(dir(), { recursive: true });
+  if (existsSync(pathFor(input.name))) {
+    throw new Error(`prompt '${input.name}' already exists`);
+  }
+  const now = new Date().toISOString();
+  const p: Prompt = {
+    name: input.name,
+    prompt: input.prompt,
+    executor: {
+      agent: input.executor?.agent ?? null,
+      skills: input.executor?.skills ?? [],
+      config: input.executor?.config,
+    },
+    created_at: now,
+    updated_at: now,
+  };
+  writeFileSync(pathFor(input.name), serialize(p), 'utf-8');
+  return p;
+}
+
+export function updatePrompt(name: string, patch: UpdatePromptInput): Prompt {
+  const cur = getPrompt(name);
+  if (!cur) throw new Error(`prompt '${name}' not found`);
+  const next: Prompt = {
+    ...cur,
+    prompt: patch.prompt ?? cur.prompt,
+    executor: patch.executor
+      ? {
+          agent: patch.executor.agent ?? cur.executor.agent,
+          skills: patch.executor.skills ?? cur.executor.skills,
+          config: patch.executor.config ?? cur.executor.config,
+        }
+      : cur.executor,
+    updated_at: new Date().toISOString(),
+  };
+  writeFileSync(pathFor(name), serialize(next), 'utf-8');
+  return next;
+}
+
+export function deletePrompt(name: string): boolean {
+  if (!NAME_RE.test(name)) return false;
+  const path = pathFor(name);
+  if (!existsSync(path)) return false;
+  unlinkSync(path);
+  return true;
+}

package/lib/prompts/types.ts

@@ -0,0 +1,53 @@
+/**
+ * Forge Prompts — types (V3 B1)
+ *
+ * A Prompt is a stored body for `body_kind='prompt'` schedules. The schedule
+ * references it by name; the actual configuration (text + executor) lives
+ * in `<dataDir>/prompts/<name>.yaml`. Same external-file pattern Pipeline
+ * uses, so prompt fields can evolve without DB migrations.
+ *
+ * Wired into scheduler dispatch in B2 (#263).
+ */
+
+export interface PromptExecutorRetry {
+  /** 0 = don't retry (default). Failed prompt tasks just wait for the next tick. */
+  max: number;
+  backoff?: 'linear' | 'exponential';
+  /** Seconds before first retry. */
+  initial_delay?: number;
+}
+
+export interface PromptExecutorConfig {
+  /** Task timeout in seconds. Falls through to system default if unset. */
+  timeout?: number;
+  retry?: PromptExecutorRetry;
+}
+
+export interface PromptExecutor {
+  /** Agent id from Settings. null = use system default. */
+  agent: string | null;
+  /** Skills attached to the dispatched task; typically includes
+   *  `ai-orchestration` so the agent can discover + call connectors. */
+  skills: string[];
+  config?: PromptExecutorConfig;
+}
+
+export interface Prompt {
+  name: string;
+  /** User-authored prompt text. MUST be preserved verbatim — no LLM rewrites. */
+  prompt: string;
+  executor: PromptExecutor;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreatePromptInput {
+  name: string;
+  prompt: string;
+  executor?: Partial<PromptExecutor>;
+}
+
+export interface UpdatePromptInput {
+  prompt?: string;
+  executor?: Partial<PromptExecutor>;
+}