lazycodex-ai 5.0.0-beta.57 → 5.0.0-beta.60

package/packages/omo-codex/plugin/components/ulw-loop/dist/cli-subcommands.js

@@ -3,15 +3,11 @@ import { hasFlag, parseCodexGoalJson, parseRecordEvidenceArgs, positionalText, r
 import { blockedDecisionHandoff, normalizeCodexGoalMode, printJson, printStatus } from "./cli-output.js";
 import { parseSteeringProposals, printSteerBatchResult, printSteerResult } from "./cli-steering.js";
 import { buildCodexGoalInstruction } from "./codex-goal-instruction.js";
-import { recordEvidence } from "./evidence.js";
 import { isEssentialCriterion } from "./goal-status.js";
-import { ulwLoopAttemptEvidenceDir } from "./paths.js";
-import { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "./plan-crud.js";
-import { readUlwLoopPlan } from "./plan-io.js";
-import { recordFinalReviewBlockers } from "./review-blockers.js";
-import { statusNextActions } from "./status-next-actions.js";
-import { steerUlwLoop } from "./steering.js";
+import { summarizeUlwLoopPlan } from "./plan-crud.js";
+import { createAgentToolkit } from "./sdk.js";
 import { steerUlwLoopBatch } from "./steering-batch.js";
+import { resolveToolkitSurface } from "./surface.js";
 import { UlwLoopError } from "./types.js";
 export async function createGoals(repoRoot, argv, json, scope) {
     const briefFile = readValue(argv, "--brief-file");
@@ -23,12 +19,12 @@ export async function createGoals(repoRoot, argv, json, scope) {
         throw new UlwLoopError("Missing brief text. Pass --brief, --brief-file, --from-stdin, or positional text.", "ULW_LOOP_BRIEF_REQUIRED");
     }
     const validationBatchesJson = readValue(argv, "--validation-batch-json");
-    const plan = await createUlwLoopPlan(repoRoot, {
+    const plan = unwrap(await toolkitFor(repoRoot, scope).createGoals({
         brief,
         codexGoalMode: normalizeCodexGoalMode(readValue(argv, "--codex-goal-mode")),
         force: hasFlag(argv, "--force"),
         ...(validationBatchesJson === undefined ? {} : { validationBatchesJson }),
-    }, scope);
+    }));
     if (json)
         printJson({ ok: true, plan, summary: summarizeUlwLoopPlan(plan) });
     else {
@@ -37,26 +33,15 @@ export async function createGoals(repoRoot, argv, json, scope) {
     return 0;
 }
 export async function status(repoRoot, json, scope) {
-    const plan = await readUlwLoopPlan(repoRoot, scope);
-    if (json) {
-        const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
-        const currentAttemptDir = plan.evidenceLayoutVersion === 2 && active
-            ? ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope)
-            : undefined;
-        printJson({
-            ok: true,
-            plan,
-            summary: summarizeUlwLoopPlan(plan),
-            ...(currentAttemptDir === undefined ? {} : { currentAttemptDir }),
-            nextActions: statusNextActions(plan),
-        });
-    }
+    const status = unwrap(await toolkitFor(repoRoot, scope).status());
+    if (json)
+        printJson({ ok: true, ...status });
     else
-        printStatus(plan);
+        printStatus(status.plan);
     return 0;
 }
 export async function completeGoals(repoRoot, argv, json, scope) {
-    const result = await startNextUlwLoop(repoRoot, { retryFailed: hasFlag(argv, "--retry-failed") }, scope);
+    const result = unwrap(await toolkitFor(repoRoot, scope).completeGoals({ retryFailed: hasFlag(argv, "--retry-failed") }));
     if ("done" in result) {
         const handoff = blockedDecisionHandoff(result.plan);
         if (json) {
@@ -84,7 +69,7 @@ export async function steer(repoRoot, argv, json, scope) {
     const proposals = await parseSteeringProposals(argv);
     const single = proposals[0];
     if (single !== undefined && proposals.length === 1 && readValue(argv, "--proposals-json") === undefined) {
-        const result = await steerUlwLoop(repoRoot, single, scope);
+        const result = unwrap(await toolkitFor(repoRoot, scope).steer(single));
         printSteerResult(result, json);
         return result.accepted ? 0 : 1;
     }
@@ -93,7 +78,10 @@ export async function steer(repoRoot, argv, json, scope) {
     return result.accepted ? 0 : 1;
 }
 export async function addGoal(repoRoot, argv, json, scope) {
-    const result = await addUlwLoopGoal(repoRoot, { title: required(argv, "--title"), objective: required(argv, "--objective") }, scope);
+    const result = unwrap(await toolkitFor(repoRoot, scope).addGoal({
+        title: required(argv, "--title"),
+        objective: required(argv, "--objective"),
+    }));
     if (json)
         printJson({ ok: true, plan: result.plan, goal: result.goal, summary: summarizeUlwLoopPlan(result.plan) });
     else {
@@ -104,16 +92,16 @@ export async function addGoal(repoRoot, argv, json, scope) {
 }
 export async function criteria(repoRoot, argv, json, scope) {
     const goalId = required(argv, "--goal-id");
-    const goal = findGoal(await readUlwLoopPlan(repoRoot, scope), goalId);
+    const result = unwrap(await toolkitFor(repoRoot, scope).criteria({ goalId }));
     if (json)
-        printJson({ ok: true, goalId: goal.id, criteria: goal.successCriteria });
+        printJson({ ok: true, goalId: result.goalId, criteria: result.criteria });
     else {
-        process.stdout.write(`criteria for ${goal.id}:\n${goal.successCriteria.map(formatCriterionForCli).join("\n")}\n`);
+        process.stdout.write(`criteria for ${result.goalId}:\n${result.criteria.map(formatCriterionForCli).join("\n")}\n`);
     }
     return 0;
 }
 export async function captureEvidence(repoRoot, argv, json, scope) {
-    const result = await recordEvidence(repoRoot, parseRecordEvidenceArgs(argv), scope);
+    const result = unwrap(await toolkitFor(repoRoot, scope).recordEvidence(parseRecordEvidenceArgs(argv)));
     if (json)
         printJson({ ok: true, ...result, summary: summarizeUlwLoopPlan(result.plan) });
     else {
@@ -126,13 +114,13 @@ export async function reviewBlockers(repoRoot, argv, json, scope) {
     if (codexGoalJson === undefined) {
         throw new UlwLoopError("Missing --codex-goal-json.", "ULW_LOOP_CODEX_GOAL_JSON_REQUIRED");
     }
-    const result = await recordFinalReviewBlockers(repoRoot, {
+    const result = unwrap(await toolkitFor(repoRoot, scope).recordReviewBlockers({
         goalId: required(argv, "--goal-id"),
         title: required(argv, "--title"),
         objective: required(argv, "--objective"),
         evidence: required(argv, "--evidence"),
         codexGoalJson,
-    }, scope);
+    }));
     if (json) {
         printJson({
             ok: true,
@@ -150,6 +138,23 @@ export async function reviewBlockers(repoRoot, argv, json, scope) {
     }
     return 0;
 }
+// Every subcommand runs through the SDK so state logic lives in one place; the CLI keeps only argv
+// parsing and the legacy output shapes. A failed envelope is rethrown as the typed error the CLI's
+// JSON error path already prints.
+function toolkitFor(repoRoot, scope) {
+    const sessionId = scope?.sessionId?.trim();
+    if (sessionId === undefined || sessionId.length === 0) {
+        throw new UlwLoopError("Missing --session-id.", "ULW_LOOP_SESSION_ID_REQUIRED", {
+            details: { flag: "--session-id" },
+        });
+    }
+    return createAgentToolkit({ cwd: repoRoot, sessionId, surface: resolveToolkitSurface() });
+}
+function unwrap(response) {
+    if (response.ok)
+        return response.result;
+    throw new UlwLoopError(response.error.message, response.error.code);
+}
 function formatCriterionForCli(criterion) {
     const marker = isEssentialCriterion(criterion) ? "essential" : "non-essential";
     return `- ${criterion.id} [${criterion.status}] [${marker}] (${criterion.userModel}) ${criterion.scenario} evidence: ${criterion.capturedEvidence ?? "pending"}`;
@@ -160,9 +165,3 @@ function required(argv, flag) {
         return value;
     throw new UlwLoopError(`Missing ${flag}.`, "ULW_LOOP_ARGUMENT_MISSING", { details: { flag } });
 }
-function findGoal(plan, goalId) {
-    const goal = plan.goals.find((candidate) => candidate.id === goalId);
-    if (goal !== undefined)
-        return goal;
-    throw new UlwLoopError(`Unknown ulw-loop id: ${goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND", { details: { goalId } });
-}

package/packages/omo-codex/plugin/components/ulw-loop/dist/cli.js

@@ -1569,7 +1569,7 @@ function buildLedger(now, args, goal, qualityGate, codexGoal, aggregateCompletio
     entry.requiredExternalDecision = goal.requiredExternalDecision;
   return entry;
 }
-async function checkpointUlwLoop(repoRoot, args, scope) {
+async function checkpointUlwLoop(repoRoot, args, scope, dependencies) {
   return withUlwLoopMutationLock(repoRoot, scope, async () => {
     const plan = await readUlwLoopPlan(repoRoot, scope);
     const goal = findGoal2(plan, args.goalId);
@@ -1621,7 +1621,7 @@ async function checkpointUlwLoop(repoRoot, args, scope) {
           qualityGate = validateQualityGate(await readJsonInput2(args.qualityGateJson, repoRoot), {
             repoRoot,
             fs: QUALITY_GATE_FS,
-            reviewerSurface: resolveToolkitSurface(),
+            reviewerSurface: dependencies?.surface ?? resolveToolkitSurface(),
             ...plan.evidenceLayoutVersion === 2 ? { currentAttemptDir: ulwLoopAttemptEvidenceDir(goal.id, goal.attempt, scope) } : {}
           });
           requireBatchGate(plan, goal, qualityGate);
@@ -1740,8 +1740,9 @@ function gateTemplate(surface, base) {
   };
   return common;
 }
-async function checkpointTemplate(repoRoot, scope, goalId) {
+async function checkpointTemplate(repoRoot, scope, goalId, dependencies) {
   const plan = await readUlwLoopPlan(repoRoot, scope);
+  const surface = dependencies?.surface ?? resolveToolkitSurface();
   const targetId = goalId ?? plan.activeGoalId;
   const active = plan.goals.find((goal) => goal.id === targetId);
   if (goalId !== undefined && active === undefined)
@@ -1753,13 +1754,13 @@ async function checkpointTemplate(repoRoot, scope, goalId) {
     "Fill every <replace:...> value with plausible non-empty evidence and use real, non-empty artifact files.",
     'Passing codex-goal-json example: {"goal":{"objective":"<plan codexObjective verbatim>","status":"complete"}}.',
     'Passing quality-gate-json example requires gateReview {"by":"category:deep","recommendation":"APPROVE","evidence":"review passed","reportPath":"<attemptDir>/gate-review.md","blockers":[],"notes":[]}, manualQa.artifactRefs objects, iteration, and criteriaCoverage.',
-    ...resolveToolkitSurface() === "lazycodex" ? [
+    ...surface === "lazycodex" ? [
       "Self-review defaults: manualQa.by and gateReview.by are main-session. Alternatives: manualQa.by accepts lazycodex-qa-executor; gateReview.by accepts lazycodex-gate-reviewer, category:deep, category:unspecified-high, or category:unspecified-low. Optional codeReview.by accepts lazycodex-code-reviewer or main-session."
     ] : [],
     ...hasAttempt ? [] : ["This plan is evidence-layout v1; artifacts go under .omo/evidence/."]
   ].join(" ");
   return {
-    qualityGateTemplate: gateTemplate(resolveToolkitSurface(), attemptDir),
+    qualityGateTemplate: gateTemplate(surface, attemptDir),
     codexGoalTemplate: {
       goal: { objective: plan.codexObjective ?? "<replace:codex objective>", status: "complete" }
     },
@@ -3039,6 +3040,129 @@ function ledgerEntry(proposal, audit, at) {
   return entry;
 }
 
+// components/ulw-loop/src/sdk/manifest.ts
+var ULW_LOOP_MANIFEST = {
+  version: 1,
+  name: "ulw-loop",
+  operations: [
+    { name: "help", mutating: false },
+    { name: "create-goals", mutating: true },
+    { name: "status", mutating: false },
+    { name: "complete-goals", mutating: true },
+    { name: "checkpoint", mutating: true },
+    { name: "steer", mutating: true },
+    { name: "add-goal", mutating: true },
+    { name: "criteria", mutating: false },
+    { name: "record-evidence", mutating: true },
+    { name: "record-review-blockers", mutating: true }
+  ]
+};
+
+// components/ulw-loop/src/sdk/factory.ts
+function validateContext(context) {
+  if (!context.cwd.trim())
+    throw new UlwLoopError("cwd is required.", "ULW_LOOP_CWD_REQUIRED");
+  if (!context.sessionId.trim())
+    throw new UlwLoopError("ULW_LOOP_SESSION_ID_REQUIRED: sessionId is required.", "ULW_LOOP_SESSION_ID_REQUIRED");
+  if (context.surface !== "omo-senpi" && context.surface !== "lazycodex")
+    throw new UlwLoopError("surface must be omo-senpi or lazycodex.", "ULW_LOOP_SURFACE_INVALID");
+}
+function errorDetails(error) {
+  const details = error.details === undefined ? undefined : Object.fromEntries(Object.entries(error.details).map(([key, value]) => [key, String(value)]));
+  return details === undefined ? { code: error.code, message: error.message } : { code: error.code, message: error.message, details };
+}
+function failure(operation, error) {
+  return { ok: false, operation, error: errorDetails(error) };
+}
+function caught(operation, error) {
+  return failure(operation, error instanceof UlwLoopError ? error : new UlwLoopError(error.message, "ULW_LOOP_ERROR"));
+}
+function isKnownRequest(request) {
+  return ULW_LOOP_MANIFEST.operations.some((operation) => operation.name === request.operation);
+}
+function unreachable(value) {
+  throw new UlwLoopError(`Unhandled operation: ${String(value)}`, "ULW_LOOP_OPERATION_UNHANDLED");
+}
+function nextActionsFrom(result) {
+  if (!("nextActions" in result) || !Array.isArray(result.nextActions))
+    return [];
+  return result.nextActions.filter((action) => typeof action === "string").slice(0, 8);
+}
+function createAgentToolkit(context, deps = {}) {
+  validateContext(context);
+  const scope = { sessionId: context.sessionId };
+  const notify = async (operation, response) => {
+    if (deps.hooks?.onOperation !== undefined)
+      await deps.hooks.onOperation({ operation, context, response });
+    return response;
+  };
+  const invoke = async (operation, fn) => {
+    try {
+      const result = await fn();
+      const nextActions = typeof result === "object" && result !== null ? nextActionsFrom(result) : [];
+      return await notify(operation, { ok: true, operation, result, nextActions });
+    } catch (error) {
+      const response = caught(operation, error instanceof Error ? error : new Error("ULW_LOOP_ERROR"));
+      return notify(operation, response);
+    }
+  };
+  const toolkit = {
+    dispatch: async (request) => {
+      if (!isKnownRequest(request))
+        return failure(request.operation, new UlwLoopError(`Unknown operation: ${request.operation}`, "ULW_LOOP_OPERATION_UNKNOWN"));
+      switch (request.operation) {
+        case "help":
+          return toolkit.help();
+        case "create-goals":
+          return toolkit.createGoals(request.args);
+        case "status":
+          return toolkit.status();
+        case "complete-goals":
+          return toolkit.completeGoals(request.args);
+        case "checkpoint":
+          return toolkit.checkpoint(request.args);
+        case "steer":
+          return toolkit.steer(request.args);
+        case "add-goal":
+          return toolkit.addGoal(request.args);
+        case "criteria":
+          return toolkit.criteria(request.args);
+        case "record-evidence":
+          return toolkit.recordEvidence(request.args);
+        case "record-review-blockers":
+          return toolkit.recordReviewBlockers(request.args);
+        default:
+          return unreachable(request);
+      }
+    },
+    help: () => invoke("help", async () => ULW_LOOP_MANIFEST),
+    createGoals: (args) => invoke("create-goals", () => createUlwLoopPlan(context.cwd, args, scope)),
+    status: () => invoke("status", async () => {
+      const plan = await readUlwLoopPlan(context.cwd, scope);
+      const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+      return {
+        plan,
+        summary: summarizeUlwLoopPlan(plan),
+        nextActions: statusNextActions(plan),
+        ...active === undefined || plan.evidenceLayoutVersion !== 2 ? {} : { currentAttemptDir: ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope) }
+      };
+    }),
+    completeGoals: (args = {}) => invoke("complete-goals", () => startNextUlwLoop(context.cwd, args, scope)),
+    checkpoint: (args) => invoke("checkpoint", () => args.printTemplate === true ? checkpointTemplate(context.cwd, scope, args.goalId, { surface: context.surface }) : checkpointUlwLoop(context.cwd, args, scope, { surface: context.surface })),
+    steer: (args) => invoke("steer", () => steerUlwLoop(context.cwd, args, scope)),
+    addGoal: (args) => invoke("add-goal", () => addUlwLoopGoal(context.cwd, args, scope)),
+    criteria: (args) => invoke("criteria", async () => {
+      const plan = await readUlwLoopPlan(context.cwd, scope);
+      const goal = plan.goals.find((candidate) => candidate.id === args.goalId);
+      if (goal === undefined)
+        throw new UlwLoopError(`Unknown ulw-loop id: ${args.goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND");
+      return { goalId: goal.id, criteria: goal.successCriteria };
+    }),
+    recordEvidence: (args) => invoke("record-evidence", () => recordEvidence(context.cwd, args, scope)),
+    recordReviewBlockers: (args) => invoke("record-review-blockers", () => recordFinalReviewBlockers(context.cwd, args, scope))
+  };
+  return toolkit;
+}
 // components/ulw-loop/src/steering-batch.ts
 async function steerUlwLoopBatch(repoRoot, proposals, scope) {
   return withUlwLoopMutationLock(repoRoot, scope, async () => {
@@ -3128,12 +3252,12 @@ async function createGoals(repoRoot, argv, json, scope) {
     throw new UlwLoopError("Missing brief text. Pass --brief, --brief-file, --from-stdin, or positional text.", "ULW_LOOP_BRIEF_REQUIRED");
   }
   const validationBatchesJson = readValue(argv, "--validation-batch-json");
-  const plan = await createUlwLoopPlan(repoRoot, {
+  const plan = unwrap(await toolkitFor(repoRoot, scope).createGoals({
     brief,
     codexGoalMode: normalizeCodexGoalMode(readValue(argv, "--codex-goal-mode")),
     force: hasFlag(argv, "--force"),
     ...validationBatchesJson === undefined ? {} : { validationBatchesJson }
-  }, scope);
+  }));
   if (json)
     printJson({ ok: true, plan, summary: summarizeUlwLoopPlan(plan) });
   else {
@@ -3146,23 +3270,15 @@ ledger: ${plan.ledgerPath}
   return 0;
 }
 async function status(repoRoot, json, scope) {
-  const plan = await readUlwLoopPlan(repoRoot, scope);
-  if (json) {
-    const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
-    const currentAttemptDir = plan.evidenceLayoutVersion === 2 && active ? ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope) : undefined;
-    printJson({
-      ok: true,
-      plan,
-      summary: summarizeUlwLoopPlan(plan),
-      ...currentAttemptDir === undefined ? {} : { currentAttemptDir },
-      nextActions: statusNextActions(plan)
-    });
-  } else
-    printStatus(plan);
+  const status = unwrap(await toolkitFor(repoRoot, scope).status());
+  if (json)
+    printJson({ ok: true, ...status });
+  else
+    printStatus(status.plan);
   return 0;
 }
 async function completeGoals(repoRoot, argv, json, scope) {
-  const result = await startNextUlwLoop(repoRoot, { retryFailed: hasFlag(argv, "--retry-failed") }, scope);
+  const result = unwrap(await toolkitFor(repoRoot, scope).completeGoals({ retryFailed: hasFlag(argv, "--retry-failed") }));
   if ("done" in result) {
     const handoff = blockedDecisionHandoff(result.plan);
     if (json) {
@@ -3191,7 +3307,7 @@ async function steer(repoRoot, argv, json, scope) {
   const proposals = await parseSteeringProposals(argv);
   const single = proposals[0];
   if (single !== undefined && proposals.length === 1 && readValue(argv, "--proposals-json") === undefined) {
-    const result = await steerUlwLoop(repoRoot, single, scope);
+    const result = unwrap(await toolkitFor(repoRoot, scope).steer(single));
     printSteerResult(result, json);
     return result.accepted ? 0 : 1;
   }
@@ -3200,7 +3316,10 @@ async function steer(repoRoot, argv, json, scope) {
   return result.accepted ? 0 : 1;
 }
 async function addGoal(repoRoot, argv, json, scope) {
-  const result = await addUlwLoopGoal(repoRoot, { title: required4(argv, "--title"), objective: required4(argv, "--objective") }, scope);
+  const result = unwrap(await toolkitFor(repoRoot, scope).addGoal({
+    title: required4(argv, "--title"),
+    objective: required4(argv, "--objective")
+  }));
   if (json)
     printJson({ ok: true, plan: result.plan, goal: result.goal, summary: summarizeUlwLoopPlan(result.plan) });
   else {
@@ -3212,19 +3331,19 @@ async function addGoal(repoRoot, argv, json, scope) {
 }
 async function criteria(repoRoot, argv, json, scope) {
   const goalId = required4(argv, "--goal-id");
-  const goal = findGoal3(await readUlwLoopPlan(repoRoot, scope), goalId);
+  const result = unwrap(await toolkitFor(repoRoot, scope).criteria({ goalId }));
   if (json)
-    printJson({ ok: true, goalId: goal.id, criteria: goal.successCriteria });
+    printJson({ ok: true, goalId: result.goalId, criteria: result.criteria });
   else {
-    process.stdout.write(`criteria for ${goal.id}:
-${goal.successCriteria.map(formatCriterionForCli).join(`
+    process.stdout.write(`criteria for ${result.goalId}:
+${result.criteria.map(formatCriterionForCli).join(`
 `)}
 `);
   }
   return 0;
 }
 async function captureEvidence(repoRoot, argv, json, scope) {
-  const result = await recordEvidence(repoRoot, parseRecordEvidenceArgs(argv), scope);
+  const result = unwrap(await toolkitFor(repoRoot, scope).recordEvidence(parseRecordEvidenceArgs(argv)));
   if (json)
     printJson({ ok: true, ...result, summary: summarizeUlwLoopPlan(result.plan) });
   else {
@@ -3238,13 +3357,13 @@ async function reviewBlockers(repoRoot, argv, json, scope) {
   if (codexGoalJson === undefined) {
     throw new UlwLoopError("Missing --codex-goal-json.", "ULW_LOOP_CODEX_GOAL_JSON_REQUIRED");
   }
-  const result = await recordFinalReviewBlockers(repoRoot, {
+  const result = unwrap(await toolkitFor(repoRoot, scope).recordReviewBlockers({
     goalId: required4(argv, "--goal-id"),
     title: required4(argv, "--title"),
     objective: required4(argv, "--objective"),
     evidence: required4(argv, "--evidence"),
     codexGoalJson
-  }, scope);
+  }));
   if (json) {
     printJson({
       ok: true,
@@ -3262,6 +3381,20 @@ async function reviewBlockers(repoRoot, argv, json, scope) {
   }
   return 0;
 }
+function toolkitFor(repoRoot, scope) {
+  const sessionId = scope?.sessionId?.trim();
+  if (sessionId === undefined || sessionId.length === 0) {
+    throw new UlwLoopError("Missing --session-id.", "ULW_LOOP_SESSION_ID_REQUIRED", {
+      details: { flag: "--session-id" }
+    });
+  }
+  return createAgentToolkit({ cwd: repoRoot, sessionId, surface: resolveToolkitSurface() });
+}
+function unwrap(response) {
+  if (response.ok)
+    return response.result;
+  throw new UlwLoopError(response.error.message, response.error.code);
+}
 function formatCriterionForCli(criterion) {
   const marker = isEssentialCriterion(criterion) ? "essential" : "non-essential";
   return `- ${criterion.id} [${criterion.status}] [${marker}] (${criterion.userModel}) ${criterion.scenario} evidence: ${criterion.capturedEvidence ?? "pending"}`;
@@ -3272,12 +3405,6 @@ function required4(argv, flag) {
     return value;
   throw new UlwLoopError(`Missing ${flag}.`, "ULW_LOOP_ARGUMENT_MISSING", { details: { flag } });
 }
-function findGoal3(plan, goalId) {
-  const goal = plan.goals.find((candidate) => candidate.id === goalId);
-  if (goal !== undefined)
-    return goal;
-  throw new UlwLoopError(`Unknown ulw-loop id: ${goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND", { details: { goalId } });
-}
 
 // components/ulw-loop/src/cli-commands.ts
 var ULW_LOOP_SUBCOMMANDS = [

package/packages/omo-codex/plugin/components/ulw-loop/dist/sdk/factory.d.ts

@@ -0,0 +1,2 @@
+import type { AgentToolkit, AgentToolkitDependencies, ToolkitContext } from "./types.js";
+export declare function createAgentToolkit(context: ToolkitContext, deps?: AgentToolkitDependencies): AgentToolkit;

package/packages/omo-codex/plugin/components/ulw-loop/dist/sdk/factory.js

@@ -0,0 +1,125 @@
+import { checkpointUlwLoop } from "../checkpoint.js";
+import { checkpointTemplate } from "../checkpoint-template.js";
+import { recordEvidence } from "../evidence.js";
+import { ulwLoopAttemptEvidenceDir } from "../paths.js";
+import { addUlwLoopGoal, createUlwLoopPlan, startNextUlwLoop, summarizeUlwLoopPlan } from "../plan-crud.js";
+import { readUlwLoopPlan } from "../plan-io.js";
+import { recordFinalReviewBlockers } from "../review-blockers.js";
+import { UlwLoopError } from "../runtime.js";
+import { statusNextActions } from "../status-next-actions.js";
+import { steerUlwLoop } from "../steering.js";
+import { ULW_LOOP_MANIFEST } from "./manifest.js";
+function validateContext(context) {
+    if (!context.cwd.trim())
+        throw new UlwLoopError("cwd is required.", "ULW_LOOP_CWD_REQUIRED");
+    if (!context.sessionId.trim())
+        throw new UlwLoopError("ULW_LOOP_SESSION_ID_REQUIRED: sessionId is required.", "ULW_LOOP_SESSION_ID_REQUIRED");
+    if (context.surface !== "omo-senpi" && context.surface !== "lazycodex")
+        throw new UlwLoopError("surface must be omo-senpi or lazycodex.", "ULW_LOOP_SURFACE_INVALID");
+}
+function errorDetails(error) {
+    const details = error.details === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(error.details).map(([key, value]) => [key, String(value)]));
+    return details === undefined
+        ? { code: error.code, message: error.message }
+        : { code: error.code, message: error.message, details };
+}
+function failure(operation, error) {
+    return { ok: false, operation, error: errorDetails(error) };
+}
+function caught(operation, error) {
+    return failure(operation, error instanceof UlwLoopError ? error : new UlwLoopError(error.message, "ULW_LOOP_ERROR"));
+}
+function isKnownRequest(request) {
+    return ULW_LOOP_MANIFEST.operations.some((operation) => operation.name === request.operation);
+}
+function unreachable(value) {
+    throw new UlwLoopError(`Unhandled operation: ${String(value)}`, "ULW_LOOP_OPERATION_UNHANDLED");
+}
+function nextActionsFrom(result) {
+    if (!("nextActions" in result) || !Array.isArray(result.nextActions))
+        return [];
+    return result.nextActions.filter((action) => typeof action === "string").slice(0, 8);
+}
+export function createAgentToolkit(context, deps = {}) {
+    validateContext(context);
+    const scope = { sessionId: context.sessionId };
+    const notify = async (operation, response) => {
+        if (deps.hooks?.onOperation !== undefined)
+            await deps.hooks.onOperation({ operation, context, response });
+        return response;
+    };
+    const invoke = async (operation, fn) => {
+        try {
+            const result = await fn();
+            const nextActions = typeof result === "object" && result !== null ? nextActionsFrom(result) : [];
+            return await notify(operation, { ok: true, operation, result, nextActions });
+        }
+        catch (error) {
+            const response = caught(operation, error instanceof Error ? error : new Error("ULW_LOOP_ERROR"));
+            return notify(operation, response);
+        }
+    };
+    const toolkit = {
+        dispatch: async (request) => {
+            if (!isKnownRequest(request))
+                return failure(request.operation, new UlwLoopError(`Unknown operation: ${request.operation}`, "ULW_LOOP_OPERATION_UNKNOWN"));
+            switch (request.operation) {
+                case "help":
+                    return toolkit.help();
+                case "create-goals":
+                    return toolkit.createGoals(request.args);
+                case "status":
+                    return toolkit.status();
+                case "complete-goals":
+                    return toolkit.completeGoals(request.args);
+                case "checkpoint":
+                    return toolkit.checkpoint(request.args);
+                case "steer":
+                    return toolkit.steer(request.args);
+                case "add-goal":
+                    return toolkit.addGoal(request.args);
+                case "criteria":
+                    return toolkit.criteria(request.args);
+                case "record-evidence":
+                    return toolkit.recordEvidence(request.args);
+                case "record-review-blockers":
+                    return toolkit.recordReviewBlockers(request.args);
+                default:
+                    return unreachable(request);
+            }
+        },
+        help: () => invoke("help", async () => ULW_LOOP_MANIFEST),
+        createGoals: (args) => invoke("create-goals", () => createUlwLoopPlan(context.cwd, args, scope)),
+        status: () => invoke("status", async () => {
+            const plan = await readUlwLoopPlan(context.cwd, scope);
+            const active = plan.goals.find((goal) => goal.id === plan.activeGoalId);
+            return {
+                plan,
+                summary: summarizeUlwLoopPlan(plan),
+                nextActions: statusNextActions(plan),
+                // Attempt directories are an evidence-layout v2 concept; a v1 plan must not advertise one.
+                ...(active === undefined || plan.evidenceLayoutVersion !== 2
+                    ? {}
+                    : { currentAttemptDir: ulwLoopAttemptEvidenceDir(active.id, active.attempt, scope) }),
+            };
+        }),
+        completeGoals: (args = {}) => invoke("complete-goals", () => startNextUlwLoop(context.cwd, args, scope)),
+        checkpoint: (args) => invoke("checkpoint", () => args.printTemplate === true
+            ? checkpointTemplate(context.cwd, scope, args.goalId, { surface: context.surface })
+            : checkpointUlwLoop(context.cwd, args, scope, { surface: context.surface })),
+        steer: (args) => invoke("steer", () => steerUlwLoop(context.cwd, args, scope)),
+        addGoal: (args) => invoke("add-goal", () => addUlwLoopGoal(context.cwd, args, scope)),
+        criteria: (args) => invoke("criteria", async () => {
+            const plan = await readUlwLoopPlan(context.cwd, scope);
+            const goal = plan.goals.find((candidate) => candidate.id === args.goalId);
+            if (goal === undefined)
+                throw new UlwLoopError(`Unknown ulw-loop id: ${args.goalId}.`, "ULW_LOOP_GOAL_NOT_FOUND");
+            return { goalId: goal.id, criteria: goal.successCriteria };
+        }),
+        recordEvidence: (args) => invoke("record-evidence", () => recordEvidence(context.cwd, args, scope)),
+        recordReviewBlockers: (args) => invoke("record-review-blockers", () => recordFinalReviewBlockers(context.cwd, args, scope)),
+    };
+    return toolkit;
+}

package/packages/omo-codex/plugin/components/ulw-loop/dist/sdk/manifest.d.ts

@@ -0,0 +1,46 @@
+export declare const ULW_LOOP_OPERATIONS: readonly ["help", "create-goals", "status", "complete-goals", "checkpoint", "steer", "add-goal", "criteria", "record-evidence", "record-review-blockers"];
+export type UlwLoopOperation = (typeof ULW_LOOP_OPERATIONS)[number];
+export interface ToolkitOperationManifest {
+    readonly name: UlwLoopOperation;
+    readonly mutating: boolean;
+}
+export interface ToolkitManifest {
+    readonly version: 1;
+    readonly name: "ulw-loop";
+    readonly operations: readonly ToolkitOperationManifest[];
+}
+export declare const ULW_LOOP_MANIFEST: {
+    version: 1;
+    name: "ulw-loop";
+    operations: ({
+        name: "help";
+        mutating: false;
+    } | {
+        name: "create-goals";
+        mutating: true;
+    } | {
+        name: "status";
+        mutating: false;
+    } | {
+        name: "complete-goals";
+        mutating: true;
+    } | {
+        name: "checkpoint";
+        mutating: true;
+    } | {
+        name: "steer";
+        mutating: true;
+    } | {
+        name: "add-goal";
+        mutating: true;
+    } | {
+        name: "criteria";
+        mutating: false;
+    } | {
+        name: "record-evidence";
+        mutating: true;
+    } | {
+        name: "record-review-blockers";
+        mutating: true;
+    })[];
+};