@pithy-sh/support 0.1.2 → 0.1.4

package/dist/provision/provisionSupport.d.ts

@@ -0,0 +1,160 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
+import { type ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+/**
+ * The provisioning orchestration for the support capability — the live counterpart to
+ * `pithy add support`'s config wiring.
+ *
+ * Three things have to exist before a support inbox works, and none of them can be a binding an
+ * adopter hand-writes: the R2 bucket attachments and raw messages land in, the prebuilt classification
+ * worker per environment, and — the one that actually delivers the mail — an Email Routing rule
+ * pointing the support address at the app worker.
+ *
+ * The live Cloudflare/wrangler steps sit behind the {@link SupportProvisioner} seam, so the
+ * orchestration (order, idempotency, per-env fan-out) is unit-tested without touching Cloudflare.
+ * Every step is idempotent; re-running is a no-op.
+ *
+ * ## The routing rule is opt-in, and that is a safety decision
+ *
+ * `ensureRoutingRule` returns `skipped: true` when no routing config is supplied, exactly as
+ * `@pithy-sh/email`'s does — because **enabling Email Routing on a zone points its MX at Cloudflare.**
+ * Creating a rule on the wrong zone would move an adopter's real inbound mail off their existing
+ * provider, which is not a mistake a provisioning command gets to make on their behalf. So the zone,
+ * the address, and the target worker are all explicit flags, and a project that has not decided yet
+ * provisions everything else and adds the rule later.
+ *
+ * The rule name is `<project>-global-support-inbound`, deliberately distinct from `@pithy-sh/email`'s
+ * `<project>-global-email-bounce`. Idempotency in `ensureWorkerRoute` keys on the rule *name*, so
+ * sharing one would make whichever capability provisioned second silently believe its rule already
+ * existed — and the project segment is what stops two Pithy projects on one zone doing the same to
+ * each other, with the loser's customer mail delivered to the winner's Worker.
+ */
+/**
+ * The name of the Email Routing rule this capability creates, for one project. Distinct from the
+ * bounce handler's, and `global` in the environment slot because there is one rule per zone: the
+ * environments are separated by which app Worker the rule is pointed at, not by the rule.
+ *
+ * **Still on the generic composer**, and deliberately: an Email Routing rule is not a namespace
+ * `@pithy-sh/core/src/naming/limits` carries a verified Cloudflare cap for, and the facade exists so a
+ * kind of thing brings its own number rather than borrowing one. It takes the conservative default
+ * until that namespace lands — the same call `@pithy-sh/email`'s bounce rule makes.
+ */
+export declare function supportRoutingRuleName(project: string): string;
+/**
+ * The deployed Worker name for a project's environment — also its resolved config basename. Composed
+ * through core's naming facade under the **`worker`** namespace, so it is measured against a Worker
+ * script's 63 and the environment is validated on the way through. One source, so the name the CLI
+ * audits and deletes under cannot drift from the name it deploys under.
+ */
+export declare function supportWorkerName(project: string, env: ManagedEnvironment): string;
+/** The live Cloudflare/wrangler seam. Each step must be idempotent. */
+export interface SupportProvisioner {
+    /**
+     * Verify account prerequisites before any resource is created — most importantly a registered
+     * `workers.dev` subdomain, which Cloudflare requires to deploy the Workflow-hosting worker.
+     */
+    preflight(): Promise<void>;
+    /**
+     * Create (or reuse) the R2 bucket attachments and raw messages live in. Idempotent.
+     *
+     * Returns `skipped: true` when the capability is configured with attachments off — a bucket nobody
+     * writes to is a resource an adopter did not ask for.
+     */
+    ensureBucket(): Promise<{
+        bucket: string;
+        created: boolean;
+        skipped: boolean;
+    }>;
+    /** Deploy the prebuilt classification worker for this environment. */
+    deployWorker(env: ManagedEnvironment): Promise<void>;
+    /**
+     * Create or drop the full-text index in this environment's app database, to match `search.fts`.
+     *
+     * A provisioning step rather than a migration, because the index is **derived** — every row in it
+     * comes from `pithy_support_messages` and `reindexThread` rebuilds it on demand. That is the line a
+     * migration is for: schema whose loss loses data. Keeping it here is also what makes the flag safe
+     * to toggle at all, since a config-conditional migration removed from the set is corruption to
+     * Kysely and blocks `pithy migrate` for every capability sharing the database.
+     */
+    ensureSearchIndex(env: ManagedEnvironment): Promise<{
+        created: boolean;
+        dropped: boolean;
+    }>;
+    /**
+     * Ensure the inbound Email Routing rule that delivers the support address to the app worker.
+     * Idempotent, keyed on the rule name. Returns `skipped: true` when no routing config was supplied.
+     */
+    ensureRoutingRule(): Promise<{
+        created: boolean;
+        skipped: boolean;
+    }>;
+}
+/** What provisioning produced. */
+export interface SupportProvisionResult {
+    /** The R2 bucket, and whether it had to be created. */
+    bucket: {
+        bucket: string;
+        created: boolean;
+        skipped: boolean;
+    };
+    /** The environments a classification worker was deployed for. */
+    environments: ManagedEnvironment[];
+    /** What the full-text index did, per environment — created, dropped, or already correct. */
+    search: Array<{
+        env: ManagedEnvironment;
+        created: boolean;
+        dropped: boolean;
+    }>;
+    /** Whether the inbound routing rule was created, already present, or skipped. */
+    routing: {
+        created: boolean;
+        skipped: boolean;
+    };
+}
+/**
+ * Provision the support infrastructure.
+ *
+ * The order matters and is the inverse of how it fails: the bucket exists before a worker that could
+ * write to it, and **the routing rule is last** — creating it first would start delivering mail to a
+ * Worker whose classification host is not deployed yet, which is a window where real customer
+ * messages arrive and stay `uncategorized` with nothing to say why.
+ *
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+ */
+export declare function provisionSupport(provisioner: SupportProvisioner, environments: DeclaredEnvironments | readonly string[]): Promise<SupportProvisionResult>;
+/** The teardown seam — the inverse of {@link SupportProvisioner}. Every step idempotent. */
+export interface SupportDeprovisioner {
+    /** Delete the env's classification worker. Idempotent. */
+    deleteWorker(env: ManagedEnvironment): Promise<void>;
+    /** Remove the inbound routing rule, so mail stops being delivered here. Idempotent. */
+    removeRoutingRule(): Promise<{
+        removed: boolean;
+    }>;
+    /**
+     * Delete the R2 bucket **and everything in it** — every attachment and every raw message an adopter's
+     * customers ever sent. Destructive, so the orchestration only calls it when explicitly asked.
+     */
+    deleteBucket(): Promise<void>;
+}
+/** Teardown options. By default the bucket is **kept**: it holds correspondence, not cache. */
+export interface SupportDeprovisionOptions {
+    /** Also delete the R2 bucket and its contents. Off by default. */
+    deleteStorage?: boolean;
+}
+/**
+ * Tear down the support infrastructure, reversing {@link provisionSupport}.
+ *
+ * The routing rule goes **first**, and that ordering is the whole point: stop new mail arriving before
+ * removing the workers that would have handled it, or messages land in a Worker with no classification
+ * host during the teardown. Stored correspondence is preserved unless explicitly requested — losing an
+ * adopter's support history to a teardown flag would be unrecoverable.
+ *
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+ */
+export declare function deprovisionSupport(deprovisioner: SupportDeprovisioner, environments: DeclaredEnvironments | readonly string[], options?: SupportDeprovisionOptions): Promise<void>;
+//# sourceMappingURL=provisionSupport.d.ts.map

package/dist/provision/provisionSupport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisionSupport.d.ts","sourceRoot":"","sources":["../../src/provision/provisionSupport.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAIlF,OAAO,EAAE,KAAK,kBAAkB,EAAuB,MAAM,6BAA6B,CAAC;AAG3F;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAElF;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B;;;;;OAKG;IACH,YAAY,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAChF,sEAAsE;IACtE,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD;;;;;;;;OAQG;IACH,iBAAiB,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC5F;;;OAGG;IACH,iBAAiB,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,kCAAkC;AAClC,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/D,iEAAiE;IACjE,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC,4FAA4F;IAC5F,MAAM,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,kBAAkB,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC/E,iFAAiF;IACjF,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CACjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,kBAAkB,EAC/B,YAAY,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,GACrD,OAAO,CAAC,sBAAsB,CAAC,CAYjC;AAED,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,uFAAuF;IACvF,iBAAiB,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACnD;;;OAGG;IACH,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,+FAA+F;AAC/F,MAAM,WAAW,yBAAyB;IACxC,kEAAkE;IAClE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,aAAa,EAAE,oBAAoB,EACnC,YAAY,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,EACtD,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/provision/provisionSupport.js

@@ -0,0 +1,112 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SUPPORT_CAPABILITY } from "../workflows/specs.js";
+import { GLOBAL_SCOPE } from "@pithy-sh/core/src/naming/environment";
+import { resourceName } from "@pithy-sh/core/src/naming/resource";
+import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
+import { managedEnvironments } from "@pithy-sh/secrets/src/scope";
+//#region src/provision/provisionSupport.ts
+/**
+* The provisioning orchestration for the support capability — the live counterpart to
+* `pithy add support`'s config wiring.
+*
+* Three things have to exist before a support inbox works, and none of them can be a binding an
+* adopter hand-writes: the R2 bucket attachments and raw messages land in, the prebuilt classification
+* worker per environment, and — the one that actually delivers the mail — an Email Routing rule
+* pointing the support address at the app worker.
+*
+* The live Cloudflare/wrangler steps sit behind the {@link SupportProvisioner} seam, so the
+* orchestration (order, idempotency, per-env fan-out) is unit-tested without touching Cloudflare.
+* Every step is idempotent; re-running is a no-op.
+*
+* ## The routing rule is opt-in, and that is a safety decision
+*
+* `ensureRoutingRule` returns `skipped: true` when no routing config is supplied, exactly as
+* `@pithy-sh/email`'s does — because **enabling Email Routing on a zone points its MX at Cloudflare.**
+* Creating a rule on the wrong zone would move an adopter's real inbound mail off their existing
+* provider, which is not a mistake a provisioning command gets to make on their behalf. So the zone,
+* the address, and the target worker are all explicit flags, and a project that has not decided yet
+* provisions everything else and adds the rule later.
+*
+* The rule name is `<project>-global-support-inbound`, deliberately distinct from `@pithy-sh/email`'s
+* `<project>-global-email-bounce`. Idempotency in `ensureWorkerRoute` keys on the rule *name*, so
+* sharing one would make whichever capability provisioned second silently believe its rule already
+* existed — and the project segment is what stops two Pithy projects on one zone doing the same to
+* each other, with the loser's customer mail delivered to the winner's Worker.
+*/
+/**
+* The name of the Email Routing rule this capability creates, for one project. Distinct from the
+* bounce handler's, and `global` in the environment slot because there is one rule per zone: the
+* environments are separated by which app Worker the rule is pointed at, not by the rule.
+*
+* **Still on the generic composer**, and deliberately: an Email Routing rule is not a namespace
+* `@pithy-sh/core/src/naming/limits` carries a verified Cloudflare cap for, and the facade exists so a
+* kind of thing brings its own number rather than borrowing one. It takes the conservative default
+* until that namespace lands — the same call `@pithy-sh/email`'s bounce rule makes.
+*/
+function supportRoutingRuleName(project) {
+	return resourceName({
+		project,
+		env: GLOBAL_SCOPE,
+		thing: `${SUPPORT_CAPABILITY}-inbound`
+	});
+}
+/**
+* The deployed Worker name for a project's environment — also its resolved config basename. Composed
+* through core's naming facade under the **`worker`** namespace, so it is measured against a Worker
+* script's 63 and the environment is validated on the way through. One source, so the name the CLI
+* audits and deletes under cannot drift from the name it deploys under.
+*/
+function supportWorkerName(project, env) {
+	return resourceNames(project).env(env).worker(SUPPORT_CAPABILITY);
+}
+/**
+* Provision the support infrastructure.
+*
+* The order matters and is the inverse of how it fails: the bucket exists before a worker that could
+* write to it, and **the routing rule is last** — creating it first would start delivering mail to a
+* Worker whose classification host is not deployed yet, which is a window where real customer
+* messages arrive and stay `uncategorized` with nothing to say why.
+*
+* `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+* environment is provisioned; an environment this skipped would be one the project deploys to with no
+* resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+*/
+async function provisionSupport(provisioner, environments) {
+	await provisioner.preflight();
+	const bucket = await provisioner.ensureBucket();
+	const search = [];
+	for (const env of managedEnvironments(environments)) {
+		await provisioner.deployWorker(env);
+		search.push({
+			env,
+			...await provisioner.ensureSearchIndex(env)
+		});
+	}
+	const routing = await provisioner.ensureRoutingRule();
+	return {
+		bucket,
+		environments: managedEnvironments(environments),
+		routing,
+		search
+	};
+}
+/**
+* Tear down the support infrastructure, reversing {@link provisionSupport}.
+*
+* The routing rule goes **first**, and that ordering is the whole point: stop new mail arriving before
+* removing the workers that would have handled it, or messages land in a Worker with no classification
+* host during the teardown. Stored correspondence is preserved unless explicitly requested — losing an
+* adopter's support history to a teardown flag would be unrecoverable.
+*
+* `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+* environment is provisioned; an environment this skipped would be one the project deploys to with no
+* resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+*/
+async function deprovisionSupport(deprovisioner, environments, options = {}) {
+	await deprovisioner.removeRoutingRule();
+	for (const env of managedEnvironments(environments)) await deprovisioner.deleteWorker(env);
+	if (options.deleteStorage) await deprovisioner.deleteBucket();
+}
+//#endregion
+export { deprovisionSupport, provisionSupport, supportRoutingRuleName, supportWorkerName };

