@alexkroman1/aai-cli 7.0.0 → 8.1.0

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