@intx/hub-sessions 0.1.2 → 0.2.2

package/dist/workflow-run-event-log.js

@@ -0,0 +1,51 @@
+// The sealed-form event log for a terminated run. Compaction folds a run's
+// per-event `runs/<runId>/events/<seq>.json` blobs into a single combined
+// file, `runs/<runId>/events.jsonl`, once the run reaches a terminal event.
+// Each line of the combined file is the verbatim text of the per-event blob
+// it replaced, in seq order, so the fold is a byte-for-byte transition that
+// the workflow-run kind handler can validate against the prior per-event
+// tree. Readers handle both shapes: per-event files for in-flight runs, the
+// combined file for sealed (terminal) runs.
+/** Filename of a run's combined event log, a sibling of its `events/` dir. */
+export const WORKFLOW_RUN_EVENTS_FILE = "events.jsonl";
+/**
+ * Split a combined event-log file's content into the per-event JSON texts it
+ * holds, in file order. Each non-empty line is the verbatim text of what was
+ * an `events/<seq>.json` blob; the trailing newline yields no extra entry.
+ * Event JSON never contains a literal newline (JSON escapes them), so a line
+ * split is a faithful inverse of the encode side.
+ */
+export function splitCombinedEventLog(content) {
+    const out = [];
+    for (const line of content.split("\n")) {
+        if (line.length === 0)
+            continue;
+        out.push(line);
+    }
+    return out;
+}
+/**
+ * Join per-event blobs (in seq order) into a combined event-log file: each
+ * blob's exact bytes followed by a newline. Operating on bytes -- not
+ * decoded strings -- keeps the sealed file a *verbatim* concatenation of
+ * the per-event blobs, which matters because each event is signed over its
+ * own bytes; a decode/re-encode round-trip could alter them. This is the
+ * single source of the combined-file byte layout shared by the compaction
+ * writer and the validator's byte-equality bridge, so the two cannot
+ * drift. An empty input yields an empty file.
+ */
+export function encodeCombinedEventLog(perEventBlobs) {
+    const NEWLINE = 0x0a;
+    let total = 0;
+    for (const blob of perEventBlobs)
+        total += blob.byteLength + 1;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const blob of perEventBlobs) {
+        out.set(blob, offset);
+        offset += blob.byteLength;
+        out[offset] = NEWLINE;
+        offset += 1;
+    }
+    return out;
+}

package/dist/workflow-run-kind.d.ts

