@alexkroman1/aai-cli 5.14.0 → 6.1.0

package/dist/templates/research-workflow/agent.test.ts

@@ -0,0 +1,525 @@
+// Copyright 2026 the AAI authors. MIT license.
+/// <reference types="vite/client" />
+
+/**
+ * Specs for the research desk's four tools.
+ *
+ * All are exercised against a STUBBED `ctx.workflows`, which is the only honest
+ * way to unit-test them: the real client needs a Workflow DevKit world, and the
+ * bodies in `workflows/` are only durable once the build has transformed them.
+ * What these assert is the agent's half of the contract — that the handoff tool
+ * passes the correlation key, that the status tool narrows a snapshot correctly
+ * before reading it aloud, and that the two tools reaching PAST a status (the
+ * progress stream, the early wake) ask for what a voice reply can use.
+ *
+ * The STEPS are exercised separately, and directly: imported through vitest with
+ * no bundler in the path, a `"use step"` function is an ordinary async function,
+ * so its prompt handling, its parsing and its `FatalError` guards are all
+ * testable — while durability, suspension and replay are not. The body itself is
+ * not driven here for that reason; `aai-cli`'s `dev-workflow.scenario.test.ts`
+ * builds a project and runs one.
+ */
+
+import type { ToolContext, WorkflowClient, WorkflowRunSnapshot } from "@alexkroman1/aai";
+import {
+  createProgressStream,
+  createRunSnapshot,
+  createStubWorkflows,
+  createToolContext,
+  runTool,
+  type StubGatewayCall,
+  withDiscoveredTools,
+} from "@alexkroman1/aai/testing";
+import { installStubGateway as stubGateway } from "@alexkroman1/aai/testing/vitest";
+import { visitWebpage, webSearch } from "@alexkroman1/aai/tools";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { FatalError, RetryableError } from "workflow";
+import authoredAgent from "./agent.ts";
+import { research } from "./shared.ts";
+import {
+  countSources,
+  dedupe,
+  findGaps,
+  investigate,
+  planAngles,
+  writeBrief,
+  writeReport,
+} from "./workflows/research.ts";
+
+/**
+ * The web, faked at the SDK's own seam.
+ *
+ * `webSearch` and `visitWebpage` screen a URL and then really fetch it, through
+ * an undici dispatcher a `globalThis.fetch` stub cannot reach — so mocking the
+ * module is the only honest way to keep this suite offline. What is asserted is
+ * that the researcher CALLS them with what the model asked for; the builtins'
+ * own behaviour is `aai`'s to test, and it does.
+ */
+vi.mock("@alexkroman1/aai/tools", () => ({
+  webSearch: vi.fn(async () => ({
+    results: [{ title: "Otters", url: "https://otters.example/tools" }],
+  })),
+  visitWebpage: vi.fn(async () => ({ content: "The page body." })),
+}));
+
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
+ *
+ * The glob is written HERE rather than reached for from a shared helper because
+ * this file SHIPS: it is what a scaffolded project runs, so it may not import
+ * anything outside its own template, and `import.meta.glob` is expanded against
+ * the file containing it either way. This is the pattern a user writes.
+ */
+const agentDef = withDiscoveredTools(
+  authoredAgent,
+  import.meta.glob("./tools/*.ts", { eager: true }),
+);
+
+/** Every tool here is driven through the agent's own table, by the name the model calls. */
+const run = (name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<unknown> =>
+  runTool(agentDef, name, args, ctx);
+
+/**
+ * A `ctx.workflows` that records `start` and answers `find` from a fixture.
+ *
+ * Returned WITHOUT a cast, which is the property worth keeping: a cast would
+ * also stop reporting the day `WorkflowClient` grows a method, and this stub is
+ * how the template's tools reach the client at all. `createStubWorkflows` is
+ * what keeps that affordable — it fills in the methods this desk does not
+ * drive, so the day the client does grow one, only the tests that use it change.
+ */
+function stubWorkflows(runs: WorkflowRunSnapshot[] = []): WorkflowClient {
+  return createStubWorkflows({
+    start: vi.fn(async () => "wrun_stub"),
+    get: vi.fn(async () => runs[0]),
+    find: vi.fn(async () => runs),
+    recent: vi.fn(async () => runs),
+    cancel: vi.fn(async () => true),
+    wakeUp: vi.fn(async () => 0),
+    // A tail of 0 means "one line written", which is the case the tools read.
+    // The `-1` case is overridden per test, because it is the one that decides
+    // whether the stream is opened at all.
+    streamTail: vi.fn(async () => 0),
+    stream: vi.fn(async () => createProgressStream([])),
+    // Name only: `WorkflowDef.description` is optional, so passing it through
+    // would mean handing `description: undefined` to a field that does not
+    // accept it. Nothing here reads the description anyway.
+    listing: () => [{ name: "research" }],
+  });
+}
+
+describe("the agent declares its workflow", () => {
+  test("under the name ctx.workflows.start resolves it by", () => {
+    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["research"]);
+    expect(agentDef.workflows?.research).toBe(research);
+  });
+
+  test("with an input schema, so a bad topic fails at the call site", async () => {
+    const result = await research.input?.["~standard"].validate({
+      topic: "otters",
+      requestedBy: "s",
+    });
+    expect(result?.issues).toBeUndefined();
+    const bad = await research.input?.["~standard"].validate({ topic: "no", requestedBy: "s" });
+    expect(bad?.issues).toBeDefined();
+  });
+});
+
+/**
+ * The options `request_research` starts its run with.
+ *
+ * AWAITED rather than `void`-ed. Reading a mock's call list off a floating
+ * promise worked only because the tool body happens to reach `start` before its
+ * first `await`; anything async landing ahead of that would have made this
+ * return `undefined` and the reader throw a `TypeError` instead of failing on
+ * the option it is about — and the dropped promise is an unhandled rejection
+ * either way.
+ *
+ * The return type is inferred from the mock, so `notify` arrives typed and the
+ * caller needs no cast.
+ */
+async function workflowsStartOptions() {
+  const workflows = stubWorkflows();
+  const ctx = createToolContext({ workflows });
+  await run("request_research", { topic: "otters" }, ctx);
+  return vi.mocked(workflows.start).mock.calls[0]?.[2];
+}
+
+describe("request_research", () => {
+  test("starts a run keyed by the session, so a later turn can find it", async () => {
+    const workflows = stubWorkflows();
+    const ctx = createToolContext({ workflows });
+    const result = await run("request_research", { topic: "otters" }, ctx);
+
+    expect(workflows.start).toHaveBeenCalledWith(
+      research,
+      { topic: "otters", requestedBy: ctx.sessionId },
+      // `key` is the DURABLE handle — a later call finds the run by it — and
+      // `notify` is the live one: this session is told when the run lands, which
+      // is what makes the agent's "I'll let you know" true.
+      { key: ctx.sessionId, notify: expect.stringContaining("read the summary") },
+    );
+    expect(result).toMatchObject({ started: true, runId: "wrun_stub", topic: "otters" });
+  });
+
+  test("asks to be TOLD when the run lands, rather than waiting to be asked", async () => {
+    // The gap this closes: the agent promised an update, the run finished, and
+    // nothing made it speak — so the caller had to think to ask again. A voice
+    // agent that starts durable work and never announces it is the shape to
+    // avoid, and one option is the whole fix.
+    const options = await workflowsStartOptions();
+    expect(options, "request_research started no run").toBeDefined();
+    expect(typeof options?.notify).toBe("string");
+  });
+
+  test("passes the definition rather than its name", async () => {
+    const workflows = stubWorkflows();
+    await run("request_research", { topic: "otters" }, createToolContext({ workflows }));
+    // The def overload is what types the input and turns a rename into a compile
+    // error; a string would still work at runtime and lose both.
+    expect(vi.mocked(workflows.start).mock.calls[0]?.[0]).toBe(research);
+  });
+});
+
+describe("research_status", () => {
+  test("says nothing was started when the key has no runs", async () => {
+    const ctx = createToolContext({ workflows: stubWorkflows([]) });
+    const result = await run("research_status", {}, ctx);
+    expect(result).toMatchObject({ runs: [], note: "Nothing started yet." });
+  });
+
+  test("reads a completed run's summary and source count back", async () => {
+    const runs = [
+      createRunSnapshot({
+        workflow: "research",
+        status: "completed",
+        output: { topic: "otters", summary: "Otters use tools.", sources: 3, filedAt: "now" },
+      }),
+    ];
+    const ctx = createToolContext({ workflows: stubWorkflows(runs) });
+    const result = (await run("research_status", {}, ctx)) as { runs: string[] };
+    expect(result.runs[0]).toContain("Otters use tools.");
+    expect(result.runs[0]).toContain("3 sources");
+  });
+
+  test("reports a live run as still working rather than as empty", async () => {
+    const ctx = createToolContext({
+      workflows: stubWorkflows([createRunSnapshot({ workflow: "research", status: "running" })]),
+    });
+    const result = (await run("research_status", {}, ctx)) as { runs: string[] };
+    expect(result.runs[0]).toContain("Still working on it.");
+  });
+
+  test("surfaces a failed run's message instead of swallowing it", async () => {
+    const runs = [
+      createRunSnapshot({ workflow: "research", status: "failed", error: "model unavailable" }),
+    ];
+    const ctx = createToolContext({ workflows: stubWorkflows(runs) });
+    const result = (await run("research_status", {}, ctx)) as { runs: string[] };
+    expect(result.runs[0]).toContain("model unavailable");
+  });
+
+  test("bounds how many past runs it reads aloud", async () => {
+    const workflows = stubWorkflows([]);
+    const ctx = createToolContext({ workflows });
+    await run("research_status", {}, ctx);
+    // A voice reply cannot be a list of twenty runs.
+    expect(workflows.find).toHaveBeenCalledWith(research, ctx.sessionId, { limit: 3 });
+  });
+});
+
+describe("research_progress", () => {
+  test("reads the run's own progress line rather than its status", async () => {
+    const workflows = stubWorkflows([
+      createRunSnapshot({ workflow: "research", status: "running" }),
+    ]);
+    vi.mocked(workflows.stream).mockResolvedValue(createProgressStream(["Found 3 sources."]));
+    const ctx = createToolContext({ workflows });
+    const result = await run("research_progress", {}, ctx);
+    expect(result).toMatchObject({ progress: "Found 3 sources." });
+  });
+
+  test("asks for the LAST line, not the whole log", async () => {
+    // A voice reply cannot recite every line the run has written.
+    const workflows = stubWorkflows([
+      createRunSnapshot({ workflow: "research", status: "running" }),
+    ]);
+    vi.mocked(workflows.stream).mockResolvedValue(createProgressStream(["a"]));
+    await run("research_progress", {}, createToolContext({ workflows }));
+    expect(workflows.stream).toHaveBeenCalledWith("wrun_1", { startIndex: -1 });
+  });
+
+  test("a run that has written nothing yet says so WITHOUT opening the stream", async () => {
+    // Not a shortcut: an empty progress channel is never closed, so reading one
+    // would wait for a line that arrives whenever the next step writes — i.e.
+    // the tool hangs instead of answering. The tail is how that is known.
+    const workflows = stubWorkflows([
+      createRunSnapshot({ workflow: "research", status: "running" }),
+    ]);
+    vi.mocked(workflows.streamTail).mockResolvedValue(-1);
+    const result = await run("research_progress", {}, createToolContext({ workflows }));
+    expect(result).toMatchObject({ note: "Started, nothing to report yet." });
+    expect(workflows.stream).not.toHaveBeenCalled();
+  });
+
+  test("says nothing was started when the key has no runs", async () => {
+    const workflows = stubWorkflows([]);
+    const result = await run("research_progress", {}, createToolContext({ workflows }));
+    expect(result).toMatchObject({ note: "Nothing started yet." });
+    expect(workflows.stream).not.toHaveBeenCalled();
+  });
+});
+
+describe("file_it_now", () => {
+  test("wakes the sleeping run so the review wait ends early", async () => {
+    const workflows = stubWorkflows([
+      createRunSnapshot({ workflow: "research", status: "running" }),
+    ]);
+    vi.mocked(workflows.wakeUp).mockResolvedValue(1);
+    const result = await run("file_it_now", {}, createToolContext({ workflows }));
+    expect(workflows.wakeUp).toHaveBeenCalledWith("wrun_1");
+    expect(result).toMatchObject({ filed: true });
+  });
+
+  test("a run that was not waiting is reported honestly, not as a failure", async () => {
+    // `wakeUp` answering 0 means the run had already moved past its sleep — the
+    // same shape as `cancel` answering false.
+    const workflows = stubWorkflows([
+      createRunSnapshot({ workflow: "research", status: "running" }),
+    ]);
+    vi.mocked(workflows.wakeUp).mockResolvedValue(0);
+    const result = await run("file_it_now", {}, createToolContext({ workflows }));
+    expect(result).toMatchObject({ filed: false });
+  });
+
+  test("says nothing was started when the key has no runs", async () => {
+    const workflows = stubWorkflows([]);
+    const result = await run("file_it_now", {}, createToolContext({ workflows }));
+    expect(result).toMatchObject({ note: "Nothing started yet." });
+    expect(workflows.wakeUp).not.toHaveBeenCalled();
+  });
+});
+
+describe("the pure helpers", () => {
+  test("dedupe keeps the first occurrence of each URL", () => {
+    const sources = [
+      { title: "One", url: "https://a.example" },
+      { title: "One again", url: "https://a.example" },
+      { title: "Two", url: "https://b.example" },
+    ];
+    expect(dedupe(sources)).toEqual([sources[0], sources[2]]);
+  });
+
+  test("countSources counts DISTINCT sources across every angle", () => {
+    // What the voice agent quotes. Two researchers finding the same page is one
+    // source, and reporting two would overstate the research.
+    const shared = { title: "Shared", url: "https://a.example" };
+    expect(
+      countSources([
+        { angle: "one", findings: "…", sources: [shared, { title: "B", url: "https://b" }] },
+        { angle: "two", findings: "…", sources: [shared] },
+      ]),
+    ).toBe(2);
+  });
+});
+
+describe("the steps that research", () => {
+  beforeEach(() => {
+    // `stepEnv` falls back to the process env when no host has published one,
+    // which is exactly the case a spec is. `unstubEnvs` clears it per test.
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "sk-test");
+  });
+
+  /**
+   * The SDK's fake gateway, installed.
+   *
+   * The fake itself is `@alexkroman1/aai/testing`'s — it answers a QUEUE of
+   * completions, repeating the last, which is what a spec needs for a loop that
+   * is a CONVERSATION (search, then read, then stop) rather than one call. What
+   * stays here is the INSTALLATION, because the lifetime of a global stub is
+   * vitest's business and the SDK helper deliberately carries no test-runner
+   * dependency.
+   */
+
+  /** The prompt the Nth model call carried. */
+  function promptOf(calls: readonly StubGatewayCall[], at: number): string {
+    return calls[at]?.prompt ?? "";
+  }
+
+  const brief = { brief: "How otters use tools", criteria: ["Which species", "How it is learned"] };
+
+  test("writeBrief turns a spoken request into a brief and its criteria", async () => {
+    const calls = stubGateway([
+      JSON.stringify({ brief: "How otters use tools", criteria: ["Which species"] }),
+    ]);
+    expect(await writeBrief("otters")).toEqual({
+      brief: "How otters use tools",
+      criteria: ["Which species"],
+    });
+    expect(promptOf(calls, 0)).toContain("otters");
+  });
+
+  test("writeBrief falls back to the topic rather than filing an empty brief", async () => {
+    // The caller said something; a model that returns no brief must not erase it.
+    stubGateway([JSON.stringify({ criteria: [] })]);
+    expect(await writeBrief("otters")).toEqual({ brief: "otters", criteria: [] });
+  });
+
+  test("planAngles asks the model for the fan-out's width", async () => {
+    const calls = stubGateway([JSON.stringify({ angles: ["Tool use", "Which species"] })]);
+    expect(await planAngles(brief)).toEqual(["Tool use", "Which species"]);
+    // The angles are measured against the brief, so the criteria travel with it.
+    expect(promptOf(calls, 0)).toContain("Which species");
+  });
+
+  test("planAngles researches the brief itself when no angles come back", async () => {
+    // Nothing to fan out over is a plan failure, not an empty result — and the
+    // brief is the one angle that is always available.
+    stubGateway([JSON.stringify({ angles: [] })]);
+    expect(await planAngles(brief)).toEqual([brief.brief]);
+  });
+
+  test("investigate stops when the model says so, without inventing findings", async () => {
+    const calls = stubGateway([JSON.stringify({ action: "stop", why: "nothing to add" })]);
+    expect(await investigate(brief, "Tool use")).toEqual({
+      angle: "Tool use",
+      findings: "Nothing was found on this angle.",
+      sources: [],
+    });
+    // One call: it stopped, so there was nothing to compress.
+    expect(calls).toHaveLength(1);
+  });
+
+  test("investigate searches, reads, and compresses what it saw", async () => {
+    const calls = stubGateway([
+      JSON.stringify({ action: "search", query: "otter tool use" }),
+      JSON.stringify({ action: "read", url: "https://otters.example/tools" }),
+      JSON.stringify({ action: "stop", why: "enough" }),
+      JSON.stringify({
+        findings: "Sea otters crack shellfish with stones [1].",
+        sources: [{ title: "Otters", url: "https://otters.example/tools" }],
+      }),
+    ]);
+
+    const note = await investigate(brief, "Tool use");
+
+    expect(webSearch).toHaveBeenCalledWith({ query: "otter tool use", max_results: 5 });
+    expect(visitWebpage).toHaveBeenCalledWith("https://otters.example/tools");
+    expect(note.findings).toContain("crack shellfish");
+    expect(note.sources).toEqual([{ title: "Otters", url: "https://otters.example/tools" }]);
+    // Everything the researcher saw reaches the compression stage, which is what
+    // keeps the journaled result small without summarizing the findings away.
+    expect(promptOf(calls, 3)).toContain("The page body.");
+  });
+
+  test("investigate stops at its BUDGET, whatever the model asks for", async () => {
+    // The budget is the mechanism, not the prompt: a run whose cost is decided
+    // by a model is a run nobody can price.
+    const calls = stubGateway([JSON.stringify({ action: "search", query: "again" })]);
+    await investigate(brief, "Tool use");
+    // Six actions, then one compression call.
+    expect(calls).toHaveLength(7);
+  });
+
+  test("a failed search costs an action rather than the whole angle", async () => {
+    vi.mocked(webSearch).mockRejectedValueOnce(new Error("search is down"));
+    const calls = stubGateway([
+      JSON.stringify({ action: "search", query: "otters" }),
+      JSON.stringify({ action: "stop", why: "give up" }),
+      JSON.stringify({ findings: "Nothing usable.", sources: [] }),
+    ]);
+    const note = await investigate(brief, "Tool use");
+    expect(note.findings).toBe("Nothing usable.");
+    expect(promptOf(calls, 2)).toContain("search is down");
+  });
+
+  test("investigate retries beyond the default, because a rate limit is expected", () => {
+    expect(investigate.maxRetries).toBeGreaterThan(3);
+  });
+
+  test("a rate limit is RETRYABLE, so the DevKit tries again", async () => {
+    // The message alone cannot say this — a 429 and a 401 read alike — so what
+    // is asserted is the class the DevKit actually branches on.
+    stubGateway([""], { status: 429 });
+    const err = await investigate(brief, "Tool use").catch((thrown: unknown) => thrown);
+    expect(RetryableError.is(err)).toBe(true);
+    expect((err as Error).message).toMatch(/HTTP 429/);
+  });
+
+  test("a rejected request is FATAL rather than retried five times", async () => {
+    stubGateway([""], { status: 401 });
+    const err = await investigate(brief, "Tool use").catch((thrown: unknown) => thrown);
+    expect(FatalError.is(err)).toBe(true);
+    expect((err as Error).message).toMatch(/HTTP 401/);
+  });
+
+  test("a missing key is FATAL, naming the key", async () => {
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "");
+    stubGateway(["anything"]);
+    const err = await investigate(brief, "Tool use").catch((thrown: unknown) => thrown);
+    expect(FatalError.is(err)).toBe(true);
+    expect((err as Error).message).toMatch(/ASSEMBLYAI_API_KEY/);
+  });
+
+  test("a malformed `sources` falls back to what the researcher was shown", async () => {
+    // `.catch(undefined)` on that field rather than a bare `.optional()`: the
+    // findings are already compressed by this point, and throwing them away to
+    // research the angle again is the expensive way to handle one bad field.
+    const calls = stubGateway([
+      JSON.stringify({ action: "search", query: "otters" }),
+      JSON.stringify({ action: "stop" }),
+      JSON.stringify({ findings: "Otters use stones.", sources: "not a list" }),
+    ]);
+    const note = await investigate(brief, "Tool use");
+
+    expect(note.findings).toBe("Otters use stones.");
+    expect(note.sources).toEqual([{ title: "Otters", url: "https://otters.example/tools" }]);
+    // Three calls, not four: the reply was USED, not retried.
+    expect(calls).toHaveLength(3);
+  });
+
+  test("a reply that is not JSON throws plainly, because a retry may well obey", async () => {
+    stubGateway(["I would rather write you an essay."]);
+    await expect(writeBrief("otters")).rejects.toThrow(/Expected JSON/);
+  });
+
+  test("findGaps asks nothing when the first wave found nothing", async () => {
+    const calls = stubGateway([JSON.stringify({ angles: ["anything"] })]);
+    expect(await findGaps(brief, [])).toEqual([]);
+    expect(calls).toHaveLength(0);
+  });
+
+  test("findGaps names what is still unanswered against the criteria", async () => {
+    const calls = stubGateway([JSON.stringify({ angles: ["How it is learned"] })]);
+    const gaps = await findGaps(brief, [
+      { angle: "Tool use", findings: "They use stones.", sources: [] },
+    ]);
+    expect(gaps).toEqual(["How it is learned"]);
+    expect(promptOf(calls, 0)).toContain("They use stones.");
+  });
+
+  test("writeReport writes the report AND the sentence a phone can carry", async () => {
+    // Two model calls in ONE step, because they are one decision: a resume must
+    // never pair a new summary with an old report.
+    const calls = stubGateway(["# Otters\n\nThey use stones [1].", "Otters use stones as tools."]);
+    const written = await writeReport("otters", brief, [
+      { angle: "Tool use", findings: "They use stones.", sources: [] },
+    ]);
+
+    expect(written.report).toContain("# Otters");
+    expect(written.summary).toBe("Otters use stones as tools.");
+    expect(calls).toHaveLength(2);
+    // Nothing researched is dropped on the way in.
+    expect(promptOf(calls, 0)).toContain("They use stones.");
+    // …and the summary is a reduction OF the report, not a second pass at the
+    // findings — which is what keeps it consistent with what a page renders.
+    expect(promptOf(calls, 1)).toContain("# Otters");
+  });
+
+  test("an empty completion throws rather than filing a blank report", async () => {
+    stubGateway([""]);
+    await expect(
+      writeReport("otters", brief, [{ angle: "a", findings: "b", sources: [] }]),
+    ).rejects.toThrow(/empty completion/);
+  });
+});

