@hyperfixation/workflows 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Graham Lutz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/actions.d.ts

@@ -0,0 +1,60 @@
+import type { StepContext } from "./step.js";
+/** What a channel is handed. `idempotencyKey` is stable across attempts, so a provider that
+ * supports one dedupes a re-send rather than sending twice. */
+export interface ActionDispatch<Req = unknown> {
+    idempotencyKey: string;
+    runId: string;
+    key: string;
+    request: Req;
+}
+export interface ActionResult {
+    externalId?: string;
+    response?: unknown;
+}
+/** `Req` is what this channel is sent; left off, a channel takes `unknown` as it always has. */
+export interface ActionChannel<Req = unknown> {
+    readonly name: string;
+    /** Whether a re-send with the same `idempotencyKey` is delivered at most once by the provider. */
+    readonly dedupes: boolean;
+    send(dispatch: ActionDispatch<Req>): Promise<ActionResult>;
+}
+export interface ActionsPerformOptions<Req = unknown> {
+    /** Unique within the run and stable across attempts, exactly as `llm.run`'s is. */
+    key: string;
+    channel: ActionChannel<Req>;
+    request?: Req;
+    recordType?: string;
+    recordId?: string;
+}
+/**
+ * A row left in flight by an attempt that is gone, on a channel that cannot dedupe: nothing was
+ * re-sent and an `hf_task` asks a human whether the first send went out. Terminal by design — it
+ * reaches the flow wrapper's catch and the run ends `failed`, because no code can decide this.
+ *
+ * `taskId` is null only for a row that went `uncertain` before this package opened tasks for it.
+ */
+export declare class ActionUncertain extends Error {
+    readonly runId: string;
+    readonly key: string;
+    readonly actionLogId: number;
+    readonly taskId: number | null;
+    constructor(runId: string, key: string, actionLogId: number, taskId: number | null);
+}
+export declare function idempotencyKey(runId: string, key: string): string;
+/**
+ * One outbound side effect, ledgered on `hf_action_log` with the same `started`-row pattern as
+ * `llm.run` and the same two-transaction shape — the lock order here is `hf_run` (via `ctx.tx`)
+ * → `hf_action_log` → `hf_task`/`hf_activity`, which sit in the last tier.
+ *
+ * Re-entry of a row this attempt did not insert is where the channel's `dedupes` declaration is
+ * spent. A channel the provider dedupes for is simply re-taken and re-sent. One that does not is
+ * never re-sent: the row goes `uncertain`, a task asks a human whether the first send went out,
+ * and `ActionUncertain` ends the run. A first dispatch always sends, so a non-deduping channel
+ * gets at most one send per row ever.
+ */
+export declare function perform<Req>(ctx: StepContext, options: ActionsPerformOptions<Req>): Promise<ActionResult>;
+export declare const actions: {
+    perform: typeof perform;
+};
+/** The only channel chunk 10 ships: it dispatches nothing and succeeds. */
+export declare function stubChannel(name?: string): ActionChannel;

package/dist/actions.js

