@alexkroman1/aai-cli 9.2.0 → 10.0.0

package/dist/templates/podcast-digest/workflows/digest.ts

@@ -39,7 +39,7 @@
  * ## Batch polling, which is this file's one genuinely new mechanism
  *
  * `spoken-summary` and `transcription-workflow` each wait for ONE transcript,
- * so their poll loop is `for (…) { if (done) return; await sleep(…) }`. Here N
+ * so their poll loop is `for (…) { if (done) return; await ctx.sleep(…) }`. Here N
  * episodes are in flight at once and they finish out of order, so the loop has
  * to carry a shrinking pending set and let the finished ones drop out — see
  * {@link waitForTranscripts}. It is the same idea one dimension up, and the
@@ -49,15 +49,16 @@
  * @module digest
  */
 
+import type { WorkflowCtx } from "@alexkroman1/aai";
 import { mapConcurrent, report, TRANSCRIBE_API } from "@alexkroman1/aai/step";
 import {
+  FatalError,
   stepGenerateJsonClassified,
   stepTranscribePollClassified,
   stepTranscribeSubmitClassified,
 } from "@alexkroman1/aai/step-errors";
 import { errorMessage } from "@alexkroman1/aai/utils";
 import type { WorkflowInputOf } from "@alexkroman1/aai/workflow-api";
-import { FatalError, sleep } from "workflow";
 import { z } from "zod";
 import type { dailyDigest } from "../agent.ts";
 import { discoverEpisodes, type Episode } from "./feeds.ts";
@@ -70,7 +71,7 @@ import { sendDigestToSlack } from "./slack.ts";
  * restating the number — an eval skips the sleep, so the duration asked for is
  * the only observable there is.
  */
-export const POLL_DELAY = "20 seconds";
+export const POLL_DELAY_MS = 20_000;
 
 /**
  * 180 rounds x 20s = an hour, which is far past any podcast episode.
@@ -93,15 +94,17 @@ const MAX_TRANSCRIPT_CHARS = 18_000;
 /**
  * Submissions in flight at once — polite to the provider, still parallel.
  *
- * Inside the workflow world's default worker concurrency (three on the
- * `DATABASE_URL` path), so this width is what really runs — see "The WINDOW is
- * not the concurrency" in `mapConcurrent`.
+ * Inside `DEFAULT_STEP_CONCURRENCY` (`aai-runtime`, 16), so this width is what
+ * really runs — see "The WINDOW is not the concurrency" in `mapConcurrent`.
  */
 const SUBMIT_CONCURRENCY = 2;
 
-/** Status checks in flight at once. Cheaper calls, so a wider gate — and three is
- *  also where the world's default worker concurrency caps it, so this is the
- *  widest a stock deployment executes. */
+/**
+ * Status checks in flight at once. Cheaper calls, so a wider gate.
+ *
+ * Well inside `DEFAULT_STEP_CONCURRENCY` (`aai-runtime`, 16), like
+ * {@link SUBMIT_CONCURRENCY} above, so this width is what really runs.
+ */
 const POLL_CONCURRENCY = 3;
 
 /**
@@ -173,9 +176,10 @@ const SummaryReply = z.object({
  * that would answer differently on the second pass — {@link timestamp} is a step
  * for exactly that reason.
  */
