amsd-pipeline-workflow 0.1.26 → 0.1.27

package/driver/hook-dispatch.js

@@ -2,7 +2,7 @@
 'use strict';
 // THE AGENTS' HOOKS, IN A LIVE SESSION (2026-10-18): the real Workflow tool does not run a hook declared in a workflow
 // agent's frontmatter (tools/hook-probe.js: never fired), but does run one declared in the session's project settings, and
-// its input names the calling agent (agent_type). driver/runtime.js liveCommand installs this one PreToolUse hook there; it
+// its input names the calling agent (agent_type). driver/runtime.js liveCommand writes this one PreToolUse hook into the session's settings file; it
 // runs the calling agent's own hook command — exactly as its definition declares it — with the same input, and passes its
 // output and exit code back unchanged. An agent with no hook for this tool passes through (no output, exit 0).
 //   node driver/hook-dispatch.js <map.json>      map: { "<agent_type>": [{ matcher, command }...] }
@@ -15,7 +15,11 @@ process.stdin.on('end', () => {
   let ev = {};
   try { ev = JSON.parse(input); } catch { process.exit(0); }
   const map = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
-  const hooks = (map[ev.agent_type] || []).filter((h) => !h.matcher || new RegExp(`^(?:${h.matcher})$`).test(ev.tool_name || ''));
+  // THE PLUGIN NAMES ITS AGENTS "<plugin>:<agent>" (driver/runtime.js): the agent is the part after the colon, and the hook is handed its own agent's
+  // name as the pipeline's hooks know it — every hook reads agent_type as it did when the agents were placed bare
+  const agent = String(ev.agent_type || '').replace(/^.*:/, '');
+  if (ev.agent_type !== undefined) { ev.agent_type = agent; input = JSON.stringify(ev); }
+  const hooks = (map[agent] || []).filter((h) => !h.matcher || new RegExp(`^(?:${h.matcher})$`).test(ev.tool_name || ''));
   for (const h of hooks) {
     const r = spawnSync('bash', ['-c', h.command], { input, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
     if (r.stdout) process.stdout.write(r.stdout);

package/driver/runtime.js

@@ -7,8 +7,9 @@
 //                  (test/layer1/hook-harness.js); each agent is answered by a generative stand-in (`standin(call)`); the
 //                  hooks are the real ones, run in `env`.
 //   live         — one clean headless Claude Code session per workflow (decision 15), memory-bounded with
-//                  bin/bounded (this package's memory bound), the workflow's agent definitions as FILES in the session's .claude/agents/
-//                  (the Writer has ~150 of them: one --agents argument would pass Linux's 128 KB argument cap). Live runs
+//                  bin/bounded (this package's memory bound), the workflow, its agent definitions (as FILES: the Writer has ~150 of
+//                  them, one --agents argument would pass Linux's 128 KB argument cap) and its hook settings in a BUNDLE under the session's
+//                  folder — OUTSIDE the codeline the session works in (--plugin-dir, --settings): the pipeline puts nothing in a client's checkout. Live runs
 //                  spend tokens: liveCommand() only builds the command; runLive() refuses unless the operator's yes is
 //                  given (EPAM_DRIVER_LIVE_APPROVED=yes AND opts.approved === true). Never run by any test.
 const fs = require('fs');
@@ -19,8 +20,8 @@ const { spawnSync } = require('child_process');
 const ROOT = path.resolve(__dirname, '..');
 const { recordSession } = require('./session-cost.js');
 
-// the names workflows were placed under by earlier versions of this driver and that a test runner's default pattern matches
-const LEGACY_WORKFLOW_FILES = ['spec'];
+/** The plugin the session's bundle is: its agents are named "<PLUGIN>:<agent>" and its workflows run as "<PLUGIN>:<workflow>". */
+const PLUGIN = 'amsd';
 
 function toMarkdown(name, def) {
   // generator/agents.js toMarkdown, from the agents JSON entry (frontmatter keys + `prompt` as the body)
@@ -33,23 +34,55 @@ function toMarkdown(name, def) {
   return `---${yaml({ name, ...fm })}\n---\n\n${String(prompt || '').trim()}\n`;
 }
 
+/** The end of a script's `export const meta = {…}` literal (and the rest of its line): braces inside strings do not count. */
+function metaEnd(src) {
+  const m = /^export const meta = \{/.exec(src);
+  if (!m) throw new Error('a workflow script must begin with `export const meta = {…}`');
+  let depth = 0; let quote = '';
+  for (let i = m[0].length - 1; i < src.length; i += 1) {
+    const c = src[i];
+    if (quote) { if (c === '\\') i += 1; else if (c === quote) quote = ''; continue; }
+    if (c === "'" || c === '"' || c === '`') quote = c;
+    else if (c === '{') depth += 1;
+    else if (c === '}' && (depth -= 1) === 0) { const nl = src.indexOf('\n', i); return nl < 0 ? src.length : nl + 1; }
+  }
+  throw new Error('the workflow script\'s `export const meta` literal is not closed');
+}
+
 /**
- * The live session, prepared but not started: its folder (workflow + agents as files) and the exact command.
- * Writes only under sessionDir.
+ * THE PLUGIN NAMES ITS AGENTS "<plugin>:<agent>" (an unprefixed type is "not found", tried 2026-10-21) and the generated scripts name them bare:
+ * the placed copy shadows agent() with one that adds the prefix where the call is made. Nothing in the generated script changes.
+ */
+function agentPrelude(plugin) {
+  return `const __amsdAgent = globalThis.agent\nconst agent = (p, o) => __amsdAgent(p, o && o.agentType && !String(o.agentType).includes(':') ? { ...o, agentType: '${plugin}:' + o.agentType } : o)\n`;
+}
+function withAgentPrefix(src, plugin = PLUGIN) {
+  const at = metaEnd(src);
+  return `${src.slice(0, at)}${agentPrelude(plugin)}${src.slice(at)}`;
+}
+
+/**
+ * The live session, prepared but not started: its bundle and the exact command. Writes only under sessionDir — NEVER in the folder the session
+ * works in (operator, 2026-10-21: the pipeline puts nothing in a client's checkout; run 11's workflow file there became a deliverable, was
+ * restored by the Writer and run as a test by the client's jest).
+ *
+ *   <sessionDir>/bundle/            the plugin (--plugin-dir): .claude-plugin/plugin.json, workflows/<name>.js, agents/<agent>.md
+ *   <sessionDir>/settings.json      the agents' hooks (--settings): one dispatcher over <sessionDir>/hook-map.json
+ *
+ * THE FOLDER THE AGENTS WORK IN (cwd): prompts' paths are relative to the codeline, as the hub runs every agent from its PROJECT_ROOT
+ * (lib/relative-paths.js), so the session starts there. Without one, the session's own folder.
  */
 function liveCommand({ name, script, agentsJson, args, sessionDir, env, cwd }) {
-  // THE FOLDER THE AGENTS WORK IN (cwd): prompts' paths are relative to the codeline, as the hub runs every agent from its
-  // PROJECT_ROOT (lib/relative-paths.js), so the session starts there; its .claude/ is listed in that copy's own
-  // .git/info/exclude — never committed, never reported as a change. Without one, the session's own folder.
   const home = cwd || sessionDir;
-  if (cwd) excludeLocally(cwd, '/.claude/');
-  const agentsDir = path.join(home, '.claude', 'agents');
-  const wfDir = path.join(home, '.claude', 'workflows');
-  fs.mkdirSync(agentsDir, { recursive: true }); fs.mkdirSync(wfDir, { recursive: true });
+  const bundle = path.join(sessionDir, 'bundle');
+  fs.rmSync(bundle, { recursive: true, force: true });   // a later session in this folder must not inherit an agent this one does not have
+  const agentsDir = path.join(bundle, 'agents'); const wfDir = path.join(bundle, 'workflows');
+  fs.mkdirSync(agentsDir, { recursive: true }); fs.mkdirSync(wfDir, { recursive: true }); fs.mkdirSync(path.join(bundle, '.claude-plugin'), { recursive: true });
+  fs.writeFileSync(path.join(bundle, '.claude-plugin', 'plugin.json'), `${JSON.stringify({ name: PLUGIN, version: '1.0.0', description: 'The pipeline\'s workflow, agents and hooks for one session' })}\n`);
   const defs = JSON.parse(fs.readFileSync(agentsJson, 'utf8'));
-  // THE AGENTS' HOOKS RUN FROM THE SESSION'S PROJECT SETTINGS (driver/hook-dispatch.js): the real Workflow tool does not run
-  // a hook in a workflow agent's frontmatter, and does run one in <cwd>/.claude/settings.json, whose input names the agent
-  // (tools/hook-probe.js, 2026-10-18). The frontmatter is written without them, so nothing could ever run twice.
+  // THE AGENTS' HOOKS RUN FROM THE SESSION'S SETTINGS (driver/hook-dispatch.js): the real Workflow tool does not run a hook in a workflow
+  // agent's frontmatter, and does run one in the settings it is given, whose input names the agent (tools/hook-probe.js, 2026-10-18).
+  // The frontmatter is written without them, so nothing could ever run twice.
   const map = {}; const matchers = new Set(); let timeout = 0;
   for (const [n, d] of Object.entries(defs)) {
     for (const g of (((d.hooks || {}).PreToolUse) || [])) for (const h of (g.hooks || [])) {
@@ -60,41 +93,21 @@ function liveCommand({ name, script, agentsJson, args, sessionDir, env, cwd }) {
     const { hooks: _h, ...noHooks } = d;
     fs.writeFileSync(path.join(agentsDir, `${n}.md`), toMarkdown(n, noHooks));
   }
-  const mapFile = path.join(home, '.claude', 'hook-map.json'); fs.writeFileSync(mapFile, JSON.stringify(map, null, 2));
-  const settingsFile = path.join(home, '.claude', 'settings.json');
-  let settings = {}; try { settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8')); } catch { settings = {}; }
+  const mapFile = path.join(sessionDir, 'hook-map.json'); fs.writeFileSync(mapFile, JSON.stringify(map, null, 2));
+  const settingsFile = path.join(sessionDir, 'settings.json');
   const dispatch = `${JSON.stringify(process.execPath)} ${JSON.stringify(path.join(__dirname, 'hook-dispatch.js'))} ${JSON.stringify(mapFile)}`;
-  const pre = (((settings.hooks || {}).PreToolUse) || []).filter((g) => !(g.hooks || []).some((h) => String(h.command || '').includes('hook-dispatch.js')));
-  if (Object.keys(map).length) pre.push({ matcher: [...matchers].join('|') || '.*', hooks: [{ type: 'command', command: dispatch, ...(timeout ? { timeout } : {}) }] });
-  settings.hooks = { ...(settings.hooks || {}), PreToolUse: pre };
-  fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2));
-  // A LEGACY FILE OF THE PIPELINE'S OWN goes (the Spec workflow was placed as spec.js, which a client's jest runs as a test — run 11): only a file named like a legacy workflow that carries a workflow header
-  // of that same name; a client's file of the same name is never touched
-  for (const legacy of LEGACY_WORKFLOW_FILES) {
-    const f = path.join(wfDir, `${legacy}.js`);
-    try { if (new RegExp(`^export const meta = \\{\\s*name: '${legacy}'`).test(fs.readFileSync(f, 'utf8')) && legacy !== name) fs.rmSync(f); } catch { /* none */ }
-  }
-  fs.copyFileSync(script, path.join(wfDir, `${name}.js`));
+  const pre = Object.keys(map).length ? [{ matcher: [...matchers].join('|') || '.*', hooks: [{ type: 'command', command: dispatch, ...(timeout ? { timeout } : {}) }] }] : [];
+  fs.writeFileSync(settingsFile, JSON.stringify({ hooks: { PreToolUse: pre } }, null, 2));
+  fs.writeFileSync(path.join(wfDir, `${name}.js`), withAgentPrefix(fs.readFileSync(script, 'utf8')));
   // THE RUNNER WAITS FOR ITS WORKFLOW (LIVE-AMSD-2974-3, 2026-10-18: the runner answered "It's still running in the
   // background…" and the session exited, taking the Spec workflow down with it): it answers only with the finished result
   // the session itself waits for its workflow (CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0 below); the runner has no task-wait tool
-  const prompt = `Run the workflow "${name}" with these args, exactly: ${JSON.stringify(args || {})}. When it has finished, reply with its result as JSON and nothing else.`;
+  const prompt = `Run the workflow "${PLUGIN}:${name}" with these args, exactly: ${JSON.stringify(args || {})}. When it has finished, reply with its result as JSON and nothing else.`;
   const claude = (env && env.CLAUDE_BIN) || 'claude';
   // memory scope (bin/bounded) → CPU bound derived from that scope (bin/cpu-bound, the pipeline's own bound_self_affinity) → the session: its tools (jest included) cannot out-size the scope (run 11 OOM)
   const argv = [path.join(__dirname, '..', 'bin', 'bounded'), path.join(__dirname, '..', 'bin', 'cpu-bound'), claude, '-p', prompt, '--output-format', 'json',
-    '--setting-sources', 'project', '--permission-mode', 'bypassPermissions'];
-  return { cwd: home, argv, agents: Object.keys(defs).length, workflow: path.join(wfDir, `${name}.js`) };
-}
-
-/** A pattern in a repository's own, uncommitted exclude list (.git/info/exclude), once. */
-function excludeLocally(repo, pattern) {
-  const g = spawnSync('git', ['-C', repo, 'rev-parse', '--git-path', 'info/exclude'], { encoding: 'utf8' });
-  if (g.status !== 0) return;
-  const f = path.resolve(repo, g.stdout.trim());
-  const cur = fs.existsSync(f) ? fs.readFileSync(f, 'utf8') : '';
-  if (cur.split('\n').includes(pattern)) return;
-  fs.mkdirSync(path.dirname(f), { recursive: true });
-  fs.writeFileSync(f, `${cur.replace(/\n?$/, cur ? '\n' : '')}${pattern}\n`);
+    '--plugin-dir', bundle, '--settings', settingsFile, '--setting-sources', 'project', '--permission-mode', 'bypassPermissions'];
+  return { cwd: home, argv, agents: Object.keys(defs).length, workflow: path.join(wfDir, `${name}.js`), bundle, settings: settingsFile };
 }
 
 /** The pipeline's tool commands as named variables (llm-handler.sh:240–245: lib/pipeline-tools.js commandEnv(), exported
@@ -219,11 +232,11 @@ async function run(o) {
   // carry its story, as the story's attempts do in the pipeline
   if (res && (res.__session || !res.__throw) && opts.env.SCRIPT_DIR && (opts.env.PHASE_COST_FILE || opts.env.LOG_DIR)) {
     res.__cost = recordSession(opts.env, res.__session, { stage: opts.name, storyId: opts.costStory || null, phase: opts.env.PHASE || null,
-      projectsDir: res.__session && res.__session.projectsDir, log: opts.log });
+      projectsDir: res.__session && res.__session.projectsDir, agentsDir: opts.sessionDir ? path.join(opts.sessionDir, 'bundle', 'agents') : undefined, log: opts.log });
     await Promise.all(res.__cost.traces || []);
   }
   if (res && res.__throw) throw res.__throw;
   return res;
 }
 
-module.exports = { run, liveCommand, toMarkdown };
+module.exports = { run, liveCommand, toMarkdown, withAgentPrefix, agentPrelude, metaEnd, PLUGIN };

package/driver/session-cost.js

@@ -41,7 +41,7 @@ function transcriptTokens(file) {
  *  toolCallsInTranscript, read from the call's own transcript). For a workflow agent: its prompt is the first user turn of its
  *  transcript, its reply the answer it gave (its StructuredOutput, else its last text), its tool calls by the pipeline's own
  *  reader. Operator, 2026-10-18: "I need all llm calls captured"; "Did you not read the code from the current pipeline?" */
-function callContent(file, scriptsDir, agentName) {
+function callContent(file, scriptsDir, agentName, agentsDir) {
   const lines = fs.readFileSync(file, 'utf8').split('\n').filter((l) => l.trim()).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
   const first = lines.find((d) => d.type === 'user' && d.message);
   const asst = lines.filter((d) => d.type === 'assistant' && d.message && Array.isArray(d.message.content)).flatMap((d) => d.message.content);
@@ -50,11 +50,11 @@ function callContent(file, scriptsDir, agentName) {
   // eslint-disable-next-line global-require, import/no-dynamic-require
   const tx = require(path.join(scriptsDir, 'lib', 'transcript-tool-calls.js'));
   const ts = lines.map((d) => d.timestamp).filter(Boolean);
-  // the agent's standing instructions: its definition in the session's folder (<cwd>/.claude/agents/<agent>.md, written by
-  // driver/runtime.js liveCommand) — sent to the model as its system prompt, not in the transcript
-  const cwd = (lines.find((d) => d.cwd) || {}).cwd; const agentType = (lines.find((d) => d.agentType) || {}).agentType || agentName;
+  // the agent's standing instructions: its definition in the session's bundle (<session>/bundle/agents/<agent>.md, written by
+  // driver/runtime.js liveCommand; the plugin names the agent "<plugin>:<agent>") — sent to the model as its system prompt, not in the transcript
+  const agentType = String((lines.find((d) => d.agentType) || {}).agentType || agentName || '').replace(/^.*:/, '');
   let system = '';
-  try { const md = fs.readFileSync(path.join(cwd, '.claude', 'agents', `${agentType}.md`), 'utf8'); system = md.replace(/^---[\s\S]*?\n---\n+/, ''); } catch { system = ''; }
+  try { const md = fs.readFileSync(path.join(agentsDir, `${agentType}.md`), 'utf8'); system = md.replace(/^---[\s\S]*?\n---\n+/, ''); } catch { system = ''; }
   const prompt = first ? first.message.content : '';
   return { input: system ? { system, prompt } : prompt, output: so ? JSON.stringify(so.input) : (text || ''),   // text: the emitter's output is text
     toolCalls: tx.toolCallsInTranscript(file), startedAt: ts[0] || null, endedAt: ts[ts.length - 1] || null };
@@ -85,7 +85,8 @@ function sessionEntries(projectsDir, sessionId) {
       for (const f of fs.readdirSync(rd).filter((x) => /^agent-.*\.jsonl$/.test(x)).sort()) {
         let meta = {}; try { meta = JSON.parse(fs.readFileSync(path.join(rd, f.replace(/\.jsonl$/, '.meta.json')), 'utf8')); } catch { meta = {}; }
         const label = meta.description || f;
-        push(meta.agentType && meta.agentType !== 'workflow-subagent' ? meta.agentType : label, label, path.join(rd, f));
+        // the plugin names an agent "<plugin>:<agent>" (driver/runtime.js): the ledger and the traces name it as the pipeline does
+        push(meta.agentType && meta.agentType !== 'workflow-subagent' ? String(meta.agentType).replace(/^.*:/, '') : label, label, path.join(rd, f));
       }
     }
   }
@@ -133,7 +134,7 @@ function allocate(entries, modelUsage, prices = {}) {
  * Record one session's cost. session: {sessionId, modelUsage, totalCostUsd} (the session's result).
  * Returns {rows, totalCostUsd, exact: bool (per-call rows written), reason, traces: the Langfuse sends, Promise<boolean>[]}.
  */
-function recordSession(env, session, { stage, storyId, phase, projectsDir, log }) {
+function recordSession(env, session, { stage, storyId, phase, projectsDir, agentsDir, log }) {
   const ledger = env.PHASE_COST_FILE || path.join(env.LOG_DIR, 'phase-cost.jsonl');
   // eslint-disable-next-line global-require, import/no-dynamic-require
   const { appendLedgerRecord } = require(path.join(env.SCRIPT_DIR, 'lib', 'cost-emitter.js'));
@@ -155,7 +156,7 @@ function recordSession(env, session, { stage, storyId, phase, projectsDir, log }
             costIsEstimate: true, costUnknown: e.costUnknown } }));
         // each agent call to Langfuse with its prompt, its answer and its tool calls, as the pipeline's cost seam traces each
         // of its calls (lib/cost-emitter.js → lib/langfuse-emit.js); off without keys
-        const c = e.file ? callContent(e.file, env.SCRIPT_DIR, e.agent) : {};
+        const c = e.file ? callContent(e.file, env.SCRIPT_DIR, e.agent, agentsDir) : {};
         traces.push(emitGeneration({ agent: e.agent, storyId, phase, model: e.model, startedAt: c.startedAt, endedAt: c.endedAt,
           input: c.input, output: c.output, toolCalls: c.toolCalls, costUsd: e.costUsd, tokensIn: e.tokens.in, tokensOut: e.tokens.out,
           cacheRead: e.tokens.cacheRead, cacheCreate: e.tokens.cacheCreate, costIsEstimate: true }, { ...process.env, ...env }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amsd-pipeline-workflow",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "The AMSD pipeline as Claude workflows. Installed by the amsd-pipeline installer: install.sh --workflows",
   "license": "UNLICENSED",
   "bin": {