@kontourai/flow-agents 0.1.1

package/scripts/hooks/stop-goal-fit.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+/**
+ * Stop Hook: warn when an active workflow is about to stop short of its goal.
+ *
+ * The hook reads .flow-agents artifacts, looks for the most recent active
+ * delivery/session file, and reports missing Definition Of Done, Goal Fit, or
+ * Final Acceptance state. It is warning-only by default. Set
+ * FLOW_AGENTS_GOAL_FIT_STRICT=true to return exit code 2 when local goal fit is
+ * incomplete.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_STDIN = 1024 * 1024;
+const ACTIVE_STATUSES = new Set([
+  'planning',
+  'planned',
+  'executing',
+  'executed',
+  'reviewing',
+  'verifying',
+  'failed',
+  'needs-decision',
+  'in-progress',
+  'blocked',
+  'partial',
+]);
+const DELIVERY_TYPES = new Set(['deliver', 'delivery', 'fix-bug', 'execute-plan', 'verify-work']);
+const SIDECAR_NAMES = new Set(['state.json', 'acceptance.json', 'evidence.json', 'handoff.json']);
+const OPTIONAL_SIDECAR_NAMES = new Set(['critique.json']);
+
+function parseJson(raw) {
+  try { return JSON.parse(raw || '{}'); } catch { return {}; }
+}
+
+function findRepoRoot(startDir) {
+  let dir = path.resolve(startDir || process.cwd());
+  const root = path.parse(dir).root;
+  for (let depth = 0; dir && depth < 40; depth++) {
+    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'AGENTS.md'))) return dir;
+    if (dir === root) break;
+    dir = path.dirname(dir);
+  }
+  return path.resolve(startDir || process.cwd());
+}
+
+function walkMarkdown(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'archive') continue;
+      walkMarkdown(full, out);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function readArtifact(file) {
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return null; }
+  const stat = fs.statSync(file);
+  const status = (text.match(/^status:\s*([A-Za-z0-9_-]+)/m) || [])[1] || '';
+  const type = (text.match(/^type:\s*([A-Za-z0-9_-]+)/m) || [])[1] || '';
+  const role = (text.match(/^role:\s*([A-Za-z0-9_-]+)/m) || [])[1] || '';
+  return { file, text, status, type, role, mtimeMs: stat.mtimeMs };
+}
+
+function hasSidecars(dir) {
+  try {
+    return fs.readdirSync(dir).some(name => SIDECAR_NAMES.has(name));
+  } catch {
+    return false;
+  }
+}
+
+function sidecarValidation(root, artifactDir) {
+  const requireSidecars = String(process.env.FLOW_AGENTS_REQUIRE_SIDECARS || '').toLowerCase() === 'true';
+  const requireCritique = String(process.env.FLOW_AGENTS_REQUIRE_CRITIQUE || '').toLowerCase() === 'true';
+  if (!requireSidecars && !requireCritique && !hasSidecars(artifactDir)) return [];
+
+  const packageRoot = fs.existsSync(path.join(root, 'package.json'))
+    ? root
+    : path.resolve(__dirname, '..', '..');
+  const packageJson = path.join(packageRoot, 'package.json');
+  if (!fs.existsSync(packageJson)) return [`${relative(root, artifactDir)} sidecar validation: package.json is missing; cannot run TypeScript workflow validator.`];
+
+  let sidecarFiles = [];
+  try {
+    sidecarFiles = fs.readdirSync(artifactDir)
+      .filter(name => SIDECAR_NAMES.has(name) || OPTIONAL_SIDECAR_NAMES.has(name))
+      .map(name => path.join(artifactDir, name));
+  } catch {
+    sidecarFiles = [];
+  }
+
+  if (requireSidecars || requireCritique) {
+    const present = new Set(sidecarFiles.map(file => path.basename(file)));
+    const requiredNames = new Set(requireSidecars ? SIDECAR_NAMES : []);
+    if (requireCritique) requiredNames.add('critique.json');
+    const missing = [...requiredNames].filter(name => !present.has(name)).sort();
+    if (missing.length > 0) {
+      return missing.map(name => `${relative(root, path.join(artifactDir, name))} sidecar validation: required sidecar is missing`);
+    }
+  }
+
+  if (sidecarFiles.length === 0) return [];
+
+  const args = ['run', 'workflow:validate-artifacts', '--silent', '--'];
+  args.push('--skip-markdown-validation');
+  if (requireSidecars) args.push('--require-sidecars');
+  if (requireCritique) args.push('--require-critique');
+  args.push(artifactDir);
+
+  const result = spawnSync('npm', args, {
+    cwd: packageRoot,
+    encoding: 'utf8',
+    timeout: 30000,
+  });
+
+  if (result.status === 0) return [];
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean)
+    .slice(0, 12);
+  if (output.length === 0) output.push(`validator exited with status ${result.status ?? 'unknown'}`);
+  return output.map(line => `${relative(root, artifactDir)} sidecar validation: ${line}`);
+}
+
+function isWorkflowArtifact(artifact) {
+  if (!artifact) return false;
+  if (artifact.role === 'plan' || artifact.role === 'review') return false;
+  if (artifact.file.endsWith('-plan.md') || artifact.file.endsWith('-review.md')) return false;
+  if (DELIVERY_TYPES.has(artifact.type)) return true;
+  return /--(deliver|fix-bug|execute-plan|verify-work)\b/.test(path.basename(artifact.file));
+}
+
+function uncheckedInSection(text, heading) {
+  const start = text.indexOf(`## ${heading}`);
+  if (start < 0) return [];
+  const rest = text.slice(start + heading.length + 3);
+  const next = rest.search(/\n##\s+/);
+  const section = next >= 0 ? rest.slice(0, next) : rest;
+  return section
+    .split('\n')
+    .filter(line => /^\s*-\s+\[\s\]/.test(line))
+    .map(line => line.replace(/^\s*-\s+\[\s\]\s*/, '').trim())
+    .filter(Boolean);
+}
+
+function hasHeading(text, heading) {
+  return new RegExp(`^##\\s+${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm').test(text);
+}
+
+function relative(root, file) {
+  return path.relative(root, file).split(path.sep).join('/');
+}
+
+function readJsonFile(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function safeOneLine(value, maxLength = 220) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 3)}...`;
+}
+
+function normalizedStatus(value) {
+  return safeOneLine(value, 80).toLowerCase();
+}
+
+function sidecarGuidance(root, artifactDir) {
+  const warnings = [];
+  const state = readJsonFile(path.join(artifactDir, 'state.json'));
+  const evidence = readJsonFile(path.join(artifactDir, 'evidence.json'));
+  const critique = readJsonFile(path.join(artifactDir, 'critique.json'));
+  const base = relative(root, artifactDir);
+
+  if (state) {
+    const status = normalizedStatus(state.status || 'unknown');
+    const phase = normalizedStatus(state.phase || 'unknown');
+    const next = state.next_action && typeof state.next_action === 'object' ? state.next_action : null;
+    if (!['done', 'delivered', 'archived', 'accepted', 'complete', 'completed'].includes(status)) {
+      const nextStatus = next ? normalizedStatus(next.status || 'unknown') : 'unknown';
+      const nextSummary = next && next.summary ? `; next_action:${nextStatus} "${safeOneLine(next.summary)}"` : '';
+      warnings.push(`${base} workflow state: status:${status} phase:${phase}${nextSummary}`);
+    }
+  }
+
+  if (state && state.next_action && normalizedStatus(state.next_action.status) !== 'done') {
+    const next = state.next_action;
+    warnings.push(`${base} next action: ${safeOneLine(next.summary)}${next.target_phase ? ` (target phase: ${safeOneLine(next.target_phase, 80)})` : ''}`);
+  }
+
+  if (evidence && normalizedStatus(evidence.verdict) && normalizedStatus(evidence.verdict) !== 'pass') {
+    warnings.push(`${base} evidence verdict:${safeOneLine(evidence.verdict, 40)}; do not deliver without accepted gap or new evidence.`);
+  }
+  if (evidence && Array.isArray(evidence.not_verified_gaps) && evidence.not_verified_gaps.length > 0) {
+    for (const gap of evidence.not_verified_gaps.slice(0, 3)) {
+      warnings.push(`${base} evidence NOT_VERIFIED gap: ${safeOneLine(gap)}`);
+    }
+  }
+  if (evidence && Array.isArray(evidence.checks)) {
+    const blockingChecks = evidence.checks.filter(check => {
+      const status = normalizedStatus(check && check.status);
+      return status === 'fail' || status === 'failed' || status === 'not_verified' || status === 'not-verified';
+    });
+    for (const check of blockingChecks.slice(0, 4)) {
+      const status = safeOneLine(check.status || 'unknown', 40);
+      warnings.push(`${base} evidence check ${safeOneLine(check.id || 'unknown', 80)} status:${status}: ${safeOneLine(check.summary)}`);
+    }
+  }
+
+  if (critique && critique.required === true && normalizedStatus(critique.status) !== 'pass') {
+    warnings.push(`${base} critique status:${safeOneLine(critique.status || 'unknown', 40)}; required critique must pass or findings be accepted.`);
+    const critiques = Array.isArray(critique.critiques) ? critique.critiques : [];
+    let openCount = 0;
+    for (const review of critiques) {
+      const findings = Array.isArray(review && review.findings) ? review.findings : [];
+      for (const finding of findings) {
+        if (!finding || normalizedStatus(finding.status) !== 'open') continue;
+        warnings.push(`${base} critique open ${safeOneLine(finding.severity || 'unknown', 40)}: ${safeOneLine(finding.description)}`);
+        openCount += 1;
+        if (openCount >= 3) break;
+      }
+      if (openCount >= 3) break;
+    }
+  }
+
+  return warnings;
+}
+
+function markdownVerdict(text) {
+  const verdict = (/###\s+Verdict:\s*([A-Za-z_ -]+)/i.exec(text) || [])[1]
+    || (/^Build:\s*\[?([A-Za-z_ -]+)\]?/im.exec(text) || [])[1]
+    || '';
+  return normalizedStatus(verdict).replace(/[^a-z_ -].*$/, '').trim();
+}
+
+function analyze(root, now = Date.now()) {
+  const dirs = [path.join(root, '.flow-agents')];
+  const artifacts = dirs
+    .flatMap(dir => walkMarkdown(dir))
+    .map(readArtifact)
+    .filter(isWorkflowArtifact)
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  if (artifacts.length === 0) return { warnings: [], blocking: false };
+
+  const latest = artifacts[0];
+  const warnings = [];
+  const relPath = relative(root, latest.file);
+  const status = latest.status || 'unknown';
+  const ageMinutes = Math.max(0, Math.round((now - latest.mtimeMs) / 60000));
+
+  if (ACTIVE_STATUSES.has(status)) {
+    warnings.push(`${relPath} is still status:${status} (${ageMinutes}m old). Do not final-answer as complete unless the next step is explicit.`);
+  }
+
+  if (!hasHeading(latest.text, 'Definition Of Done')) {
+    warnings.push(`${relPath} is missing ## Definition Of Done, so the user-facing finish line is not explicit.`);
+  }
+
+  if (!hasHeading(latest.text, 'Goal Fit Gate')) {
+    warnings.push(`${relPath} is missing ## Goal Fit Gate, so local acceptance has not been checked.`);
+  } else {
+    for (const item of uncheckedInSection(latest.text, 'Goal Fit Gate').slice(0, 6)) {
+      warnings.push(`${relPath} Goal Fit unchecked: ${item}`);
+    }
+  }
+
+  if (status === 'delivered' && hasHeading(latest.text, 'Final Acceptance')) {
+    const uncheckedFinal = uncheckedInSection(latest.text, 'Final Acceptance');
+    if (uncheckedFinal.length > 0) {
+      warnings.push(`${relPath} local delivery is marked delivered, but Final Acceptance still has ${uncheckedFinal.length} open item(s) for CI/merge/docs promotion.`);
+    }
+  }
+
+  warnings.push(...sidecarValidation(root, path.dirname(latest.file)));
+  const evidence = readJsonFile(path.join(path.dirname(latest.file), 'evidence.json'));
+  if (evidence && markdownVerdict(latest.text) === 'pass' && normalizedStatus(evidence.verdict) === 'fail') {
+    warnings.push(`${relPath} Markdown PASS contradicts evidence.json verdict fail.`);
+  }
+  warnings.push(...sidecarGuidance(root, path.dirname(latest.file)));
+
+  const blocking = warnings.some(w => /status:|Definition Of Done|Goal Fit|sidecar validation|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action/.test(w));
+  return { warnings, blocking };
+}
+
+function run(rawInput) {
+  const input = parseJson(rawInput);
+  const root = findRepoRoot(input.cwd || process.cwd());
+  const result = analyze(root);
+  if (result.warnings.length === 0) return rawInput;
+
+  const message = [
+    '[Hook] Goal Fit warning:',
+    ...result.warnings.map(w => ` - ${w}`),
+  ].join('\n');
+  const strict = String(process.env.FLOW_AGENTS_GOAL_FIT_STRICT || '').toLowerCase() === 'true';
+  return {
+    stdout: rawInput,
+    stderr: message,
+    exitCode: strict && result.blocking ? 2 : 0,
+  };
+}
+
+if (require.main === module) {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (data.length < MAX_STDIN) data += chunk.substring(0, MAX_STDIN - data.length);
+  });
+  process.stdin.on('end', () => {
+    const output = run(data);
+    if (output && typeof output === 'object') {
+      if (output.stderr) process.stderr.write(output.stderr.endsWith('\n') ? output.stderr : `${output.stderr}\n`);
+      process.stdout.write(String(output.stdout ?? data));
+      process.exit(Number.isInteger(output.exitCode) ? output.exitCode : 0);
+    }
+    process.stdout.write(String(output));
+  });
+}
+
+module.exports = { analyze, run, uncheckedInSection, findRepoRoot, sidecarGuidance, safeOneLine };

