@pithy-sh/support 0.1.0

package/src/workflows/classify.ts

@@ -0,0 +1,164 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { SupportAi } from "../ai/classify";
+import { classifyMessage } from "../ai/classify";
+import type { SupportAiConfig } from "../config/config";
+import type { SupportCategories } from "../data/categories";
+import { SupportClassification } from "../data/classification";
+import { SPAM } from "../data/enums";
+import {
+  SUPPORT_CLASSIFICATIONS_TABLE,
+  SUPPORT_MESSAGES_TABLE,
+  SUPPORT_THREADS_TABLE,
+  type SupportDatabase,
+} from "../data/tables";
+
+/**
+ * The classification orchestration — the pure, testable core the Workflow step runs.
+ *
+ * Reads a message, asks the model about it, **appends** a classification row, and denormalizes the
+ * answer onto its thread. The two writes are deliberate and asymmetric: the history is append-only
+ * so a model upgrade is visible in the data rather than a silent rewrite, and the thread carries only
+ * the current answer because that is what the inbox query reads.
+ *
+ * Idempotent by construction. Re-running over the same message appends a second row and overwrites
+ * the same three thread columns with a fresh judgment — which is what makes a Workflow retry, a
+ * manual reclassify, and a post-upgrade backfill the same operation.
+ */
+
+/** Everything classification needs, all injectable. */
+export interface ClassifyDeps {
+  /** The support tables. */
+  db: SupportDatabase;
+  /** The Workers AI binding. */
+  ai: SupportAi;
+  /** The effective taxonomy — the defaults plus the adopter's. */
+  categories: SupportCategories;
+  /** Model, bounds, and temperature. */
+  ai_config: SupportAiConfig;
+  /**
+   * Archive a thread the classifier calls `spam`, so it never reaches the open inbox.
+   *
+   * **Archived, never deleted.** The classifier is wrong sometimes, and a pass that destroyed mail
+   * would be untrustworthy the first time it was — whereas an archived thread is still readable under
+   * the archived filter and one click from being back. That is what makes `spam` a filter rather than
+   * a bin, and it is why this is safe to have on by default.
+   */
+  archiveSpam: boolean;
+  /** Generate a row id. */
+  newId: () => string;
+  /** Now. */
+  now: () => Date;
+}
+
+/** What one classification run did. `null` when the message no longer exists. */
+export interface ClassifyOutcome {
+  /** The thread the classification landed on. */
+  threadId: string;
+  /** The category chosen. */
+  category: string;
+  /** The model's confidence. */
+  confidence: number;
+  /** The model that produced it. */
+  model: string;
+  /** Whether this run archived the thread because it classified as spam. */
+  archivedAsSpam: boolean;
+}
+
+/** Classify one stored message and write the result. Returns null when the message is gone. */
+export async function runClassification(deps: ClassifyDeps, messageId: string): Promise<ClassifyOutcome | null> {
+  const message = await deps.db
+    .selectFrom(SUPPORT_MESSAGES_TABLE)
+    .select(["id", "threadId", "subject", "textBody"])
+    .where("id", "=", messageId)
+    .executeTakeFirst();
+  // Not an error. A Workflow instance can outlive the row that started it, and a retry after a
+  // rollback is the ordinary way that happens.
+  if (!message) return null;
+
+  const result = await classifyMessage(deps.ai, {
+    categories: deps.categories,
+    subject: message.subject,
+    body: message.textBody,
+    model: deps.ai_config.model,
+    maxChars: deps.ai_config.maxChars,
+    temperature: deps.ai_config.temperature,
+  });
+
+  const now = deps.now();
+
+  await deps.db
+    .insertInto(SUPPORT_CLASSIFICATIONS_TABLE)
+    .values(
+      SupportClassification.encode({
+        id: deps.newId(),
+        threadId: message.threadId,
+        messageId: message.id,
+        category: result.category,
+        priority: result.priority,
+        sentiment: result.sentiment,
+        confidence: result.confidence,
+        model: result.model,
+        createdAt: now,
+      }),
+    )
+    .execute();
+
+  // Spam gets archived in the same write that classifies it, not a second pass — otherwise there is a
+  // window where it sits in somebody's open inbox, which is the whole thing this avoids.
+  const archivedAsSpam = deps.archiveSpam && result.category === SPAM;
+
+  await deps.db
+    .updateTable(SUPPORT_THREADS_TABLE)
+    .set({
+      category: result.category,
+      priority: result.priority,
+      sentiment: result.sentiment,
+      confidence: result.confidence,
+      model: result.model,
+      classifiedAt: now.getTime(),
+      updatedAt: now.getTime(),
+      ...(archivedAsSpam
+        ? {
+            archived: 1 as const,
+            archivedAt: now.getTime(),
+            // The model, named as the actor. An operator looking at why a thread is archived should
+            // see that nobody decided it — and `archivedBy` is exactly where they will look.
+            archivedBy: result.model,
+          }
+        : {}),
+    })
+    .where("id", "=", message.threadId)
+    .execute();
+
+  return {
+    threadId: message.threadId,
+    category: result.category,
+    confidence: result.confidence,
+    model: result.model,
+    archivedAsSpam,
+  };
+}
+
+/**
+ * The message a manual reclassify runs against: a thread's most recent **inbound** message.
+ *
+ * Inbound, not latest — a thread whose last message is our own reply would otherwise be reclassified
+ * on the text the adopter wrote, which says nothing about what the customer wanted.
+ */
+export async function latestInboundMessageId(db: SupportDatabase, threadId: string): Promise<string | undefined> {
+  const row = await db
+    .selectFrom(SUPPORT_MESSAGES_TABLE)
+    .select(["id"])
+    .where("threadId", "=", threadId)
+    .where("direction", "=", "inbound")
+    .orderBy("receivedAt", "desc")
+    // Tiebroken on id: two messages can share a millisecond (a redelivery burst, or a fixed clock in
+    // a test), and without it "the latest inbound message" is whichever the database felt like —
+    // so a reclassify or a reply could thread against the wrong parent.
+    .orderBy("id", "desc")
+    .limit(1)
+    .executeTakeFirst();
+  return row?.id;
+}

