@kontourai/flow-agents 2.4.0 → 3.1.0

package/src/cli.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { basename } from "node:path";
 import { main as effectiveBacklogSettings } from "./cli/effective-backlog-settings.js";
+import { main as effectiveAssignmentProviderSettings } from "./cli/effective-assignment-provider-settings.js";
+import { main as assignmentProvider } from "./cli/assignment-provider.js";
 import { main as consoleLearningProjection } from "./cli/console-learning-projection.js";
 import { main as kit } from "./cli/kit.js";
 import { main as fixtureRetirementAudit } from "./cli/fixture-retirement-audit.js";
@@ -25,6 +27,8 @@ const availableCommands = new Map<string, (argv: string[]) => number | Promise<n
   ["build-bundles", () => buildBundles()],
   ["console-learning-projection", consoleLearningProjection],
   ["context-map", contextMap],
+  ["assignment-provider", assignmentProvider],
+  ["effective-assignment-provider-settings", effectiveAssignmentProviderSettings],
   ["effective-backlog-settings", effectiveBacklogSettings],
   ["fixture-retirement-audit", fixtureRetirementAudit],
   ["kit", kit],
@@ -48,6 +52,8 @@ const aliases = new Map<string, string>([
   ["flow-agents-build-bundles", "build-bundles"],
   ["flow-agents-console-learning-projection", "console-learning-projection"],
   ["flow-agents-context-map", "context-map"],
+  ["flow-agents-assignment-provider", "assignment-provider"],
+  ["flow-agents-effective-assignment-provider-settings", "effective-assignment-provider-settings"],
   ["flow-agents-effective-backlog-settings", "effective-backlog-settings"],
   ["flow-agents-fixture-retirement-audit", "fixture-retirement-audit"],
   ["flow-agents-kit", "kit"],

package/src/lib/flow-resolver.ts

@@ -15,6 +15,8 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 
 // ─── Security: Layer 1 traversal defense ─────────────────────────────────────
 //
@@ -323,28 +325,47 @@ function findRepoRoot(startDir: string): string {
   return process.cwd();
 }
 
+/**
+ * Delegate to the shared pure-CJS per-actor current-pointer reader
+ * (scripts/hooks/lib/current-pointer.js), mirroring the exact createRequire idiom
+ * workflow-sidecar.ts already uses for its own cross-boundary CJS helper reuse (Wave 2 Task 2.2,
+ * #291). Deliberately NO inline duplicate fallback — this is the single choke point for the
+ * per-actor-first/legacy-fallback compat-shim rule; a second hand-rolled reader here would let it
+ * drift from every other consumer.
+ */
+function loadCurrentPointerHelper(): {
+  readCurrentPointer: (flowAgentsDir: string, actorKey?: string) => { payload: Record<string, unknown> | null; source: "per-actor" | "legacy" | "none"; file: string | null };
+} {
+  const _req = createRequire(import.meta.url);
+  const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/current-pointer.js");
+  return _req(helperPath) as {
+    readCurrentPointer: (flowAgentsDir: string, actorKey?: string) => { payload: Record<string, unknown> | null; source: "per-actor" | "legacy" | "none"; file: string | null };
+  };
+}
+
 /**
  * Resolve the active flow step from current.json.
  *
- * Reads active_flow_id and active_step_id from <flowAgentsDir>/current.json.
- * If both are present, delegates to resolveFlowStep. The repoRoot is derived by
- * walking upward from flowAgentsDir to find the nearest ancestor containing kits/,
- * with a fallback to process.cwd(). This handles temp dirs, CI workspaces, and
- * subproject layouts without hardcoding the repo structure.
+ * Reads active_flow_id and active_step_id via the shared per-actor current-pointer helper
+ * (#291 Wave 2 Task 2.2): when `actorKey` is a resolved actor with its own
+ * `current/<actor>.json` projection, that file is preferred; otherwise (no actorKey, an
+ * unresolved actor, or no per-actor file yet) this falls straight back to the legacy global
+ * `<flowAgentsDir>/current.json` — IDENTICAL to this function's pre-#291 behavior for every
+ * caller that does not pass `actorKey`. The repoRoot is derived by walking upward from
+ * flowAgentsDir to find the nearest ancestor containing kits/, with a fallback to
+ * process.cwd(). This handles temp dirs, CI workspaces, and subproject layouts without
+ * hardcoding the repo structure.
  *
  * @param flowAgentsDir Path to the runtime artifact root directory (contains current.json).
+ * @param actorKey Optional resolved actor identity (Wave 2 Task 2.1's `writeCurrent()` dual-write
+ *   key) — when omitted, behavior is unchanged (legacy-file-only, exactly as before #291).
  * @returns ActiveFlowStep or null when fields are absent or resolution fails.
  */
-export function resolveActiveFlowStep(flowAgentsDir: string): ActiveFlowStep | null {
+export function resolveActiveFlowStep(flowAgentsDir: string, actorKey?: string): ActiveFlowStep | null {
   if (!flowAgentsDir) return null;
-  const currentFile = path.join(flowAgentsDir, "current.json");
-  let current: Record<string, unknown>;
-  try {
-    const raw = fs.readFileSync(currentFile, "utf8");
-    current = JSON.parse(raw) as Record<string, unknown>;
-  } catch {
-    return null;
-  }
+  const pointer = loadCurrentPointerHelper().readCurrentPointer(flowAgentsDir, actorKey);
+  if (pointer.source === "none" || !pointer.payload) return null;
+  const current = pointer.payload;
 
   const flowId = typeof current["active_flow_id"] === "string" ? current["active_flow_id"] : null;
   const stepId = typeof current["active_step_id"] === "string" ? current["active_step_id"] : null;

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

@@ -83,6 +83,7 @@ const hookFilePolicies = new Map<string, { category: string; requiredNeedles: st
   ["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/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/liveness-heartbeat.js", { category: "shared hook library", requiredNeedles: ["maybeEmitHeartbeat", "resolveHeartbeatThrottleSeconds"] }],
   ["scripts/hooks/lib/liveness-policy.js", { category: "shared hook library", requiredNeedles: ["isLivenessEnabled", "resolveTtlSeconds"] }],
@@ -93,6 +94,7 @@ const hookFilePolicies = new Map<string, { category: string; requiredNeedles: st
   ["scripts/hooks/lib/resolve-formatter.js", { category: "shared hook library", requiredNeedles: ["resolveFormatter"] }],
 ]);
 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" }],