@@ -0,0 +1,326 @@
+import { type AuthorizeFn, type KindHandler, type Principal, type RepoId, type RepoStore } from "./repo-store/index.js";
+export type WorkflowRunHubPrincipal = {
+    readonly kind: "hub";
+};
+export type WorkflowRunSidecarPrincipal = {
+    readonly kind: "sidecar";
+    readonly agentId: string;
+};
+export type WorkflowRunWorkflowProcessPrincipal = {
+    readonly kind: "workflow-process";
+    readonly deploymentId: string;
+    readonly runId?: string;
+};
+export type WorkflowRunSupervisorPrincipal = {
+    readonly kind: "supervisor";
+    readonly deploymentId: string;
+};
+export type WorkflowRunPrincipal = WorkflowRunHubPrincipal | WorkflowRunSidecarPrincipal | WorkflowRunWorkflowProcessPrincipal | WorkflowRunSupervisorPrincipal;
+export declare const WORKFLOW_RUN_GITIGNORE_PATH = ".gitignore";
+export declare const WORKFLOW_RUN_RUNS_PREFIX = "runs";
+export declare const WORKFLOW_RUN_EVENTS_DIR = "events";
+export declare const WORKFLOW_RUN_BLOBS_DIR = "blobs";
+export declare const WORKFLOW_RUN_ADDRESSES_PREFIX = "addresses";
+export declare const WORKFLOW_RUN_CONTROL_PREFIX = "control";
+export declare const WORKFLOW_RUN_INBOX_DIR = "inbox";
+export declare const WORKFLOW_RUN_PROCESSING_DIR = "processing";
+export declare const WORKFLOW_RUN_CONSUMED_DIR = "consumed";
+/**
+ * Filename of the per-address retention watermark blob, a direct child
+ * of `addresses/<urlEncoded>/` (a file, not a directory). Carries the
+ * monotonic `receivedAt`-horizon below which consumed entries may be
+ * pruned and at-or-below which inbound enqueues are refused as stale.
+ */
+export declare const WORKFLOW_RUN_WATERMARK_FILE = "watermark.json";
+/**
+ * Default retention horizon for the consumed dedup index, in
+ * milliseconds. The boot edge resolves the operator's
+ * `CONSUMED_RETENTION_MS` config to a concrete value and threads it
+ * into `markConsumed`; this default applies only when no operator
+ * value is supplied. 24 hours is the conservative default: long enough
+ * that a duplicate from a retrying upstream within a day is still
+ * deduped by a retained consumed entry, short enough that `consumed/`
+ * reaches a bounded steady state of one day's message volume.
+ *
+ * INVARIANT (operator-owned): the horizon must be >= the longest
+ * window in which the same `messageId` could legitimately be
+ * re-submitted and still must be caught as a duplicate. There is no
+ * automatic internal mail redelivery in the system today, so this is
+ * the external re-submission window. If an at-least-once redelivery
+ * source is ever added, the horizon must be >= its maximum redelivery
+ * window or dedup breaks; a breach surfaces LOUDLY (a too-late
+ * re-submission carrying an old `receivedAt` is refused at enqueue,
+ * not silently reprocessed) rather than as silent double-processing.
+ */
+export declare const DEFAULT_CONSUMED_RETENTION_MS: number;
+/**
+ * Per-agent durable conversation-state subtree (design §3c). A
+ * long-lived single-step agent's multi-turn conversation context is
+ * committed under `agent-state/<agentKey>/...` so it survives child
+ * respawn: on respawn the rebuilt warm agent reads its prior
+ * conversation back from here before the resumed run replays.
+ *
+ * Unlike `runs/` (append-only events, immutable blobs) this subtree is
+ * MUTABLE: each run boundary overwrites the agent's conversation
+ * snapshot with the latest turns. It is therefore exempt from the
+ * append-only / deletion-direction walks `runs/` is subject to; the
+ * only push-time constraint is segment shape (a single round-trip-safe
+ * `<agentKey>` directory layer below the prefix).
+ */
+export declare const WORKFLOW_RUN_AGENT_STATE_PREFIX = "agent-state";
+/**
+ * JSON envelope carried by inbox and processing entries. Keys:
+ *   - `messageId`: dedup key for the inbound message.
+ *   - `receivedAt`: epoch-ms timestamp the reactor accepted the
+ *     message; sortable FIFO key prefix.
+ *   - `address`: decoded canonical address (not URL-encoded).
+ *   - `mailAuditRef`: pointer to the raw mail bytes in the mail-audit
+ *     store. For the in-process single-agent path a separate
+ *     `MailAuditStore` holds the authoritative bytes and this ref joins
+ *     onto it.
+ *   - `rawMessage`: base64 of the inbound mail's raw MIME bytes,
+ *     inlined so the workflow-process child can read its step input by
+ *     messageId at `trigger.fired` time. The supervisor is the sole
+ *     mail owner under the unified-execution host (§3a); it has no
+ *     separate durable byte store the child can read, so the bytes ride
+ *     the claim-check envelope itself. Present whenever the supervisor
+ *     enqueued the entry; omitted by callers that only stamp the audit
+ *     ref. The bytes survive the inbox→processing transition verbatim
+ *     (the dequeue copies the entry bytes), so a `trigger.fired` for a
+ *     processing entry can always recover the input.
+ */
+declare const ClaimCheckEnvelope: import("arktype/internal/variants/object.ts").ObjectType<{
+    messageId: string;
+    receivedAt: number;
+    address: string;
+    mailAuditRef: {
+        store: string;
+        path: string;
+    };
+    rawMessage?: string;
+}, {}>;
+/**
+ * JSON envelope carried by consumed entries. The consumed entry is the
+ * canonical dedup index keyed by messageId; the envelope preserves
+ * the originating receivedAt for audit and carries the runId that
+ * consumed the message.
+ */
+declare const ConsumedEnvelope: import("arktype/internal/variants/object.ts").ObjectType<{
+    messageId: string;
+    receivedAt: number;
+    address: string;
+    runId: string;
+    consumedAt: number;
+    mailAuditRef: {
+        store: string;
+        path: string;
+    };
+}, {}>;
+/**
+ * JSON envelope carried by the per-address `watermark.json` blob. The
+ * `watermark` is a `receivedAt` horizon (epoch ms): the oldest
+ * `receivedAt` a consumed entry may still retain. It only ever
+ * advances. A retention prune drops consumed entries strictly below
+ * it; `enqueueInbox` refuses any inbound strictly below it.
+ */
+declare const WatermarkEnvelope: import("arktype/internal/variants/object.ts").ObjectType<{
+    watermark: number;
+}, {}>;
+export type ClaimCheckEnvelope = typeof ClaimCheckEnvelope.infer;
+export type ConsumedEnvelope = typeof ConsumedEnvelope.infer;
+export type WatermarkEnvelope = typeof WatermarkEnvelope.infer;
+export declare const workflowRunKindHandler: KindHandler;
+export declare const workflowRunAuthorize: AuthorizeFn;
+export type EnqueueInboxArgs = {
+    address: string;
+    messageId: string;
+    receivedAt: number;
+    mailAuditRef: {
+        store: string;
+        path: string;
+    };
+    /**
+     * Base64 of the inbound mail's raw MIME bytes. Inlined on the
+     * claim-check envelope so the workflow-process child can recover its
+     * step input by messageId at `trigger.fired` time (§3a -- the
+     * supervisor is the sole mail owner and has no separate durable byte
+     * store the child reads). Omit to stamp only the audit ref.
+     */
+    rawMessage?: string;
+};
+export type EnqueueInboxResult = {
+    commitSha: string;
+    inboxKey: string;
+    envelope: ClaimCheckEnvelope;
+};
+/**
+ * Append a new inbox entry for `address`. The merge callback reads
+ * the address subtree under the per-repo lock, augments the inbox
+ * with the new entry, and returns the full set of address files. The
+ * substrate replaces the address subtree wholesale.
+ *
+ * Rejects if a same-messageId entry already exists in any queue
+ * state at the address — including a prior inbox entry at a
+ * different `receivedAt`. The caller is expected to consult the
+ * dedup index (consumed/) before calling, but enforcing the
+ * invariant here also catches the concurrent-enqueue race that the
+ * per-repo lock alone cannot surface.
+ */
+export declare function enqueueInbox(store: RepoStore, principal: Principal, repoId: RepoId, args: EnqueueInboxArgs): Promise<EnqueueInboxResult>;
+export type DequeueToProcessingResult = {
+    commitSha: string;
+    key: string;
+    envelope: ClaimCheckEnvelope;
+} | null;
+/**
+ * Move the FIFO-first inbox entry for `address` to processing.
+ * Returns `null` when the inbox is empty so the caller can
+ * distinguish "nothing to do" from "operation failed".
+ *
+ * FIFO is keyed on the parsed numeric `receivedAt` prefix of the
+ * inbox filename, with a lexicographic messageId tiebreak. The
+ * substrate does NOT rely on uniform digit widths — sorting raw
+ * filenames would put `"100-…"` ahead of `"99-…"` since `'1' < '9'`,
+ * which violates the FIFO invariant.
+ */
+export declare function dequeueToProcessing(store: RepoStore, principal: Principal, repoId: RepoId, address: string): Promise<DequeueToProcessingResult>;
+export type ReadProcessingEntryResult = {
+    envelope: ClaimCheckEnvelope;
+} | null;
+/**
+ * Read the processing-queue entry for `messageId` at `address` without
+ * mutating the tree. Returns the decoded claim-check envelope (carrying
+ * `mailAuditRef` and, when the enqueuer inlined them, the base64
+ * `rawMessage` bytes) or `null` when no processing entry exists for the
+ * messageId.
+ *
+ * This is the read half of mailbox ownership (§3a): the supervisor's
+ * dispatch loop moves an inbox entry to processing and forwards a
+ * `trigger.fired{messageId}` to the workflow-process child; the child
+ * calls this to recover the inbound message bytes that become its step
+ * input.
+ *
+ * The read is a flat working-tree read of
+ * `addresses/<seg>/processing/`. The substrate materializes each
+ * claim-check commit's touched paths into the repo's working tree (the
+ * delta write removes each deleted path and writes each put after
+ * validation passes), so a read issued after `dequeueToProcessing`
+ * committed -- which is exactly when the supervisor forwards
+ * `trigger.fired` -- observes the processing entry. Reading the working tree (rather than walking the
+ * committed git tree) matches the workflow-process child's sibling
+ * reads of `workflow.json` and `runs/<runId>/events/`. Because the
+ * read issues no commit it cannot race the supervisor's `markConsumed`
+ * write; it returns a point-in-time snapshot of the directory.
+ */
+export declare function readProcessingEntry(store: RepoStore, _principal: Principal, repoId: RepoId, address: string, messageId: string): Promise<ReadProcessingEntryResult>;
+export type MarkConsumedArgs = {
+    address: string;
+    messageId: string;
+    runId: string;
+    consumedAt: number;
+    /**
+     * Retention horizon for the consumed dedup index, in milliseconds.
+     * The commit advances the per-address watermark to
+     * `consumedAt - retentionHorizonMs` (never backward, never past the
+     * entry being written) and prunes consumed entries below it. The
+     * boot edge resolves the operator's `CONSUMED_RETENTION_MS` config
+     * to a concrete value and threads it here. Omit to apply
+     * `DEFAULT_CONSUMED_RETENTION_MS` (24h).
+     */
+    retentionHorizonMs?: number;
+};
+export type MarkConsumedResult = {
+    commitSha: string;
+    envelope: ConsumedEnvelope;
+    /** Watermark the commit advanced to (epoch-ms `receivedAt` horizon). */
+    watermark: number;
+    /** messageIds whose consumed entries this commit pruned. */
+    prunedMessageIds: string[];
+};
+/**
+ * Atomically remove the processing entry for `messageId` at `address`,
+ * write the canonical `consumed/<messageId>.json` dedup index entry,
+ * advance the per-address retention watermark, and prune consumed
+ * entries the watermark has passed. The caller is expected to have
+ * called `dequeueToProcessing` for this messageId; calling
+ * `markConsumed` without a matching processing entry throws.
+ *
+ * The consumed envelope preserves the original `receivedAt` and
+ * `mailAuditRef` from the processing entry so the dedup index doubles
+ * as an audit record.
+ *
+ * Retention (the bounded-`consumed/` contract): the watermark advances
+ * to `max(priorWatermark, min(consumedAt - retentionHorizonMs,
+ * thisEntry.receivedAt))` -- monotonic, and never past the entry being
+ * written so the new entry is always retained. Every consumed entry
+ * whose `receivedAt` is strictly below the new watermark is dropped
+ * (the oldest age-ordered tail). `consumed/` therefore reaches a
+ * bounded steady state of roughly one horizon's worth of entries
+ * instead of growing one entry per message forever.
+ */
+export declare function markConsumed(store: RepoStore, principal: Principal, repoId: RepoId, args: MarkConsumedArgs): Promise<MarkConsumedResult>;
+export type ReplayProcessingToInboxResult = {
+    commitSha: string;
+    replayedKeys: string[];
+};
+/**
+ * Read the run event logs under `runs/` and return the set of
+ * `consumedMessageId`s belonging to NON-terminal runs -- the messages a
+ * live run still owns. The caller (the supervisor's spawn-time replay)
+ * feeds this into `replayProcessingToInbox`'s `ownedMessageIds` so a
+ * parked run's message is not re-admitted to inbox and dispatched a
+ * second time while the run is recovered by re-driving its durable log.
+ * Without this, the re-drive AND the re-triggered fresh run both re-park
+ * the same awaitSignal gate on the same runId, and the two concurrent
+ * runtime bodies race to a corrupt terminal.
+ *
+ * Reads the substrate's working tree via `getRepoDir`, mirroring the
+ * child's `discoverInFlightRuns`. The working tree tracks the run-event
+ * ref (`refs/heads/main`); the claim-check ref (`refs/heads/events`)
+ * cannot see it, which is why this lives at the caller rather than inside
+ * `replayProcessingToInbox`'s single-ref delta. A run whose log is sealed
+ * (combined `events.json`, only permitted for a terminated run) or
+ * carries a terminal event is excluded; an absent `runs/` directory
+ * yields an empty set.
+ */
+export declare function readOwnedMessageIds(store: RepoStore, repoId: RepoId): Promise<Set<string>>;
+export type ReplayProcessingToInboxOpts = {
+    /**
+     * MessageIds whose run is still LIVE (non-terminal) and therefore owns
+     * its inbound message: recovery re-drives that run against the durable
+     * log, so re-admitting the message to `inbox/` would dispatch a SECOND
+     * run for it, colliding with the re-drive on the shared runId. Entries
+     * in this set are left in `processing/` untouched; the run's eventual
+     * `markConsumed` clears them. The caller computes this by reading the
+     * run event logs, which live on a DIFFERENT ref (`refs/heads/main`)
+     * than the claim-check subtree this operation commits to
+     * (`refs/heads/events`). Empty/absent means replay every processing
+     * entry (the pre-existing behaviour: recover all orphans).
+     */
+    ownedMessageIds?: ReadonlySet<string>;
+};
+/**
+ * Recovery path: move every processing entry at `address` back to
+ * inbox preserving the original `<receivedAt>-<messageId>` filename
+ * key so FIFO ordering survives a workflow-process crash. Returns
+ * the set of keys that were moved; when nothing was in processing
+ * the returned `replayedKeys` is empty (and the commit is a no-op
+ * rewrite of the same tree).
+ *
+ * The replay is atomic across all processing entries — a partial
+ * replay that left some entries in processing would corrupt the
+ * FIFO discipline (the next dequeue would pull the wrong entry).
+ *
+ * Watermark carve-out (load-bearing — do NOT "tighten" this): the
+ * replay deliberately does NOT apply the `receivedAt < watermark`
+ * stale-reject that `enqueueInbox` applies. A `processing/` entry was
+ * already dequeued past the dedup index, so re-admitting it to
+ * `inbox/` even when its `receivedAt` has fallen below an advanced
+ * watermark is correct — the message is a legitimately in-flight one
+ * recovered after a crash, not a fresh inbound that could be a
+ * duplicate. Applying the stale-reject here would silently LOSE that
+ * message. The watermark only ever gates fresh inbound at the enqueue
+ * boundary; the recovery replay is exempt by design.
+ */
+export declare function replayProcessingToInbox(store: RepoStore, principal: Principal, repoId: RepoId, address: string, opts?: ReplayProcessingToInboxOpts): Promise<ReplayProcessingToInboxResult>;
+export {};