@alexkroman1/aai-cli 5.14.0 → 6.1.0

package/dist/templates/dispatch-center/shared.ts

@@ -1,7 +1,7 @@
 // ─── Types ───────────────────────────────────────────────────────────────────
 
-import type { ToolFailure } from "@alexkroman1/aai";
-import { pushCapped, type SlotStateOf, sessionSlot } from "@alexkroman1/aai";
+import type { DeepReadonly, ToolFailure } from "@alexkroman1/aai";
+import { pushCapped, sessionSlot } from "@alexkroman1/aai";
 
 export const SEVERITIES = ["critical", "urgent", "moderate", "minor"] as const;
 export type Severity = (typeof SEVERITIES)[number];
@@ -101,7 +101,7 @@ export interface IncidentSummary {
   location: string;
 }
 
-export function incidentSummary(inc: Incident): IncidentSummary {
+export function incidentSummary(inc: DeepReadonly<Incident>): IncidentSummary {
   return { id: inc.id, severity: inc.severity, status: inc.status, location: inc.location };
 }
 
@@ -114,7 +114,7 @@ export interface DashboardView {
 /** The `syncState` projection — the whole contract with client.tsx. Takes the
  *  board itself, not the slot: `dispatchSlot.projection` supplies a real one
  *  even before the first tool call. */
-export function dashboardView(state: DispatchState): DashboardView {
+export function dashboardView(state: FrozenDispatchState): DashboardView {
   return {
     systemAlertLevel: state.alertLevel,
     incidents: Object.values(state.incidents).map(incidentSummary),
@@ -162,9 +162,9 @@ export function createDefaultState(): DispatchState {
 }
 
 // ─── State helpers ───────────────────────────────────────────────────────────
-// The dispatch board lives in `ctx.state`, the agent's per-session mutable
-// state — sessions must not see each other's incidents, and ctx.state gives
-// that isolation by construction. Nothing here needs to outlive the session.
+// The dispatch board lives in one `sessionSlot`, keyed per session — sessions
+// must not see each other's incidents, and a slot gives that isolation by
+// construction.
 
 /**
  * Growth caps. The whole dispatch state is one object whose summaries feed
@@ -186,12 +186,22 @@ function pruneState(state: DispatchState): void {
 }
 
 /**
- * The session's dispatch board, as one typed slot inside `ctx.state`.
+ * The session's dispatch board, as one typed slot.
  *
- * Mutating tools go through `dispatchSlot.update`, which serializes them per
- * session: the LLM loop runs a step's tool calls concurrently, and two
- * interleaving async mutators would each observe the other's half-applied
- * changes.
+ * Every tool here is declared through the slot rather than reaching for it from
+ * inside a `tool()` body, and WHICH HALF is the whole decision: `updateTool`
+ * runs the body inside the mutation window and hands it a draft that is stored
+ * when the body returns, `tool` hands it the deep-frozen stored value. That
+ * makes "does this tool write?" a property of the declaration a reader can see,
+ * and choosing wrong a compile error rather than a `TypeError` on the first
+ * call.
+ *
+ * The window is SYNCHRONOUS, which is what makes a read-modify-write atomic
+ * with no lock — the LLM loop runs a step's tool calls concurrently. It does
+ * NOT serialize anything (an earlier version of this comment claimed it did):
+ * there is nothing to serialize, because no other JS turn can interleave with
+ * a synchronous body. `updateTool` is what enforces the rule, refusing a
+ * thenable body by name.
  *
  * `after` is the bookkeeping every mutating tool needs and none of them should
  * have to remember — pruning resolved incidents, and recalculating the alert
@@ -205,7 +215,16 @@ export const dispatchSlot = sessionSlot("dispatch", createDefaultState, {
   },
 });
 
-export type StateSlot = SlotStateOf<typeof dispatchSlot>;
+/**
+ * The board as a READ hands it out: deep-frozen, and typed to say so.
+ *
+ * The pure helpers below take this rather than {@link DispatchState}, which is
+ * the widening a deep-readonly slot forces and the reason it is worth doing: a
+ * mutable board still satisfies it, so a helper called with an `updateTool`
+ * draft is unaffected, while a helper that WOULD have mutated stops compiling
+ * instead of throwing at its first call in production.
+ */
+export type FrozenDispatchState = DeepReadonly<DispatchState>;
 
 // ─── Incident helpers ────────────────────────────────────────────────────────
 
@@ -237,7 +256,20 @@ export function createIncident(state: DispatchState, overrides: Partial<Incident
   return incident;
 }
 
-export function findIncident(state: DispatchState, incidentId: string): Incident | ToolFailure {
+/**
+ * One incident by id, or the failure the model should read.
+ *
+ * Generic over the incident's own type rather than pinned to {@link Incident},
+ * so ONE lookup serves both halves of the slot: a mutating tool passes its
+ * draft and gets a mutable incident back to change, while `incident_get` passes
+ * what `dispatchSlot.tool` handed it — deep-frozen — and gets a readonly one.
+ * Pinning it would have made the read path the odd one out, and its way out
+ * would have been a cast.
+ */
+export function findIncident<I extends DeepReadonly<Incident>>(
+  state: { readonly incidents: { readonly [id: string]: I } },
+  incidentId: string,
+): I | ToolFailure {
   return state.incidents[incidentId] ?? { error: `Incident ${incidentId} not found` };
 }
 
@@ -251,17 +283,19 @@ export function logEvent(inc: Incident, event: string): void {
 }
 
 /** Minutes since the incident was created, rounded. */
-export function incidentAgeMinutes(inc: Incident): number {
+export function incidentAgeMinutes(inc: DeepReadonly<Incident>): number {
   return Math.round((Date.now() - inc.createdAt) / 60_000);
 }
 
 /** A resource as tool results describe it to the LLM. */
-export function resourceBrief(r: Resource): {
+export function resourceBrief(r: DeepReadonly<Resource>): {
   callsign: string;
   type: Resource["type"];
   capabilities: string[];
 } {
-  return { callsign: r.callsign, type: r.type, capabilities: r.capabilities };
+  // `capabilities` is COPIED: a brief is a fresh object handed to the LLM, and
+  // the source list belongs either to a frozen slot value or to a live draft.
+  return { callsign: r.callsign, type: r.type, capabilities: [...r.capabilities] };
 }
 
 /**
@@ -269,7 +303,7 @@ export function resourceBrief(r: Resource): {
  * resources have been released (and possibly reassigned), so escalating,
  * re-resolving, or dispatching to it would corrupt resource assignments.
  */
-export function assertNotResolved(inc: Incident, action: string): ToolFailure | null {
+export function assertNotResolved(inc: DeepReadonly<Incident>, action: string): ToolFailure | null {
   if (inc.status === "resolved") {
     return {
       error: `Incident ${inc.id} is resolved — cannot ${action}. Create a new incident if the situation has reopened.`,
@@ -575,7 +609,7 @@ export function recommendResources(
 /** Fraction of resources not currently available, 0–1. The alert level and
  *  the dashboard's displayed utilization both derive from this, so they can
  *  never disagree about what "utilization" means. */
-export function resourceUtilization(state: DispatchState): number {
+export function resourceUtilization(state: FrozenDispatchState): number {
   const available = state.resources.filter((r) => r.status === "available").length;
   return 1 - available / state.resources.length;
 }

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

@@ -1,27 +1,25 @@
-import { isToolFailure, tool } from "@alexkroman1/aai";
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { dispatchSlot, findIncident, logEvent } from "../shared.ts";
 
-export const incidentAddNote = tool({
+export default dispatchSlot.updateTool({
   description: "Add a situational update note to an incident's timeline.",
   inputSchema: z.object({
     incidentId: z.string().max(20).describe("The incident ID"),
     note: z.string().max(1000).describe("The note to add"),
     source: z.string().max(100).describe("Who reported this — unit callsign or caller").optional(),
   }),
-  async execute(args, ctx) {
-    return dispatchSlot.update(ctx, (state) => {
-      const inc = findIncident(state, args.incidentId);
-      if (isToolFailure(inc)) return inc;
+  execute(args, state) {
+    const inc = findIncident(state, args.incidentId);
+    if (isToolFailure(inc)) return inc;
 
-      const entry = args.source ? `[${args.source}] ${args.note}` : args.note;
-      logEvent(inc, entry);
+    const entry = args.source ? `[${args.source}] ${args.note}` : args.note;
+    logEvent(inc, entry);
 
-      return {
-        incidentId: args.incidentId,
-        noteAdded: entry,
-        timelineEntries: inc.timeline.length,
-      };
-    });
+    return {
+      incidentId: args.incidentId,
+      noteAdded: entry,
+      timelineEntries: inc.timeline.length,
+    };
   },
 });

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

@@ -1,4 +1,3 @@
-import { tool } from "@alexkroman1/aai";
 import { z } from "zod";
 import {
   calculateTriageScore,
@@ -11,7 +10,7 @@ import {
   resourceBrief,
 } from "../shared.ts";
 
-export const incidentCreate = tool({
+export default dispatchSlot.updateTool({
   description: "Create a new incident from an incoming emergency call.",
   inputSchema: z.object({
     location: z.string().max(300).describe("Address or location description"),
@@ -30,50 +29,48 @@ export const incidentCreate = tool({
       .describe("Known hazards: fire, chemical, electrical, structural, weapons")
       .optional(),
   }),
-  async execute(args, ctx) {
-    return dispatchSlot.update(ctx, (state) => {
-      const recSeverity = recommendSeverity(args.description);
-      const recType = recommendType(args.description);
-      const triageScore = calculateTriageScore(
-        recSeverity,
-        recType,
-        args.estimatedCasualties ?? 0,
-        args.hazards?.length ?? 0,
-      );
+  execute(args, state) {
+    const recSeverity = recommendSeverity(args.description);
+    const recType = recommendType(args.description);
+    const triageScore = calculateTriageScore(
+      recSeverity,
+      recType,
+      args.estimatedCasualties ?? 0,
+      args.hazards?.length ?? 0,
+    );
 
-      const incident = createIncident(state, {
-        type: recType,
-        severity: recSeverity,
-        location: args.location,
-        description: args.description,
-        callerName: args.callerName ?? "Unknown",
-        callerPhone: args.callerPhone ?? "Unknown",
-        triageScore,
-        timeline: [{ time: Date.now(), event: `Incident created: ${args.description}` }],
-        casualties: {
-          confirmed: 0,
-          estimated: args.estimatedCasualties ?? 0,
-          treated: 0,
-        },
-        hazards: args.hazards ?? [],
-      });
-      const id = incident.id;
+    const incident = createIncident(state, {
+      type: recType,
+      severity: recSeverity,
+      location: args.location,
+      description: args.description,
+      callerName: args.callerName ?? "Unknown",
+      callerPhone: args.callerPhone ?? "Unknown",
+      triageScore,
+      timeline: [{ time: Date.now(), event: `Incident created: ${args.description}` }],
+      casualties: {
+        confirmed: 0,
+        estimated: args.estimatedCasualties ?? 0,
+        treated: 0,
+      },
+      hazards: args.hazards ?? [],
+    });
+    const id = incident.id;
 
-      const protocols = getApplicableProtocols(recType, recSeverity);
-      const recommended = recommendResources(recType, recSeverity, state);
+    const protocols = getApplicableProtocols(recType, recSeverity);
+    const recommended = recommendResources(recType, recSeverity, state);
 
-      return {
-        incidentId: id,
-        recommendedSeverity: recSeverity,
-        recommendedType: recType,
-        triageScore,
-        applicableProtocols: protocols.map((p) => p.name),
-        recommendedResources: recommended.map(resourceBrief),
-        message:
-          recSeverity === "critical"
-            ? `PRIORITY ONE — ${id} created. Immediate dispatch recommended. ${protocols.length} protocol(s) applicable.`
-            : `${id} created. Triage score ${triageScore}. ${recommended.length} resource(s) recommended.`,
-      };
-    });
+    return {
+      incidentId: id,
+      recommendedSeverity: recSeverity,
+      recommendedType: recType,
+      triageScore,
+      applicableProtocols: protocols.map((p) => p.name),
+      recommendedResources: recommended.map(resourceBrief),
+      message:
+        recSeverity === "critical"
+          ? `PRIORITY ONE — ${id} created. Immediate dispatch recommended. ${protocols.length} protocol(s) applicable.`
+          : `${id} created. Triage score ${triageScore}. ${recommended.length} resource(s) recommended.`,
+    };
   },
 });

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

@@ -1,4 +1,4 @@
-import { isToolFailure, tool } from "@alexkroman1/aai";
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import {
   assertNotResolved,
@@ -9,7 +9,7 @@ import {
   recommendResources,
 } from "../shared.ts";
 
-export const incidentEscalate = tool({
+export default dispatchSlot.updateTool({
   description: "Escalate an incident when it exceeds current capacity or severity increases.",
   inputSchema: z.object({
     incidentId: z.string().max(20).describe("The incident ID"),
@@ -20,69 +20,67 @@ export const incidentEscalate = tool({
       .optional(),
     newSeverity: z.enum(["critical", "urgent"]).describe("Escalated severity level").optional(),
   }),
-  async execute(args, ctx) {
-    return dispatchSlot.update(ctx, (state) => {
-      const inc = findIncident(state, args.incidentId);
-      if (isToolFailure(inc)) return inc;
-      const blocked = assertNotResolved(inc, "escalate");
-      if (blocked) return blocked;
+  execute(args, 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"],
-          },
-        );
-      }
-
-      inc.triageScore = calculateTriageScore(
-        inc.severity,
-        inc.type,
-        inc.casualties.estimated,
-        inc.hazards.length,
+    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"],
+        },
       );
+    }
 
-      const additionalResources = recommendResources(inc.type, inc.severity, state).filter(
-        (r) => !inc.assignedResources.includes(r.id),
-      );
+    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),
+    );
 
-      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_get.ts

@@ -1,4 +1,4 @@
-import { isToolFailure, tool } from "@alexkroman1/aai";
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import {
   dispatchSlot,
@@ -7,13 +7,12 @@ import {
   incidentAgeMinutes,
 } from "../shared.ts";
 
-export const incidentGet = tool({
+export default dispatchSlot.tool({
   description: "Get full details on a specific incident including timeline and assigned resources.",
   inputSchema: z.object({
     incidentId: z.string().max(20).describe("The incident ID"),
   }),
-  async execute(args, ctx) {
-    const state = dispatchSlot.get(ctx);
+  execute(args, state) {
     const inc = findIncident(state, args.incidentId);
     if (isToolFailure(inc)) return inc;
 

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

@@ -1,4 +1,4 @@
-import { isToolFailure, tool } from "@alexkroman1/aai";
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import {
   assertNotResolved,
@@ -12,7 +12,7 @@ import {
   SEVERITIES,
 } from "../shared.ts";
 
-export const incidentTriage = tool({
+export default dispatchSlot.updateTool({
   description:
     "Triage an incident — confirm or override severity, type, hazards, and casualty count.",
   inputSchema: z.object({
@@ -27,52 +27,50 @@ export const incidentTriage = tool({
     casualtyUpdate: z.number().int().nonnegative().describe("Updated casualty count").optional(),
     notes: z.string().max(1000).describe("Triage notes").optional(),
   }),
-  async execute(args, ctx) {
-    return dispatchSlot.update(ctx, (state) => {
-      const inc = findIncident(state, args.incidentId);
-      if (isToolFailure(inc)) return inc;
-      const blocked = assertNotResolved(inc, "triage");
-      if (blocked) return blocked;
+  execute(args, 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,
+      })),
+    };
   },
 });