npm - @alexkroman1/aai-cli - Versions diffs - 5.14.0 → 6.1.0 - Mend

@alexkroman1/aai-cli 5.14.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (231) hide show

package/dist/templates/link-digest/agent.test.ts ADDED Viewed

@@ -0,0 +1,223 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * Specs for the link digest — the workflow-app template.
+ *
+ * There are no tools to exercise, which is the point: what this template
+ * demonstrates is a DECLARATION, so the spec asserts the declaration. Three
+ * things carry the shape and each is silent when wrong — the `page: "static"`
+ * field (without it the deployed agent still offers a `/websocket` nothing will
+ * answer), the workflow's NAME (the page starts a run by that string, so a
+ * rename here is a runtime 400 there), and the input schema (which is both the
+ * call-site validation and the JSON Schema `GET /workflows` serves).
+ *
+ * The workflow BODY is not tested here: it is only durable once the Workflow
+ * DevKit's build has transformed it, so a unit test of it would exercise a plain
+ * async function and prove nothing about replay. Its STEPS are, and directly —
+ * imported with no bundler in the path a `"use step"` function is an ordinary
+ * async function, so its HTML handling, its JSON contract with the model and its
+ * `FatalError` guards are all testable.
+ */
+import { stubStepFetch } from "@alexkroman1/aai/testing";
+import { installStubGateway as stubGateway } from "@alexkroman1/aai/testing/vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import agentDef, { digest } from "./agent.ts";
+import { extractText, extractTitle, fetchArticle, summarize } from "./workflows/digest.ts";
+describe("the agent declares itself a workflow app", () => {
+  test("its front door is a page, not a microphone", () => {
+    // Not decoration: `createServer` declines `/websocket` with a reason for a
+    // static agent, and telephony defaults off.
+    expect(agentDef.page).toBe("static");
+  });
+  test("it declares no voice pipeline and no tools, because nothing talks", () => {
+    expect(agentDef.stt).toBeUndefined();
+    expect(agentDef.llm).toBeUndefined();
+    expect(agentDef.tts).toBeUndefined();
+    expect(agentDef.s2s).toBeUndefined();
+    expect(agentDef.tools).toEqual({});
+  });
+  test("under the name the page starts a run by", () => {
+    // `api.start("digest", …)` in client.tsx names this key. Nothing else
+    // records it, so a rename here is a 400 there rather than a compile error.
+    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["digest"]);
+    expect(agentDef.workflows?.digest).toBe(digest);
+  });
+});
+describe("the input schema", () => {
+  test("accepts a URL", async () => {
+    const result = await digest.input?.["~standard"].validate({ url: "https://example.com/a" });
+    expect(result?.issues).toBeUndefined();
+  });
+  test("rejects a non-URL at the CALL SITE rather than three steps into a run", async () => {
+    const result = await digest.input?.["~standard"].validate({ url: "not a url" });
+    expect(result?.issues).toBeDefined();
+  });
+  test("carries a description, which is what a rendered form labels the field with", () => {
+    expect(digest.description).toBeTruthy();
+    expect(digest.input).toBeDefined();
+  });
+});
+describe("the agent declares the credential its steps read", () => {
+  test("so a deploy checks for it rather than the first run", () => {
+    // A workflow app declares no providers, so `requiredEnv` is the ONLY thing
+    // in its config that can name a credential.
+    expect(agentDef.requiredEnv).toContain("ASSEMBLYAI_API_KEY");
+  });
+});
+describe("extractText", () => {
+  test("drops script and style CONTENT, not just their tags", () => {
+    // Stripping tags alone leaves a page's JavaScript in the prompt — expensive,
+    // and a way to smuggle instructions past the reader.
+    const text = extractText(
+      "<html><head><style>body{color:red}</style></head><body><script>alert('x')</script><p>Real words here.</p></body></html>",
+    );
+    expect(text).toBe("Real words here.");
+  });
+  test("decodes &amp; LAST, so an escaped entity is not decoded twice", () => {
+    // `&amp;lt;` is a literal `&lt;` on the page; decoding `&amp;` first would
+    // turn it into a `<` the author never wrote.
+    expect(extractText("<p>a &amp;lt; b &amp; c</p>")).toBe("a &lt; b & c");
+  });
+  test("collapses whitespace, because HTML indentation is not prose", () => {
+    expect(extractText("<p>one</p>\n\n   <p>two</p>")).toBe("one two");
+  });
+  test("caps what crosses the queue to the next step", () => {
+    const huge = `<p>${"word ".repeat(20_000)}</p>`;
+    expect(extractText(huge).length).toBeLessThanOrEqual(24_000);
+  });
+});
+describe("extractTitle", () => {
+  test("reads the document title", () => {
+    expect(extractTitle("<html><title>  Otters &amp; tools </title></html>")).toBe(
+      "Otters & tools",
+    );
+  });
+  test("answers undefined when there is none, so the caller can fall back", () => {
+    expect(extractTitle("<html><body>hi</body></html>")).toBeUndefined();
+  });
+});
+describe("fetchArticle", () => {
+  /** Unpublished between specs — a fetch left behind reaches the next file. */
+  let restore: (() => void) | undefined;
+  afterEach(() => {
+    restore?.();
+    restore = undefined;
+  });
+  /**
+   * A page server answering `html` with `status`.
+   *
+   * Published into `stepFetch`'s own slot rather than over `globalThis.fetch`:
+   * the step calls `stepFetch`, and stubbing the global would pass while
+   * exercising the fallback path production never takes.
+   */
+  function stubPage(html: string, status = 200) {
+    const stub = stubStepFetch(() => ({
+      status,
+      body: html,
+      headers: { "Content-Type": "text/html" },
+    }));
+    restore = stub.restore;
+    return stub;
+  }
+  test("returns the page's title and its readable text", async () => {
+    stubPage(
+      `<html><title>Otters</title><body><p>${"Otters use tools. ".repeat(20)}</p></body></html>`,
+    );
+    const article = await fetchArticle("https://example.com/otters");
+    expect(article.title).toBe("Otters");
+    expect(article.text).toContain("Otters use tools.");
+    expect(article.url).toBe("https://example.com/otters");
+  });
+  test("falls back to the hostname when the page has no title", async () => {
+    stubPage(`<html><body><p>${"Otters use tools. ".repeat(20)}</p></body></html>`);
+    expect((await fetchArticle("https://example.com/otters")).title).toBe("example.com");
+  });
+  test("fails FATALLY on a page with no readable text", async () => {
+    // A JS-rendered site is the usual cause, and no number of attempts fixes it.
+    stubPage("<html><body><div id='root'></div></body></html>");
+    await expect(fetchArticle("https://example.com/app")).rejects.toThrow(/no readable text/);
+  });
+  test("fails FATALLY on a 404 and plainly on a 503", async () => {
+    stubPage("", 404);
+    await expect(fetchArticle("https://example.com/gone")).rejects.toThrow(/HTTP 404/);
+    stubPage("", 503);
+    await expect(fetchArticle("https://example.com/gone")).rejects.toThrow(/HTTP 503/);
+  });
+});
+describe("summarize", () => {
+  const ARTICLE = { url: "https://example.com/a", title: "Otters", text: "Otters use tools." };
+  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");
+  });
+  test("returns the headline and points the model produced", async () => {
+    const calls = stubGateway('{"headline":"Otters are clever","points":["a","b","c"]}');
+    const result = await summarize(ARTICLE);
+    expect(result).toEqual({
+      url: ARTICLE.url,
+      headline: "Otters are clever",
+      points: ["a", "b", "c"],
+    });
+    // The key is a BEARER here — the gateway is OpenAI-compatible, unlike
+    // AssemblyAI's streaming sockets, which take it raw.
+    expect(calls[0]?.headers.authorization).toBe("Bearer sk-test");
+  });
+  test("unwraps a fenced reply rather than failing on it", async () => {
+    stubGateway('```json\n{"headline":"H","points":["a"]}\n```');
+    expect((await summarize(ARTICLE)).headline).toBe("H");
+  });
+  test("throws PLAINLY when the model answered with prose, so the step retries", async () => {
+    // The distinction that is the whole retry policy: a model that ignored the
+    // format may well obey on the next attempt, where a 401 will not. Plain
+    // means NOT a `FatalError`, which is what the DevKit stops retrying on.
+    stubGateway("Here is a summary of the article about otters.");
+    const err = await summarize(ARTICLE).catch((thrown: unknown) => thrown);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).name).not.toBe("FatalError");
+    expect(err).toMatchObject({ message: expect.stringContaining("Expected JSON from the model") });
+  });
+  test("rejects JSON of the wrong shape as firmly as no JSON at all", async () => {
+    // The reply parses and is an object, so only the SCHEMA catches it — which
+    // is what taking a schema bought over the guard this used to hand-roll: the
+    // failure NAMES the field that was missing.
+    stubGateway('{"headline":"H"}');
+    await expect(summarize(ARTICLE)).rejects.toThrow(/did not match the shape: points/);
+  });
+  test("fails FATALLY with no API key rather than retrying five times", async () => {
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "");
+    stubGateway('{"headline":"H","points":["a"]}');
+    await expect(summarize(ARTICLE)).rejects.toThrow(/ASSEMBLYAI_API_KEY/);
+  });
+  test("retries beyond the default, because a rate limit and a bad format both happen", () => {
+    expect(summarize.maxRetries).toBeGreaterThan(3);
+  });
+});