package/dist/templates/research-workflow/agent.ts

@@ -0,0 +1,94 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * A voice agent that hands work off to a durable workflow — the worked example
+ * for `agent({ workflows })`.
+ *
+ * This is the HANDOFF shape: a caller is on the line, so a tool starts a run and
+ * answers the turn. When the workflow IS the product — a form rather than a
+ * call — the agent is declared with `workflowApp()` instead and has no session
+ * at all; `link-digest` is that one, at its smallest.
+ *
+ * The whole point is the thing a voice agent cannot otherwise do: **answer the
+ * caller now, finish the work later.** Research takes minutes; the caller is on
+ * the line. So `request_research` starts a run and returns in the same turn, the
+ * run outlives the call, and a LATER call reads the result back.
+ *
+ * ## The four tools are four files
+ *
+ * `tools/` is the tool list — a file there IS a tool, named by its own filename —
+ * so this module declares the agent and the workflow it hands off to, and nothing
+ * about tools. The declaration they all share lives in `shared.ts`, because a
+ * tool starts a run by passing the DEFINITION rather than its name.
+ *
+ * ## And it SAYS SO when the work lands
+ *
+ * `start(…, { notify })` is what closes the loop that used to be open: the agent
+ * promised an update, the run finished, and nothing made it speak — the caller
+ * had to think to ask again. With it, a finished run takes an unprompted,
+ * interruptible turn on this session, built from the run's own output.
+ *
+ * Two limits worth knowing, both by construction. It reaches the session that
+ * STARTED the run, only while that session is alive — an announcement into a
+ * call that has ended is nobody's — and it needs a transport that can take an
+ * unprompted turn, which pipeline mode can and S2S cannot. That is why `key`
+ * stays: the next call still finds the run.
+ *
+ * ## The correlation key is what makes the second call possible
+ *
+ * `start()` hands back a `runId`, and the obvious place for a tool to keep it is
+ * a `sessionSlot` — which is swept shortly after the caller hangs up. So the
+ * run outlives the session and the only handle to it does not. Passing
+ * `{ key: ctx.sessionId }` puts the run in an index the agent can search later
+ * with `find`, without maintaining its own table.
+ *
+ * `ctx.sessionId` keys THIS call. A real desk would key on something that
+ * survives across calls — the caller's phone number, an account id — so
+ * "what happened to my research?" works from a different session. The mechanism
+ * is identical; only the key changes.
+ *
+ * ## What is NOT here
+ *
+ * No `ctx.step`, no `ctx.waitFor`. Steps are `"use step"` functions in
+ * `workflows/research.ts` and waitpoints are the Workflow DevKit's own
+ * `defineHook()`. The SDK's job is declaring the workflow and starting runs; the
+ * durable execution belongs to `workflow`.
+ *
+ * ## The research is real, and it really searches the web
+ *
+ * `workflows/research.ts` is a deep-research pass, not three model calls in a
+ * row: it writes a brief, plans the angles worth pursuing, gives each angle its
+ * own researcher step that SEARCHES and READS until its budget runs out, asks
+ * what is still unanswered, and only then writes the report. The search and the
+ * page reads go through `webSearch`/`visitWebpage` from `@alexkroman1/aai/tools`
+ * — the same implementations behind the model-facing builtins, which is the
+ * point: a step is not a lesser environment than a tool body.
+ *
+ * The model calls go through the same `ASSEMBLYAI_API_KEY` this agent's voice
+ * pipeline uses. A step is handed no `ToolContext`, so it reads that key with
+ * `requireStepEnv` rather than `ctx.env`; see that file's module doc for the one
+ * thing that changes under `aai dev` (the key has to be in `.env`, not just your
+ * shell).
+ *
+ * Requires storage (`aai storage enable`, or `DATABASE_URL` under `aai dev`) —
+ * runs and the key index both live there.
+ */
+
+import { agent } from "@alexkroman1/aai";
+import { research } from "./shared.ts";
+
+export default agent({
+  name: "Research Desk",
+  greeting: "Research desk. What would you like me to look into?",
+  systemPrompt: [
+    "You take research requests over the phone and read back results.",
+    "When someone asks you to research something, call request_research and tell them",
+    "you have started it — do NOT wait for it or promise a time. You WILL be told",
+    "when it lands, so it is safe to say you will let them know.",
+    "When someone asks about earlier work, call research_status.",
+    "If they ask what is happening right now, call research_progress.",
+    "If they say they need it immediately, call file_it_now.",
+    "Keep replies to one or two sentences; this is a voice call.",
+  ].join(" "),
+
+  workflows: { research },
+});

