@alexkroman1/aai-cli 6.11.0 → 8.0.0

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

@@ -0,0 +1,139 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * A SCHEDULED workflow app — a run that repeats on an interval and outlives
+ * everything, including the tab that started it.
+ *
+ * Its front door is a form, not a microphone: no session, no WebSocket, no
+ * voice pipeline. `client.tsx` starts a run over the workflow HTTP API and
+ * watches it, and `workflows/digest.ts` does the work.
+ *
+ * ## What makes this a different KIND of workflow app from `link-digest`
+ *
+ * `link-digest` is the smallest one: one URL in, one digest out, run over. This
+ * is the same front door around a run that **sleeps for days and wakes up
+ * again**. Three consequences worth reading before copying it:
+ *
+ * - **The run is the schedule.** There is no cron anywhere in this template.
+ *   `sleep()` inside a durable body IS the scheduler — the run suspends,
+ *   nothing is resident, and the platform brings it back. That is the cheapest
+ *   recurring job you can write here and it needs no infrastructure.
+ * - **It is asked when to stop.** `daysToRun` is an input rather than a
+ *   constant because a run with no end is a resource nobody can see. It posts
+ *   what it owes and finishes.
+ * - **Storage stops being optional.** A multi-day sleep does not survive in
+ *   process memory. See `workflows/digest.ts` for what that looks like when you
+ *   forget (the first digest arrives; the second never does).
+ *
+ * ## 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 transcribes
+ * the episodes and really summarizes them. `requiredEnv` 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` — which the SDK's transcription and model helpers do
+ * for you, and which is why nothing in `workflows/` mentions the key by name.
+ *
+ * The Slack webhook is the other credential and is deliberately NOT env: it is
+ * per-run input, so one deployed agent can post to whichever channel each run
+ * names.
+ */
+
+import { type WorkflowDef, workflow, workflowApp } from "@alexkroman1/aai";
+import { isSlackWebhookUrl } from "@alexkroman1/aai/channels";
+import { z } from "zod";
+import { type DailyDigestOutput, dailyDigestFlow } from "./workflows/digest.ts";
+
+/** Somebody pastes a list; anything not http(s) is a typo worth catching here. */
+function isHttpUrl(value: string): boolean {
+  try {
+    const { protocol } = new URL(value);
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The declaration: schema, description, and the body.
+ *
+ * The `input` schema does double duty in a way it cannot for a voice agent. It
+ * validates at `start()` — so a bad feed URL or a non-Slack webhook is a 400 at
+ * the call site rather than a failed run discovered an hour later, after
+ * transcription has already been paid for — and it is served on
+ * `GET /workflows` as JSON Schema, which is what lets a page render a form for
+ * a workflow it was not written against.
+ *
+ * Every field carries `.describe()` for that second reason, and every optional
+ * one carries `.default()` so the page and the body agree on the fallback
+ * instead of each picking its own.
+ */
+const digestInput = z.object({
+  podcastChannels: z
+    .string()
+    .trim()
+    .min(1)
+    .refine(
+      (value) => value.split(",").every((url) => isHttpUrl(url.trim())),
+      "Enter comma-separated podcast links",
+    )
+    .describe("Podcast links — Apple Podcasts, Spotify, RSS, or a show page — comma-separated"),
+  // A host check, not a URL check. This value is the target of a POST
+  // carrying summarized content, so "is it a URL" would accept an
+  // exfiltration endpoint somebody typed into a form.
+  slackWebhookUrl: z
+    .string()
+    .trim()
+    .url()
+    .refine(isSlackWebhookUrl, "Enter a Slack webhook URL from hooks.slack.com")
+    .describe("Slack incoming webhook or workflow trigger URL"),
+  slackWorkflowTextParam: z
+    .string()
+    .trim()
+    // A Slack workflow variable name. Constrained because it is used as an
+    // object KEY in the request body, and an arbitrary string there is a way
+    // to shape a payload the workflow never declared.
+    .regex(/^[A-Za-z_][A-Za-z0-9_]*$/)
+    .default("text")
+    .describe("Slack workflow variable name (workflow trigger URLs only)"),
+  maxEpisodesPerDigest: z
+    .number()
+    .int()
+    .min(1)
+    .max(20)
+    .default(5)
+    .describe("Most episodes to include in one digest"),
+  intervalEvery: z.number().int().min(1).max(365).default(1).describe("Repeat every"),
+  intervalUnit: z
+    .enum(["minutes", "hours", "days"])
+    .default("days")
+    .describe("Unit for the repeat interval"),
+  // Bounded on purpose — see the module doc on why a run is asked to end.
+  daysToRun: z
+    .number()
+    .int()
+    .min(1)
+    .max(30)
+    .default(7)
+    .describe("How many digests to post before the run completes"),
+});
+
+export const dailyDigest: WorkflowDef<typeof digestInput, DailyDigestOutput> = workflow({
+  description:
+    "Watch podcast feeds, transcribe new episodes with AssemblyAI, summarize them, " +
+    "and post a digest to Slack on a repeating schedule",
+  input: digestInput,
+  run: dailyDigestFlow,
+});
+
+export default workflowApp({
+  name: "Podcast Digest",
+  // The whole product. A workflow app is an agent whose work happens here.
+  workflows: { dailyDigest },
+  // 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/podcast-digest/client.tsx

@@ -0,0 +1,154 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The browser half — a form that starts a run, and a panel that watches one
+ * that may outlive the browser by a week.
+ *
+ * Mounted with `page()` rather than `client()`: there is no session to build, so
+ * no socket, no audio graph, no microphone request. `useWorkflowSubmit()` starts
+ * the run, follows its STATUS, and hands back the controls bound to it. The API
+ * is durable, so the `runId` is the whole state — it survives a reload, another
+ * device, or `curl`.
+ *
+ * ## The form is DECLARED, not written
+ *
+ * Every property of this workflow's input schema is a scalar, so
+ * `<WorkflowFields>` renders the whole form from what `GET /workflows` serves —
+ * a `<SelectField>` for the `z.enum`, number spinners for the counts, the
+ * `.describe()` text as each hint, and the `.default()` as each control's
+ * starting value. Adding an eighth field to `agent.ts` adds an eighth control
+ * here with no edit to this file, and the defaults are stated once, in the
+ * schema, rather than here AND in the schema AND in the workflow body.
+ *
+ * `link-digest` is the page that writes its one control by hand, deliberately,
+ * so a reader can see what this layer stands on. `redline` is the MIXED case —
+ * declared scalars beside one hand-written array field.
+ *
+ * ## What a SCHEDULED run adds to `link-digest`'s page
+ *
+ * Two controls that only make sense when a run spends most of its life asleep,
+ * and both are the point of copying this file rather than that one:
+ *
+ * - **Wake.** A sleeping run's next digest is hours or days out. `wake()` cuts
+ *   the wait short and sends it now. Without it the only handle on a sleeping
+ *   run is `cancel`, so "send it now" and "throw it away" would be the same
+ *   button. `wake` answering 0 means the run had already moved past its sleep,
+ *   which is why nothing here treats that as a failure.
+ * - **Cancel.** A run scheduled for thirty digests is a standing commitment, and
+ *   the page that started it is the obvious place to end it. Cancelling is why
+ *   `daysToRun` can be generous.
+ *
+ * Both are bound to the run the submission is following, which is the whole
+ * reason this page no longer holds a `createWorkflowApi()` of its own.
+ *
+ * ## Why the status panel reads `digestsSent` and not a progress bar
+ *
+ * There is nothing to fill. A run posts digest 3 of 7 and then sleeps for a day
+ * — a bar would sit at 43% looking stalled for most of the run's life. The
+ * honest display is the count plus the run's own newest line.
+ */
+
+import {
+  Form,
+  page,
+  SubmitButton,
+  useWorkflowSubmit,
+  WorkflowFields,
+  WorkflowProgress,
+} 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/workflow-api";
+import type { dailyDigest } from "./agent.ts";
+
+/** What a completed run reports, derived from the workflow rather than restated. */
+type Digest = WorkflowOutputOf<typeof dailyDigest>;
+
+/** The workflow this page drives. Matches the key in `workflowApp({ workflows })`. */
+const WORKFLOW = "dailyDigest";
+
+export function App() {
+  // The generic is what makes `run.status === "completed"` narrow to a TYPED
+  // `run.output` instead of `unknown`. `error` is the agent's own sentence for a
+  // rejected input — better copy than anything this page could write, and the
+  // reason there is no `try`/`catch` here.
+  const { submit, run, pending, error, wake, cancel } = useWorkflowSubmit<Digest>(WORKFLOW);
+
+  return (
+    <main className="mx-auto flex max-w-2xl flex-col gap-6 p-8">
+      <h1 className="text-2xl font-medium">Podcast Digest</h1>
+
+      {/* `submit()` resolves as soon as the run EXISTS — deliberately not when it
+          finishes, which here could be a month away. */}
+      <Form onSubmit={(values) => submit(values)} error={error}>
+        <WorkflowFields workflow={WORKFLOW} />
+        <SubmitButton pending={pending}>
+          {pending ? "Digest scheduled" : "Start digest"}
+        </SubmitButton>
+      </Form>
+
+      {/* A run that has not settled says so. `pending` is not derivable from the
+          snapshot alone — an id the agent never knew leaves `run` undefined,
+          which would otherwise read as "still waiting" forever. */}
+      {pending && <p>You can close this tab — the run continues without it.</p>}
+
+      {/* The run's own narration, newest line only. `lines={1}` is the window;
+          everything else — the replay, and the "serves no stream" case that is
+          otherwise indistinguishable from "wrote nothing yet" — belongs to the
+          component. */}
+      <WorkflowProgress runId={run?.runId} lines={1} className="text-sm opacity-70" />
+
+      {pending && (
+        <div className="flex gap-2">
+          {/* The counterpart of the `sleep` in `workflows/digest.ts` — see the
+              module doc on why a scheduled run needs this AND cancel. */}
+          <button
+            type="button"
+            onClick={() => void wake()}
+            className="rounded-md border px-3 py-1 text-sm"
+          >
+            Send the next digest now
+          </button>
+          <button
+            type="button"
+            onClick={() => void cancel()}
+            className="rounded-md border px-3 py-1 text-sm text-red-600"
+          >
+            Stop the schedule
+          </button>
+        </div>
+      )}
+
+      {run?.status === "failed" && <p className="text-red-600">That run failed: {run.error}</p>}
+      {run?.status === "cancelled" && <p>Cancelled — no further digests will be posted.</p>}
+
+      {run?.status === "completed" && (
+        <article className="flex flex-col gap-4">
+          <p className="text-sm opacity-70">
+            Posted {run.output.digestsSent} of {run.output.digestsScheduled} digests to{" "}
+            {run.output.deliveryTarget}, every {run.output.scheduleInterval}.
+          </p>
+          {run.output.lastDigest?.episodes.map((episode) => (
+            <section key={episode.id} className="flex flex-col gap-1 border-t pt-3">
+              <p className="text-sm opacity-70">{episode.podcastTitle}</p>
+              <h2 className="text-lg">
+                <a href={episode.url} className="underline">
+                  {episode.title}
+                </a>
+              </h2>
+              <p>{episode.summary}</p>
+              <ul className="flex list-disc flex-col gap-1 pl-5 text-sm">
+                {episode.keyPoints.map((point) => (
+                  <li key={point}>{point}</li>
+                ))}
+              </ul>
+            </section>
+          ))}
+        </article>
+      )}
+    </main>
+  );
+}
+
+page({ name: "Podcast Digest", component: App });