@@ -0,0 +1,175 @@
+import { sql } from "drizzle-orm";
+/**
+ * A row left in flight by an attempt that is gone, on a channel that cannot dedupe: nothing was
+ * re-sent and an `hf_task` asks a human whether the first send went out. Terminal by design — it
+ * reaches the flow wrapper's catch and the run ends `failed`, because no code can decide this.
+ *
+ * `taskId` is null only for a row that went `uncertain` before this package opened tasks for it.
+ */
+export class ActionUncertain extends Error {
+    runId;
+    key;
+    actionLogId;
+    taskId;
+    constructor(runId, key, actionLogId, taskId) {
+        super(`ActionUncertain: action ${key} on run ${runId} (hf_action_log ${actionLogId}) was left ` +
+            "in flight by an attempt that is gone and its channel cannot dedupe; nothing was " +
+            `re-sent and hf_task ${taskId ?? "(none)"} asks a human to confirm`);
+        this.name = "ActionUncertain";
+        this.runId = runId;
+        this.key = key;
+        this.actionLogId = actionLogId;
+        this.taskId = taskId;
+    }
+}
+export function idempotencyKey(runId, key) {
+    return `${runId}:${key}`;
+}
+function titleOf(ctx, options) {
+    return `Confirm ${options.channel.name} send ${options.key} for run ${ctx.runId}`;
+}
+/**
+ * The task for one uncertain action row. `DO NOTHING` on the partial unique index rather than an
+ * upsert: whoever asked first owns the wording, and the id is looked up so the error can name it.
+ *
+ * The target columns follow the action row's, NULL included — a stand-in record type would fail
+ * E002 at the next boot, and `origin_ref` is what points the task back at the row.
+ */
+async function openTask(db, row, title) {
+    const inserted = await db.execute(sql `
+    INSERT INTO hf_task (record_type, record_id, title, origin, origin_ref)
+    VALUES (${row.record_type}, ${row.record_id}, ${title}, 'flow', ${row.id})
+    ON CONFLICT (origin, origin_ref) WHERE origin_ref IS NOT NULL DO NOTHING
+    RETURNING id
+  `);
+    if (inserted.rows[0] !== undefined)
+        return Number(inserted.rows[0].id);
+    return existingTaskId(db, row.id);
+}
+/** Either writer may own it, so the lookup is not predicated on `origin`. */
+async function existingTaskId(db, actionLogId) {
+    const found = await db.execute(sql `
+    SELECT id FROM hf_task WHERE origin_ref = ${actionLogId} AND origin IN ('flow', 'sweep')
+    ORDER BY id LIMIT 1
+  `);
+    const row = found.rows[0];
+    return row === undefined ? null : Number(row.id);
+}
+/** A row somebody else already moved to `uncertain`: report it, write nothing. */
+async function uncertainOf(db, ctx, options, row) {
+    const taskId = await existingTaskId(db, row.id);
+    return new ActionUncertain(ctx.runId, options.key, Number(row.id), taskId);
+}
+/**
+ * One outbound side effect, ledgered on `hf_action_log` with the same `started`-row pattern as
+ * `llm.run` and the same two-transaction shape — the lock order here is `hf_run` (via `ctx.tx`)
+ * → `hf_action_log` → `hf_task`/`hf_activity`, which sit in the last tier.
+ *
+ * Re-entry of a row this attempt did not insert is where the channel's `dedupes` declaration is
+ * spent. A channel the provider dedupes for is simply re-taken and re-sent. One that does not is
+ * never re-sent: the row goes `uncertain`, a task asks a human whether the first send went out,
+ * and `ActionUncertain` ends the run. A first dispatch always sends, so a non-deduping channel
+ * gets at most one send per row ever.
+ */
+export async function perform(ctx, options) {
+    const taken = await ctx.tx(async (db) => {
+        const insert = await db.execute(sql `
+      INSERT INTO hf_action_log
+        (run_id, key, workflow_id, channel, idempotency_key, status, request, record_type, record_id)
+      VALUES (${ctx.runId}, ${options.key}, ${ctx.workflowId}, ${options.channel.name},
+              ${idempotencyKey(ctx.runId, options.key)}, 'started',
+              ${JSON.stringify(options.request) ?? null}::jsonb,
+              ${options.recordType ?? null}, ${options.recordId ?? null})
+      ON CONFLICT (run_id, key) DO NOTHING
+    `);
+        const read = await db.execute(sql `
+      SELECT id::text AS id, status, external_id, response, record_type, record_id
+      FROM hf_action_log WHERE run_id = ${ctx.runId} AND key = ${options.key}
+    `);
+        const row = read.rows[0];
+        if (row.status === "ok") {
+            return { result: { externalId: row.external_id ?? undefined, response: row.response } };
+        }
+        // Already asked about, whatever the channel says: a second send behind the human's back is
+        // the one thing the task exists to prevent.
+        if (row.status === "uncertain")
+            return { uncertain: await uncertainOf(db, ctx, options, row) };
+        if (insert.rowCount !== 1) {
+            if (options.channel.dedupes) {
+                await db.execute(sql `
+          UPDATE hf_action_log
+          SET status = 'started', workflow_id = ${ctx.workflowId}, finished_at = NULL
+          WHERE run_id = ${ctx.runId} AND key = ${options.key}
+        `);
+                return undefined;
+            }
+            // `failed` joins `started` here: a channel that threw after delivering leaves exactly that,
+            // so it is as unknown as a row nobody finished.
+            const moved = await db.execute(sql `
+        UPDATE hf_action_log SET status = 'uncertain', finished_at = now()
+        WHERE run_id = ${ctx.runId} AND key = ${options.key}
+          AND status IN ('started', 'failed')
+      `);
+            // The transition is the serialization point: a pass that moved the row first owns the task.
+            if (moved.rowCount !== 1)
+                return { uncertain: await uncertainOf(db, ctx, options, row) };
+            const taskId = await openTask(db, row, titleOf(ctx, options));
+            await db.execute(sql `
+        INSERT INTO hf_activity (record_type, record_id, kind, run_id, meta)
+        VALUES (${row.record_type}, ${row.record_id}, 'action.uncertain', ${ctx.runId},
+                ${JSON.stringify({
+                actionLogId: Number(row.id),
+                key: options.key,
+                channel: options.channel.name,
+                taskId,
+            })}::jsonb)
+      `);
+            return { uncertain: new ActionUncertain(ctx.runId, options.key, Number(row.id), taskId) };
+        }
+        return undefined;
+    });
+    // Outside the transaction: `ctx.tx` rolls back on anything thrown inside `work`, and the
+    // `uncertain` row and its task are the whole point of this branch.
+    if (taken?.uncertain !== undefined)
+        throw taken.uncertain;
+    if (taken?.result !== undefined)
+        return taken.result;
+    let result;
+    try {
+        result = await options.channel.send({
+            idempotencyKey: idempotencyKey(ctx.runId, options.key),
+            runId: ctx.runId,
+            key: options.key,
+            // `request` stays optional here, as it always was; a channel that declares a `Req` is
+            // saying it will not be performed without one.
+            request: options.request,
+        });
+    }
+    catch (error) {
+        await ctx.tx(async (db) => {
+            await db.execute(sql `
+        UPDATE hf_action_log SET status = 'failed', finished_at = now()
+        WHERE run_id = ${ctx.runId} AND key = ${options.key}
+      `);
+        });
+        throw error;
+    }
+    await ctx.tx(async (db) => {
+        await db.execute(sql `
+      UPDATE hf_action_log
+      SET status = 'ok', external_id = ${result.externalId ?? null},
+          response = ${JSON.stringify(result.response) ?? null}::jsonb, finished_at = now()
+      WHERE run_id = ${ctx.runId} AND key = ${options.key}
+    `);
+    });
+    return result;
+}
+export const actions = { perform };
+/** The only channel chunk 10 ships: it dispatches nothing and succeeds. */
+export function stubChannel(name = "stub") {
+    return {
+        name,
+        dedupes: true,
+        send: (dispatch) => Promise.resolve({ externalId: dispatch.idempotencyKey, response: { stub: true } }),
+    };
+}