package/dist/provision/resolveSupportConfig.d.ts

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { type WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
+import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+import type { SupportConfig } from "../config/config";
+/**
+ * Resolve the support worker's committed `wrangler.jsonc` template into one environment's standalone
+ * config. Every per-environment decision lives here; everything static — the compatibility date, the
+ * AI binding, the Workflow class name — stays as the template committed it.
+ *
+ * Thin over core's {@link resolveWorkflowHost}, which owns the mechanics (clone, fill by binding name,
+ * stamp `ENVIRONMENT`). This file owns only what is support's: which binding maps to which provisioned
+ * resource, the Workflow name derived from support's own specs, and the serialized config the worker
+ * parses.
+ *
+ * **`AI` is marked remote.** Workflows cannot use remote bindings in general, so a host always runs
+ * locally under `wrangler dev` — and Workers AI has no local emulation, so without this flag the
+ * classification step has nothing to call in development. Same treatment `@pithy-sh/vector` gives
+ * Vectorize, for the same reason.
+ *
+ * There is no secrets binding and no secrets database, and that absence is deliberate: this worker
+ * reads a message and writes a classification. The AI binding is its entire dependency, so it holds no
+ * credential at all — which is the smallest blast radius a deployed worker can have.
+ */
+/** The resolved resource ids + per-env values for one environment's support-worker deploy. */
+export interface SupportConfigParams {
+    /**
+     * The project name — the `<project>` segment the deployed worker and its classification Workflow
+     * lead with. The root `pithy.config.ts` `name`, resolved by `requireProjectName` and never guessed.
+     */
+    project: string;
+    /** The target environment. */
+    env: ManagedEnvironment;
+    /** The app database id for this environment — where the support tables live. */
+    appDatabaseId: string;
+    /**
+     * The app's resolved support config, serialized into the worker's `SUPPORT_CONFIG` var.
+     *
+     * This is how an adopter's federated categories reach the prompt. The worker is deployed from this
+     * package and cannot import their code, so the taxonomy has to travel as data — which it does,
+     * because it always was data.
+     */
+    supportConfig: SupportConfig;
+}
+/** Fill the template for one environment. */
+export declare function resolveSupportConfig(template: WorkflowHostTemplate, params: SupportConfigParams): WorkflowHostTemplate;
+//# sourceMappingURL=resolveSupportConfig.d.ts.map

package/dist/provision/resolveSupportConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveSupportConfig.d.ts","sourceRoot":"","sources":["../../src/provision/resolveSupportConfig.ts"],"names":[],"mappings":"AAGA,OAAO,EAAyC,KAAK,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACpH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8FAA8F;AAC9F,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,GAAG,EAAE,kBAAkB,CAAC;IACxB,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,6CAA6C;AAC7C,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,EAAE,mBAAmB,GAC1B,oBAAoB,CAatB"}

package/dist/provision/resolveSupportConfig.js

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SUPPORT_CAPABILITY, supportWorkflowRegistry } from "../workflows/specs.js";
+import { hostWorkflowsFor, resolveWorkflowHost } from "@pithy-sh/core/src/workflow/host";
+//#region src/provision/resolveSupportConfig.ts
+/** Fill the template for one environment. */
+function resolveSupportConfig(template, params) {
+	const { project, env } = params;
+	return resolveWorkflowHost(template, {
+		project,
+		capability: SUPPORT_CAPABILITY,
+		env,
+		databaseIds: { DB: params.appDatabaseId },
+		remoteBindings: ["AI"],
+		vars: { SUPPORT_CONFIG: JSON.stringify(params.supportConfig) },
+		workflows: hostWorkflowsFor(supportWorkflowRegistry, {
+			project,
+			capability: SUPPORT_CAPABILITY,
+			env
+		}).workflows
+	});
+}
+//#endregion
+export { resolveSupportConfig };

