@alexkroman1/aai-cli 6.10.1 → 7.0.0

package/dist/templates/recap-workflow/tools/recap_status.ts

@@ -1,9 +1,5 @@
-import {
-  isTerminal,
-  tool,
-  type WorkflowOutputOf,
-  type WorkflowRunSnapshot,
-} from "@alexkroman1/aai";
+import { tool } from "@alexkroman1/aai";
+import { isTerminal, type WorkflowRunOf } from "@alexkroman1/aai/workflow-api";
 import { recap } from "../shared.ts";
 
 /** How many past runs the status tool will look at. Newest first. */
@@ -14,10 +10,13 @@ const RECENT_RUNS = 3;
  *
  * This is the QUERY, and `isTerminal` is what makes it typed: it narrows to the
  * three finished statuses, which is what puts `run.output` and `run.error`
- * within reach without a cast. `WorkflowOutputOf` names the output type from the
- * declaration, so this signature never reaches past it into the body.
+ * within reach without a cast. `WorkflowRunOf` is the snapshot with that output
+ * already named from the declaration — the
+ * `WorkflowRunSnapshot<WorkflowOutputOf<typeof recap>>` this file used to
+ * compose by hand, for a three-name import — so the signature never reaches past
+ * the declaration into the body, and it is still the discriminated union.
  */