package/dist/approval-notifier.d.ts

@@ -0,0 +1,31 @@
+import type { ApprovalNotice, ApprovalNotifier } from "./approvals.js";
+import type { StepContext } from "./step.js";
+/** Text only: a notification is a line and a link, and an HTML body is a second thing to escape. */
+export interface ApprovalMessage {
+    to: string[];
+    subject: string;
+    text: string;
+    /** Also in `text`; separate so a channel that renders its own button has it. */
+    url: string;
+}
+export interface ApprovalNotifierOptions {
+    /** The workspace's base URL; a trailing slash is trimmed rather than doubled into the path. */
+    appUrl: string;
+    /**
+     * Who to tell. Called with the step's context, so the read belongs to the step's own fenced
+     * transaction — `ctx.tx` — and not to a pool of the notifier's own.
+     */
+    recipients(notice: ApprovalNotice, ctx: StepContext): Promise<string[]>;
+    send(message: ApprovalMessage): Promise<void>;
+}
+/** `<marker> <json>`: an approval nobody could be told about, which is a wiring problem. */
+export declare const NO_RECIPIENTS_MARKER = "hf-approval-notifier: no recipients";
+/**
+ * The notifier a worker hands `startWorker({ approvalNotifier })`: it resolves the recipients,
+ * builds the one message and sends it.
+ *
+ * Zero recipients is warned about and sent to nobody. It is deliberately not a throw: the step
+ * stamps `notified_at` once this returns, and failing here would leave the gate re-notifying
+ * every attempt over a list that is not going to fill itself.
+ */
+export declare function createApprovalNotifier(options: ApprovalNotifierOptions): ApprovalNotifier;

