@alexkroman1/aai-cli 6.11.0 → 8.0.0

package/dist/templates/briefing-desk/shared.ts

@@ -0,0 +1,200 @@
+/**
+ * The desk's two subagents, and the board of what they have found.
+ *
+ * **This template is the worked example for `ctx.delegate`.** Everything here
+ * exists to show the three things a subagent buys that `ctx.generate` cannot:
+ *
+ * 1. **A context window the caller never pays for.** `researcher` reads whole
+ *    web pages. A briefing on four angles can spend a hundred thousand tokens
+ *    doing it, and what comes back into the phone call's conversation is four
+ *    paragraphs — because {@link DelegateResult.text} is the subagent's final
+ *    message and nothing else crosses back.
+ * 2. **Parallelism.** Four angles are four independent runs, so
+ *    `tools/research_topic.ts` fans them out with one `Promise.allSettled` and
+ *    the caller waits for the slowest, not for the sum.
+ * 3. **Tools isolated by capability.** `researcher` can read the open web;
+ *    `factChecker` can only search it, on a cheaper model with a third of the
+ *    budget. Neither can reach the other's tools, and the DESK — the voice
+ *    agent the caller is talking to — has no web tools at all.
+ */
+
+import {
+  type DeepReadonly,
+  type DelegateFn,
+  type DelegateOptions,
+  type DelegateResult,
+  pushCapped,
+  type SubagentToolCall,
+  sessionSlot,
+  subagent,
+} from "@alexkroman1/aai";
+import { assemblyAILlm } from "@alexkroman1/aai/llm";
+
+/**
+ * Steps one angle may take. A budget, not a limit to be raised when an answer
+ * disappoints: a subagent told to "keep looking until sure" is a subagent whose
+ * cost nobody can quote, and the caller is on the phone. Past it the researcher
+ * is asked for its answer with its tools withheld, so a capped run still comes
+ * back with prose rather than stopping mid-chain.
+ */
+export const MAX_RESEARCH_STEPS = 6;
+
+/**
+ * The researcher, and the one line that decides whether any of this works.
+ *
+ * "Finish with a summary" is not politeness. The parent gets the subagent's
+ * FINAL message, so a run that ends by saying "Done." has thrown away
+ * everything it read and no budget recovers it — this is the failure mode the
+ * `SubagentDef.instructions` contract warns about, stated once, here.
+ */
+export const researcher = subagent({
+  name: "researcher",
+  instructions: [
+    "You are a research agent working one angle of a briefing.",
+    "",
+    "Search, then open the two or three most promising pages and read them.",
+    "Prefer primary sources and recent ones. If the sources disagree, say so",
+    "rather than picking a side.",
+    "",
+    "IMPORTANT: your FINAL message is the only thing the desk receives — it",
+    "does not see your searches, the pages you opened, or your reasoning. End",
+    "with a self-contained paragraph of what you found, naming the sources you",
+    "trusted. Three sentences is plenty; do not write a report.",
+  ].join("\n"),
+  // Read/browse. Independent of the desk's own builtins, which are none: the
+  // agent the caller talks to never touches the network.
+  builtinTools: ["web_search", "visit_webpage"],
+  maxSteps: MAX_RESEARCH_STEPS,
+});
+
+/**
+ * The fact-checker: a second ROLE, deliberately narrower than the first.
+ *
+ * Its own `llm` (cheaper and quicker — checking one sentence is not the job
+ * `researcher` does), its own budget, and search only. That split is the third
+ * reason to reach for a subagent: a capability a run does not need is one it
+ * cannot misuse.
+ */
+export const factChecker = subagent({
+  name: "fact-checker",
+  instructions: [
+    "You check ONE claim against what you can find on the web.",
+    "",
+    "Search for it. Answer in one sentence, starting with one of",
+    "'Confirmed:', 'Contradicted:' or 'Unclear:', and name what you found.",
+    "'Unclear' is a real answer — say it rather than guessing.",
+  ].join("\n"),
+  llm: assemblyAILlm({ model: "gemini-2.5-flash-lite" }),
+  builtinTools: ["web_search"],
+  maxSteps: 2,
+});
+
+/** One angle, as the desk holds it. */
+export interface Finding {
+  /** The angle the researcher was given. */
+  angle: string;
+  /** Its final message — the whole of what crossed back. */
+  summary: string;
+  /** Searches it ran and pages it opened, for narrating the wait. */
+  work: AngleWork;
+}
+
+/** What one angle COST, as the desk is willing to say it out loud. */
+export interface AngleWork {
+  searches: number;
+  reads: number;
+}
+
+/**
+ * The brief one angle is sent with.
+ *
+ * Its own function because the `context` line is the whole of what a
+ * researcher learns about the call it belongs to — a subagent's context is
+ * ISOLATED, so anything the conversation knows and the angle does not say is
+ * lost unless it is written here. A spec asserts on this rather than on a
+ * template literal buried in a tool body.
+ */
+export function angleBrief(topic: string, angle: string): DelegateOptions {
+  return { task: angle, context: `This angle belongs to a briefing on: ${topic}.` };
+}
+
+/**
+ * What a run did, read off the calls it made.
+ *
+ * {@link DelegateResult.toolCalls} carries the CALLS and not their results —
+ * the results are what stayed in the subagent's window — so this is the most
+ * the desk can honestly say about the wait. An unrecognised tool name counts
+ * as neither: a researcher that gains a third tool should not silently inflate
+ * "searches".
+ */
+export function countWork(toolCalls: readonly SubagentToolCall[]): AngleWork {
+  let searches = 0;
+  let reads = 0;
+  for (const call of toolCalls) {
+    if (call.name === "web_search") searches += 1;
+    else if (call.name === "visit_webpage") reads += 1;
+  }
+  return { searches, reads };
+}
+
+/**
+ * Run one angle and reduce it to what the board holds.
+ *
+ * Takes the DELEGATE rather than the whole tool context — the same seam
+ * `plan-and-execute` puts on `ctx.generate`. The desk's own logic is then
+ * exercised against a fake without a context at all, and the tool that fans
+ * these out stays one line per angle.
+ */
+export async function researchAngle(
+  delegate: DelegateFn,
+  topic: string,
+  angle: string,
+): Promise<Finding> {
+  const result: DelegateResult = await delegate(researcher, angleBrief(topic, angle));
+  return { angle, summary: result.text, work: countWork(result.toolCalls) };
+}
+
+/** Angles one `research_topic` call may fan out. Four researchers at once is
+ *  already four model bills; past that a caller is waiting on a queue. */
+export const MAX_ANGLES = 4;
+
+/** Findings the board holds. Older ones fall off — they ride in every prompt
+ *  the desk builds and in every recap it reads back. */
+export const MAX_FINDINGS = 12;
+
+export interface BriefingState {
+  /** What the caller asked about, as last stated. */
+  topic: string | null;
+  /** Every angle researched on this call, oldest first. */
+  findings: Finding[];
+}
+
+export function emptyBriefing(): BriefingState {
+  return { topic: null, findings: [] };
+}
+
+export const briefingSlot = sessionSlot("briefing", emptyBriefing);
+
+/** Record a finding, holding {@link MAX_FINDINGS}. */
+export function recordFinding(state: BriefingState, finding: Finding): void {
+  pushCapped(state.findings, finding, MAX_FINDINGS);
+}
+
+/**
+ * The board as a READ hands it out — deep-frozen, and typed to say so, which is
+ * what a slot's read returns.
+ */
+export type FrozenBriefing = DeepReadonly<BriefingState>;
+
+/** A finding named by what the caller would say: its angle, loosely matched. */
+export function findByAngle(
+  state: FrozenBriefing,
+  angle: string,
+): DeepReadonly<Finding> | undefined {
+  const wanted = angle.trim().toLowerCase();
+  if (wanted === "") return undefined;
+  return state.findings.find(
+    (finding) =>
+      finding.angle.toLowerCase().includes(wanted) || wanted.includes(finding.angle.toLowerCase()),
+  );
+}

