@alexkroman1/aai-cli 6.11.0 → 7.0.0

package/dist/templates/plan-and-execute/shared.ts

@@ -13,9 +13,16 @@
  * a different template (`solo-rpg` has the save-slot version).
  */
 
-import { type DeepReadonly, pushCapped, sessionSlot } from "@alexkroman1/aai";
+import {
+  type DeepReadonly,
+  type DialogPosition,
+  type DialogSpec,
+  dialog,
+  isToolFailure,
+  pushCapped,
+  sessionSlot,
+} from "@alexkroman1/aai";
 import { webSearch } from "@alexkroman1/aai/tools";
-import { isToolFailure } from "@alexkroman1/aai/utils";
 
 /** One completed step — their `past_steps`, as a pair rather than a tuple. */
 export interface PastStep {
@@ -61,6 +68,68 @@ export function emptyPlan(): PlanState {
 
 export const planSlot = sessionSlot("plan", emptyPlan);
 
+/**
+ * The plan's LIFECYCLE, as a declared machine rather than a guard per tool.
+ *
+ * Three of the four tools used to open with the same shape — `if
+ * (!plan.objective) return toolFailure("There is no plan yet …")`, and
+ * `work_next_step` carried a second one for the already-answered case. Those are
+ * not data checks, they are the question "where is this conversation", and
+ * getting one wrong is silent: the tool runs, the model reads a plausible
+ * result, and the caller is told about a plan that does not exist. A fifth tool
+ * would have had to remember both.
+ *
+ * `when` is that check now, and it is the SDK's rather than this template's — so
+ * the refusal names where the call actually is and quotes the instruction below,
+ * which is what lets the model recover on its own turn instead of apologizing.
+ *
+ * The states are the notebook's own, read off `PlanExecute`: no `input` yet,
+ * an `input` with steps left, and a `response`. `PLANNED` is accepted from all
+ * three because `start_plan` is always legal — a caller may re-plan from
+ * scratch at any point, which is the one transition that is not a progression.
+ */
+const planSpec = {
+  initial: "idle",
+  states: {
+    idle: {
+      instruction:
+        "There is no plan yet. Find out what the caller wants to get done, then use start_plan.",
+      on: { PLANNED: "working" },
+    },
+    working: {
+      instruction:
+        "Work the plan one step at a time with work_next_step, reporting after each step.",
+      on: { ANSWERED: "answered", PLANNED: "working" },
+    },
+    answered: {
+      instruction:
+        "The plan is finished — give the caller the answer. Use revise_plan if they change their mind.",
+      on: { REOPENED: "working", PLANNED: "working" },
+    },
+  },
+} as const satisfies DialogSpec;
+
+/**
+ * The flow. Its own slot key, because a flow stores an actor snapshot and
+ * {@link planSlot} stores the plan — the position and the payload are two
+ * things, and one tool call moves both.
+ */
+export const planFlow = dialog("planFlow", planSpec);
+
+/**
+ * How the stage reads to a caller, from the flow's own position.
+ *
+ * A helper over a {@link DialogPosition} rather than over {@link PlanState}, which
+ * is the point: "where is this call" is the machine's answer, and deriving it a
+ * second time from the plan's fields is what the three removed guards were
+ * doing. `plan_status` reads this, and so would any prompt that wants to say it
+ * aloud.
+ */
+export function stageLabel(at: DialogPosition): string {
+  if (at.state === "idle") return "no plan yet";
+  return at.state === "answered" ? "finished" : "in progress";
+}
+
 export function noteRevision(state: PlanState, entry: string): void {
   pushCapped(state.revisions, entry, MAX_REVISIONS);
 }

package/dist/templates/plan-and-execute/tools/plan_status.ts

@@ -1,16 +1,28 @@
-import { planSlot } from "../shared.ts";
+import { tool } from "@alexkroman1/aai";
+import { planFlow, planSlot, stageLabel } from "../shared.ts";
 
 /**
- * Where the plan is. Read-only, so plain `tool` semantics — a synchronous
- * read cannot interleave with anything.
+ * Where the plan is. Read-only, so plain `tool` semantics — a synchronous read
+ * cannot interleave with anything.
+ *
+ * **Legal in every state, which is why it is not a `planFlow.tool`**, and it is
+ * the one tool that reports the flow's own POSITION: `stage` and `next` come
+ * from the machine rather than from a second reading of the plan's fields, so
+ * "no plan yet" is the same fact here as the refusal `work_next_step` would
+ * give. It used to derive that from `!plan.objective`, which was a third copy of
+ * the same question.
  */
-export default planSlot.tool({
+export default tool({
   description:
     "Say where the plan has got to: what is done, what is left, and the answer " +
     "if there is one. Use it when the caller asks, or to pick a call back up.",
-  execute(_args, plan) {
-    if (!plan.objective) return { message: "No plan yet. Ask what they want to get done." };
+  execute(_args, ctx) {
+    const at = planFlow.position(ctx);
+    const plan = planSlot.get(ctx);
     return {
+      stage: at.state,
+      reads: stageLabel(at),
+      next: at.instruction,
       objective: plan.objective,
       done: plan.pastSteps.map((past) => ({ step: past.step, result: past.result })),
       remaining: plan.plan,

package/dist/templates/plan-and-execute/tools/revise_plan.ts

@@ -1,8 +1,8 @@
-import { errorMessage, tool, toolFailure } from "@alexkroman1/aai";
+import { errorMessage, toolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { replanNode } from "../graph.ts";
+import { replanNode } from "../procedure.ts";
 import { REVISE_SYSTEM } from "../prompts.ts";
-import { noteRevision, planSlot } from "../shared.ts";
+import { noteRevision, planFlow, planSlot } from "../shared.ts";
 
 /**
  * The replanner, driven by the caller instead of by a step result.
@@ -16,8 +16,14 @@ import { noteRevision, planSlot } from "../shared.ts";
  * The await-then-mutate shape is `start_plan`'s, for the reason it gives — and
  * note the READ before the await is `planSlot.get`, which the replanner only
  * needs to look at.
+ *
+ * **Legal in `working` AND `answered`, which is the whole point of it.** A
+ * finished plan is exactly what a caller most often wants changed, so this is
+ * the one tool that reopens one — `REOPENED` takes the flow back to `working`,
+ * and the body's clearing of `plan.response` is the same decision at the data
+ * level. Its `!objective` guard is gone: `when` is that check now.
  */
-export default tool({
+export default planFlow.tool({
   description:
     "Rewrite the remaining plan because the caller changed what they want. " +
     "Pass their instruction as they said it. Completed steps are never redone.",
@@ -27,11 +33,8 @@ export default tool({
       .max(400)
       .describe("What the caller now wants changed, in their own words"),
   }),
+  when: ["working", "answered"],
   async execute(args, ctx) {
-    if (!planSlot.get(ctx).objective) {
-      return toolFailure("There is no plan to revise — use start_plan first.");
-    }
-
     try {
       const act = await replanNode(ctx.generate, planSlot.get(ctx), {
         system: REVISE_SYSTEM,
@@ -43,7 +46,7 @@ export default tool({
         if (act.kind === "respond") {
           plan.plan = [];
           plan.response = act.response;
-          return { done: true, response: act.response, message: "Nothing is left to do." };
+          return { finished: true, response: act.response, message: "Nothing is left to do." };
         }
 
         plan.plan = act.steps;
@@ -51,7 +54,7 @@ export default tool({
         // moved the goalposts, so the old answer is no longer the answer.
         plan.response = null;
         return {
-          done: false,
+          finished: false,
           remaining: act.steps,
           message: "Read the revised steps back and ask if that is right.",
         };
@@ -60,4 +63,9 @@ export default tool({
       return toolFailure(`The plan could not be revised: ${errorMessage(err)}`);
     }
   },
+  // Below `execute` deliberately — see the note on `work_next_step`'s own
+  // `sendFrom`: this body's return type is itself inferred, so a `sendFrom`
+  // written first has nothing to be contextually typed against.
+  sendFrom: (outcome) =>
+    outcome.finished ? ({ type: "ANSWERED" } as const) : ({ type: "REOPENED" } as const),
 });

package/dist/templates/plan-and-execute/tools/start_plan.ts

@@ -1,7 +1,7 @@
 import { errorMessage, tool, toolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { planNode } from "../graph.ts";
-import { noteRevision, planSlot } from "../shared.ts";
+import { planNode } from "../procedure.ts";
+import { noteRevision, planFlow, planSlot } from "../shared.ts";
 
 /**
  * Their `plan_step`, as the call's opening move.
@@ -13,6 +13,12 @@ import { noteRevision, planSlot } from "../shared.ts";
  * version guarded against is unchanged (the LLM loop runs a step's tool calls
  * concurrently, so two plans started at once must not interleave); what changed
  * is that the window is now too short to interleave IN.
+ *
+ * **This one is an ordinary `tool()` and NOT a `planFlow.tool`, deliberately.**
+ * `PLANNED` is accepted in all three states — re-planning from scratch is always
+ * legal — so a `when` listing every state would be a gate that gates nothing,
+ * paying the wrapper for it. It sends the event itself instead, which is what
+ * `dialog.send` is public for.
  */
 export default tool({
   description:
@@ -32,6 +38,11 @@ export default tool({
       return toolFailure(`The planner failed: ${errorMessage(err)}`);
     }
 
+    // The flow moves first: `work_next_step` gates on `working`, and a plan
+    // written to the slot while the flow still said `idle` would be refused by
+    // its own next tool call.
+    planFlow.send(ctx, { type: "PLANNED" });
+
     return planSlot.update(ctx, (plan) => {
       plan.objective = args.objective;
       plan.plan = steps;

package/dist/templates/plan-and-execute/tools/work_next_step.ts

@@ -1,6 +1,26 @@
-import { errorMessage, isToolFailure, tool, toolFailure } from "@alexkroman1/aai";
-import { executeStep, replanNode } from "../graph.ts";
-import { liveSearch, noteRevision, type PastStep, planSlot, recordStep } from "../shared.ts";
+import { errorMessage, type ToolFailure, toolFailure } from "@alexkroman1/aai";
+import { executeStep, replanNode } from "../procedure.ts";
+import {
+  liveSearch,
+  noteRevision,
+  type PastStep,
+  planFlow,
+  planSlot,
+  recordStep,
+} from "../shared.ts";
+
+/**
+ * What the claim window decided, as a DISCRIMINATED union.
+ *
+ * The three arms used to be told apart by `"done" in claimed`, which stopped
+ * working once the outcome had a declared type: union normalization gives every
+ * arm the other arms' keys as `?: never`, and `in` cannot rule out a key that is
+ * optional-never. A `kind` tag is both narrower and easier to read.
+ */
+type Claim =
+  | { kind: "failed"; failure: ToolFailure }
+  | { kind: "dry" }
+  | { kind: "step"; step: string; objective: string; pastSteps: PastStep[] };
 
 /**
  * One turn of their execute→replan loop: do the head step, then let the
@@ -22,33 +42,54 @@ import { liveSearch, noteRevision, type PastStep, planSlot, recordStep } from ".
  * behind each other to get the same guarantee. A step whose work then FAILS is
  * put back, because a failed model call is worth retrying and a silently dropped
  * step leaves the caller with a plan that skipped something.
+ *
+ * **`when: "working"` replaced two hand-rolled guards** — the `!plan.objective`
+ * check and the already-answered one — and neither was a data check: both asked
+ * where the conversation was. See {@link planFlow}. The flow is what refuses now,
+ * naming the state and quoting its instruction, so this body only ever runs when
+ * there is a plan in progress.
+ *
+ * **`ANSWERED` is sent only when the replanner produced a RESPONSE.** A plan
+ * that merely ran out of steps stays in `working`: nothing was concluded, and
+ * the caller can still revise or add to it. Conflating the two would announce an
+ * answer that does not exist.
  */
-export default tool({
+export default planFlow.tool({
   description:
     "Do the next step of the plan and report what it found. Call this once per " +
     "step — never in a loop. Say a short 'let me look into that' first, since " +
     "the step may take a few seconds.",
+  when: "working",
   async execute(_args, ctx) {
     // The whole read-and-claim, in one window nothing can interleave with.
-    const claimed = planSlot.update(ctx, (plan) => {
-      if (!plan.objective) return toolFailure("There is no plan yet — use start_plan first.");
-      if (plan.response) {
-        return {
-          done: true as const,
-          response: plan.response,
-          message: "The plan is already finished.",
-        };
+    const claimed = planSlot.update(ctx, (plan): Claim => {
+      // `when: "working"` means there IS a plan, so this arm is unreachable by
+      // the flow's own guarantee — kept because the slot and the flow are two
+      // values, and a plan cleared by something else should refuse rather than
+      // claim a step off an empty objective.
+      if (!plan.objective) {
+        return { kind: "failed", failure: toolFailure("There is no plan yet — use start_plan.") };
       }
       const step = plan.plan.shift();
-      if (!step) {
-        return {
-          done: true as const,
-          message: "No steps are left. Ask the caller what they want next.",
-        };
-      }
-      return { step, objective: plan.objective, pastSteps: [...plan.pastSteps] as PastStep[] };
+      if (!step) return { kind: "dry" };
+      return {
+        kind: "step",
+        step,
+        objective: plan.objective,
+        pastSteps: [...plan.pastSteps] as PastStep[],
+      };
     });
-    if (isToolFailure(claimed) || "done" in claimed) return claimed;
+    if (claimed.kind === "failed") return claimed.failure;
+    if (claimed.kind === "dry") {
+      // `response: undefined` is spelled out rather than omitted: `sendFrom`
+      // below reads that field to decide whether to send ANSWERED, and a key
+      // missing from one arm of a union is not readable on the union at all.
+      return {
+        finished: true,
+        response: undefined,
+        message: "No steps are left. Ask the caller what they want next.",
+      };
+    }
     const { step, objective, pastSteps } = claimed;
 
     try {
@@ -69,7 +110,7 @@ export default tool({
           plan.plan = [];
           noteRevision(plan, `Finished after ${plan.pastSteps.length} step(s)`);
           return {
-            done: true,
+            finished: true,
             step,
             result: outcome.result,
             searches: outcome.searches,
@@ -82,7 +123,7 @@ export default tool({
         plan.plan = act.steps;
         if (changed) noteRevision(plan, `Replanned to ${act.steps.length} step(s) after: ${step}`);
         return {
-          done: false,
+          finished: false,
           step,
           result: outcome.result,
           searches: outcome.searches,
@@ -98,4 +139,11 @@ export default tool({
       return toolFailure(`That step could not be worked: ${errorMessage(err)}`);
     }
   },
+  // Written BELOW `execute` deliberately. `sendFrom`'s parameter is
+  // `Exclude<NoInfer<R>, ToolFailure>`, and `NoInfer` keeps it from bidding on
+  // `R` — but this body's own return type is itself an inference
+  // (`planSlot.update`'s), so with `sendFrom` first there is no candidate to
+  // contextually type it against and the parameter lands as `unknown`.
+  sendFrom: (outcome) =>
+    outcome.response === undefined ? undefined : ({ type: "ANSWERED" } as const),
 });