-function describeRun(run: WorkflowRunSnapshot<WorkflowOutputOf<typeof recap>>): string {
+function describeRun(run: WorkflowRunOf<typeof recap>): string {
   if (!isTerminal(run)) return "Still working on that one.";
   switch (run.status) {
     case "completed": {

package/dist/templates/recap-workflow/tools/request_recap.ts

@@ -1,4 +1,5 @@
-import { isTerminal, tool } from "@alexkroman1/aai";
+import { tool } from "@alexkroman1/aai";
+import { isTerminal } from "@alexkroman1/aai/workflow-api";
 import { z } from "zod";
 import { recap, SAMPLE_RECORDING } from "../shared.ts";
 

package/dist/templates/recap-workflow/workflows/recap.ts

@@ -55,7 +55,7 @@
  * Everything the desk claims to do. `submitRecording`, `checkTranscript` and
  * `discardTranscript` are AssemblyAI's pre-recorded API (`POST`, `GET` and
  * `DELETE` on `/v2/transcript`), and `summarize` is a real model call through
- * `stepGenerate`. The BATCH API is what makes the polling port honest: it
+ * `stepGenerateJsonClassified`. The BATCH API is what makes the polling port honest: it
  * answers with a job id in milliseconds and finishes minutes later, so the wait
  * is the provider's, not a `setTimeout` this template chose. (Its sibling
  * `transcription-workflow` takes the other endpoint — the sync one, which answers in
@@ -67,16 +67,14 @@
  * just your shell.
  */
 
-import { throwStepError, toStepError } from "@alexkroman1/aai/step-errors";
+import { report, requireStepEnv, stepFetch } from "@alexkroman1/aai/step";
 import {
-  errorMessage,
-  isRecord,
-  omitUndefined,
-  report,
-  requireStepEnv,
-  stepFetch,
-  stepGenerateJson,
-} from "@alexkroman1/aai/utils";
+  stepFetchOk,
+  stepGenerateJsonClassified,
+  stepTranscribeSubmitClassified,
+  toStepError,
+} from "@alexkroman1/aai/step-errors";
+import { errorMessage, isRecord, omitUndefined } from "@alexkroman1/aai/utils";
 import { createHook, FatalError, sleep } from "workflow";
 import { z } from "zod";
 import { retentionToken } from "./tokens.ts";
@@ -150,7 +148,7 @@ const POINTS = 3;
 /**
  * The shape the model must answer in.
  *
- * `stepGenerateJson` validates against this and throws PLAINLY when the reply
+ * `stepGenerateJsonClassified` validates against this and throws PLAINLY when the reply
  * misses, which is the retry policy in one distinction: a model that answered in
  * prose may answer correctly next time, where a 401 will not. `spoken` is the
  * field this template exists for — without it the announced turn has nothing to
@@ -256,7 +254,7 @@ export async function recapFlow(input: { url: string; requestedBy: string }) {
  * to completion in a worker, where the body is what may suspend. Splitting it
  * out keeps `recapFlow` readable and costs nothing, since the WDK transform
  * rewrites a step's DECLARATION rather than its call sites, so a step called
- * from a helper is still a real step (`mapInBatches` rests on the same
+ * from a helper is still a real step (`mapConcurrent` rests on the same
  * property).
  *
  * The loop is deterministic despite looking like it is not: every branch turns
@@ -358,14 +356,14 @@ export async function submitRecording(url: string): Promise<{ id: string }> {
 
   await report(`Submitting ${new URL(url).hostname} for transcription…`);
 
-  const response = await request(TRANSCRIPT_ENDPOINT, {
-    method: "POST",
-    body: JSON.stringify({ audio_url: url, speaker_labels: true }),
-  });
-  const body = await response.json();
-  const id = readString(body, "id");
-  if (!id) throw new Error("The provider accepted the recording but named no transcript id.");
-  return { id };
+  // `stepTranscribeSubmitClassified` owns the endpoint, the raw-key auth, the
+  // PLURAL `speech_models` field and the failure classification — the
+  // `Classified` suffix being that last part: it is `stepTranscribeSubmit` with
+  // `throwStepError` already applied, so a provider refusal stays terminal and a
+  // rate limit waits out the delay the provider itself named. `speaker_labels`
+  // is this desk's own request, which is what `params` is for — the async API's
+  // surface is large and the SDK deliberately does not mirror it.
+  return await stepTranscribeSubmitClassified(url, { params: { speaker_labels: true } });
 }
 
 /**
@@ -374,6 +372,17 @@ export async function submitRecording(url: string): Promise<{ id: string }> {
  * One poll is one step, so each attempt is journaled on its own: a run that dies
  * mid-wait resumes knowing what the last answer was instead of starting the
  * recording over.
+ *
+ * **Deliberately NOT `stepTranscribePoll`, though its sibling above did move to
+ * the SDK.** That helper answers `done` and THROWS on a job the provider gave
+ * up on, which is the right shape for a flow whose only question is "is the
+ * text ready". This desk's question is different: `status` is a VALUE here,
+ * read by the Query port (`recap_status`) while the run is still going, and an
+ * `error` status is the branch that unwinds the saga's compensation stack
+ * rather than a failure to propagate. Converting this would trade a documented
+ * state machine — the thing this template is actually about — for a throw.
+ * The provider's status union is the template's subject, so it stays in the
+ * template.
  */
 export async function checkTranscript(id: string): Promise<TranscriptState> {
   "use step";
@@ -456,19 +465,20 @@ export async function summarize(url: string, transcript: TranscriptState): Promi
     throw new FatalError("That recording came back with no speech in it.");
   }
 
-  // `stepGenerateJson` unwraps the fence a model puts around JSON however firmly
-  // it is told not to, parses it, and validates it — all four things this step
-  // used to re-derive. `throwStepError` is what makes a terminal gateway failure
-  // (a bad key, a rejected request) stop rather than burn the remaining
-  // attempts, where a reply that missed the SHAPE throws plainly and retries.
-  const parsed = await stepGenerateJson(text, {
+  // `stepGenerateJsonClassified` unwraps the fence a model puts around JSON
+  // however firmly it is told not to, parses it, and validates it — all four
+  // things this step used to re-derive. The `Classified` half is what makes a
+  // terminal gateway failure (a bad key, a rejected request) stop rather than
+  // burn the remaining attempts, where a reply that missed the SHAPE throws
+  // plainly and retries.
+  const parsed = await stepGenerateJsonClassified(text, {
     schema: RecapReply,
     system:
       "You write up recordings for someone who will hear the result on a phone call. " +
       `Reply with JSON only: {"headline": string, "points": string[], "spoken": string}. ` +
       `Give exactly ${POINTS} points. "spoken" is ONE sentence, under 30 words, ` +
       "written to be read aloud. No markdown fence, no preamble.",
-  }).catch(throwStepError);
+  });
 
   return {
     url,
@@ -508,27 +518,24 @@ async function request(
   url: string,
   init: { method?: string; body?: string } = {},
 ): Promise<Response> {
-  // `stepFetch`, not `fetch`: it pins HTTP/1.1, so several concurrent runs (and
-  // this workflow POLLS, so one run is many requests) get a socket each rather
-  // than N streams on one connection — and a connection failure arrives as a
-  // `StepTransportError` naming its cause instead of a bare
+  // Through `stepFetch`, not `fetch`: it pins HTTP/1.1, so several concurrent
+  // runs (and this workflow POLLS, so one run is many requests) get a socket
+  // each rather than N streams on one connection — and a connection failure
+  // arrives as a `StepTransportError` naming its cause instead of a bare
   // `TypeError: fetch failed`, which for a template whose whole subject is
   // durability is the difference between a diagnosable resume and a mystery.
   // `sdk/step-fetch.ts` carries the measurements.
-  const response = await stepFetch(url, {
+  // `stepFetchOk` makes the three-way retry decision: a 401 or a 400 answers the
+  // same way on the fourth attempt and burns the step, a 429 or a 5xx is what
+  // retries are for, and a `Retry-After` the provider named is waited out rather
+  // than replaced by the DevKit's one-second default — which matters here more
+  // than usual, because a fan-out of segments hits a rate limit together. The
+  // DELETE below stays on plain `stepFetch`, because there a 404 is a SUCCESS.
+  return await stepFetchOk(url, {
     ...init,
     headers: { authorization: requireStepEnv(API_KEY_ENV), "content-type": "application/json" },
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
   });
-  // The three-way retry decision, made by the SDK: a 401 or a 400 answers the
-  // same way on the fourth attempt and burns the step, a 429 or a 5xx is what
-  // retries are for, and a `Retry-After` the provider named is waited out rather
-  // than replaced by the DevKit's one-second default — which matters here more
-  // than usual, because a fan-out of segments hits a rate limit together.
-  if (!response.ok) {
-    throw toStepError(response, `${init.method ?? "GET"} ${url} failed: HTTP ${response.status}`);
-  }
-  return response;
 }
 
 /** A string field of a JSON body, when it really is one. */

package/dist/templates/redline/agent.test.ts

@@ -17,6 +17,7 @@
  * of that lives.
  */
 
+import { parseSchemaInput, schemaInputIssues } from "@alexkroman1/aai/testing";
 import { installStubGateway as stubGateway } from "@alexkroman1/aai/testing/vitest";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { FatalError } from "workflow";
@@ -24,7 +25,6 @@ import agentDef, { MAX_ROUNDS, redline } from "./agent.ts";
 import {
   briefBlock,
   clampScore,
-  countWords,
   critiqueDraft,
   MAX_NOTES,
   type RedlineInput,
@@ -70,30 +70,37 @@ describe("the agent declares itself a workflow app", () => {
 });
 
 describe("the input schema", () => {
-  const validate = (value: unknown) => redline.input?.["~standard"].validate(value);
+  // `schemaInputIssues` / `parseSchemaInput` rather than a local reach through
+  // `["~standard"].validate`: that is the vendor WIRE contract, and whether it
+  // answers synchronously or with a promise is the vendor's business — a missing
+  // `await` there leaves `.issues` undefined and every refusing test below
+  // passes for the wrong reason.
+  const issues = (value: unknown) => schemaInputIssues(redline.input, value, "redline");
 
   test("caps the rounds at the CALL SITE rather than on the bill", async () => {
-    const tooMany = await validate({ ...INPUT, rounds: MAX_ROUNDS + 1 });
-    expect(tooMany?.issues).toBeDefined();
+    expect(await issues({ ...INPUT, rounds: MAX_ROUNDS + 1 })).toBeDefined();
   });
 
   test("defaults the rounds and the required points, so the form need not", async () => {
-    const result = await validate({ brief: INPUT.brief, audience: "engineers" });
-    if (!result || result.issues) throw new Error("expected valid input");
-    expect(result.value).toMatchObject({ rounds: 2, mustCover: [] });
+    const parsed = await parseSchemaInput(
+      redline.input,
+      { brief: INPUT.brief, audience: "engineers" },
+      "redline",
+    );
+    expect(parsed).toMatchObject({ rounds: 2, mustCover: [] });
   });
 
   test("rejects an audience outside the enum — which is also what makes it a select", async () => {
     // `<WorkflowFields>` renders a `z.enum` as a `<SelectField>`; the same
     // declaration is what stops an API caller inventing a fifth audience.
-    expect((await validate({ ...INPUT, audience: "cats" }))?.issues).toBeDefined();
+    expect(await issues({ ...INPUT, audience: "cats" })).toBeDefined();
   });
 
   test("declares mustCover as an array, which is what the page renders by hand", async () => {
     // The mixed-form case: `<WorkflowFields>` renders scalars only, so client.tsx
     // writes this field itself and maps a textarea into it.
-    expect((await validate({ ...INPUT, mustCover: "one point" }))?.issues).toBeDefined();
-    expect((await validate({ ...INPUT, mustCover: ["one point"] }))?.issues).toBeUndefined();
+    expect(await issues({ ...INPUT, mustCover: "one point" })).toBeDefined();
+    expect(await issues({ ...INPUT, mustCover: ["one point"] })).toBeUndefined();
   });
 });
 
@@ -111,11 +118,6 @@ describe("pure helpers", () => {
     expect(briefBlock({ ...INPUT, mustCover: [] })).toContain("nothing specific");
   });
 
-  test("countWords ignores surrounding and repeated whitespace", () => {
-    expect(countWords("  one  two\nthree ")).toBe(3);
-    expect(countWords("   ")).toBe(0);
-  });
-
   test("clampScore holds a model's number inside the range it was given", () => {
     expect(clampScore(12)).toBe(10);
     expect(clampScore(0)).toBe(1);

package/dist/templates/redline/client.tsx

@@ -27,7 +27,8 @@
  */
 
 import "@alexkroman1/aai-ui/styles.css";
-import type { WorkflowOutputOf } from "@alexkroman1/aai";
+import { plural } from "@alexkroman1/aai/utils";
+import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import {
   Form,
   type FormValues,
@@ -35,6 +36,7 @@ import {
   SubmitButton,
   TextAreaField,
   useWorkflowSubmit,
+  WORKFLOW_STATUS_LABELS,
   WorkflowFields,
   WorkflowProgress,
   type WorkflowRun,
@@ -150,8 +152,8 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Redline>; onClear: () =>
       {run.status === "completed" && (
         <>
           <p className="text-xs opacity-60">
-            {run.output.words} words · {run.output.roundsRun} round
-            {run.output.roundsRun === 1 ? "" : "s"} ·{" "}
+            {run.output.words} words · {run.output.roundsRun}{" "}
+            {plural(run.output.roundsRun, "round")} ·{" "}
             {/* Which of the two stop conditions ended the loop is the one thing
                 a reader cannot infer from the round count alone. */}
             {run.output.shipped ? "the critic stopped it" : "the round budget stopped it"}
@@ -170,15 +172,13 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Redline>; onClear: () =>
 /**
  * One line describing where a run has got to.
  *
- * A `Record` keyed by the status union rather than a switch, so a status added
- * to the SDK is a compile error here instead of falling through a `default:`.
+ * The SDK's map with the one label this desk wants differently: `running` is
+ * "Writing…" here because that is what the run is doing. Spreading a COMPLETE
+ * `Record<WorkflowRunStatus, string>` cannot drop a key, so the exhaustiveness
+ * the hand-written copy was written for survives — and now lives at the SDK
+ * boundary, where a status added upstream is one compile error rather than one
+ * per page.
  */
-const STATUS_LINE: Record<WorkflowRun["status"], string> = {
-  pending: "Queued",
-  running: "Writing…",
-  completed: "Done",
-  failed: "Failed",
-  cancelled: "Cancelled",
-};
+const STATUS_LINE = { ...WORKFLOW_STATUS_LABELS, running: "Writing…" };
 
 page({ name: "Redline", component: RedlineDesk });

package/dist/templates/redline/workflows/redline.ts

@@ -31,8 +31,9 @@
  * three functions read more tidily than one.
  */
 
-import { throwStepError } from "@alexkroman1/aai/step-errors";
-import { report, stepGenerate, stepGenerateJson } from "@alexkroman1/aai/utils";
+import { report } from "@alexkroman1/aai/step";
+import { stepGenerateClassified, stepGenerateJsonClassified } from "@alexkroman1/aai/step-errors";
+import { countWords } from "@alexkroman1/aai/utils";
 import { FatalError } from "workflow";
 import { z } from "zod";
 import { CRITIC_SYSTEM, REVISER_SYSTEM, WRITER_SYSTEM } from "./prompts.ts";
@@ -145,7 +146,7 @@ export async function writeDraft(input: RedlineInput): Promise<string> {
   // `stepGenerate` already refuses an empty completion, as a RETRYABLE
   // `StepGenerateError` — which is the right answer, and one a hand-written
   // check would have to re-derive.
-  const draft = await ask(briefBlock(input), { system: WRITER_SYSTEM });
+  const draft = await stepGenerateClassified(briefBlock(input), { system: WRITER_SYSTEM });
   return draft.trim();
 }
 
@@ -168,10 +169,10 @@ export async function critiqueDraft(
   // `stepGenerateJson` owns the fence, the parse, the non-object case and the
   // shape — and throws PLAINLY when any of them misses, unlike the fatal one
   // above: a model that answered with prose may well obey on the next attempt.
-  const parsed = await stepGenerateJson(`${briefBlock(input)}\n\nThe submission:\n${draft}`, {
-    schema: CritiqueReply,
-    system: CRITIC_SYSTEM,
-  }).catch(throwStepError);
+  const parsed = await stepGenerateJsonClassified(
+    `${briefBlock(input)}\n\nThe submission:\n${draft}`,
+    { schema: CritiqueReply, system: CRITIC_SYSTEM },
+  );
 
   const critique: Critique = {
     verdict: parsed.verdict,
@@ -199,7 +200,7 @@ export async function reviseDraft(
   "use step";
 
   await report(`Round ${round}: revising.`);
-  const revised = await ask(
+  const revised = await stepGenerateClassified(
     [
       briefBlock(input),
       `Your current draft:\n${draft}`,
@@ -221,11 +222,6 @@ export function briefBlock(input: RedlineInput): string {
   return [`Brief: ${input.brief}`, `Audience: ${input.audience}`, must].join("\n\n");
 }
 
-export function countWords(text: string): number {
-  const trimmed = text.trim();
-  return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
-}
-
 /** Scores arrive from a model, so they arrive out of range often enough. */
 export function clampScore(score: number): number {
   if (!Number.isFinite(score)) return 0;
@@ -233,24 +229,16 @@ export function clampScore(score: number): number {
 }
 
 // ---- The model call ---------------------------------------------------------
-
-/**
- * `stepGenerate`, with this desk's retry POLICY on top.
- *
- * The SDK classifies the gateway's failure (`StepGenerateError.retryable`) and
- * stops there: whether a terminal failure should burn the step's remaining
- * attempts is the caller's call. `throwStepError`
- * (`@alexkroman1/aai/step-errors`) is that call made one way — terminal stays
- * terminal, and a rate limit becomes a `RetryableError` carrying the delay the
- * gateway itself named, which beats `RetryableError`'s own one-second default.
- *
- * This desk used to carry that mapping itself, as did `research-workflow` and
- * `link-digest`; it is one import now, and the delay is no longer the one line
- * only this template remembered.
- */
-async function ask(prompt: string, opts: { system: string }): Promise<string> {
-  return await stepGenerate(prompt, opts).catch(throwStepError);
-}
+//
+// There is no local `ask()` any more, and its absence is the point. The SDK
+// classifies the gateway's failure (`StepGenerateError.retryable`) and stops
+// there — whether a terminal failure should burn the step's remaining attempts
+// is the caller's call — so `stepGenerateClassified` and
+// `stepGenerateJsonClassified` (`@alexkroman1/aai/step-errors`) are that call
+// made one way: terminal stays terminal, and a rate limit becomes a
+// `RetryableError` carrying the delay the gateway itself named, which beats
+// `RetryableError`'s own one-second default. Three templates each wrapped the
+// raw `/step` call to say that; the wrapper is a suffix on the import now.
 
 /** A rate limit — and a model that ignored the format — are both expected. */
 critiqueDraft.maxRetries = 5;