-export async function dailyDigestFlow(input: DigestInput): Promise<DailyDigestOutput> {
-  "use workflow";
-
+export async function dailyDigestFlow(
+  input: DigestInput,
+  ctx: WorkflowCtx,
+): Promise<DailyDigestOutput> {
   // No `??` fallbacks: {@link DigestInput} is the schema's OUTPUT, so every
   // `.default()` has already run by the time a run reaches this line. The
   // chain this replaces restated all four of them, which is a second place for
@@ -188,26 +192,42 @@ export async function dailyDigestFlow(input: DigestInput): Promise<DailyDigestOu
   let digestsSent = 0;
 
   for (let digestNumber = 1; digestNumber <= totalDigests; digestNumber += 1) {
-    const episodes = await discoverEpisodes(input.podcastChannels, maxEpisodes);
-    const jobs = await mapConcurrent(episodes, SUBMIT_CONCURRENCY, submitTranscript);
-    const transcripts = await waitForTranscripts(jobs);
-    const digests = await mapConcurrent(transcripts, SUBMIT_CONCURRENCY, summarizeTranscript);
-
-    const slackStatus = await sendDigestToSlack({
-      slackWebhookUrl: input.slackWebhookUrl,
-      slackWorkflowTextParam: input.slackWorkflowTextParam,
-      podcastChannels: input.podcastChannels,
+    const episodes = await ctx.step("discoverEpisodes", () =>
+      discoverEpisodes(input.podcastChannels, maxEpisodes),
+    );
+    // `maxAttempts` was a `maxRetries` property on each function (4, 4, 5 —
+    // retries AFTER the first attempt, so 5, 5, 6 in all). It is an argument to
+    // the CALL now, which is where a policy belongs: the same function called
+    // from two places may deserve different patience.
+    const jobs = await mapConcurrent(episodes, SUBMIT_CONCURRENCY, (episode) =>
+      ctx.step("submitTranscript", () => submitTranscript(episode), { maxAttempts: 5 }),
+    );
+    const transcripts = await waitForTranscripts(jobs, ctx);
+    const digests = await mapConcurrent(transcripts, SUBMIT_CONCURRENCY, (transcript) =>
+      ctx.step("summarizeTranscript", () => summarizeTranscript(transcript), { maxAttempts: 6 }),
+    );
+
+    const slackStatus = await ctx.step("postDigest", () =>
+      sendDigestToSlack({
+        slackWebhookUrl: input.slackWebhookUrl,
+        slackWorkflowTextParam: input.slackWorkflowTextParam,
+        podcastChannels: input.podcastChannels,
+        episodes: digests,
+        digestNumber,
+        totalDigests,
+      }),
+    );
+
+    lastDigest = {
+      sentAt: await ctx.step("timestamp", () => timestamp()),
+      slackStatus,
       episodes: digests,
-      digestNumber,
-      totalDigests,
-    });
-
-    lastDigest = { sentAt: await timestamp(), slackStatus, episodes: digests };
+    };
     digestsSent += 1;
 
     // Not after the last one: a run that has delivered everything it owes
     // should end, not sleep for a day and then end.
-    if (digestNumber < totalDigests) await sleep(intervalMs);
+    if (digestNumber < totalDigests) await ctx.sleep(intervalMs);
   }
 
   return {
@@ -223,10 +243,10 @@ export async function dailyDigestFlow(input: DigestInput): Promise<DailyDigestOu
 /**
  * Wait for a whole BATCH of transcripts, letting them finish out of order.
  *
- * A plain async function rather than a step, and not because it is small: it
- * calls steps and it `sleep`s, neither of which a step may do. So it runs as
- * part of the body and is replayed with it — legal for the ordinary reason,
- * that every line is either a step call or a `sleep`.
+ * Part of the BODY rather than a step, and not because it is small: it CALLS
+ * steps and it sleeps, neither of which may happen inside one. So it is replayed
+ * with the body — legal for the ordinary reason, that every line is either a
+ * `ctx.step` or a `ctx.sleep` — and it takes the `ctx` for that reason.
  *
  * The shape to notice is that `pending` SHRINKS. A loop that waited for all N
  * on every round would hold the whole batch hostage to its slowest member, and
@@ -247,19 +267,24 @@ export async function dailyDigestFlow(input: DigestInput): Promise<DailyDigestOu
  * the top. Found by `agent.eval.test.ts`, which is the only tier that can see
  * it, a per-step spec having no batch to order.
  */
-async function waitForTranscripts(jobs: TranscriptJob[]): Promise<TranscriptState[]> {
+async function waitForTranscripts(
+  jobs: TranscriptJob[],
+  ctx: WorkflowCtx,
+): Promise<TranscriptState[]> {
   let pending = jobs;
   // Keyed by episode id rather than appended, and that is what keeps the digest
   // in PUBLICATION order — see this function's doc.
   const settled = new Map<string, TranscriptState>();
 
   for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS && pending.length > 0; attempt += 1) {
-    const polled = await mapConcurrent(pending, POLL_CONCURRENCY, pollTranscript);
+    const polled = await mapConcurrent(pending, POLL_CONCURRENCY, (job) =>
+      ctx.step("pollTranscript", () => pollTranscript(job), { maxAttempts: 5 }),
+    );
     for (const state of polled) {
       if (state.transcriptStatus !== "submitted") settled.set(state.id, state);
     }
     pending = polled.filter((state) => state.transcriptStatus === "submitted");
-    if (pending.length > 0) await sleep(POLL_DELAY);
+    if (pending.length > 0) await ctx.sleep(POLL_DELAY_MS);
   }
 
   for (const job of pending) settled.set(job.id, gaveUpOn(job));
@@ -305,8 +330,6 @@ function gaveUpOn(job: TranscriptJob): TranscriptState {
  * one-second default instead.
  */
 export async function submitTranscript(episode: Episode): Promise<TranscriptJob> {
-  "use step";
-
   await report(`Submitting ${episode.title} for transcription.`);
   try {
     const { id } = await stepTranscribeSubmitClassified(episode.audioUrl, {
@@ -320,8 +343,6 @@ export async function submitTranscript(episode: Episode): Promise<TranscriptJob>
   }
 }
 
-submitTranscript.maxRetries = 4;
-
 /**
  * Ask once whether one job has finished.
  *
@@ -332,8 +353,6 @@ submitTranscript.maxRetries = 4;
  * for "still going".
  */
 export async function pollTranscript(job: TranscriptJob): Promise<TranscriptState | TranscriptJob> {
-  "use step";
-
   if (job.transcriptStatus === "unavailable") return job;
 
   try {
@@ -358,12 +377,8 @@ export async function pollTranscript(job: TranscriptJob): Promise<TranscriptStat
   }
 }
 
-pollTranscript.maxRetries = 4;
-
 /** Reduce one transcript to the summary and points the digest carries. */
 export async function summarizeTranscript(state: TranscriptState): Promise<EpisodeDigest> {
-  "use step";
-
   if (state.transcriptStatus === "unavailable") {
     // Still an entry in the digest. A reader who sees four summaries and one
     // stated reason knows what happened; four summaries and silence looks like
@@ -404,17 +419,21 @@ export async function summarizeTranscript(state: TranscriptState): Promise<Episo
   };
 }
 
-summarizeTranscript.maxRetries = 5;
-
 /**
  * The clock, as a step.
  *
  * A step's result is journaled and therefore stable across replays, where
  * `new Date()` in the body would answer differently on every one — and a body
- * that is not deterministic is a body the DevKit cannot replay.
+ * that is not deterministic is a body the engine cannot replay.
+ *
+ * The read below is therefore a BASELINED occurrence of `guard-invariants`
+ * rule 30, and that is the reason: it is inside a step, not inside a body. The
+ * rule bans the call anywhere in a shipped `workflows/` file because the
+ * `ctx.step` callback boundary is not decidable from a line; `dailyDigestFlow`
+ * is what reaches this one, as `ctx.step("timestamp", () => timestamp())`.
+ * Anything at BODY level is the bug, not an exception.
  */
 export async function timestamp(): Promise<string> {
-  "use step";
   return new Date().toISOString();
 }
 

package/dist/templates/podcast-digest/workflows/feeds.ts

@@ -45,9 +45,8 @@
  */
 
 import { report } from "@alexkroman1/aai/step";
-import { stepFetchOk } from "@alexkroman1/aai/step-errors";
+import { FatalError, stepFetchOk } from "@alexkroman1/aai/step-errors";
 import { decodeHtmlEntities, isRecord, omitUndefined, safeJsonParse } from "@alexkroman1/aai/utils";
-import { FatalError } from "workflow";
 
 /** How long any one of these lookups may take before it is a failure. */
 const REQUEST_TIMEOUT_MS = 30_000;
@@ -93,8 +92,6 @@ export async function discoverEpisodes(
   podcastChannels: string,
   maxEpisodes: number,
 ): Promise<Episode[]> {
-  "use step";
-
   await report("Finding recent podcast episodes.");
   const links = parsePodcastChannels(podcastChannels);
   if (links.length === 0) throw new FatalError("Add at least one podcast link.");

package/dist/templates/podcast-digest/workflows/slack.ts

@@ -19,10 +19,11 @@
  *
  * ## What a step still owns
  *
- * The `"use step"` stays HERE, and it has to. The Workflow DevKit's builder
- * rewrites step bodies it finds in this directory; one written inside the SDK
- * would be transformed by nothing, so it would run inline with no journal and
- * no retry while looking durable at the call site.
+ * The step BOUNDARY is not here — only a body holds a `ctx`, and the call this
+ * file is reached through is `ctx.step("postDigest", …)` in `digest.ts`. What
+ * stays here is what a step DOES: the digest rendered as a `ChannelMessage` and
+ * one `sendToChannelClassified` call. Deciding which steps exist is the
+ * template's job; what happens inside one is the SDK's.
  */
 
 import { type ChannelMessage, slackChannel } from "@alexkroman1/aai/channels";
@@ -51,8 +52,6 @@ export type SlackDigestInput = {
  * `RetryableError` carrying Slack's own `Retry-After` on a 5xx.
  */
 export async function sendDigestToSlack(input: SlackDigestInput): Promise<string> {
-  "use step";
-
   await report("Posting the digest to Slack.");
   return await sendToChannelClassified(
     slackChannel({ webhookUrl: input.slackWebhookUrl, textParam: input.slackWorkflowTextParam }),

package/dist/templates/recap-workflow/agent.eval.test.ts

@@ -16,12 +16,33 @@
 //     `sleep()` is RECORDED rather than taken — so the poll loop below runs at
 //     full speed and the only way to observe a run in flight is to hold the
 //     provider's answer, which is what `hold` does.
-//   * **`createHook()` throws untransformed**, so the RETENTION GATE — this
-//     template's headline port of Temporal's `expense` — cannot be reached at
-//     all here, and neither can `keep_transcript`'s signal: a run that gets past
-//     `summarize` fails on the hook. Nothing below asserts the gate, its three
-//     outcomes, or its safe default; `agent.test.ts` drives
-//     `askWhetherToKeep` directly for those, and it is the only tier that can.
+//   * **Nobody can answer a hook here**, which reaches the RETENTION GATE — this
+//     template's headline port of Temporal's `expense` — through exactly ONE of
+//     its three branches. `ctx.waitFor` carrying a `timeoutMs` resolves
+//     `undefined` in this engine, which IS the closed window, so every run that
+//     gets past `summarize` takes the gate's safe default: it deletes the
+//     transcript it made and completes. That branch is asserted below. The two
+//     ANSWERED branches are the unreachable ones — `signal()` answers `false`
+//     for every token, there being nothing in process to deliver a payload — so
+//     an approval, a decline and `keep_transcript` itself are `agent.test.ts`'s
+//     to drive against `askWhetherToKeep`, and it is the only tier that can.
+//   * **Every run here takes the NO-CALLBACK arm, and that must not be read as
+//     coverage of the webhook path.** The eval publishes no webhook minter, so
+//     `stepWebhookUrl` throws, the template's `callbackUrl` degrades to
+//     `undefined`, the job is submitted with no `webhook_url`, and
+//     `awaitTranscript` never parks on a hook at all — it polls, exactly as it
+//     did before the provider could call back. That is worth having rather than
+//     working around: it is the arm a deployment with no public URL takes, it is
+//     the arm a dropped delivery lands on, and it is the one that must never
+//     hang. A case below asserts it POSITIVELY — that the submitted job carries
+//     no `webhook_url` — so an eval runtime that later publishes a minter fails
+//     here instead of silently changing what all of these cases measure.
+//
+//     What no eval here can show is a delivery RESUMING a run, so no case claims
+//     it. The answered arm is `agent.test.ts`'s, through
+//     `createWorkflowCtx({ hooks })`, which is the only tier that can send a
+//     payload at all; a real HTTP POST to the public callback route is
+//     `aai-cli`'s `dev-workflow.scenario.test.ts`'s, and is not yet written.
 //   * **The provider is scripted, in BOTH modes**, through `stepFetch`'s
 //     published slot — so the transcription, the recap's model call and the
 //     compensating DELETE are all deterministic and free, while the SESSION's
@@ -186,7 +207,10 @@ const START_TURN = [
  * Not tidiness: the scripted provider is unpublished when the test that
  * installed it finishes, so a body still mid-flight would make its next request
  * against whatever the next case publishes — or against the real provider, with
- * a real key. Every run here ends FAILED, on `createHook()`; see the header.
+ * a real key. A run drained here COMPLETES rather than failing, and the last
+ * thing it does on the way is delete its own transcript: the retention gate's
+ * window closes with nobody having answered, which is the safe default. See the
+ * header, and the case that pins it.
  */
 async function drain(workflows: EvalWorkflows | undefined, provider: ScriptedProvider) {
   provider.release();
@@ -226,10 +250,18 @@ describeEval(
         expect(posts).toHaveLength(1);
         // And it submitted the recording the DESK supplies, because a phone
         // caller cannot read a URL aloud.
-        expect(JSON.parse(String(posts[0]?.body))).toMatchObject({
+        const submitted = JSON.parse(String(posts[0]?.body));
+        expect(submitted).toMatchObject({
           audio_url: SAMPLE_RECORDING,
           speaker_labels: true,
         });
+        // NO `webhook_url`, asserted positively — see the third boundary in this
+        // file's header. Nothing publishes a webhook minter here, so
+        // `stepWebhookUrl` throws, `callbackUrl` degrades, and every run in this
+        // file polls rather than parking on a callback. Pinning it here is what
+        // stops an eval runtime that later publishes one from silently changing
+        // which arm all of these cases measure.
+        expect(Object.keys(submitted)).not.toContain("webhook_url");
 
         await drain(workflows, provider);
       },
@@ -328,6 +360,38 @@ describeEval(
       },
     );
 
+    test("nobody answers the retention gate, so the transcript is not kept", async ({
+      workflows,
+    }) => {
+      // The gate's SAFE DEFAULT, and the branch of it this tier really does
+      // reach: `ctx.waitFor` here carries a `timeoutMs` and no one can send a
+      // payload, which is the closed window rather than a missing feature. So
+      // this is the ordinary ending of every run in this file, and it is worth
+      // an assertion of its own — a gate whose no-answer branch KEPT the data
+      // would be a prompt with a grace period, and nothing else here would
+      // notice the difference.
+      const provider = stubProvider();
+
+      const run = await workflows?.run(recap, {
+        url: SAMPLE_RECORDING,
+        requestedBy: "eval-session",
+      });
+
+      expect(run?.status).toBe("completed");
+      // `answered: false` is the half that separates this from a caller who
+      // said no: the desk reports which of the two happened rather than only
+      // what it did.
+      expect(run?.output).toMatchObject({ kept: false, answered: false });
+      // And the default really is DELETE — the same request the compensation
+      // makes, reached by the opposite path: this run succeeded.
+      expect(requests(provider, "DELETE").map((one) => one.url)).toEqual([
+        `https://api.assemblyai.com/v2/transcript/${TRANSCRIPT_ID}`,
+      ]);
+      // The caller was ASKED first, which is what makes two minutes of silence
+      // an answer at all.
+      expect(run?.reported.join("\n")).toMatch(/Keep the transcript on file/);
+    });
+
     test("a run that fails after creating a transcript deletes it again", async ({ workflows }) => {
       // Started from the CASE rather than through a tool, because the subject
       // is the saga and the failure has to be injected: the provider refuses