package/src/workflows/retryPolicy.ts

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { WorkflowRetryPolicy } from "@pithy-sh/core/src/workflow/faults";
+
+/**
+ * **What a classification retries, and what it refuses to.**
+ *
+ * `ai/classify.ts` already drew this line and drew it correctly: a model that returns prose, an invented
+ * label, or an envelope nobody documented yields `uncategorized` at zero confidence and never throws,
+ * because throwing would burn a retry budget on a model that is going to say the same thing next time.
+ * The one case it deliberately does not swallow is a binding that is *unavailable*. This is that
+ * sentence in the form the durable step reads (pithy-sh/pithy#348).
+ *
+ * ## Retryable, and why
+ *
+ * - **`core/upstream_failed`** — Workers AI rejected the call. Raised at exactly one place, the wrap
+ *   around `ai.run` in `classifyMessage`, and it means the model did not answer at all. That is the
+ *   whole population of transient faults in a classification, and the code is what lets the step tell
+ *   it from a bad answer — a raw throw would be `unclassified`, and unclassified is terminal.
+ * - **A transient D1 fault** — the message read, the appended history row, the thread denormalization.
+ *   Classified in core by `withD1Retry`, never restated here.
+ *
+ * ## Terminal, and why
+ *
+ * - **`support/not_found`** — a thread or message that is gone. `runClassification` does not even raise
+ *   it for the message it was started for: a missing row returns `null`, because an instance outliving
+ *   the row that started it is the ordinary way a rollback looks.
+ * - **`support/classification_failed`** — the AI binding is absent from the env. A binding does not
+ *   appear on the fourth attempt; this wants `pithy support provision`.
+ * - **`support/invalid_category`** — the adopter's taxonomy will not validate. Config, and identical
+ *   next time.
+ * - **`support/unparseable_message`, `support/rejected`, `support/reply_failed`** — all inbound-path and
+ *   reply-path refusals. None runs inside the classify step.
+ * - **`validation/invalid_input`** — a payload the schema refuses.
+ *
+ * **Re-running is free, which is what makes the retryable entry safe.** Classification is idempotent by
+ * construction: a second pass appends a second history row and overwrites the same three thread columns
+ * with a fresh judgment, which is why a Workflow retry, a manual reclassify, and a post-upgrade
+ * backfill are the same operation.
+ */
+export const supportWorkflowRetry: WorkflowRetryPolicy = {
+  capability: "support",
+  retryable: {
+    "core/upstream_failed":
+      "The model did not answer at all; classification is idempotent, so asking again costs one call.",
+  },
+};