package/dist/reply/send.d.ts

@@ -0,0 +1,125 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { AuditEmit } from "@pithy-sh/core/src/audit/recorder";
+import type { Logger } from "@pithy-sh/core/src/logger/logger";
+import type { SupportConfig } from "../config/config";
+import { type SupportDatabase } from "../data/tables";
+/**
+ * Sending a reply — through `@pithy-sh/email`'s durable send path, never directly.
+ *
+ * ## Why the reply is composed here and not in the dashboard
+ *
+ * Three things have to be true of an answer, and a dashboard can guarantee none of them. It has to
+ * leave from the adopter's domain carrying the adopter's DKIM, so it is not filtered as a forgery.
+ * It has to be durable and retryable, which is what the email capability's job row and Workflow buy.
+ * And it has to set `In-Reply-To` and `References` correctly — which only the Worker can do, because
+ * only the Worker holds the thread's chain. Implemented dashboard-side, threading breaks in the
+ * customer's mail client and every conversation fragments into one message per answer.
+ *
+ * So the dashboard POSTs a body. That is the entire contract, and it is why the reply route is small.
+ *
+ * ## The sent Message-ID is not ours to know
+ *
+ * Cloudflare assigns the real `Message-ID` at send time and does not tell the enqueuer, so the
+ * outbound row stores `emailJobId` and leaves `mimeMessageId` null. Threading back still works, and
+ * this is the part worth being clear about: when the customer replies, their `References` carries the
+ * whole ancestry — including the *inbound* ids this capability stored itself — so `parentCandidates`
+ * finds the thread through one of those even though it has never seen the id of its own reply.
+ *
+ * ## Storing the answer and sending it are two steps, and one of them is optional
+ *
+ * Everything above describes mail. An `app` thread has a second destination that already exists:
+ * `readOwnThread` hands the submitter every message on their own conversation, outbound ones
+ * included, so an answer stored and never sent is an answer they will read next time they open it.
+ *
+ * That is the whole shape of in-app delivery — the outbound row, the thread counters and the audit
+ * event are written exactly as they are for mail, and only the `enqueue` is skipped. It is taken in
+ * two situations, and they are different in kind:
+ *
+ * - **The adopter chose it.** `reply.deliverInApp` on a project whose mail works perfectly well.
+ *   Email Routing takes over a zone's MX, so a project already running mail on that domain cannot
+ *   receive support replies without disturbing everything else on it — and a fallback conditioned on
+ *   mail being *impossible* is unreachable by exactly the adopter who most wants this.
+ * - **There is nothing to send with.** No address a reply could come back to, or no email capability
+ *   composed at all. Storing the answer beats refusing it, because the person can still read it.
+ *
+ * An `email` thread never takes it. Its sender has no read-back — there is no session, only an
+ * address — so an answer stored there is one nobody would ever see, and a missing reply address on a
+ * mail thread stays the misconfiguration it always was.
+ *
+ * **The two are never rendered the same.** "Sent by email" and "waiting in the app" are different
+ * promises about when somebody will read the answer, and `ReplyResult` is a union rather than an
+ * object with an optional `jobId` so that a console has to say which one it is showing.
+ */
+/** What a reply needs, all injectable. */
+export interface ReplyDeps {
+    /** The support tables. */
+    db: SupportDatabase;
+    /** The resolved config. */
+    config: SupportConfig;
+    /**
+     * The email capability's `enqueue`, already bound to the request env. Support never assembles the
+     * send infrastructure — it hands over a recipient, a template id, and a payload.
+     *
+     * **Optional, because a project can compose support without composing email.** Absent, an `app`
+     * thread is answered in the app rather than refused, and only a mail thread has nothing left to
+     * try. The refusal is raised here rather than by the caller so that the one place that knows
+     * whether mail is needed is the one that asks for it.
+     */
+    enqueue?: (input: {
+        to: string;
+        template: string;
+        payload: unknown;
+        replyTo?: string;
+        /** The language to write the shell in — the reporter's, taken off their submission context. */
+        locale?: string;
+        inReplyTo?: string;
+        references?: string;
+    }) => Promise<{
+        jobId: string;
+    }>;
+    /** Whether the full-text index is in use. */
+    fts: boolean;
+    /** The audit seam. */
+    emit: AuditEmit;
+    /** The request logger. */
+    log: Logger;
+    /** Generate a row id. */
+    newId: () => string;
+    /** Now. */
+    now: () => Date;
+}
+/** What the operator is sending. */
+export interface ReplyInput {
+    /** The thread being answered. */
+    threadId: string;
+    /** The reply text, as a human wrote and edited it. */
+    body: string;
+    /** Who is answering, signed at the bottom. Optional. */
+    agentName?: string;
+    /** The verified control-plane subject sending it — the audit actor. */
+    viewer: string;
+}
+/**
+ * What the reply produced, discriminated on the channel it was delivered over.
+ *
+ * A union rather than one object with an optional `jobId`, because the two outcomes are different
+ * promises about when the customer reads the answer — and an optional field is exactly what lets a
+ * console render "sent" over both of them.
+ */
+export type ReplyResult = {
+    /** Handed to the email capability's durable send path. */
+    channel: "email";
+    /** The outbound `pithy_support_messages.id`. */
+    messageId: string;
+    /** The `pithy_email_jobs.id` the send was enqueued as. */
+    jobId: string;
+} | {
+    /** Stored for the submitter to read in the app. No mail was sent, and there is no job. */
+    channel: "app";
+    /** The outbound `pithy_support_messages.id`. */
+    messageId: string;
+};
+/** Send a reply on a thread. */
+export declare function sendReply(deps: ReplyDeps, input: ReplyInput): Promise<ReplyResult>;
+//# sourceMappingURL=send.d.ts.map