package/dist/approval-notifier.js

@@ -0,0 +1,51 @@
+/**
+ * Where the workspace serves one approval. Inline until `@hyperfixation/core/workspace` owns
+ * the route; this notifier is then to take the path from its `approvalPath()`.
+ */
+function approvalPath(approvalId) {
+    return `/w/approvals/${approvalId}`;
+}
+/** `<marker> <json>`: an approval nobody could be told about, which is a wiring problem. */
+export const NO_RECIPIENTS_MARKER = "hf-approval-notifier: no recipients";
+/**
+ * The notifier a worker hands `startWorker({ approvalNotifier })`: it resolves the recipients,
+ * builds the one message and sends it.
+ *
+ * Zero recipients is warned about and sent to nobody. It is deliberately not a throw: the step
+ * stamps `notified_at` once this returns, and failing here would leave the gate re-notifying
+ * every attempt over a list that is not going to fill itself.
+ */
+export function createApprovalNotifier(options) {
+    const base = options.appUrl.replace(/\/+$/, "");
+    return async (notice, ctx) => {
+        const url = `${base}${approvalPath(notice.approvalId)}`;
+        // Before the send, so a bump that arrives while the gate is being re-entered is refused by
+        // `ctx.tx`'s fence with nothing delivered.
+        const to = await options.recipients(notice, ctx);
+        if (to.length === 0) {
+            console.warn(`${NO_RECIPIENTS_MARKER} ${JSON.stringify({
+                approvalId: notice.approvalId,
+                runId: notice.runId,
+                key: notice.key,
+                assigneeId: notice.assigneeId,
+            })}`);
+            return;
+        }
+        await options.send({
+            to,
+            subject: `Approval needed: ${notice.type}`,
+            text: body(notice, url),
+            url,
+        });
+    };
+}
+function body(notice, url) {
+    const lines = [`${notice.type} is waiting for a decision.`];
+    if (notice.recordType !== null && notice.recordId !== null) {
+        lines.push(`Record: ${notice.recordType} ${notice.recordId}`);
+    }
+    if (notice.expiresAt !== null)
+        lines.push(`Expires: ${notice.expiresAt.toISOString()}`);
+    lines.push("", `Decide: ${url}`, "");
+    return lines.join("\n");
+}

package/dist/approvals.d.ts

