@kontourai/flow-agents 3.3.0 → 3.4.1

package/src/tools/build-universal-bundles.ts

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { loadJson, readText, root, walkFiles, writeText } from "./common.js";
+import { CODEX_REASONING_EFFORTS, codexAgentRoutingErrors } from "./codex-agent-routing.js";
 import { DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR } from "../lib/local-artifact-root.js";
 
 type Agent = Record<string, unknown> & { name: string; prompt: string };
@@ -188,8 +189,36 @@ function mapped(mapName: string, value: unknown): string {
   const map = manifest[mapName];
   return map[modelPrefix(String(value ?? ""))] ?? map.default;
 }
+function codexAgentOverride(spec: Agent): Record<string, unknown> | undefined {
+  const override = manifest.codex_agent_map?.[spec.name];
+  if (override === undefined) return undefined;
+  if (!override || typeof override !== "object" || Array.isArray(override)) {
+    throw new Error(`packaging/manifest.json: codex_agent_map.${spec.name} must be an object`);
+  }
+  const keys = Object.keys(override).sort();
+  if (keys.join(",") !== "model,reasoning_effort") {
+    throw new Error(`packaging/manifest.json: codex_agent_map.${spec.name} must contain exactly model and reasoning_effort`);
+  }
+  return override;
+}
+function validateCodexModel(model: string, context: string): string {
+  const allowed = new Set(manifest.codex?.allowed_agent_models ?? []);
+  if (!allowed.has(model)) throw new Error(`packaging/manifest.json: ${context} uses unsupported Codex agent model '${model}'`);
+  return model;
+}
 function resolveCodexModel(spec: Agent): string {
-  return ["tool-agent-delegate", "tool-agent-handoff"].includes(spec.name) ? "gpt-5.4-mini" : mapped("codex_model_map", spec.model);
+  const override = codexAgentOverride(spec)?.model;
+  if (typeof override === "string" && override) return validateCodexModel(override, `codex_agent_map.${spec.name}.model`);
+  const fallback = ["tool-agent-delegate", "tool-agent-handoff"].includes(spec.name) ? "gpt-5.4-mini" : mapped("codex_model_map", spec.model);
+  return validateCodexModel(fallback, `resolved model for ${spec.name}`);
+}
+function resolveCodexReasoningEffort(spec: Agent): string {
+  const override = codexAgentOverride(spec)?.reasoning_effort;
+  const effort = typeof override === "string" && override ? override : mapped("codex_reasoning_map", spec.model);
+  if (!CODEX_REASONING_EFFORTS.has(effort)) {
+    throw new Error(`packaging/manifest.json: resolved reasoning effort for ${spec.name} is invalid: '${effort}'`);
+  }
+  return effort;
 }
 function normalizeCodexText(text: string): string {
   const replacements: Record<string, string> = { "—": "-", "–": "-", "→": "->", "←": "<-", "’": "'", "“": '"', "”": '"', "⚡": "[quick]", "🖥️": "[interactive]" };
@@ -230,7 +259,7 @@ function codexNicknames(agentName: string): string[] {
 function exportCodexAgent(spec: Agent): string {
   const prompt = appendExportNote(normalizeCodexText(sanitizeText(spec.prompt, "codex", "<bundle-root>")), "Exported from a Kiro agent spec. Hooks, resource auto-loading, and tool allowlists were converted into prompt guidance only. Any explicit Kiro scheduler commands are preserved as optional shell workflows.");
   const description = normalizeCodexText(String(spec.description ?? "")).replace(/"/g, "'");
-  return `# exported from agents/${spec.name}.json\nname = "${spec.name}"\nnickname_candidates = ${JSON.stringify(codexNicknames(spec.name))}\ndescription = "${description}"\nmodel = "${resolveCodexModel(spec)}"\nmodel_reasoning_effort = "${mapped("codex_reasoning_map", spec.model)}"\ndeveloper_instructions = ${JSON.stringify(prompt)}\n`;
+  return `# exported from agents/${spec.name}.json\nname = "${spec.name}"\nnickname_candidates = ${JSON.stringify(codexNicknames(spec.name))}\ndescription = "${description}"\nmodel = "${resolveCodexModel(spec)}"\nmodel_reasoning_effort = "${resolveCodexReasoningEffort(spec)}"\ndeveloper_instructions = ${JSON.stringify(prompt)}\n`;
 }
 function tomlValue(value: unknown): string {
   if (typeof value === "boolean") return value ? "true" : "false";
@@ -733,6 +762,11 @@ export function main(): number {
     return 1;
   }
   const agents = fs.readdirSync(path.join(root, "agents")).filter((name) => name.endsWith(".json")).sort().map((name) => loadJson<Agent>(path.join(root, "agents", name)));
+  const routingErrors = codexAgentRoutingErrors(manifest, agents.map((agent) => agent.name));
+  if (routingErrors.length) {
+    for (const error of routingErrors) console.error(`flow-agents: packaging/manifest.json: ${error}`);
+    return 1;
+  }
   buildBase(agents);
   buildKiro(agents);
   buildClaudeCode(agents);

package/src/tools/codex-agent-routing.ts

@@ -0,0 +1,48 @@
+export const CODEX_REASONING_EFFORTS = new Set(["low", "medium", "high", "xhigh", "max", "ultra"]);
+
+export function codexAgentRoutingErrors(manifest: any, agentNames: Iterable<string>): string[] {
+  const errors: string[] = [];
+  const knownAgents = new Set(agentNames);
+  const allowedModels = manifest.codex?.allowed_agent_models;
+  if (!Array.isArray(allowedModels) || allowedModels.length === 0) {
+    errors.push("codex.allowed_agent_models must be a non-empty list");
+  }
+  const allowedModelSet = new Set(Array.isArray(allowedModels) ? allowedModels : []);
+  for (const model of allowedModelSet) {
+    if (typeof model !== "string" || !model) errors.push("codex.allowed_agent_models entries must be non-empty strings");
+  }
+  if (allowedModelSet.size !== (Array.isArray(allowedModels) ? allowedModels.length : 0)) {
+    errors.push("codex.allowed_agent_models must not contain duplicates");
+  }
+
+  for (const [family, model] of Object.entries(manifest.codex_model_map ?? {})) {
+    if (!allowedModelSet.has(model)) errors.push(`codex_model_map.${family} uses unsupported model '${String(model)}'`);
+  }
+  for (const [family, effort] of Object.entries(manifest.codex_reasoning_map ?? {})) {
+    if (!CODEX_REASONING_EFFORTS.has(String(effort))) errors.push(`codex_reasoning_map.${family} uses invalid reasoning effort '${String(effort)}'`);
+  }
+
+  const agentMap = manifest.codex_agent_map;
+  if (!agentMap || typeof agentMap !== "object" || Array.isArray(agentMap)) {
+    errors.push("codex_agent_map must be an object");
+    return errors;
+  }
+  for (const [agentName, override] of Object.entries(agentMap)) {
+    if (!knownAgents.has(agentName)) errors.push(`codex_agent_map agent '${agentName}' does not exist`);
+    if (!override || typeof override !== "object" || Array.isArray(override)) {
+      errors.push(`codex_agent_map.${agentName} must be an object`);
+      continue;
+    }
+    const entry = override as Record<string, unknown>;
+    if (Object.keys(entry).sort().join(",") !== "model,reasoning_effort") {
+      errors.push(`codex_agent_map.${agentName} must contain exactly model and reasoning_effort`);
+    }
+    if (!allowedModelSet.has(entry.model)) {
+      errors.push(`codex_agent_map.${agentName}.model uses unsupported model '${String(entry.model)}'`);
+    }
+    if (!CODEX_REASONING_EFFORTS.has(String(entry.reasoning_effort))) {
+      errors.push(`codex_agent_map.${agentName}.reasoning_effort is invalid: '${String(entry.reasoning_effort)}'`);
+    }
+  }
+  return errors;
+}

package/src/tools/generate-context-map.ts

@@ -28,6 +28,7 @@ const commands = [
   ["Claim lookup", "npm run workflow:sidecar -- claim <id> <dir>"],
   ["Context map drift", "npm run context-map:check"],
   ["Bundle build", "npm run build:bundles"],
+  ["Skill drift check", "flow-agents skill-drift-check"],
 ];
 
 function frontmatter(text: string): Record<string, string> {

package/src/tools/validate-source-tree.ts

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { validateKitRepository as validateFlowKitRepository } from "../flow-kit/validate.js";
+import { codexAgentRoutingErrors } from "./codex-agent-routing.js";
 import { loadJson, readText, rel, root, walkFiles } from "./common.js";
 
 class Reporter {
@@ -31,6 +32,8 @@ const mirroredFiles = new Map<string, { mirror: string; allowedDifferences: Arra
   // fails `npm run validate:source` instead of silently accumulating.
   ["scripts/hooks/config-protection.js", { mirror: "context/scripts/hooks/config-protection.js", allowedDifferences: [] }],
   ["scripts/hooks/lib/config-protection-remedies.js", { mirror: "context/scripts/hooks/lib/config-protection-remedies.js", allowedDifferences: [] }],
+  ["scripts/hooks/lib/kit-catalog.js", { mirror: "context/scripts/hooks/lib/kit-catalog.js", allowedDifferences: [] }],
+  ["scripts/hooks/lib/runnable-command.js", { mirror: "context/scripts/hooks/lib/runnable-command.js", allowedDifferences: [] }],
   ["scripts/hooks/stop-goal-fit.js", { mirror: "context/scripts/hooks/stop-goal-fit.js", allowedDifferences: [] }],
   ["scripts/hooks/run-hook.js", { mirror: "context/scripts/hooks/run-hook.js", allowedDifferences: [] }],
   ["scripts/hooks/workflow-steering.js", { mirror: "context/scripts/hooks/workflow-steering.js", allowedDifferences: [] }],
@@ -82,9 +85,11 @@ const hookFilePolicies = new Map<string, { category: string; requiredNeedles: st
   ["scripts/hooks/desktop-notify.sh", { category: "local notification helper", requiredNeedles: ["desktop-notify.sh", "osascript"] }],
   ["scripts/hooks/lib/actor-identity.js", { category: "shared hook library", requiredNeedles: ["resolveActor", "FLOW_AGENTS_ACTOR"] }],
   ["scripts/hooks/lib/audit-transport.sh", { category: "shared hook library", requiredNeedles: ["audit_emit"] }],
+  ["scripts/hooks/lib/codex-exit-code.js", { category: "shared hook library", requiredNeedles: ["extractExitCodeFromBanner", "readExitCodeFromRollout"] }],
   ["scripts/hooks/lib/config-protection-remedies.js", { category: "shared hook library", requiredNeedles: ["SANCTIONED_REMEDIES", "REMEDY_COMMAND_CANDIDATES"] }],
   ["scripts/hooks/lib/current-pointer.js", { category: "shared hook library", requiredNeedles: ["readCurrentPointer", "perActorCurrentFile"] }],
   ["scripts/hooks/lib/hook-flags.js", { category: "shared hook library", requiredNeedles: ["isHookEnabled"] }],
+  ["scripts/hooks/lib/kit-catalog.js", { category: "shared hook library", requiredNeedles: ["readKitManifests", "workflowTriggersFor"] }],
   ["scripts/hooks/lib/liveness-heartbeat.js", { category: "shared hook library", requiredNeedles: ["maybeEmitHeartbeat", "resolveHeartbeatThrottleSeconds"] }],
   ["scripts/hooks/lib/liveness-policy.js", { category: "shared hook library", requiredNeedles: ["isLivenessEnabled", "resolveTtlSeconds"] }],
   ["scripts/hooks/lib/liveness-read.js", { category: "shared hook library", requiredNeedles: ["freshHolders", "readLivenessEvents"] }],
@@ -92,18 +97,23 @@ const hookFilePolicies = new Map<string, { category: string; requiredNeedles: st
   ["scripts/hooks/lib/local-artifact-paths.js", { category: "shared hook library", requiredNeedles: ["flowAgentsArtifactRoot", "defaultArtifactRootForRead"] }],
   ["scripts/hooks/lib/patterns.sh", { category: "shared hook library", requiredNeedles: ["_detect_secrets"] }],
   ["scripts/hooks/lib/resolve-formatter.js", { category: "shared hook library", requiredNeedles: ["resolveFormatter"] }],
+  ["scripts/hooks/lib/runnable-command.js", { category: "shared hook library", requiredNeedles: ["isRunnableCommandText"] }],
+  ["scripts/hooks/lib/skill-drift.js", { category: "shared hook library", requiredNeedles: ["compareSkillDrift", "buildManifest"] }],
 ]);
 const fixtureOwnerPolicies = new Map<string, { owners: string[]; classification: string }>([
   ["evals/fixtures/assignment-provider", { owners: ["evals/integration/test_assignment_provider_local_file.sh", "evals/integration/test_assignment_provider_github.sh", "evals/integration/test_pull_work_assignment_join.sh", "evals/integration/test_ensure_session_ownership_guard.sh"], classification: "AssignmentProvider local-file and GitHub render/status fixtures (#290); hostile-effective-state.json is the #291 ensure-session ownership guard's AC9 sanitization fixture" }],
   ["evals/fixtures/backlog-provider-settings", { owners: ["evals/integration/test_effective_backlog_settings.sh"], classification: "settings precedence fixtures" }],
   ["evals/fixtures/builder-kit-workflow-state", { owners: ["evals/static/test_workflow_skills.sh"], classification: "Builder Kit workflow-state fixtures" }],
   ["evals/fixtures/console-learning-projection", { owners: ["evals/integration/test_console_learning_projection.sh"], classification: "console learning projection fixtures" }],
+  ["evals/fixtures/economics", { owners: ["evals/integration/test_economics_record.sh"], classification: "per-run kit-economics record fixtures (#349): a transcript with .message.usage blocks, state.json/acceptance.json/critique.json join sources, a session.usage event, and the golden expected kontour.console.economics record" }],
   ["evals/fixtures/flow-kit-repository", { owners: ["evals/integration/test_flow_kit_repository.sh", "evals/integration/test_local_flow_kit_install.sh", "evals/integration/test_runtime_adapter_activation.sh", "evals/integration/test_activate_npx_context.sh", "evals/integration/test_flow_kit_install_git.sh", "evals/static/test_workflow_skills.sh"], classification: "Flow Kit repository contract fixtures" }],
   ["evals/fixtures/kit-conformance-levels", { owners: ["evals/integration/test_kit_conformance_levels.sh"], classification: "K-level conformance and consumer-target derivation fixtures" }],
   ["evals/fixtures/hook-influence", { owners: ["evals/integration/test_hook_influence_cases.sh", "evals/static/test_workflow_skills.sh", "scripts/validate-hook-influence-cases.js"], classification: "hook influence behavioral cases" }],
+  ["evals/fixtures/learning-review-proposals", { owners: ["evals/integration/test_learning_review_proposals.sh"], classification: "learning-review kit/gate tuning proposal fixtures (#352): pattern-present (engineered cost-inflation + gate false-block-rate pattern, with sessions/ trust.bundle + gate-review.inquiries.json joins and a hand-computed expected-aggregates.json), balanced (proportional cost/findings movement -> zero proposals), under-threshold (below LR_MIN_WINDOW_SAMPLE), repeat-window (idempotency), and effect-follow-up (later-window effect-fill pass for a ratified proposal)" }],
   ["evals/fixtures/pull-work-provider", { owners: ["evals/integration/test_pull_work_provider.sh"], classification: "work item provider normalization fixtures" }],
   ["evals/fixtures/pull-work-wip-shepherding", { owners: ["evals/static/test_workflow_skills.sh"], classification: "WIP shepherding state fixtures" }],
   ["evals/fixtures/surface-trust", { owners: ["evals/integration/test_workflow_sidecar_writer.sh"], classification: "Surface trust evidence fixtures" }],
+  ["evals/fixtures/telemetry", { owners: ["evals/integration/test_usage_cost.sh", "evals/integration/test_telemetry_usage_pipeline.sh"], classification: "hermetic Stop-hook usage transcript fixture (#defect-2026-07 telemetry-usage-cost-extraction): a multi-model JSONL transcript with .message.model + .message.usage token blocks proving real token/cost/model extraction end-to-end" }],
   ["evals/fixtures/reconcile-preflight", { owners: ["evals/integration/test_reconcile_preflight.sh"], classification: "#356 reconcile-preflight shape fixtures not already covered by trust-reconcile-exploits (un-superseded disputed critique, standalone disputed session-local claim)" }],
   ["evals/fixtures/trust-reconcile-exploits", { owners: ["evals/integration/test_trust_reconcile_negatives.sh", "evals/integration/test_reconcile_preflight.sh"], classification: "WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions); also reused by the #356 local reconcile-preflight eval (same shapes, no forked copies)" }],
   ["evals/fixtures/trust-reconcile-mixed-bundle", { owners: ["evals/integration/test_trust_reconcile_mixed_bundle.sh", "evals/integration/test_reconcile_preflight.sh"], classification: "WS8 trust-reconcile mixed-evidence end-to-end proof fixture; also reused by the #356 reconcile-preflight eval as its CLEAN-BUNDLE (AC4) case" }],
@@ -130,6 +140,9 @@ const allowedPythonCommandFiles = [
   // as prose). These are literal recognizer tokens, NOT a flow-agents Python dependency — no
   // .py file is ever invoked — so the two byte-identical mirror copies are exempt here.
   /^(context\/)?scripts\/hooks\/stop-goal-fit\.js$/,
+  // #412: the recognizer allowlist itself now lives in scripts/hooks/lib/runnable-command.js
+  // (single source of truth), so the same literal-token exemption applies there too.
+  /^(context\/)?scripts\/hooks\/lib\/runnable-command\.js$/,
 ];
 
 function tryLoadJson(file: string, reporter: Reporter): any {
@@ -197,6 +210,7 @@ function validateManifest(reporter: Reporter, manifest: any, agentNames: Set<str
   }
   for (const dir of manifest.optional_copy_dirs ?? []) if (!fs.existsSync(path.join(root, dir))) console.log(`warning: ${rel(manifestPath)} optional_copy_dirs entry absent: ${dir}`);
   for (const agent of manifest.codex?.excluded_agents ?? []) reporter.check(agentNames.has(agent), `${rel(manifestPath)}: codex excluded agent '${agent}' does not exist`);
+  for (const error of codexAgentRoutingErrors(manifest, agentNames)) reporter.fail(`${rel(manifestPath)}: ${error}`);
 }
 async function validateKitRepository(kitDir: string, reporter: Reporter): Promise<void> {
   if (!fs.existsSync(kitDir) || !fs.statSync(kitDir).isDirectory()) { reporter.fail(`${rel(kitDir)}: kit directory does not exist`); return; }
@@ -241,6 +255,16 @@ function validateLegacyRefs(reporter: Reporter): void {
   // Collect all kit-owned asset relative paths so legacy-ref scanning can skip matches
   // that are subpaths of kit-owned assets. E.g. legacyRefRe matches "skills/plan-work/SKILL.md"
   // within "kits/builder/skills/plan-work/SKILL.md"; the kit declares and validates these.
+  //
+  // Deliberately NO directory-level exemption: a ref must be an exact registered path, or a
+  // parent directory of one, to be skipped. A kit that ships a helper file living alongside a
+  // registered asset (e.g. a skill's own script next to its SKILL.md) must register that
+  // helper as its own kit.json entry (e.g. under an "assets" section) rather than relying on
+  // sibling-directory proximity — widening the exemption to "any file in the same directory
+  // as a registered path" would silence real missing-path detection for every OTHER file that
+  // happens to sit next to a registered asset, not just the intended one. See
+  // kits/veritas-governance/kit.json's "assets" section for the registration this exact case
+  // uses.
   const kitOwnedSubPaths = new Set<string>();
   const kitsDir = path.join(root, "kits");
   if (fs.existsSync(kitsDir)) {
@@ -271,7 +295,8 @@ function validateLegacyRefs(reporter: Reporter): void {
       if (ref.split(/[\\/]/).includes("node_modules")) continue;
       // Skip refs that are declared kit-owned asset paths or their parent directories
       // (e.g. "skills/plan-work/SKILL.md" or "skills/plan-work" matched inside
-      // "kits/builder/skills/plan-work/SKILL.md" in eval files).
+      // "kits/builder/skills/plan-work/SKILL.md" in eval files). No directory-level
+      // exemption — see the kitOwnedSubPaths comment above.
       if (kitOwnedSubPaths.has(ref) || [...kitOwnedSubPaths].some((p) => p.startsWith(ref + "/"))) continue;
       const candidates = [path.join(root, ref), ...(ref.startsWith("evals/") ? [] : [path.join(root, "evals", ref)])];
       if (!candidates.some(fs.existsSync)) reporter.fail(`${rel(file)}: references missing source path: ${ref}`);