package/src/workflows/specs.ts

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
+import type { WorkflowRegistry, WorkflowSpecMap } from "@pithy-sh/core/src/workflow/spec";
+import { z } from "zod";
+
+/**
+ * The one durable job support owns, declared once.
+ *
+ * **Classification is a Workflow, not part of the `email()` handler**, and that is a hard constraint
+ * rather than a preference. An inbound handler runs under a tight CPU budget; a model call is
+ * hundreds of milliseconds of wall time it cannot spend, and a model that is slow or briefly
+ * unavailable would take the *persistence* of the message down with it. So the handler does the
+ * cheap, must-not-fail half — parse, bound, store — and hands off. A classification that fails
+ * retries against a message that is already safely in D1.
+ *
+ * `optional: true`: the Workflow lives in the prebuilt support worker that `pithy support provision`
+ * deploys, so a project that has not provisioned must still boot and still receive mail. An absent
+ * binding degrades to a logged skip and a thread that stays `uncategorized` — which is exactly the
+ * state a classification is allowed to be in.
+ */
+
+/** The capability name — the first segment of the dispatch key and of every deployed workflow name. */
+export const SUPPORT_CAPABILITY = "support";
+
+/** Which message to classify. */
+export const SupportClassifyParams = z
+  .object({
+    messageId: z
+      .string()
+      .min(1)
+      .describe(
+        "The `pithy_support_messages.id` to classify. The Workflow reads that message, asks the model about it, appends a classification row, and denormalizes the answer onto its thread.",
+      ),
+  })
+  .describe("The instance parameters of the classification Workflow — the one message it runs against.");
+export type SupportClassifyParams = z.infer<typeof SupportClassifyParams>;
+
+/** Support's durable jobs, keyed by job name. The key is the second segment of the `support/<job>` dispatch key. */
+export const supportWorkflows = {
+  classify: {
+    binding: "SUPPORT_CLASSIFY",
+    className: "SupportClassifyWorkflow",
+    params: SupportClassifyParams,
+    optional: true,
+  },
+} as const satisfies WorkflowSpecMap;
+
+/**
+ * Support's jobs as a dispatch registry, keyed `support/<job>`. Built here rather than through
+ * `composeWorkflows` because the inbound handler dispatches from inside the capability, before any
+ * project-wide registry exists — and the key format comes from core's {@link workflowKey} either
+ * way, so the two cannot drift.
+ */
+export const supportWorkflowRegistry: WorkflowRegistry = Object.fromEntries(
+  Object.entries(supportWorkflows).map(([job, spec]) => {
+    const key = workflowKey(SUPPORT_CAPABILITY, job);
+    return [key, { key, capability: SUPPORT_CAPABILITY, job, spec }];
+  }),
+);

package/src/workflows/worker.ts

@@ -0,0 +1,82 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
+import { NonRetryableError } from "cloudflare:workflows";
+import type { D1Database } from "@cloudflare/workers-types";
+import { classifiedSteps } from "@pithy-sh/core/src/workflow/faults";
+import { workflowHostEntry } from "@pithy-sh/core/src/workflow/hostEntry";
+import type { SupportAi } from "../ai/classify";
+import { SupportConfig } from "../config/config";
+import { resolveCategories } from "../data/categories";
+import { supportDatabase } from "../data/tables";
+import { runClassification } from "./classify";
+import { supportWorkflowRetry } from "./retryPolicy";
+import { SUPPORT_CAPABILITY } from "./specs";
+
+/**
+ * The prebuilt support worker. `pithy support provision` deploys one per environment; the adopter
+ * authors no code for it. It hosts the classification Workflow — a thin durable shell around the
+ * tested orchestration in `classify.ts`. The app worker receives the mail, stores it, and starts an
+ * instance.
+ *
+ * This module imports `cloudflare:workers`, so it runs only in the Workers runtime and is excluded
+ * from the node `.describe()` meta-test.
+ *
+ * **The effective taxonomy arrives as config, not as code.** `SUPPORT_CONFIG` carries the adopter's
+ * own categories, so their `tournament_dispute` reaches the prompt without this worker importing
+ * anything of theirs — which it could not do anyway, since it is deployed from this package.
+ *
+ * **The default export is what makes this an ES module** (#426). It exports one Workflow class and has
+ * no cron, so until now it exported no default — and wrangler infers a worker's module format from
+ * exactly that, so the build read it as a service worker and refused `cloudflare:workers` outright.
+ * The host did not build, `pithy dev` carried on past it, and classification silently never ran. The
+ * refusal it exports is the honest body for a host with no request surface; see
+ * `@pithy-sh/core/src/workflow/hostEntry`.
+ */
+
+/** The support worker's env: the app database, the AI binding, and the serialized config. */
+export interface SupportWorkerEnv {
+  /** The app database the support tables live in. */
+  DB: D1Database;
+  /** The Workers AI binding. */
+  AI: SupportAi;
+  /** The resolved support config as a JSON string, filled at provision. */
+  SUPPORT_CONFIG?: string;
+}
+
+/** Classify one stored message and write the result. */
+export class SupportClassifyWorkflow extends WorkflowEntrypoint<SupportWorkerEnv, { messageId: string }> {
+  override async run(event: WorkflowEvent<{ messageId: string }>, step: WorkflowStep): Promise<void> {
+    const config = SupportConfig.parse(this.env.SUPPORT_CONFIG ? JSON.parse(this.env.SUPPORT_CONFIG) : {});
+    const deps = {
+      db: supportDatabase(this.env.DB),
+      ai: this.env.AI,
+      categories: resolveCategories(config.categories),
+      ai_config: config.ai,
+      archiveSpam: config.guard.archiveSpam,
+      newId: () => crypto.randomUUID(),
+      now: () => new Date(),
+    };
+
+    // One step. The unit of retry is the whole judgment, because a classification that half-ran —
+    // a history row with no thread update — would leave the inbox disagreeing with its own audit
+    // trail, and re-running the model is cheap enough that splitting it buys nothing.
+    // Under `supportWorkflowRetry`: a model that could not be reached re-drives, and everything else
+    // fails at once. `classifyMessage` already refuses to throw on a bad *answer*, so the only fault
+    // that reaches this classifier as retryable is the binding not answering. See `retryPolicy.ts`.
+    await classifiedSteps(step, supportWorkflowRetry, NonRetryableError).do(
+      `classify-${event.payload.messageId}`,
+      async () => {
+        await runClassification(deps, event.payload.messageId);
+      },
+    );
+  }
+}
+
+/**
+ * The module's default export, and therefore its format. See `hostEntry` for why a Workflow host needs
+ * one at all, and why this one refuses rather than being empty: nothing reaches this worker over HTTP —
+ * the app worker stores the message and starts an instance on the `SUPPORT_CLASSIFY` binding.
+ */
+export default workflowHostEntry(SUPPORT_CAPABILITY);

