@alexkroman1/aai-cli 6.11.0 → 7.0.0

package/dist/templates/dispatch-center/tools/resources_dispatch.ts

@@ -3,15 +3,22 @@ import { z } from "zod";
 import type { Resource } from "../shared.ts";
 import {
   assertNotResolved,
+  callFlow,
   dispatchSlot,
   findIncident,
   logEvent,
   recommendResources,
 } from "../shared.ts";
 
-export default dispatchSlot.updateTool({
+/**
+ * Gated on `working`, and legal from `triaging` as well as `dispatching` — the
+ * prompt's "critical incidents get immediate dispatch, triage can happen
+ * simultaneously" is why the gate is the parent state rather than one child.
+ */
+export default callFlow.tool({
   description:
     "Dispatch units to an incident. Can auto-dispatch recommended resources or manually specify callsigns.",
+  when: "working",
   inputSchema: z.object({
     incidentId: z.string().max(20).describe("The incident ID"),
     callsigns: z
@@ -30,66 +37,76 @@ export default dispatchSlot.updateTool({
       .describe("Dispatch priority — affects simulated ETA")
       .optional(),
   }),
-  execute(args, state) {
-    const inc = findIncident(state, args.incidentId);
-    if (isToolFailure(inc)) return inc;
-    const blocked = assertNotResolved(inc, "dispatch resources");
-    if (blocked) return blocked;
+  execute: (args, ctx) =>
+    dispatchSlot.update(ctx, (state) => {
+      const inc = findIncident(state, args.incidentId);
+      if (isToolFailure(inc)) return inc;
+      const blocked = assertNotResolved(inc, "dispatch resources");
+      if (blocked) return blocked;
 
-    const dispatched: { callsign: string; type: string; eta: number }[] = [];
-    const failed: { callsign: string; reason: string }[] = [];
+      const dispatched: { callsign: string; type: string; eta: number }[] = [];
+      const failed: { callsign: string; reason: string }[] = [];
 
-    // The literal "auto" callsign means the same thing as autoDispatch.
-    const wantsAuto =
-      args.autoDispatch || args.callsigns?.some((cs) => cs.toLowerCase() === "auto");
+      // The literal "auto" callsign means the same thing as autoDispatch.
+      const wantsAuto =
+        args.autoDispatch || args.callsigns?.some((cs) => cs.toLowerCase() === "auto");
 
-    let resourcesToDispatch: Resource[] = [];
+      let resourcesToDispatch: Resource[] = [];
 
-    if (wantsAuto) {
-      resourcesToDispatch = recommendResources(inc.type, inc.severity, state);
-    } else if (args.callsigns) {
-      for (const cs of args.callsigns) {
-        const r = state.resources.find((r) => r.callsign.toLowerCase() === cs.toLowerCase());
-        if (!r) {
-          failed.push({ callsign: cs, reason: "Not found" });
-          continue;
+      if (wantsAuto) {
+        resourcesToDispatch = recommendResources(inc.type, inc.severity, state);
+      } else if (args.callsigns) {
+        for (const cs of args.callsigns) {
+          const r = state.resources.find((r) => r.callsign.toLowerCase() === cs.toLowerCase());
+          if (!r) {
+            failed.push({ callsign: cs, reason: "Not found" });
+            continue;
+          }
+          if (r.status !== "available") {
+            failed.push({ callsign: cs, reason: `Currently ${r.status}` });
+            continue;
+          }
+          resourcesToDispatch.push(r);
         }
-        if (r.status !== "available") {
-          failed.push({ callsign: cs, reason: `Currently ${r.status}` });
-          continue;
-        }
-        resourcesToDispatch.push(r);
       }
-    }
 
-    const etaBase = args.priority === "emergency" ? 3 : args.priority === "priority" ? 6 : 10;
+      const etaBase = args.priority === "emergency" ? 3 : args.priority === "priority" ? 6 : 10;
 
-    for (const r of resourcesToDispatch) {
-      const eta = etaBase + Math.floor(Math.random() * 5);
-      r.status = "dispatched";
-      r.assignedIncident = args.incidentId;
-      r.eta = eta;
-      inc.assignedResources.push(r.id);
-      dispatched.push({ callsign: r.callsign, type: r.type, eta });
-      logEvent(inc, `Dispatched ${r.callsign} — ETA ${eta} min`);
-    }
+      for (const r of resourcesToDispatch) {
+        const eta = etaBase + Math.floor(Math.random() * 5);
+        r.status = "dispatched";
+        r.assignedIncident = args.incidentId;
+        r.eta = eta;
+        inc.assignedResources.push(r.id);
+        dispatched.push({ callsign: r.callsign, type: r.type, eta });
+        logEvent(inc, `Dispatched ${r.callsign} — ETA ${eta} min`);
+      }
 
-    if (dispatched.length > 0) {
-      inc.status = "dispatched";
-    }
+      if (dispatched.length > 0) {
+        inc.status = "dispatched";
+      }
 
-    const availableCount = state.resources.filter((r) => r.status === "available").length;
+      const availableCount = state.resources.filter((r) => r.status === "available").length;
 
-    return {
-      incidentId: args.incidentId,
-      dispatched,
-      failed: failed.length > 0 ? failed : undefined,
-      totalAssignedToIncident: inc.assignedResources.length,
-      remainingAvailableResources: availableCount,
-      capacityWarning:
-        availableCount <= 3
-          ? "WARNING: Resource capacity critically low. Consider mutual aid."
-          : undefined,
-    };
-  },
+      return {
+        incidentId: args.incidentId,
+        dispatched,
+        failed: failed.length > 0 ? failed : undefined,
+        totalAssignedToIncident: inc.assignedResources.length,
+        remainingAvailableResources: availableCount,
+        capacityWarning:
+          availableCount <= 3
+            ? "WARNING: Resource capacity critically low. Consider mutual aid."
+            : undefined,
+      };
+    }),
+  // Only when units actually rolled: a dispatch whose every requested callsign
+  // was busy answers `dispatched: []`, which is not a refusal but is not
+  // progress either, so the call stays where it is.
+  //
+  // `result` is the SUCCESS type — `sendFrom` takes `Exclude<R, ToolFailure>`,
+  // so the `"dispatched" in result` guard that used to stand in for the failure
+  // arm leaking into `R` is a plain property read.
+  sendFrom: (result) =>
+    result.dispatched.length > 0 ? { type: "DISPATCHED" as const } : undefined,
 });

package/dist/templates/dispatch-center/tools/resources_update_status.ts

@@ -1,59 +1,63 @@
 import { z } from "zod";
-import { dispatchSlot, logEvent, RESOURCE_STATUSES } from "../shared.ts";
+import { callFlow, dispatchSlot, logEvent, RESOURCE_STATUSES } from "../shared.ts";
 
-export default dispatchSlot.updateTool({
+/** Gated on `working`: a unit radios in about an incident, so there has to be
+ *  one. Sends nothing — a unit changing status does not move the call. */
+export default callFlow.tool({
   description: "Update a resource unit's status when it radios in.",
+  when: "working",
   inputSchema: z.object({
     callsign: z.string().max(50).describe("The resource callsign"),
     status: z.enum(RESOURCE_STATUSES).describe("New status"),
     notes: z.string().max(1000).describe("Status notes").optional(),
   }),
-  execute(args, state) {
-    const resource = state.resources.find(
-      (r) => r.callsign.toLowerCase() === args.callsign.toLowerCase(),
-    );
-    if (!resource) {
-      return { error: `Resource ${args.callsign} not found` };
-    }
-
-    const previousStatus = resource.status;
-
-    // Log to the incident timeline BEFORE unassigning, so the
-    // return-to-available transition is recorded too.
-    if (resource.assignedIncident) {
-      const inc = state.incidents[resource.assignedIncident];
-      if (inc) {
-        logEvent(
-          inc,
-          `${resource.callsign}: ${previousStatus} → ${args.status}${args.notes ? ` (${args.notes})` : ""}`,
-        );
+  execute: (args, ctx) =>
+    dispatchSlot.update(ctx, (state) => {
+      const resource = state.resources.find(
+        (r) => r.callsign.toLowerCase() === args.callsign.toLowerCase(),
+      );
+      if (!resource) {
+        return { error: `Resource ${args.callsign} not found` };
       }
-    }
 
-    resource.status = args.status;
+      const previousStatus = resource.status;
 
-    if (args.status === "available") {
-      // Detach from the old incident on BOTH sides — leaving the id in
-      // assignedResources lets that incident later yank a unit that has
-      // been re-dispatched elsewhere.
+      // Log to the incident timeline BEFORE unassigning, so the
+      // return-to-available transition is recorded too.
       if (resource.assignedIncident) {
         const inc = state.incidents[resource.assignedIncident];
         if (inc) {
-          inc.assignedResources = inc.assignedResources.filter((id) => id !== resource.id);
+          logEvent(
+            inc,
+            `${resource.callsign}: ${previousStatus} → ${args.status}${args.notes ? ` (${args.notes})` : ""}`,
+          );
         }
       }
-      resource.assignedIncident = null;
-      resource.eta = null;
-    }
-    if (args.status === "on_scene") {
-      resource.eta = null;
-    }
 
-    return {
-      callsign: resource.callsign,
-      previousStatus,
-      newStatus: args.status,
-      assignedIncident: resource.assignedIncident,
-    };
-  },
+      resource.status = args.status;
+
+      if (args.status === "available") {
+        // Detach from the old incident on BOTH sides — leaving the id in
+        // assignedResources lets that incident later yank a unit that has
+        // been re-dispatched elsewhere.
+        if (resource.assignedIncident) {
+          const inc = state.incidents[resource.assignedIncident];
+          if (inc) {
+            inc.assignedResources = inc.assignedResources.filter((id) => id !== resource.id);
+          }
+        }
+        resource.assignedIncident = null;
+        resource.eta = null;
+      }
+      if (args.status === "on_scene") {
+        resource.eta = null;
+      }
+
+      return {
+        callsign: resource.callsign,
+        previousStatus,
+        newStatus: args.status,
+        assignedIncident: resource.assignedIncident,
+      };
+    }),
 });

package/dist/templates/embedded-assets/agent.test.ts

@@ -1,7 +1,6 @@
 /// <reference types="vite/client" />
 
-import type { ToolContext } from "@alexkroman1/aai";
-import { createToolContext, runTool, withDiscoveredTools } from "@alexkroman1/aai/testing";
+import { toolRunner, withDiscoveredTools } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import authoredAgent from "./agent.ts";
 import { faqs, searchable } from "./shared.ts";
@@ -18,8 +17,14 @@ const agentDef = withDiscoveredTools(
   import.meta.glob("./tools/*.ts", { eager: true }),
 );
 
-const run = (name: string, args: Record<string, unknown>, ctx: ToolContext) =>
-  runTool(agentDef, name, args, ctx);
+/**
+ * Both tools here are stateless, so no call passes a context: `runTool` builds
+ * a fresh one, which is a distinct session with empty slots — right for a tool
+ * that reads nothing but its arguments, and never what two calls sharing state
+ * want. `list_topics` takes no arguments either, and may say so by leaving them
+ * out rather than passing a `{}` between the two values a reader cares about.
+ */
+const run = toolRunner(agentDef);
 
 describe("embedded-assets template", () => {
   test("the JSON asset really is bundled, and the index is built from it", () => {
@@ -44,7 +49,7 @@ describe("embedded-assets template", () => {
 
 describe("list_topics", () => {
   test("answers with every question in the knowledge base", async () => {
-    const topics = await run("list_topics", {}, createToolContext());
+    const topics = await run("list_topics");
     expect(topics).toEqual(faqs.map((f) => f.question));
   });
 });
@@ -59,25 +64,23 @@ describe("search_knowledge", () => {
       .toLowerCase()
       .split(/\W+/)
       .filter((w) => w.length > 2);
-    const result = await run(
-      "search_knowledge",
-      { query: `hey, could you tell me ${words.join(" ")}?` },
-      createToolContext(),
-    );
+    const result = await run("search_knowledge", {
+      query: `hey, could you tell me ${words.join(" ")}?`,
+    });
     expect(result).toEqual(target);
   });
 
   test("a query with no words longer than two characters is refused early", async () => {
     // The guard before the scan: with no scoreable words every entry ties at
     // zero, and returning the first one would be an answer to nothing.
-    expect(await run("search_knowledge", { query: "is it a" }, createToolContext())).toEqual({
+    expect(await run("search_knowledge", { query: "is it a" })).toEqual({
       result: "No matching FAQ found.",
     });
   });
 
   test("a query that overlaps nothing reports no match rather than guessing", async () => {
-    expect(
-      await run("search_knowledge", { query: "zzzqqq wibbleflange" }, createToolContext()),
-    ).toEqual({ result: "No matching FAQ found." });
+    expect(await run("search_knowledge", { query: "zzzqqq wibbleflange" })).toEqual({
+      result: "No matching FAQ found.",
+    });
   });
 });

package/dist/templates/health-assistant/agent.test.ts

@@ -1,7 +1,7 @@
 /// <reference types="vite/client" />
 
-import { isToolFailure, type ToolContext } from "@alexkroman1/aai";
-import { createToolContext, runTool, withDiscoveredTools } from "@alexkroman1/aai/testing";
+import { isToolFailure } from "@alexkroman1/aai";
+import { toolInputIssues, toolRunner, withDiscoveredTools } from "@alexkroman1/aai/testing";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import authoredAgent from "./agent.ts";
 import { excerptAround, type FdaLabel, toDrugInfo } from "./fda.ts";
@@ -35,8 +35,13 @@ const agentDef = withDiscoveredTools(
   import.meta.glob("./tools/*.ts", { eager: true }),
 );
 
-const run = (name: string, args: Record<string, unknown>, ctx: ToolContext = createToolContext()) =>
-  runTool(agentDef, name, args, ctx);
+/**
+ * Every tool here takes arguments and none of them touches session state, so no
+ * call passes a context: `runTool` builds a fresh one per call, which is a
+ * distinct session — right for a stateless tool, and never what two calls
+ * sharing state want.
+ */
+const run = toolRunner(agentDef);
 
 const IBUPROFEN: FdaLabel = {
   openfda: { generic_name: ["IBUPROFEN"], brand_name: ["Advil"], manufacturer_name: ["Acme"] },
@@ -150,6 +155,19 @@ describe("check_drug_interaction", () => {
     expect(isToolFailure(result) && result.error).toContain("at least two");
     expect(label).not.toHaveBeenCalled();
   });
+
+  test("the schema itself accepts those names, which is why the body re-checks", async () => {
+    // The other half of the claim above, asked of the schema directly rather
+    // than through `~standard`: `min(2)` counts ENTRIES and `min(1)` counts
+    // CHARACTERS, so `"   "` is a valid entry and the refusal is the body's.
+    expect(
+      await toolInputIssues(agentDef, "check_drug_interaction", { drugs: ["ibuprofen", "   "] }),
+    ).toBeUndefined();
+    // And the schema is still doing its own half — one drug is not a check.
+    expect(
+      await toolInputIssues(agentDef, "check_drug_interaction", { drugs: ["ibuprofen"] }),
+    ).toBeDefined();
+  });
 });
 
 describe("fda.ts helpers", () => {

package/dist/templates/infocom-adventure/agent.test.ts

@@ -1,7 +1,6 @@
 /// <reference types="vite/client" />
 
-import type { ToolContext } from "@alexkroman1/aai";
-import { createToolContext, runTool, withDiscoveredTools } from "@alexkroman1/aai/testing";
+import { createToolContext, toolRunner, withDiscoveredTools } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import authoredAgent from "./agent.ts";
 
@@ -21,8 +20,7 @@ const agentDef = withDiscoveredTools(
 import { DEFAULT_GAME_STATE, gameSlot, MAX_HISTORY, REPORTED_HISTORY } from "./shared.ts";
 
 /** A tool by the name the model calls it by, bound to this agent. */
-const run = (name: string, args: Record<string, unknown>, ctx: ToolContext) =>
-  runTool(agentDef, name, args, ctx);
+const run = toolRunner(agentDef);
 
 /** Each context owns its OWN slot store, which is what makes two playthroughs
  *  independent by construction. */
@@ -153,7 +151,7 @@ describe("the adventure's tools", () => {
       await run("game_state_history", { value: `command ${i}` }, ctx);
     }
 
-    expect(await run("game_state_get", {}, ctx)).toEqual({
+    expect(await run("game_state_get", ctx)).toEqual({
       currentRoom: "Echo Chamber",
       inventory: ["lantern"],
       score: 7,
@@ -169,7 +167,7 @@ describe("the adventure's tools", () => {
     await run("game_state_score", { value: 30 }, ctx);
     await run("game_state_move", { value: "Echo Chamber" }, ctx);
 
-    const restarted = (await run("game_state_restart", {}, ctx)) as {
+    const restarted = (await run("game_state_restart", ctx)) as {
       restarted: boolean;
       currentRoom: string;
     };