package/scripts/hooks/workflow-steering.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * Workflow Steering Hook
+ *
+ * Injects phase-transition reminders after use_subagent calls complete and
+ * ambient workflow-state reminders at the start of the next user turn.
+ *
+ * Non-blocking — always exits 0.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const STEERING = {
+  'tool-planner': [
+    '⚡ PLAN COMPLETE — Next: execute-plan (step 3).',
+    'Present plan to user. Get approval before executing.',
+  ].join(' '),
+
+  'tool-worker': [
+    '⚡ EXECUTION COMPLETE — Next: review (step 4) then verify (step 5).',
+    'Delegate to review-work for critique (report only — it cannot fix code).',
+    'Then delegate to verify-work for evidence (report only — it cannot fix code).',
+    'Do NOT deliver until review + verify are both clean.',
+    'If this was a VISUAL change (UI, CSS, HTML), you MUST delegate to tool-playwright for screenshot verification before delivering.',
+  ].join(' '),
+
+  'tool-code-reviewer': [
+    '⚡ REVIEW COMPLETE — Next: verify (step 5).',
+    'Reviewer reported findings only — it did NOT fix anything.',
+    'If CRITICAL/HIGH findings: route back to execute-plan, then re-review + re-verify.',
+    'If clean: proceed to verify-work. If findings exist, route back through execute-plan or a user decision.',
+  ].join(' '),
+
+  'tool-security-reviewer': [
+    '⚡ SECURITY REVIEW COMPLETE — Check findings.',
+    'If CRITICAL security findings: route back to execute-plan, then re-review + re-verify.',
+    'If clean: proceed to next step.',
+  ].join(' '),
+
+  'tool-verifier': [
+    '⚡ VERIFICATION COMPLETE — Route on verdict.',
+    'All PASS + no review issues → deliver.',
+    'Any FAIL or unfixed findings → route back to execute-plan, then re-review + re-verify.',
+    'Loop exits ONLY when review + verify are BOTH clean in the same iteration.',
+  ].join(' '),
+};
+
+const ACTIVE_STATE_STATUSES = new Set([
+  'new',
+  'planning',
+  'planned',
+  'in_progress',
+  'blocked',
+  'verifying',
+  'verified',
+  'needs_decision',
+  'not_verified',
+  'failed',
+  'delivered',
+]);
+
+function findRepoRoot(startDir) {
+  let dir = path.resolve(startDir || process.cwd());
+  const root = path.parse(dir).root;
+  for (let depth = 0; dir && depth < 40; depth++) {
+    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'AGENTS.md'))) return dir;
+    if (dir === root) break;
+    dir = path.dirname(dir);
+  }
+  return path.resolve(startDir || process.cwd());
+}
+
+function walkStateFiles(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'archive') continue;
+      walkStateFiles(full, out);
+    } else if (entry.isFile() && entry.name === 'state.json') {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function latestWorkflowState(root) {
+  const states = walkStateFiles(path.join(root, '.flow-agents'))
+    .map(file => {
+      let stat;
+      try { stat = fs.statSync(file); } catch { return null; }
+      const payload = readJson(file);
+      if (!payload || !ACTIVE_STATE_STATUSES.has(payload.status)) return null;
+      return { file, payload, mtimeMs: stat.mtimeMs };
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return states[0] || null;
+}
+
+function safeStateText(value, maxLength = 240) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 3)}...`;
+}
+
+function normalizedStateValue(value) {
+  return safeStateText(value, 80).toLowerCase();
+}
+
+function stateNeedsAmbientSteering(state) {
+  if (!state || typeof state !== 'object') return false;
+  const status = normalizedStateValue(state.status);
+  const nextStatus = normalizedStateValue(state.next_action && state.next_action.status);
+  return (
+    status === 'blocked' ||
+    status === 'failed' ||
+    status === 'needs_decision' ||
+    status === 'not_verified' ||
+    nextStatus === 'needs_user'
+  );
+}
+
+function critiqueSteering(workflowDir) {
+  const critique = readJson(path.join(workflowDir, 'critique.json'));
+  if (!critique || critique.required !== true) return '';
+  if (critique.status === 'pass' || critique.status === 'not_required') return '';
+  const critiques = Array.isArray(critique.critiques) ? critique.critiques : [];
+  const openFindings = [];
+  let nonPassReviews = 0;
+  for (const review of critiques) {
+    if (!review || typeof review !== 'object') continue;
+    if (review.verdict === 'fail' || review.verdict === 'not_verified') nonPassReviews += 1;
+    const findings = Array.isArray(review.findings) ? review.findings : [];
+    for (const finding of findings) {
+      if (finding && finding.status === 'open') openFindings.push(finding);
+    }
+  }
+  const parts = [
+    `CRITIQUE: required critique is status:${safeStateText(critique.status, 60)}.`,
+  ];
+  if (nonPassReviews) parts.push(`${nonPassReviews} review(s) have fail/not_verified verdicts.`);
+  if (openFindings.length) {
+    const severityCounts = openFindings.reduce((acc, finding) => {
+      const severity = safeStateText(finding.severity || 'unknown', 30);
+      acc[severity] = (acc[severity] || 0) + 1;
+      return acc;
+    }, {});
+    const counts = Object.entries(severityCounts)
+      .map(([severity, count]) => `${severity}:${count}`)
+      .join(', ');
+    parts.push(`Open findings: ${counts}.`);
+    parts.push(`First open finding: "${safeStateText(openFindings[0].description)}"`);
+  }
+  parts.push('Do not deliver as complete until required critique is pass or findings are explicitly accepted.');
+  return parts.join(' ');
+}
+
+function stateSteering(root) {
+  const current = latestWorkflowState(root);
+  if (!current) return '';
+  const state = current.payload;
+  const next = state.next_action || {};
+  if (next.status === 'done' || state.status === 'archived' || state.status === 'accepted') return '';
+  const parts = [
+    `STATE: ${state.task_slug || path.basename(path.dirname(current.file))} is status:${state.status} phase:${state.phase}.`,
+  ];
+  if (next.summary) parts.push(`Recorded next_action.summary: "${safeStateText(next.summary)}"`);
+  if (next.target_phase) parts.push(`Target phase: ${safeStateText(next.target_phase, 80)}.`);
+  if (next.status === 'needs_user' || state.status === 'needs_decision' || state.status === 'not_verified') {
+    parts.push('Do not deliver as complete until the user decision or accepted gap is recorded.');
+  }
+  if (state.status === 'failed') {
+    parts.push('Route back through execution, then re-review and re-verify.');
+  }
+  const critiqueHint = critiqueSteering(path.dirname(current.file));
+  if (critiqueHint) parts.push(critiqueHint);
+  return parts.join(' ');
+}
+
+function contextMapSteering(root) {
+  const mapPath = path.join(root, 'docs', 'context-map.md');
+  if (!fs.existsSync(mapPath)) return '';
+  return [
+    'CONTEXT MAP: use docs/context-map.md before broad repo rediscovery.',
+    'If structure, commands, schemas, skills, agents, or packs changed, run `npm run context-map -- --check`.',
+  ].join(' ');
+}
+
+function run(rawInput) {
+  try {
+    const input = JSON.parse(rawInput);
+    const event = input.hook_event_name || '';
+    const toolOutput = input.tool_response || input.tool_output || '';
+    const toolInput = input.tool_input || {};
+    const root = findRepoRoot(input.cwd || process.cwd());
+    const current = latestWorkflowState(root);
+    const hints = [];
+    let shouldAppendWorkflowContext = false;
+
+    if (toolInput.command === 'InvokeSubagents') {
+      const subagents = toolInput.content?.subagents || [];
+      hints.push(...subagents
+        .map(s => STEERING[s.agent_name])
+        .filter(Boolean));
+      shouldAppendWorkflowContext = hints.length > 0;
+    }
+
+    if (event === 'UserPromptSubmit' && current && stateNeedsAmbientSteering(current.payload)) {
+      hints.push('WORKFLOW STATE ATTENTION: current sidecars show unresolved workflow state at turn start.');
+      shouldAppendWorkflowContext = true;
+    }
+
+    if (shouldAppendWorkflowContext) {
+      const stateHint = stateSteering(root);
+      if (stateHint) hints.push(stateHint);
+      const contextHint = contextMapSteering(root);
+      if (contextHint) hints.push(contextHint);
+    }
+    if (hints.length === 0) return rawInput;
+
+    const steering = '\n\n---\n' + hints.join('\n') + '\n---';
+    return rawInput + steering;
+  } catch { /* pass through */ }
+  return rawInput;
+}
+
+if (require.main === module) {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    data += chunk;
+  });
+  process.stdin.on('end', () => {
+    process.stdout.write(String(run(data)));
+  });
+}
+
+module.exports = { run, stateSteering, critiqueSteering, contextMapSteering, latestWorkflowState, findRepoRoot, safeStateText, stateNeedsAmbientSteering };

package/scripts/install-codex-home.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# install-codex-home.sh - Install Flow Agents as an isolated Codex home.
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+usage() {
+  cat >&2 <<'EOF'
+usage: install-codex-home.sh [destination] [options]
+
+Options:
+  --telemetry-sink NAME   local-files, local-kontour-console,
+                          kontour-hosted-console, user-hosted-console,
+                          or legacy aliases. May be repeated.
+  --console-url URL       Persist Console telemetry base URL.
+  --console-endpoint URL  Persist full Console telemetry records endpoint URL.
+  --console-token-file PATH
+                          Read Console telemetry bearer token from a file.
+  --console-tenant ID     Persist Console tenant identifier.
+EOF
+}
+
+DEST="$HOME/.flow-agents/codex"
+DEST_SET=0
+CONSOLE_CONFIG_ARGS=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --telemetry-sink|--telemetry-sinks|--console-url|--console-endpoint|--console-endpoint-url|--console-token-file|--console-tenant|--console-tenant-id)
+      [[ $# -ge 2 ]] || { echo "install-codex-home.sh: $1 requires a value" >&2; exit 2; }
+      CONSOLE_CONFIG_ARGS+=("$1" "$2")
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    -*)
+      echo "install-codex-home.sh: unknown option: $1" >&2
+      usage
+      exit 2
+      ;;
+    *)
+      if [[ "$DEST_SET" -eq 1 ]]; then
+        echo "install-codex-home.sh: unexpected argument: $1" >&2
+        usage
+        exit 2
+      fi
+      DEST="$1"
+      DEST_SET=1
+      shift
+      ;;
+  esac
+done
+REAL_CODEX_HOME="${CODEX_REAL_HOME:-$HOME/.codex}"
+if command -v npm >/dev/null 2>&1; then
+  (cd "$ROOT_DIR" && FLOW_AGENTS_EXPORT_DIAGNOSTICS=0 npm run build:bundles --silent >/dev/null)
+else
+  echo "install-codex-home.sh: requires npm on PATH" >&2
+  exit 1
+fi
+
+mkdir -p "$DEST"
+
+# This is an isolated generated Codex home. Clean generated bundle content before
+# overlaying so renamed/deleted source files do not survive across installs.
+rm -rf \
+  "$DEST/.flow-agents" \
+  "$DEST/.codex" \
+  "$DEST/AGENTS.md" \
+  "$DEST/README.md" \
+  "$DEST/console.telemetry.json" \
+  "$DEST/install.sh" \
+  "$DEST/config.toml" \
+  "$DEST/hooks.json" \
+  "$DEST/agent-cards" \
+  "$DEST/agents" \
+  "$DEST/context" \
+  "$DEST/docs" \
+  "$DEST/evals" \
+  "$DEST/integrations" \
+  "$DEST/kits" \
+  "$DEST/packaging" \
+  "$DEST/powers" \
+  "$DEST/prompts" \
+  "$DEST/schemas" \
+  "$DEST/scripts" \
+  "$DEST/skills"
+find "$DEST" -maxdepth 1 -type f -name 'k*.config.toml' -delete
+
+rsync -a "$ROOT_DIR/dist/codex/." "$DEST/"
+rsync -a "$ROOT_DIR/dist/codex/.codex/." "$DEST/"
+rm -rf "$DEST/.codex" 2>/dev/null || true
+
+for auth_file in auth.json version.json installation_id models_cache.json; do
+  if [[ -f "$REAL_CODEX_HOME/$auth_file" ]]; then
+    cp "$REAL_CODEX_HOME/$auth_file" "$DEST/$auth_file"
+  fi
+done
+
+chmod 700 "$DEST" 2>/dev/null || true
+[[ -f "$DEST/auth.json" ]] && chmod 600 "$DEST/auth.json" 2>/dev/null || true
+if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then
+  bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"
+fi
+
+echo "Installed isolated Flow Agents Codex home at $DEST"
+echo "Use: CODEX_HOME=$DEST codex --profile kdev"

package/scripts/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}