package/dist/templates/link-digest/agent.ts ADDED Viewed

@@ -0,0 +1,79 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * A WORKFLOW APP — the worked example for `workflowApp()`.
+ *
+ * Its front door is a form, not a microphone. There is no session, no
+ * WebSocket, and no voice pipeline: the page (`client.tsx`) starts a run over
+ * the workflow HTTP API and watches it, and the run outlives the tab.
+ *
+ * ## What makes this a different KIND of agent from `research-workflow`
+ *
+ * `research-workflow` is a voice agent that HANDS OFF to a workflow — a caller is on
+ * the line, so a tool starts a run and answers the turn. Here the workflow is
+ * the entire product, and the declaration says so:
+ *
+ * - `workflowApp()` is `agent({ …, page: "static" })` with the discriminant
+ *   already set. The declaration is not decoration: `createServer` declines
+ *   `/websocket` with a reason (so a page mounted with `client()` by mistake
+ *   fails the same way in `aai dev` and in production rather than only after a
+ *   deploy) and telephony defaults off.
+ * - There is no `stt`/`llm`/`tts`, no `tools` and no `systemPrompt` — and they
+ *   are not merely omitted, they are UNDECLARABLE here. Nothing talks and no
+ *   model runs, so every one of them was inert; this file used to carry a
+ *   `systemPrompt` addressed to a model that never ran.
+ *
+ * ## What the page needs from this file, and how it gets it
+ *
+ * Only the workflow's NAME and its output TYPE. The name is the key in
+ * `workflows` below — `"digest"` — and the type is
+ * `WorkflowOutputOf<typeof digest>`, derived from a `import type` of this module
+ * which is ERASED at build time, so naming it pulls no server graph into the
+ * browser bundle. Nothing is generated and nothing is restated.
+ *
+ * ## What it needs
+ *
+ * `ASSEMBLYAI_API_KEY` in the agent env — `.env` under `aai dev`, `aai secret
+ * put ASSEMBLYAI_API_KEY` once deployed — because the run really reads the page
+ * and really summarizes it with a model. `requiredEnv` below is what makes a
+ * deploy check for it rather than letting the first run find out, and it is
+ * load-bearing here in a way it is not for a voice agent: a workflow app
+ * declares no providers, so nothing else in its config names a credential.
+ *
+ * A step is handed no `ToolContext`, so it reads that key with `requireStepEnv`
+ * rather than `ctx.env`; see `workflows/digest.ts` and `research-workflow`'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 correlation-key index both live there.
+ */
+import { workflow, workflowApp } from "@alexkroman1/aai";
+import { z } from "zod";
+import { digestFlow } from "./workflows/digest.ts";
+/**
+ * The declaration: schema, description, and the directive body.
+ *
+ * The `input` schema does double duty here in a way it cannot for a voice agent.
+ * It validates at `start()` — so a bad URL is a 400 at the call site rather than
+ * a failed run discovered later — and it is served on `GET /workflows` as JSON
+ * Schema, which is what lets a page render a form from a workflow it was not
+ * written against.
+ */
+export const digest = workflow({
+  description: "Read a link, reduce it to a headline and three points, then file the digest",
+  input: z.object({
+    url: z.url().describe("The link to digest"),
+  }),
+  run: digestFlow,
+});
+export default workflowApp({
+  name: "Link Digest",
+  // The whole product. A workflow app is an agent whose work happens here.
+  workflows: { digest },
+  // Checked at deploy time. A workflow app declares no providers, so this is the
+  // only thing that can name the credential its steps read.
+  requiredEnv: ["ASSEMBLYAI_API_KEY"],
+});