package/dist/reply/send.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../src/reply/send.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAiD,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAKrG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,0CAA0C;AAC1C,MAAM,WAAW,SAAS;IACxB,0BAA0B;IAC1B,EAAE,EAAE,eAAe,CAAC;IACpB,2BAA2B;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE;QAChB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,+FAA+F;QAC/F,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KAAK,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjC,6CAA6C;IAC7C,GAAG,EAAE,OAAO,CAAC;IACb,sBAAsB;IACtB,IAAI,EAAE,SAAS,CAAC;IAChB,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB,WAAW;IACX,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAED,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GACnB;IACE,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE,0FAA0F;IAC1F,OAAO,EAAE,KAAK,CAAC;IACf,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEN,gCAAgC;AAChC,wBAAsB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CA2LxF"}

package/dist/reply/send.js

@@ -0,0 +1,155 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SupportNotFoundError, SupportReplyFailedError } from "../error/errors.js";
+import { SupportMessage } from "../data/message.js";
+import { SUPPORT_MESSAGES_TABLE, SUPPORT_THREADS_TABLE } from "../data/tables.js";
+import { SupportAuditActions } from "../audit/actions.js";
+import { buildReferencesHeader, replySubject } from "../mime/threading.js";
+import { indexMessage } from "../store/search.js";
+//#region src/reply/send.ts
+/** Send a reply on a thread. */
+async function sendReply(deps, input) {
+	if (!deps.config.reply.enabled) throw new SupportReplyFailedError({
+		message: "Replying is disabled on this deployment.",
+		action: "Set `reply.enabled` on the support capability in pithy.config.ts, then redeploy.",
+		detail: "support config has reply.enabled = false"
+	});
+	const thread = await deps.db.selectFrom(SUPPORT_THREADS_TABLE).select([
+		"id",
+		"channel",
+		"subject",
+		"fromAddress",
+		"fromName",
+		"inboxAddress",
+		"messageCount"
+	]).where("id", "=", input.threadId).executeTakeFirst();
+	if (!thread) throw new SupportNotFoundError({ detail: `no support thread ${input.threadId}` });
+	const parent = await deps.db.selectFrom(SUPPORT_MESSAGES_TABLE).select([
+		"mimeMessageId",
+		"mimeReferences",
+		"context"
+	]).where("threadId", "=", input.threadId).where("direction", "=", "inbound").orderBy("receivedAt", "desc").orderBy("id", "desc").limit(1).executeTakeFirst();
+	/**
+	* The language to answer in: the one the reporter's app was rendering in when they wrote.
+	*
+	* **The customer's, never the agent's.** A reply is composed inside an operator's request, and that
+	* request's negotiated locale is the operator's — so reading `c.var.t` here would answer a Spanish
+	* customer in whatever language the support console happens to be open in. The submission context is
+	* the only thing on this thread that says something about the *reader*, and it is already collected
+	* because a locale-shaped bug is only reproducible in the reporter's locale.
+	*
+	* It moves the shell and not the letter. `supportReply`'s words are the adopter's — a human wrote
+	* them, and a catalog cannot translate a sentence it has never seen — so what follows this tag is the
+	* document's `lang` and `dir` and the footer. That is the honest half, and it is the half that decides
+	* whether an Arabic reply lays out right-to-left.
+	*
+	* Absent on every mail-path message, which is most of them, and absent renders as it always has.
+	*/
+	const parentContext = SupportMessage.shape.context.safeParse(parent?.context);
+	const replyLocale = parentContext.success ? parentContext.data?.locale ?? void 0 : void 0;
+	const parentReferences = SupportMessage.shape.mimeReferences.safeParse(parent?.mimeReferences);
+	const chain = parentReferences.success && Array.isArray(parentReferences.data) ? parentReferences.data : [];
+	const references = buildReferencesHeader(chain, parent?.mimeMessageId ?? void 0);
+	const subject = replySubject(thread.subject);
+	const now = deps.now();
+	const replyTo = deps.config.reply.replyToAddress ?? thread.inboxAddress;
+	const enqueue = deps.enqueue;
+	const deliverable = enqueue !== void 0 && replyTo !== null && replyTo !== void 0;
+	const inApp = thread.channel === "app" && (deps.config.reply.deliverInApp || !deliverable);
+	let jobId = null;
+	if (!inApp) {
+		if (!enqueue) throw new SupportReplyFailedError({
+			message: "This deployment cannot send mail.",
+			action: "Add the email capability (`pithy add email`) and provision it, then retry.",
+			detail: `thread ${input.threadId} needs a mailed reply and no email capability is composed`
+		});
+		if (!replyTo) throw new SupportReplyFailedError({
+			message: "This deployment has no address a reply can come back to.",
+			action: "Set `inboundAddresses` or `reply.replyToAddress` on the support capability, then retry.",
+			detail: `thread ${input.threadId} has no inboxAddress and no reply.replyToAddress is configured`
+		});
+		try {
+			jobId = (await enqueue({
+				to: thread.fromAddress,
+				template: "supportReply",
+				payload: {
+					subject,
+					body: input.body,
+					...input.agentName ? { agentName: input.agentName } : {}
+				},
+				replyTo,
+				locale: replyLocale,
+				inReplyTo: parent?.mimeMessageId ? `<${parent.mimeMessageId}>` : void 0,
+				references: references.length > 0 ? references : void 0
+			})).jobId;
+		} catch (cause) {
+			throw new SupportReplyFailedError({ detail: `enqueue failed for thread ${input.threadId}` }, { cause });
+		}
+	}
+	const messageId = deps.newId();
+	const message = {
+		id: messageId,
+		threadId: input.threadId,
+		direction: "outbound",
+		channel: inApp ? "app" : "email",
+		submittedByUserId: null,
+		context: null,
+		mimeMessageId: null,
+		mimeInReplyTo: parent?.mimeMessageId ?? null,
+		mimeReferences: chain.length > 0 ? chain : null,
+		fromAddress: inApp ? null : replyTo,
+		fromName: null,
+		toAddress: inApp ? null : thread.fromAddress,
+		subject,
+		textBody: input.body,
+		htmlBody: null,
+		emailJobId: jobId,
+		rawKey: null,
+		rawBytes: null,
+		receivedAt: now,
+		createdAt: now
+	};
+	await deps.db.insertInto(SUPPORT_MESSAGES_TABLE).values(SupportMessage.encode(message)).execute();
+	if (deps.fts) try {
+		await indexMessage(deps.db, {
+			threadId: input.threadId,
+			messageId,
+			subject,
+			body: input.body
+		});
+	} catch (error) {
+		deps.log.warn("support reply not indexed", {
+			messageId,
+			error
+		});
+	}
+	await deps.db.updateTable(SUPPORT_THREADS_TABLE).set((eb) => ({
+		messageCount: eb("messageCount", "+", 1),
+		lastMessageAt: now.getTime(),
+		updatedAt: now.getTime()
+	})).where("id", "=", input.threadId).execute();
+	await deps.emit({
+		action: SupportAuditActions.replySent,
+		outcome: "success",
+		actorType: "control-plane",
+		actorId: input.viewer,
+		resourceType: "support_thread",
+		resourceId: input.threadId,
+		metadata: {
+			channel: message.channel,
+			messageId,
+			threaded: Boolean(parent?.mimeMessageId),
+			...jobId === null ? {} : { jobId }
+		}
+	});
+	return jobId === null ? {
+		channel: "app",
+		messageId
+	} : {
+		channel: "email",
+		messageId,
+		jobId
+	};
+}
+//#endregion
+export { sendReply };