package/dist/templates/briefing-desk/system-prompt.md

@@ -0,0 +1,39 @@
+You are the Briefing Desk. Someone has phoned you to find out about something,
+and you have a small team of researchers you can put on it.
+
+## How you work
+
+- You have no way to look anything up yourself. Everything you know about the
+  outside world comes back from `research_topic` or `verify_claim`.
+- When the caller names a subject, decide the two or three ANGLES worth
+  researching and call `research_topic` once with all of them. Do not call it
+  once per angle — they run in parallel, and that is why the caller is not
+  waiting four times over.
+- Each angle must stand on its own. A researcher has not heard this call and
+  cannot see the others' work, so "the same but for Europe" is not an angle;
+  "how European home battery prices moved in 2025" is.
+- Say you are looking it up BEFORE you call the tool. A silent line is the
+  worst thing that can happen on a phone call, and a briefing takes a moment.
+
+## How you talk
+
+- Lead with the through-line — what it all adds up to — in one or two
+  sentences. Then the angles, one at a time, in the order that makes the point.
+- Never read a summary out verbatim. They are written to be read, and you are
+  being listened to: shorten, and say the number rather than the sentence
+  around it.
+- Say where something came from when it matters ("the manufacturers' own
+  figures say", "one industry blog says") and say when your researchers
+  disagreed. A briefing that flattens a disagreement is worse than no briefing.
+- If the caller pushes back on a fact, check it with `verify_claim` rather than
+  defending it. If it comes back contradicted, correct yourself plainly.
+- `briefing_so_far` is for a recap. It costs nothing, so use it rather than
+  reciting from memory.
+
+## What not to do
+
+- Do not answer a factual question about the world from memory. If you have not
+  had it researched on this call, say so and offer to look it up.
+- Do not offer more angles than you can hold. Three good ones beat six.
+- Do not describe your researchers, your tools, or how any of this works unless
+  the caller asks. They phoned a desk, not an architecture.

package/dist/templates/briefing-desk/tools/briefing_so_far.ts

@@ -0,0 +1,35 @@
+import { tool } from "@alexkroman1/aai";
+import { z } from "zod";
+import { briefingSlot } from "../shared.ts";
+
+/**
+ * Read the board back.
+ *
+ * The one tool here that spends no model at all, and it earns its place for
+ * that reason: a caller who says "what have you got so far" after four
+ * delegated runs should not cost a fifth. What the desk knows is on the slot;
+ * this hands it over.
+ */
+export default tool({
+  description:
+    "List the angles researched on this call and what each one found. Use it " +
+    "when the caller asks for a recap, or before you offer to dig further.",
+  inputSchema: z.object({}),
+  execute: (_args, ctx) => {
+    const board = briefingSlot.get(ctx);
+    if (board.findings.length === 0) {
+      return {
+        topic: null,
+        findings: [],
+        message: "Nothing researched yet — ask what they want looked into.",
+      };
+    }
+    return {
+      topic: board.topic,
+      findings: board.findings,
+      totalSearches: board.findings.reduce((sum, finding) => sum + finding.work.searches, 0),
+      totalReads: board.findings.reduce((sum, finding) => sum + finding.work.reads, 0),
+      message: "Recap the through-line in one breath, then offer to go deeper on one angle.",
+    };
+  },
+});

package/dist/templates/briefing-desk/tools/research_topic.ts

@@ -0,0 +1,88 @@
+import { errorMessage, tool, toolFailure } from "@alexkroman1/aai";
+import { z } from "zod";
+import type { Finding } from "../shared.ts";
+import { briefingSlot, MAX_ANGLES, recordFinding, researchAngle } from "../shared.ts";
+
+/**
+ * Fan a topic out across angles, one researcher subagent each, in PARALLEL.
+ *
+ * **The `Promise.allSettled` is the template's whole point.** Each angle is an
+ * independent run with its own context window, so four of them cost the caller
+ * the SLOWEST one rather than the sum — and nothing they read reaches this
+ * conversation, only what each one concluded. Running the same four angles as
+ * four `ctx.generate` calls in one loop would be slower and would put every
+ * intermediate page in the desk's own prompt.
+ *
+ * **`allSettled`, not `all`.** One angle that fails (a provider hiccup, a
+ * subagent that ran out of budget with nothing to say) must not sink a
+ * briefing whose other three came back — a caller on the phone would rather
+ * hear three answers and one apology than an error. The failures are reported
+ * BY ANGLE so the desk can say which one is missing and offer to retry it.
+ *
+ * **The await comes first, then the mutation.** `slot.update`'s window is
+ * synchronous by contract, so the fan-out finishes before the board is touched
+ * and the whole write lands at once.
+ */
+export default tool({
+  description:
+    "Research a topic across several angles at once and report what each one " +
+    "found. Use this when the caller asks about something you would need to " +
+    "look up. Pick the angles yourself from what they said — two or three is " +
+    "usually right. Tell them you are looking it up before you call this.",
+  inputSchema: z.object({
+    topic: z.string().max(200).describe("The subject, in the caller's own terms"),
+    angles: z
+      .array(z.string().max(200))
+      .min(1)
+      .max(MAX_ANGLES)
+      .describe(
+        "The separate questions to research, one per researcher. Each must " +
+          "stand on its own: a researcher has not heard the conversation.",
+      ),
+  }),
+  async execute(args, ctx) {
+    const angles = args.angles.map((angle) => angle.trim()).filter((angle) => angle.length > 0);
+    if (angles.length === 0) {
+      return toolFailure("No angles to research — say what the caller wants looked up.");
+    }
+
+    const settled = await Promise.allSettled(
+      angles.map((angle) => researchAngle(ctx.delegate, args.topic, angle)),
+    );
+
+    // Two typed lists rather than one union filtered twice: `"summary" in one`
+    // reads fine and narrows nothing a `.filter` result keeps, so the union
+    // version needs a cast — the laundering this repo's ratchet counts.
+    const summaries: Finding[] = [];
+    const failures: { angle: string; error: string }[] = [];
+    settled.forEach((outcome, index) => {
+      if (outcome.status === "fulfilled") {
+        summaries.push(outcome.value);
+        return;
+      }
+      failures.push({ angle: angles[index] ?? "", error: errorMessage(outcome.reason) });
+    });
+
+    if (summaries.length === 0) {
+      return toolFailure(
+        `Every angle failed. The first said: ${failures[0]?.error ?? "no reason given"}`,
+      );
+    }
+
+    return briefingSlot.update(ctx, (board) => {
+      board.topic = args.topic;
+      for (const finding of summaries) recordFinding(board, finding);
+      return {
+        topic: args.topic,
+        findings: summaries,
+        failed: failures,
+        message:
+          "Give the caller the through-line first, in one or two sentences, then " +
+          "the angles. Do not read the summaries out verbatim." +
+          (failures.length > 0
+            ? " Mention which angle you could not get to and offer to try it again."
+            : ""),
+      };
+    });
+  },
+});

package/dist/templates/briefing-desk/tools/verify_claim.ts

@@ -0,0 +1,77 @@
+import { errorMessage, omitUndefined, tool, toolFailure } from "@alexkroman1/aai";
+import { z } from "zod";
+import { briefingSlot, countWork, factChecker, findByAngle } from "../shared.ts";
+
+/**
+ * Check one sentence against the web, on the narrower of the desk's two
+ * subagents.
+ *
+ * **Why this is a second SUBAGENT and not a second prompt.** Checking a claim
+ * needs a search and one sentence back, so it runs on a cheaper model with a
+ * third of the researcher's budget and search only — no page reads. Expressing
+ * that as `ctx.generate` would mean the desk doing the searching itself, in the
+ * conversation's own context; expressing it as one subagent with two modes
+ * would mean a run that can browse whenever the model feels like it. A
+ * capability a run does not need is one it cannot misuse.
+ *
+ * **The claim may be quoted from the board.** The caller says "check the second
+ * thing you told me", so `about` names an angle and the claim is read out of
+ * the slot — a subagent has not heard the call, and handing it "the second
+ * thing" as its task would get a confident answer about nothing.
+ */
+export default tool({
+  description:
+    "Check one specific factual claim against the web. Use it when the caller " +
+    "pushes back on something, or asks whether a finding is right. Pass the " +
+    "claim as a complete sentence.",
+  inputSchema: z.object({
+    claim: z
+      .string()
+      .max(400)
+      .describe("The claim to check, stated as one self-contained sentence"),
+    about: z
+      .string()
+      .max(200)
+      .optional()
+      .describe(
+        "The angle this claim came from, when the caller is pointing at " +
+          "something already on the board",
+      ),
+  }),
+  async execute(args, ctx) {
+    const claim = args.claim.trim();
+    if (claim === "") return toolFailure("Nothing to check — say the claim in a full sentence.");
+
+    const board = briefingSlot.get(ctx);
+    const source = args.about ? findByAngle(board, args.about) : undefined;
+
+    let verdict: string;
+    let searches: number;
+    try {
+      // What the checker gets of the conversation, and no more: the finding the
+      // claim came out of, so it can tell a misquote from a disagreement.
+      // Through `omitUndefined` rather than a truthiness-guarded spread — the
+      // repo's one spelling for an optional field, and the shape its own
+      // `guard-invariants` rule 22 counts as debt.
+      const context = source ? `The desk told the caller: ${source.summary}` : undefined;
+      const result = await ctx.delegate(factChecker, {
+        task: claim,
+        ...omitUndefined({ context }),
+      });
+      verdict = result.text;
+      searches = countWork(result.toolCalls).searches;
+    } catch (err: unknown) {
+      return toolFailure(`The check did not come back: ${errorMessage(err)}`);
+    }
+
+    return {
+      claim,
+      verdict,
+      searches,
+      checkedAgainst: source?.angle ?? null,
+      message:
+        "Say the verdict plainly, in the caller's words. If it is contradicted, " +
+        "correct what you told them earlier rather than defending it.",
+    };
+  },
+});