package/src/workflows/wrangler.jsonc

@@ -0,0 +1,46 @@
+{
+  // The prebuilt support classification worker. Like the media and email workers, this is a TEMPLATE,
+  // not a wrangler env-stanza file: staging and prod are separate workers. `pithy support
+  // provision` resolves it into one complete config per environment — filling the `<...>` placeholders
+  // — and deploys each with `wrangler deploy --config <resolved>`. The adopter authors none of it.
+  //
+  // It hosts the one classification Workflow. The app worker receives the mail, stores it, and starts
+  // an instance; this worker is what talks to the model. That split is the whole reason classification
+  // is durable: an inbound handler has a tight CPU budget and a model call does not fit in it.
+  // Resolved per project and env → <project>-staging-support / <project>-prod-support. Worker
+  // script names are account-scoped, so the project segment is what stops a second Pithy project's
+  // deploy overwriting this one's running worker instead of colliding with it.
+  "name": "pithy-support",
+  "main": "./worker.ts",
+  // The compatibility date every Worker in this repository runs on. Stated once in the repository
+  // root's `compatibility.ts` and copied here because JSONC cannot import it —
+  // `cli/src/ci/compatibilityDates.test.ts` fails on any Worker older than it.
+  "compatibility_date": "2026-06-01",
+  "compatibility_flags": ["nodejs_compat"],
+
+  // No public URL. The support routes live in the app worker; this one is reached only by Workflow
+  // dispatch.
+  "workers_dev": false,
+
+  // The app database the support tables live in. No secrets database: this worker reads a message and
+  // writes a classification, and neither needs a credential — the AI binding is the whole dependency.
+  "d1_databases": [{ "binding": "DB", "database_name": "pithy-app", "database_id": "<filled-at-provision>" }],
+
+  // The Workers AI binding — classification runs on the adopter's own inference, on their own bill,
+  // and their customers' support mail never leaves their account.
+  "ai": { "binding": "AI" },
+
+  // The classification Workflow this worker hosts. `class_name` matches the exported
+  // WorkflowEntrypoint subclass; `binding` is what the app worker dispatches to after storing a message.
+  "workflows": [
+    { "binding": "SUPPORT_CLASSIFY", "name": "pithy-support-classify", "class_name": "SupportClassifyWorkflow" }
+  ],
+
+  "vars": {
+    // The resolved SupportConfig as one JSON blob, filled at provision from the app's support() config.
+    // The worker parses and validates it; absent falls back to the defaults. It carries the effective
+    // taxonomy, so an adopter's own categories reach the prompt without this worker importing their code.
+    "SUPPORT_CONFIG": "<filled-at-provision>",
+    "ENVIRONMENT": "<filled-at-provision>"
+  }
+}