package/dist/templates/research-workflow/shared.ts

@@ -0,0 +1,35 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The workflow DECLARATION, in a module both `agent.ts` and every tool can
+ * import.
+ *
+ * It lives here rather than in `agent.ts` because all four tools name it —
+ * `ctx.workflows.start(research, …)` takes the definition itself rather than its
+ * name, which is what types the input and makes a typo a compile error instead of
+ * a rejected promise the model reads as a tool failure. A tool is its own file,
+ * so "both halves import the declaration" needs the declaration to have a home
+ * that is neither half.
+ *
+ * The `"use workflow"` BODY stays in `workflows/research.ts`: the Workflow DevKit
+ * builder scans that directory and rewrites what it finds, and a body written
+ * anywhere else runs inline once with no durability and nothing saying so.
+ */
+
+import { workflow } from "@alexkroman1/aai";
+import { z } from "zod";
+import { researchFlow } from "./workflows/research.ts";
+
+/**
+ * The declaration: schema, description, and the directive body.
+ *
+ * Exported so a client page could derive its output type with `WorkflowOutputOf`.
+ */
+export const research = workflow({
+  description:
+    "Research a topic properly — brief, angles, web search per angle, a gap pass, then a written report",
+  input: z.object({
+    topic: z.string().min(3).describe("What to research"),
+    requestedBy: z.string().describe("Who asked — used when filing the result"),
+  }),
+  run: researchFlow,
+});

package/dist/templates/research-workflow/tools/file_it_now.ts

@@ -0,0 +1,22 @@
+import { tool } from "@alexkroman1/aai";
+import { research } from "../shared.ts";
+
+export default tool({
+  description:
+    "Skip the review wait on the research and file it immediately. Use when the caller says they need it now.",
+  execute: async (_args, ctx) => {
+    const [latest] = await ctx.workflows.find(research, ctx.sessionId, { limit: 1 });
+    if (!latest) return { note: "Nothing started yet." };
+    // The counterpart of the `sleep` in `workflows/research.ts`. Without it
+    // the only handle on a sleeping run is `cancel`, so "send it now" and
+    // "throw it away" would be the same button — and the wait a real desk
+    // uses is hours, not the thirty seconds this template ships.
+    //
+    // `0` is an honest answer, not a failure: the run had already moved past
+    // its wait, or finished.
+    const woken = await ctx.workflows.wakeUp(latest.runId);
+    return woken > 0
+      ? { filed: true, note: "Filing it now." }
+      : { filed: false, note: "That one was not waiting — it has already moved on." };
+  },
+});