@alexkroman1/aai-cli 6.11.0 → 8.0.0

package/dist/templates/plan-and-execute/agent.test.ts

@@ -1,10 +1,11 @@
 /// <reference types="vite/client" />
 
-import type { GenerateFn, ToolContext } from "@alexkroman1/aai";
+import type { ToolContext } from "@alexkroman1/aai";
 import {
   createToolContext,
-  runTool,
+  okPosition,
   stubGenerate,
+  toolRunner,
   withDiscoveredTools,
 } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
@@ -23,10 +24,10 @@ const agentDef = withDiscoveredTools(
   import.meta.glob("./tools/*.ts", { eager: true }),
 );
 
-import { executeStep, MAX_STEP_SEARCHES, normalizeAct, planNode } from "./graph.ts";
+import { executeStep, MAX_STEP_SEARCHES, normalizeAct, planNode } from "./procedure.ts";
 import { EXECUTOR_SYSTEM, PLANNER_SYSTEM, REPLANNER_SYSTEM, REVISE_SYSTEM } from "./prompts.ts";
 import type { SearchFn } from "./shared.ts";
-import { MAX_PAST_STEPS, planProjection, planSlot, planView } from "./shared.ts";
+import { MAX_PAST_STEPS, planFlow, planProjection, planSlot, planView } from "./shared.ts";
 
 // ─── A scripted model ────────────────────────────────────────────────────────
 //
@@ -80,15 +81,11 @@ function fakeSearch(hits: Record<string, { title: string; url: string }[]>): {
   return { search, queries };
 }
 
