@alexkroman1/aai-cli 6.10.1 → 7.0.0

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

@@ -3,14 +3,22 @@ import { z } from "zod";
 import {
   assertNotResolved,
   calculateTriageScore,
+  callFlow,
   dispatchSlot,
   findIncident,
   logEvent,
   recommendResources,
 } from "../shared.ts";
 
-export default dispatchSlot.updateTool({
+/**
+ * Gated on `working`, and `ESCALATED` puts the call back in `dispatching`: an
+ * incident that outgrew its response needs more units, which is exactly that
+ * state's instruction.
+ */
+export default callFlow.tool({
   description: "Escalate an incident when it exceeds current capacity or severity increases.",
+  when: "working",
+  send: { type: "ESCALATED" },
   inputSchema: z.object({
     incidentId: z.string().max(20).describe("The incident ID"),
     reason: z.string().max(1000).describe("Reason for escalation"),
@@ -20,67 +28,68 @@ export default dispatchSlot.updateTool({
       .optional(),
     newSeverity: z.enum(["critical", "urgent"]).describe("Escalated severity level").optional(),
   }),
-  execute(args, state) {
-    const inc = findIncident(state, args.incidentId);
-    if (isToolFailure(inc)) return inc;
-    const blocked = assertNotResolved(inc, "escalate");
-    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, "escalate");
+      if (blocked) return blocked;
 
-    inc.escalationLevel++;
-    if (args.newSeverity) inc.severity = args.newSeverity;
-    inc.status = "escalated";
-    logEvent(inc, `ESCALATED (Level ${inc.escalationLevel}): ${args.reason}`);
+      inc.escalationLevel++;
+      if (args.newSeverity) inc.severity = args.newSeverity;
+      inc.status = "escalated";
+      logEvent(inc, `ESCALATED (Level ${inc.escalationLevel}): ${args.reason}`);
 
-    if (args.requestMutualAid) {
-      logEvent(inc, "Mutual aid requested from neighboring jurisdictions");
-      // Counter-based ids/callsigns: Date.now() collides across rapid
-      // escalations, and duplicate callsigns break dispatch-by-callsign.
-      const medicN = ++state.mutualAidCounter;
-      const engineN = ++state.mutualAidCounter;
-      state.resources.push(
-        {
-          id: `MA-${medicN}`,
-          type: "ambulance",
-          callsign: `Mutual-Aid-Medic-${medicN}`,
-          status: "available",
-          assignedIncident: null,
-          eta: null,
-          capabilities: ["als"],
-        },
-        {
-          id: `MA-${engineN}`,
-          type: "fire_engine",
-          callsign: `Mutual-Aid-Engine-${engineN}`,
-          status: "available",
-          assignedIncident: null,
-          eta: null,
-          capabilities: ["structural"],
-        },
-      );
-    }
+      if (args.requestMutualAid) {
+        logEvent(inc, "Mutual aid requested from neighboring jurisdictions");
+        // Counter-based ids/callsigns: Date.now() collides across rapid
+        // escalations, and duplicate callsigns break dispatch-by-callsign.
+        const medicN = ++state.mutualAidCounter;
+        const engineN = ++state.mutualAidCounter;
+        state.resources.push(
+          {
+            id: `MA-${medicN}`,
+            type: "ambulance",
+            callsign: `Mutual-Aid-Medic-${medicN}`,
+            status: "available",
+            assignedIncident: null,
+            eta: null,
+            capabilities: ["als"],
+          },
+          {
+            id: `MA-${engineN}`,
+            type: "fire_engine",
+            callsign: `Mutual-Aid-Engine-${engineN}`,
+            status: "available",
+            assignedIncident: null,
+            eta: null,
+            capabilities: ["structural"],
+          },
+        );
+      }
 
-    inc.triageScore = calculateTriageScore(
-      inc.severity,
-      inc.type,
-      inc.casualties.estimated,
-      inc.hazards.length,
-    );
+      inc.triageScore = calculateTriageScore(
+        inc.severity,
+        inc.type,
+        inc.casualties.estimated,
+        inc.hazards.length,
+      );
 
-    const additionalResources = recommendResources(inc.type, inc.severity, state).filter(
-      (r) => !inc.assignedResources.includes(r.id),
-    );
+      const additionalResources = recommendResources(inc.type, inc.severity, state).filter(
+        (r) => !inc.assignedResources.includes(r.id),
+      );
 
-    return {
-      incidentId: args.incidentId,
-      escalationLevel: inc.escalationLevel,
-      newSeverity: inc.severity,
-      newTriageScore: inc.triageScore,
-      mutualAidRequested: args.requestMutualAid ?? false,
-      additionalResourcesAvailable: additionalResources.map((r) => ({
-        callsign: r.callsign,
-        type: r.type,
-      })),
-      message: `ESCALATION CONFIRMED — ${args.incidentId} now Level ${inc.escalationLevel}. ${additionalResources.length} additional resource(s) available for dispatch.`,
-    };
-  },
+      return {
+        incidentId: args.incidentId,
+        escalationLevel: inc.escalationLevel,
+        newSeverity: inc.severity,
+        newTriageScore: inc.triageScore,
+        mutualAidRequested: args.requestMutualAid ?? false,
+        additionalResourcesAvailable: additionalResources.map((r) => ({
+          callsign: r.callsign,
+          type: r.type,
+        })),
+        message: `ESCALATION CONFIRMED — ${args.incidentId} now Level ${inc.escalationLevel}. ${additionalResources.length} additional resource(s) available for dispatch.`,
+      };
+    }),
 });

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

@@ -3,6 +3,7 @@ import { z } from "zod";
 import {
   assertNotResolved,
   calculateTriageScore,
+  callFlow,
   dispatchSlot,
   findIncident,
   getApplicableProtocols,
@@ -12,9 +13,21 @@ import {
   SEVERITIES,
 } from "../shared.ts";
 
-export default dispatchSlot.updateTool({
+/**
+ * Gated on `working`: there is nothing to triage until something has been
+ * logged, and the flow's refusal says so in the dispatcher's own terms where
+ * `findIncident` would have answered `Incident INC-0001 not found` — a data
+ * answer to a positional question.
+ *
+ * `TRIAGED` moves the call to `dispatching`, whose instruction is "assign
+ * units", so the sequencing the system prompt used to spell out tool by tool
+ * arrives in this tool's own result.
+ */
+export default callFlow.tool({
   description:
     "Triage an incident — confirm or override severity, type, hazards, and casualty count.",
+  when: "working",
+  send: { type: "TRIAGED" },
   inputSchema: z.object({
     incidentId: z.string().max(20).describe("The incident ID"),
     severity: z.enum(SEVERITIES).describe("Confirmed severity after triage").optional(),
@@ -27,50 +40,51 @@ export default dispatchSlot.updateTool({
     casualtyUpdate: z.number().int().nonnegative().describe("Updated casualty count").optional(),
     notes: z.string().max(1000).describe("Triage notes").optional(),
   }),
-  execute(args, state) {
-    const inc = findIncident(state, args.incidentId);
-    if (isToolFailure(inc)) return inc;
-    const blocked = assertNotResolved(inc, "triage");
-    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, "triage");
+      if (blocked) return blocked;
 
-    if (args.severity) inc.severity = args.severity;
-    if (args.type) inc.type = args.type;
-    for (const hazard of args.additionalHazards ?? []) {
-      if (!inc.hazards.includes(hazard)) inc.hazards.push(hazard);
-    }
-    if (args.casualtyUpdate !== undefined) {
-      inc.casualties.estimated = args.casualtyUpdate;
-    }
-    if (args.notes) logEvent(inc, `Triage note: ${args.notes}`);
+      if (args.severity) inc.severity = args.severity;
+      if (args.type) inc.type = args.type;
+      for (const hazard of args.additionalHazards ?? []) {
+        if (!inc.hazards.includes(hazard)) inc.hazards.push(hazard);
+      }
+      if (args.casualtyUpdate !== undefined) {
+        inc.casualties.estimated = args.casualtyUpdate;
+      }
+      if (args.notes) logEvent(inc, `Triage note: ${args.notes}`);
 
-    inc.triageScore = calculateTriageScore(
-      inc.severity,
-      inc.type,
-      inc.casualties.estimated,
-      inc.hazards.length,
-    );
-    inc.status = "triaged";
-    logEvent(inc, `Triaged: ${inc.severity} ${inc.type}, score ${inc.triageScore}`);
+      inc.triageScore = calculateTriageScore(
+        inc.severity,
+        inc.type,
+        inc.casualties.estimated,
+        inc.hazards.length,
+      );
+      inc.status = "triaged";
+      logEvent(inc, `Triaged: ${inc.severity} ${inc.type}, score ${inc.triageScore}`);
 
-    const protocols = getApplicableProtocols(inc.type, inc.severity);
-    const recommended = recommendResources(inc.type, inc.severity, state);
+      const protocols = getApplicableProtocols(inc.type, inc.severity);
+      const recommended = recommendResources(inc.type, inc.severity, state);
 
-    return {
-      incidentId: args.incidentId,
-      severity: inc.severity,
-      type: inc.type,
-      triageScore: inc.triageScore,
-      hazards: inc.hazards,
-      estimatedCasualties: inc.casualties.estimated,
-      protocols: protocols.map((p) => ({
-        name: p.name,
-        steps: p.steps,
-        requiredResources: p.requiredResources,
-      })),
-      recommendedResources: recommended.map((r) => ({
-        callsign: r.callsign,
-        type: r.type,
-      })),
-    };
-  },
+      return {
+        incidentId: args.incidentId,
+        severity: inc.severity,
+        type: inc.type,
+        triageScore: inc.triageScore,
+        hazards: inc.hazards,
+        estimatedCasualties: inc.casualties.estimated,
+        protocols: protocols.map((p) => ({
+          name: p.name,
+          steps: p.steps,
+          requiredResources: p.requiredResources,
+        })),
+        recommendedResources: recommended.map((r) => ({
+          callsign: r.callsign,
+          type: r.type,
+        })),
+      };
+    }),
 });

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

@@ -1,9 +1,17 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { assertNotResolved, dispatchSlot, findIncident, logEvent } from "../shared.ts";
+import { assertNotResolved, callFlow, dispatchSlot, findIncident, logEvent } from "../shared.ts";
 
-export default dispatchSlot.updateTool({
+/**
+ * Gated on `working`; sends nothing. A status update moves the INCIDENT, not
+ * the call — the dispatcher is still in `monitoring` afterwards, and closing
+ * one incident says nothing about the others still on the board. Omitting both
+ * `send` and `sendFrom` is how a flow tool reads without advancing, and the
+ * result still carries the position it read.
+ */
+export default callFlow.tool({
   description: "Update an incident's status (en_route, on_scene, resolved, escalated).",
+  when: "working",
   inputSchema: z.object({
     incidentId: z.string().max(20).describe("The incident ID"),
     status: z.enum(["en_route", "on_scene", "resolved", "escalated"]).describe("New status"),
@@ -16,51 +24,52 @@ export default dispatchSlot.updateTool({
       .describe("Updated casualty numbers")
       .optional(),
   }),
-  execute(args, state) {
-    const inc = findIncident(state, args.incidentId);
-    if (isToolFailure(inc)) return inc;
-    const blocked = assertNotResolved(inc, `set status to ${args.status}`);
-    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, `set status to ${args.status}`);
+      if (blocked) return blocked;
 
-    inc.status = args.status;
-    logEvent(inc, `Status → ${args.status}${args.notes ? `: ${args.notes}` : ""}`);
+      inc.status = args.status;
+      logEvent(inc, `Status → ${args.status}${args.notes ? `: ${args.notes}` : ""}`);
 
-    if (args.casualtyUpdate) {
-      if (args.casualtyUpdate.confirmed !== undefined) {
-        inc.casualties.confirmed = args.casualtyUpdate.confirmed;
+      if (args.casualtyUpdate) {
+        if (args.casualtyUpdate.confirmed !== undefined) {
+          inc.casualties.confirmed = args.casualtyUpdate.confirmed;
+        }
+        if (args.casualtyUpdate.treated !== undefined) {
+          inc.casualties.treated = args.casualtyUpdate.treated;
+        }
       }
-      if (args.casualtyUpdate.treated !== undefined) {
-        inc.casualties.treated = args.casualtyUpdate.treated;
-      }
-    }
 
-    // Only touch resources still assigned to THIS incident — a unit that
-    // radioed available and was re-dispatched elsewhere belongs to its
-    // new incident now.
-    const ownResources = state.resources.filter((r) => r.assignedIncident === inc.id);
+      // Only touch resources still assigned to THIS incident — a unit that
+      // radioed available and was re-dispatched elsewhere belongs to its
+      // new incident now.
+      const ownResources = state.resources.filter((r) => r.assignedIncident === inc.id);
 
-    if (args.status === "resolved") {
-      for (const r of ownResources) {
-        r.status = "returning";
-        r.assignedIncident = null;
-        r.eta = null;
+      if (args.status === "resolved") {
+        for (const r of ownResources) {
+          r.status = "returning";
+          r.assignedIncident = null;
+          r.eta = null;
+        }
+        inc.assignedResources = [];
+        logEvent(inc, "All resources released — incident closed");
       }
-      inc.assignedResources = [];
-      logEvent(inc, "All resources released — incident closed");
-    }
 
-    if (args.status === "en_route" || args.status === "on_scene") {
-      for (const r of ownResources) {
-        r.status = args.status;
-        if (args.status === "on_scene") r.eta = null;
+      if (args.status === "en_route" || args.status === "on_scene") {
+        for (const r of ownResources) {
+          r.status = args.status;
+          if (args.status === "on_scene") r.eta = null;
+        }
       }
-    }
 
-    return {
-      incidentId: args.incidentId,
-      newStatus: args.status,
-      timeline: inc.timeline.slice(-5).map((t) => t.event),
-      casualties: inc.casualties,
-    };
-  },
+      return {
+        incidentId: args.incidentId,
+        newStatus: args.status,
+        timeline: inc.timeline.slice(-5).map((t) => t.event),
+        casualties: inc.casualties,
+      };
+    }),
 });

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

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import type { Incident, IncidentType, Severity } from "../shared.ts";
-import { calculateTriageScore, createIncident, dispatchSlot } from "../shared.ts";
+import { calculateTriageScore, callFlow, createIncident, dispatchSlot } from "../shared.ts";
 
 type ScenarioIncident = Pick<Incident, "location" | "description" | "type" | "severity">;
 type ScenarioDef = { narrative: string; incidents: ScenarioIncident[] };
@@ -116,12 +116,15 @@ const scenarios = {
 type ScenarioName = keyof typeof scenarios;
 const SCENARIO_NAMES = Object.keys(scenarios) as [ScenarioName, ...ScenarioName[]];
 
+/** Logs incidents like a real call does, so it sends `LOGGED` for the same
+ *  reason `incident_create` does — and is ungated for the same reason too: a
+ *  drill may be started at any point in a shift. */
 export default dispatchSlot.updateTool({
   description: "Run a training scenario that creates simulated incidents for dispatch practice.",
   inputSchema: z.object({
     scenario: z.enum(SCENARIO_NAMES).describe("Scenario type to simulate"),
   }),
-  execute(args, state) {
+  execute(args, state, ctx) {
     const s = scenarios[args.scenario];
 
     const created: string[] = [];
@@ -140,6 +143,9 @@ export default dispatchSlot.updateTool({
       scenario: args.scenario,
       narrative: s.narrative,
       incidentsCreated: created,
+      // As `incident_create`: the position spread verbatim, so an ungated tool
+      // reports it under the same keys a gated one does.
+      ...callFlow.send(ctx, { type: "LOGGED" }),
       message: `SCENARIO ACTIVE: ${s.narrative}. ${created.length} incidents created. Awaiting dispatch orders.`,
     };
   },

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,
 });