package/dist/templates/link-digest/client.tsx ADDED Viewed

@@ -0,0 +1,146 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The browser half of a workflow app.
+ *
+ * Mounted with `page()` rather than `client()`: there is no session to build, so
+ * there is no socket, no audio graph, and no microphone request. Everything else
+ * is the same — the same `client.tsx` filename, React, Tailwind, and the same
+ * theme tokens the voice components read.
+ *
+ * What replaces `useSession()` is three things: `createWorkflowApi()` to start a
+ * run, `useWorkflowRun()` to watch its STATUS, and `useWorkflowProgress()` to
+ * read what it has WRITTEN. The API is durable, so the `runId` is the whole
+ * state — it survives a reload, a different device, or `curl`.
+ *
+ * ## Status and progress are different questions
+ *
+ * `useWorkflowRun` answers "where has this got to" from the world's own record —
+ * pending, running, completed. `useWorkflowProgress` answers "what is it doing"
+ * from what the run wrote itself (`report()` in `workflows/digest.ts`). A page
+ * with only the first shows "Working…" for the length of the run; a page with
+ * only the second cannot tell a finished run from a quiet one. Both are cheap:
+ * one stream each, ended by the agent when there is nothing left to say.
+ *
+ * Progress also REPLAYS — chunks are retained with the run — so a reload mid-run
+ * catches up rather than starting from whatever arrives next. This page renders
+ * only the newest line, because on a page this small that is the whole of what a
+ * status wants; `transcription-workflow` renders the full log, where a fan-out makes
+ * the history worth seeing.
+ */
+import { createWorkflowApi, page, useWorkflowProgress, useWorkflowRun } from "@alexkroman1/aai-ui";
+import "@alexkroman1/aai-ui/styles.css";
+// ERASED at build time, so naming the agent's own type costs the browser bundle
+// nothing — and it is what stops this file restating a shape `workflows/
+// digest.ts` already declares.
+import type { WorkflowOutputOf } from "@alexkroman1/aai";
+// The one runtime import from the SDK a browser bundle wants: `/utils` is the
+// zod-free subpath, so it costs a few hundred bytes rather than the root
+// barrel's module graph.
+import { errorMessage } from "@alexkroman1/aai/utils";
+import { useState } from "react";
+import type { digest } from "./agent.ts";
+/** What a completed run reports, derived from the workflow rather than restated. */
+type Digest = WorkflowOutputOf<typeof digest>;
+/**
+ * Hoisted out of the component deliberately.
+ *
+ * `useWorkflowRun` holds the client in a ref precisely so a fresh object per
+ * render cannot restart its watch, but building one in render is still a new
+ * `fetch` closure every time and reads as though it were free.
+ */
+const api = createWorkflowApi();
+export function App() {
+  const [url, setUrl] = useState("");
+  const [runId, setRunId] = useState<string>();
+  const [error, setError] = useState<string>();
+  // The generic is what makes `run.status === "completed"` narrow to a TYPED
+  // `run.output` instead of `unknown`.
+  const { run, polling } = useWorkflowRun<Digest>(runId, { api });
+  // What the run has SAID, as against where it has got to. Defaults to `string`,
+  // which is what `report()` writes.
+  const { latest, supported } = useWorkflowProgress(runId, { api });
+  const submit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    setError(undefined);
+    try {
+      // Resolves as soon as the run exists — deliberately not when it finishes.
+      // That is the whole mechanism: the digest sleeps for a while, and this
+      // page is free to be closed in the meantime.
+      setRunId(await api.start("digest", { url }));
+    } catch (err) {
+      // The agent's own sentence: an input failing the workflow's schema names
+      // the issue, which is better copy than anything this page could write.
+      setError(errorMessage(err));
+    }
+  };
+  return (
+    <main className="mx-auto flex max-w-2xl flex-col gap-6 p-8">
+      <h1 className="text-2xl font-medium">Link Digest</h1>
+      <form onSubmit={submit} className="flex gap-2">
+        <input
+          type="url"
+          required
+          value={url}
+          onChange={(e) => setUrl(e.target.value)}
+          placeholder="https://example.com/article"
+          className="flex-1 rounded-md border px-3 py-2"
+        />
+        <button type="submit" disabled={polling} className="rounded-md border px-4 py-2">
+          {polling ? "Working…" : "Digest"}
+        </button>
+      </form>
+      {error !== undefined && <p className="text-red-600">{error}</p>}
+      {/* A run that has not settled says so. `polling` is not derivable from the
+          snapshot alone — an id the agent never knew leaves `run` undefined,
+          which would otherwise read as "still waiting" forever. */}
+      {polling && <p>You can close this tab — the run continues without it.</p>}
+      {/* The run's own narration, newest line only — see the module doc.
+          `supported` is what keeps this from being blank forever on an agent
+          deployed before progress streams existed: "wrote nothing yet" and
+          "serves no stream" are indistinguishable from `progress` alone. */}
+      {supported && latest !== undefined && <p className="text-sm opacity-70">{latest}</p>}
+      {/* The counterpart of the `sleep` in `workflows/digest.ts`. Without it the
+          only handle on a sleeping run is `cancel`, so "file it now" and "throw
+          it away" would be the same button. `wake` answering 0 means the run had
+          already moved past its wait, which is why nothing here treats that as a
+          failure. */}
+      {runId !== undefined && polling && (
+        <button
+          type="button"
+          onClick={() => void api.wake(runId)}
+          className="self-start rounded-md border px-3 py-1 text-sm"
+        >
+          File it now
+        </button>
+      )}
+      {run?.status === "failed" && <p className="text-red-600">That one failed: {run.error}</p>}
+      {run?.status === "completed" && (
+        <article className="flex flex-col gap-3">
+          <h2 className="text-xl">{run.output.headline}</h2>
+          <ul className="flex list-disc flex-col gap-1 pl-5">
+            {run.output.points.map((point) => (
+              <li key={point}>{point}</li>
+            ))}
+          </ul>
+          <p className="text-sm opacity-70">Filed {run.output.filedAt}</p>
+        </article>
+      )}
+    </main>
+  );
+}
+page({ name: "Link Digest", component: App });