-function makeCtx(generate: GenerateFn, sessionId?: string) {
-  return createToolContext({ generate, ...(sessionId ? { sessionId } : {}) });
-}
-
-/** A tool by the name the model calls it by, bound to this agent. The lookup
- *  and its "no such tool" message are `runTool`'s (`@alexkroman1/aai/testing`);
- *  what is local is only which agent they run against. */
-const run = (name: string, args: Record<string, unknown>, ctx: ToolContext) =>
-  runTool(agentDef, name, args, ctx);
+/** A tool by the name the model calls it by, bound to this agent. The lookup,
+ *  its "no such tool" message and the args-or-context shape are all
+ *  `toolRunner`'s (`@alexkroman1/aai/testing`); what is local is only which
+ *  agent it runs against. */
+const run = toolRunner(agentDef);
 
 function stateOf(ctx: ToolContext) {
   return planSlot.get(ctx);
@@ -190,7 +187,7 @@ describe("normalizeAct", () => {
 describe("start_plan", () => {
   test("stores the objective and the steps", async () => {
     const { generate } = scriptedModel({ steps: ["Check prices", "Compare hotels", "Book"] });
-    const ctx = makeCtx(generate);
+    const ctx = createToolContext({ generate });
     const result = (await run("start_plan", { objective: "a weekend in Lisbon" }, ctx)) as {
       steps: string[];
     };
@@ -214,12 +211,20 @@ describe("start_plan", () => {
 });
 
 describe("work_next_step", () => {
-  test("refuses before there is a plan", async () => {
+  test("is refused before there is a plan, by the flow rather than by the body", async () => {
     const { generate } = scriptedModel();
-    const ctx = makeCtx(generate);
-    expect(await run("work_next_step", {}, ctx)).toEqual({
-      error: "There is no plan yet — use start_plan first.",
+    const ctx = createToolContext({ generate });
+    // The gate is `when: "working"`, so the refusal names the state the call is
+    // actually in and quotes that state's instruction — which is what the model
+    // needs in order to do the right thing on its own next turn.
+    expect(await run("work_next_step", ctx)).toMatchObject({
+      error: expect.stringContaining('this conversation is at "idle"'),
     });
+    expect(await run("work_next_step", ctx)).toMatchObject({
+      error: expect.stringContaining("use start_plan"),
+    });
+    // Refused means the body did not run: nothing was claimed off the plan.
+    expect(stateOf(ctx).pastSteps).toEqual([]);
   });
 
   test("does the head step, records it, and takes the replanner's next plan", async () => {
@@ -228,19 +233,21 @@ describe("work_next_step", () => {
       turns: [{ answer: "Fares are about 180 return." }],
       acts: [{ kind: "plan", steps: ["Compare hotels"] }],
     });
-    const ctx = makeCtx(generate);
+    const ctx = createToolContext({ generate });
     await run("start_plan", { objective: "a weekend in Lisbon" }, ctx);
 
-    const first = (await run("work_next_step", {}, ctx)) as {
-      done: boolean;
+    const first = okPosition<{
+      finished: boolean;
       step: string;
       result: string;
       remaining: string[];
-    };
-    expect(first.done).toBe(false);
-    expect(first.step).toBe("Check prices");
-    expect(first.result).toContain("180");
-    expect(first.remaining).toEqual(["Compare hotels"]);
+    }>(await run("work_next_step", ctx));
+    expect(first.result.finished).toBe(false);
+    expect(first.result.step).toBe("Check prices");
+    expect(first.result.result).toContain("180");
+    expect(first.result.remaining).toEqual(["Compare hotels"]);
+    // Still working: nothing was concluded, so the flow has not moved on.
+    expect(first.state).toBe("working");
 
     const state = stateOf(ctx);
     expect(state.pastSteps).toHaveLength(1);
@@ -254,19 +261,29 @@ describe("work_next_step", () => {
       turns: [{ answer: "Fares are about 180 return." }],
       acts: [{ kind: "respond", response: "Go in May — flights are about 180 return." }],
     });
-    const ctx = makeCtx(generate);
+    const ctx = createToolContext({ generate });
     await run("start_plan", { objective: "a weekend in Lisbon" }, ctx);
-    const result = (await run("work_next_step", {}, ctx)) as { done: boolean; response: string };
+    const answered = okPosition<{ finished: boolean; response: string }>(
+      await run("work_next_step", ctx),
+    );
+
+    expect(answered.result.finished).toBe(true);
+    expect(answered.result.response).toContain("180");
+    // A response is what sends ANSWERED — the flow and the data agree because
+    // one tool call moved both.
+    expect(answered.state).toBe("answered");
+    expect(planFlow.position(ctx).state).toBe("answered");
 
-    expect(result.done).toBe(true);
-    expect(result.response).toContain("180");
     const state = stateOf(ctx);
     // The replanner deciding early is a good outcome, so the pending step goes.
     expect(state.plan).toEqual([]);
-    expect(state.response).toBe(result.response);
+    expect(state.response).toBe(answered.result.response);
 
-    // A finished plan is not worked again.
-    expect(await run("work_next_step", {}, ctx)).toMatchObject({ done: true });
+    // A finished plan is not worked again, and now it CANNOT be: the tool is
+    // gated out of `answered` rather than returning a done-shaped result.
+    expect(await run("work_next_step", ctx)).toMatchObject({
+      error: expect.stringContaining('this conversation is at "answered"'),
+    });
     expect(stateOf(ctx).pastSteps).toHaveLength(1);
   });
 
@@ -283,9 +300,9 @@ describe("work_next_step", () => {
         steps: Array.from({ length: total - i - 1 }, (_, j) => `Step ${i + j + 2}`),
       })),
     });
-    const ctx = makeCtx(generate);
+    const ctx = createToolContext({ generate });
     await run("start_plan", { objective: "a long one" }, ctx);
-    for (let i = 0; i < total; i++) await run("work_next_step", {}, ctx);
+    for (let i = 0; i < total; i++) await run("work_next_step", ctx);
 
     const state = stateOf(ctx);
     expect(state.pastSteps).toHaveLength(MAX_PAST_STEPS);
@@ -302,13 +319,15 @@ describe("work_next_step", () => {
     // session ids would prove nothing extra, and `sessionSlot` could stop
     // keying by session with this still passing.
     const { generate } = scriptedModel({ steps: ["Only step"] });
-    const first = makeCtx(generate);
-    const second = makeCtx(generate);
+    const first = createToolContext({ generate });
+    const second = createToolContext({ generate });
 
     await run("start_plan", { objective: "mine" }, first);
     expect(stateOf(second).objective).toBeNull();
-    expect(await run("work_next_step", {}, second)).toMatchObject({
-      error: "There is no plan yet — use start_plan first.",
+    // The FLOW is per-session too, not just the plan — `second` is still idle.
+    expect(planFlow.position(second).state).toBe("idle");
+    expect(await run("work_next_step", second)).toMatchObject({
+      error: expect.stringContaining('this conversation is at "idle"'),
     });
   });
 });
@@ -323,17 +342,19 @@ describe("revise_plan", () => {
         { kind: "plan", steps: ["Check Porto prices"] },
       ],
     });
-    const ctx = makeCtx(generate);
+    const ctx = createToolContext({ generate });
     await run("start_plan", { objective: "a weekend in Lisbon" }, ctx);
-    await run("work_next_step", {}, ctx);
+    await run("work_next_step", ctx);
     expect(stateOf(ctx).response).not.toBeNull();
 
-    const revised = (await run("revise_plan", { instruction: "make it Porto instead" }, ctx)) as {
-      done: boolean;
-      remaining: string[];
-    };
-    expect(revised.done).toBe(false);
-    expect(revised.remaining).toEqual(["Check Porto prices"]);
+    const revised = okPosition<{ finished: boolean; remaining: string[] }>(
+      await run("revise_plan", { instruction: "make it Porto instead" }, ctx),
+    );
+    expect(revised.result.finished).toBe(false);
+    expect(revised.result.remaining).toEqual(["Check Porto prices"]);
+    // REOPENED: the one transition that goes backwards, and the reason
+    // `revise_plan` is legal in `answered` at all.
+    expect(revised.state).toBe("working");
 
     const state = stateOf(ctx);
     // The old answer is no longer the answer — the caller moved the goalposts.
@@ -346,13 +367,27 @@ describe("revise_plan", () => {
     expect(calls.at(-1)?.prompt).toContain("make it Porto instead");
   });
 
-  test("refuses before there is a plan", async () => {
+  test("is refused before there is a plan", async () => {
     const { generate } = scriptedModel();
-    const ctx = makeCtx(generate);
-    expect(await run("revise_plan", { instruction: "change it" }, ctx)).toEqual({
-      error: "There is no plan to revise — use start_plan first.",
+    const ctx = createToolContext({ generate });
+    expect(await run("revise_plan", { instruction: "change it" }, ctx)).toMatchObject({
+      error: expect.stringContaining('this conversation is at "idle"'),
     });
   });
+
+  test("a revision that answers outright lands in `answered`", async () => {
+    const { generate } = scriptedModel({
+      steps: ["Check Lisbon prices"],
+      acts: [{ kind: "respond", response: "Nothing to do — you already booked it." }],
+    });
+    const ctx = createToolContext({ generate });
+    await run("start_plan", { objective: "a weekend in Lisbon" }, ctx);
+    const revised = okPosition<{ finished: boolean }>(
+      await run("revise_plan", { instruction: "never mind, it is booked" }, ctx),
+    );
+    expect(revised.result.finished).toBe(true);
+    expect(revised.state).toBe("answered");
+  });
 });
 
 describe("plan_status", () => {
@@ -362,14 +397,20 @@ describe("plan_status", () => {
       turns: [{ answer: "About 180 return." }],
       acts: [{ kind: "plan", steps: ["Book"] }],
     });
-    const ctx = makeCtx(generate);
-    expect(await run("plan_status", {}, ctx)).toEqual({
-      message: "No plan yet. Ask what they want to get done.",
+    const ctx = createToolContext({ generate });
+    // Legal in every state, so it READS the position rather than being gated on
+    // one — and "no plan yet" is the flow's own answer, not a third derivation
+    // of `!objective`.
+    expect(await run("plan_status", ctx)).toMatchObject({
+      stage: "idle",
+      next: expect.stringContaining("start_plan"),
+      objective: null,
     });
 
     await run("start_plan", { objective: "a weekend in Lisbon" }, ctx);
-    await run("work_next_step", {}, ctx);
-    expect(await run("plan_status", {}, ctx)).toMatchObject({
+    await run("work_next_step", ctx);
+    expect(await run("plan_status", ctx)).toMatchObject({
+      stage: "working",
       objective: "a weekend in Lisbon",
       remaining: ["Book"],
       response: null,
@@ -399,11 +440,11 @@ describe("planView projection", () => {
       turns: [{ answer: "Done one." }],
       acts: [{ kind: "plan", steps: ["Two", "Three"] }],
     });
-    const ctx = makeCtx(generate);
+    const ctx = createToolContext({ generate });
     await run("start_plan", { objective: "three things" }, ctx);
     expect(planView(stateOf(ctx)).progress).toBe(0);
 
-    await run("work_next_step", {}, ctx);
+    await run("work_next_step", ctx);
     const view = planView(stateOf(ctx));
     expect(view.progress).toBeCloseTo(1 / 3, 5);
     expect(view.done[0]?.step).toBe("One");

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

@@ -3,7 +3,7 @@ import { planProjection } from "./shared.ts";
 
 /**
  * A planning desk you can phone: plan-and-execute, with the caller in the loop.
- * `prompts.ts` carries the attribution, `graph.ts` the three nodes, `shared.ts`
+ * `prompts.ts` carries the attribution, `procedure.ts` the three nodes, `shared.ts`
  * the state (which is their `PlanExecute`, field for field).
  *
  * **The steps do real work.** `work_next_step` runs a bounded search/answer loop

package/dist/templates/plan-and-execute/client.tsx

@@ -1,5 +1,5 @@
 import "@alexkroman1/aai-ui/styles.css";
-import { AutoScroll, client, useAgentState, useTheme } from "@alexkroman1/aai-ui";
+import { AutoScroll, client, useAgentState } from "@alexkroman1/aai-ui";
 import { planProjection } from "./shared.ts";
 
 /**
@@ -10,14 +10,13 @@ import { planProjection } from "./shared.ts";
  * out. The sidebar is where that lives; the call is where the decisions happen.
  */
 function PlanSidebar() {
-  const theme = useTheme();
   const plan = useAgentState(planProjection);
 
   if (!plan.objective) {
     return (
       <div className="flex h-full flex-col items-center justify-center gap-3 p-6 text-center">
         <span className="text-4xl">🗂️</span>
-        <p className="text-sm opacity-60" style={{ color: theme.text }}>
+        <p className="text-sm opacity-60 text-aai-text">
           Say what you want to get done and the plan appears here.
         </p>
       </div>
@@ -25,14 +24,16 @@ function PlanSidebar() {
   }
 
   return (
-    <div className="flex h-full min-h-0 flex-col gap-4 p-4" style={{ color: theme.text }}>
+    <div className="flex h-full min-h-0 flex-col gap-4 p-4 text-aai-text">
       <div className="flex flex-col gap-2">
         <h3 className="text-sm font-bold uppercase tracking-wide opacity-60">Objective</h3>
         <p className="text-sm">{plan.objective}</p>
-        <div className="h-1.5 w-full rounded-full" style={{ background: theme.surface }}>
+        <div className="h-1.5 w-full rounded-full bg-aai-surface">
+          {/* The WIDTH is the one thing here that is genuinely computed, so it
+              stays inline; the colour is a token. */}
           <div
-            className="h-1.5 rounded-full transition-all"
-            style={{ width: `${Math.round(plan.progress * 100)}%`, background: theme.primary }}
+            className="h-1.5 rounded-full transition-all bg-aai-primary"
+            style={{ width: `${Math.round(plan.progress * 100)}%` }}
           />
         </div>
         <p className="text-xs opacity-50">
@@ -45,9 +46,9 @@ function PlanSidebar() {
         contentClassName="flex flex-col gap-2 pr-1"
       >
         {plan.done.map((past) => (
-          <div key={past.step} className="rounded-lg p-3" style={{ background: theme.surface }}>
+          <div key={past.step} className="rounded-lg p-3 bg-aai-surface">
             <p className="text-sm">
-              <span style={{ color: theme.primary }}>✓</span> {past.step}
+              <span className="text-aai-primary">✓</span> {past.step}
             </p>
             <p className="mt-1 text-xs opacity-70">{past.result}</p>
             {past.searches.length > 0 && (
@@ -60,8 +61,7 @@ function PlanSidebar() {
           // a revision, so the position is part of the identity.
           <div
             key={`${index}-${step}`}
-            className="rounded-lg p-3 text-sm opacity-60"
-            style={{ border: `1px dashed ${theme.border}` }}
+            className="rounded-lg p-3 text-sm opacity-60 border border-dashed border-aai-border"
           >
             <span className="opacity-50">{plan.done.length + index + 1}.</span> {step}
           </div>
@@ -69,10 +69,7 @@ function PlanSidebar() {
       </AutoScroll>
 
       {plan.response && (
-        <div
-          className="rounded-lg p-3"
-          style={{ background: theme.surface, border: `1px solid ${theme.primary}` }}
-        >
+        <div className="rounded-lg p-3 bg-aai-surface border border-aai-primary">
           <p className="text-[11px] font-bold uppercase tracking-wide opacity-60">Answer</p>
           <p className="mt-1 text-sm">{plan.response}</p>
         </div>

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;