@@ -0,0 +1,137 @@
+import type { DBOSClient } from "@dbos-inc/dbos-sdk";
+import { type ApprovalStatus, type ApprovalVia } from "@hyperfixation/db";
+import type { Pool } from "pg";
+import { type ZodType } from "zod";
+import { type StepContext } from "./step.js";
+/** Named in `ControlPlaneInWorkflow` and `CommitLost`. */
+export declare const DECIDE_OPERATION = "approvals.decide";
+/** The statuses `decide()` may write; `pending` is the only one it accepts as input. */
+export declare const APPROVAL_DECISIONS: readonly ["approved", "rejected", "expired", "cancelled"];
+export type ApprovalDecisionKind = (typeof APPROVAL_DECISIONS)[number];
+export interface ApprovalNotice {
+    approvalId: number;
+    runId: string;
+    key: string;
+    type: string;
+    draft: unknown;
+    /** The four below are read back from the row, so `expires_at` is the one the database computed. */
+    assigneeId: string | null;
+    recordType: string | null;
+    recordId: string | null;
+    expiresAt: Date | null;
+}
+/**
+ * The step context is the notifier's only database handle: a recipient read goes through
+ * `ctx.tx`, so it is fenced by the same `FOR SHARE` on `hf_run` as the rest of the step.
+ */
+export type ApprovalNotifier = (notice: ApprovalNotice, ctx: StepContext) => Promise<void>;
+export interface WaitForApprovalOptions {
+    /** Unique within the run and stable across attempts, exactly as a ledger key is. */
+    key: string;
+    /** What is being approved; Phase 2 resolves it to a Zod schema for the edited draft. */
+    type: string;
+    draft?: unknown;
+    assigneeId?: string;
+    recordType?: string;
+    recordId?: string;
+    /** From the row's creation; `reconcile()` step (5) expires the row once it is past. */
+    expiresInMs?: number;
+    /** Overrides the worker's `approvalNotifier`, which is what the gate falls back to. */
+    notify?: ApprovalNotifier;
+}
+export interface ApprovalDecision {
+    approvalId: number;
+    key: string;
+    status: Exclude<ApprovalStatus, "pending">;
+    /** The edited draft when a decider replaced it, otherwise the one the flow proposed. */
+    draft: unknown;
+    decidedBy: string | null;
+    decidedVia: ApprovalVia | null;
+}
+/**
+ * The gate a flow opts into. Not a `step()` itself but a pair of them plus a `Suspend`: the
+ * throw has to leave from the flow body, because a step that throws has its error checkpointed
+ * through `serialize-error` and a replay would revive a plain `Error` that `defineFlow`'s
+ * `instanceof Suspend` no longer catches.
+ *
+ * A decided row returns its decision and the flow carries on — that is how the attempt
+ * `decide()` enqueued passes through the gate it stopped at. Everything before this call runs
+ * again on that attempt and must be idempotent.
+ */
+export declare function waitForApproval(options: WaitForApprovalOptions): Promise<ApprovalDecision>;
+/** What an approval type's `schema` has to be: anything zod can `safeParse` an edit with. */
+export type ApprovalDraftSchema = ZodType;
+export interface DecideOptions {
+    ids: number[];
+    decision: ApprovalDecisionKind;
+    via: ApprovalVia;
+    /** The replay token: a second call carrying one already on a row writes nothing. */
+    decisionKey: string;
+    userId?: string | null;
+    /** Per-approval replacement drafts, each parsed against its type's schema before any write. */
+    edits?: Record<number, unknown>;
+    /**
+     * True when the decider holds the admin role, which lets them decide a row assigned to
+     * someone else. The caller's session decides that; `decide()` has no idea who is an admin.
+     */
+    admin?: boolean;
+    /**
+     * An approval `type` to the schema its edited draft must parse against. Sync and pure — it
+     * runs inside the locked transaction. Required whenever `edits` is non-empty; the schemas
+     * live in `core`'s registry, which `workflows` cannot import.
+     */
+    schemaFor?: (type: string) => ApprovalDraftSchema | undefined;
+    lockTimeout?: string;
+}
+export interface DecidedApproval {
+    approvalId: number;
+    runId: string;
+    key: string;
+    status: ApprovalDecisionKind;
+    /** The attempt this decision enqueued to carry the run on. */
+    resumeWorkflowId: string;
+}
+export interface DecideResult {
+    /** True when the batch was already decided under this `decisionKey`; nothing was written. */
+    replayed: boolean;
+    decided: DecidedApproval[];
+    reattempted: {
+        runId: string;
+        attempt: number;
+        workflowId: string;
+    }[];
+    /** Stamped on every row of a batch of more than one; null for a batch of one. */
+    batchId: string | null;
+}
+export declare class ApprovalBatchRefused extends Error {
+    readonly reasons: {
+        approvalId: number;
+        reason: string;
+    }[];
+    constructor(reasons: {
+        approvalId: number;
+        reason: string;
+    }[]);
+}
+export declare class ApprovalRunMoved extends Error {
+    constructor(approvalId: number);
+}
+export declare class ApprovalWriteLost extends Error {
+    constructor(approvalId: number, rowCount: number);
+}
+/**
+ * The one way an approval is decided, whoever decides it: the inbox, the admin, a Telegram
+ * callback, `records.archive()` and `reconcile()`'s expiry sweep all come through here.
+ *
+ * A control-plane operation, and one transaction: the decision, the attempt bump and the
+ * enqueue of the resume workflow commit together or not at all, so a crash anywhere before the
+ * tag-asserted `COMMIT` leaves the approval `pending` and the run untouched, and a retry with
+ * the same `decisionKey` starts over. **Nothing in here catches** — a swallowed error would
+ * leave the transaction aborted and Postgres would answer `COMMIT` with a `ROLLBACK` tag
+ * (round-3 finding 5).
+ */
+export declare function decide(pool: Pool, dbosClient: DBOSClient, options: DecideOptions): Promise<DecideResult>;
+export declare const approvals: {
+    decide: typeof decide;
+    waitForApproval: typeof waitForApproval;
+};