@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/resume-drain.js

@@ -0,0 +1,158 @@
+/** Bounds only the wait for a turn's FIRST message (never mid-turn): a stale
+ * (not-yet-flushed) residue read must not hang us on a backlog turn that never
+ * arrives. Comfortably longer than the CLI's inter-turn gap. */
+const FIRST_MESSAGE_TIMEOUT_MS = 8000;
+/** Overall ceiling so consumption can never hang indefinitely. */
+const DEFAULT_DEADLINE_MS = 180000;
+function isErrorResult(m) {
+    return (typeof m.subtype === "string" && m.subtype.startsWith("error")) || m.success === false;
+}
+/**
+ * Pump the message stream until the next terminal `result`, invoking `onMessage`
+ * per message. Drives a SINGLE in-flight `next()` (threaded via `pending`) so the
+ * iterator is never advanced twice concurrently.
+ *
+ * `firstMessageTimeoutMs` bounds ONLY the wait for this turn's first message; once
+ * a message has been received the turn is consumed to its `result` unbounded (a
+ * slow turn is never cut off). On a first-message timeout the still-in-flight
+ * `pending` is handed straight back to the caller.
+ */
+async function pumpToResult(iterator, pending, onMessage, onSessionId, firstMessageTimeoutMs) {
+    let awaitingFirst = true;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        let step;
+        if (awaitingFirst && firstMessageTimeoutMs !== undefined) {
+            const TIMED_OUT = Symbol("first-message-timeout");
+            let timer;
+            const raced = await Promise.race([
+                pending,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(TIMED_OUT), firstMessageTimeoutMs);
+                }),
+            ]);
+            if (timer)
+                clearTimeout(timer);
+            if (raced === TIMED_OUT)
+                return { pending, result: null, done: false, timedOut: true };
+            step = raced;
+        }
+        else {
+            step = await pending;
+        }
+        if (step.done)
+            return { pending: Promise.resolve(step), result: null, done: true, timedOut: false };
+        awaitingFirst = false;
+        const m = step.value;
+        if (m.session_id && onSessionId)
+            onSessionId(m.session_id);
+        if (onMessage)
+            await onMessage(step.value);
+        if (m.type === "result") {
+            return { pending: iterator.next(), result: m, done: false, timedOut: false };
+        }
+        pending = iterator.next();
+    }
+}
+/**
+ * Consume a resumed session's stream to the caller's real turn, first draining any
+ * stale async-input backlog that replays ahead of it. See the module doc.
+ *
+ * The session must already have the caller's prompt seeded (chatSession opens with
+ * the prompt; runCommand `send`s the command; the wake path is opened with its
+ * prompt by herdctl) — this only governs WHEN we stop consuming, never what runs.
+ */
+export async function consumeResumedTurn(session, opts) {
+    const iterator = session.messages[Symbol.asyncIterator]();
+    let pending = iterator.next();
+    let sessionId = null;
+    const onSid = (id) => {
+        sessionId = id;
+        opts.onSessionId?.(id);
+    };
+    const overallDeadline = Date.now() + (opts.deadlineMs ?? DEFAULT_DEADLINE_MS);
+    let success = false;
+    let turns = 0;
+    while (Date.now() < overallDeadline) {
+        // Bound only the wait for the next turn's first message while a backlog may
+        // still be queued (residue > 0); wait unbounded when the queue is empty (the
+        // running turn is the real one and may be slow).
+        const firstMsgTimeout = (await opts.residueProbe()) > 0 ? FIRST_MESSAGE_TIMEOUT_MS : undefined;
+        const r = await pumpToResult(iterator, pending, opts.onMessage, onSid, firstMsgTimeout);
+        pending = r.pending;
+        if (r.done)
+            break;
+        if (r.timedOut)
+            break; // no further turn arrived → the queue is effectively drained
+        if (r.result) {
+            turns++;
+            success = !isErrorResult(r.result);
+        }
+        if ((await opts.residueProbe()) === 0)
+            break; // async queue drained → real turn done
+    }
+    if (turns > 1)
+        opts.log?.(`drained ${turns - 1} backlog turn(s) ahead of the real turn`);
+    return { success, sessionId, iterator, pending };
+}
+/**
+ * Gap B — deliver autonomous background-completion turns.
+ *
+ * After {@link consumeResumedTurn} returns, the primary turn is done but the
+ * session may be held OPEN by the reaper because the turn launched continuous
+ * background work (`decideReap` keepAlives while `backgroundTasks.length > 0`).
+ * The `claude` subprocess keeps running and, when a background task completes,
+ * the SDK hands the parent the result as a fresh autonomous re-invocation turn —
+ * emitted on the SAME message stream. Paddock used to stop consuming at the
+ * primary `result`, so those messages buffered undelivered: the CLI still
+ * PERSISTED the re-invocation to the transcript (the subprocess writes JSONL
+ * directly), but the live UI never saw it until a refresh replayed history.
+ *
+ * This keeps consuming the handed-back {@link ConsumeResumedTurnResult.iterator}
+ * (never a second iterator — that would split the stream), forwarding every
+ * subsequent message to `onMessage`. The caller's `onMessage` renders each
+ * autonomous turn to the hub exactly like the scheduler-wake path does, so it
+ * appears live. Consumption ALSO keeps `tapLifecycleStream` advancing, so the
+ * reaper keeps receiving its mid-turn `activity` / `background_tasks_changed`
+ * signals (they fire as a side effect of the consumer pulling messages) — the
+ * behaviour the reaper was designed around.
+ *
+ * The loop ends cleanly when the reaper reaps the idle session: `close()` ends
+ * the SDK query, the iterator yields `done`, and we return. A stream error is
+ * swallowed (the turn is already over). Detached by the caller (`void`), it
+ * never throws to the event loop.
+ */
+export async function consumeBackgroundTurns(iterator, pending, onMessage, onDone) {
+    try {
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            let step;
+            try {
+                step = await pending;
+            }
+            catch {
+                return; // stream errored/closed — nothing more to deliver
+            }
+            if (step.done)
+                return; // reaper reaped the session → stream ended
+            try {
+                await onMessage(step.value);
+            }
+            catch {
+                /* a rendering failure for one message must not abort delivery */
+            }
+            pending = iterator.next();
+        }
+    }
+    finally {
+        // Signal the caller (the background sink) that the stream has ended so it can
+        // finalize its single hub turn (emit chat:complete + turn.end()). Runs on
+        // normal end, error, or reap. Never throws to the event loop.
+        try {
+            await onDone?.();
+        }
+        catch {
+            /* completion signalling must not throw to a detached consumer */
+        }
+    }
+}

package/packages/server/dist/route-context.d.ts

@@ -0,0 +1,168 @@
+/**
+ * The route dependency bag + the shared per-request context the route groups
+ * close over.
+ *
+ * `RouteDeps` is the raw service bag `app.ts` hands to {@link registerRoutes}.
+ * `buildRouteContext` constructs — ONCE — the handful of helper closures that the
+ * original single `registerRoutes` defined inline (read-state user resolution,
+ * slug→agent/dir resolution, attachment cleanup, the per-chat usage resolver) and
+ * returns them alongside every dep as a {@link RouteCtx}. Each `registerXRoutes`
+ * group then takes that context instead of relying on closure scope — which is
+ * what lets the ~50 handlers live in per-group modules while sharing one wiring.
+ */
+import type { FastifyRequest } from "fastify";
+import type { DiscoveredSession } from "@herdctl/core";
+import type { ProjectStore } from "./projects.js";
+import { AttachmentStore } from "./attachments.js";
+import type { HerdctlService } from "./herdctl.js";
+import type { GitService } from "./git.js";
+import type { GithubAuth } from "./github-auth.js";
+import type { ArchiveStore } from "./archive.js";
+import type { StarStore } from "./star.js";
+import type { ReadStateStore } from "./read-state.js";
+import type { UnreadStore } from "./unread.js";
+import type { ParentDetachStore } from "./parent-detach.js";
+import type { RunProvenanceStore } from "./run-provenance.js";
+import type { MessageProvenanceStore } from "./message-provenance.js";
+import type { PaddockConfig } from "./config.js";
+import { type Transcriber } from "./transcribe.js";
+import type { PaddockEventBus } from "./event-bus.js";
+import type { ChatHandlerContext } from "./ws-context.js";
+import type { TriggerService } from "./triggers.js";
+import { type ChatUsage } from "./chat-dto.js";
+/**
+ * The subset of @fastify/multipart's decorated request we use. The plugin
+ * decorates `req.file()` at runtime; we model just what we need here rather than
+ * rely on the plugin's global `declare module 'fastify'` augmentation, which is
+ * brittle under workspace hoisting (fastify can resolve to a different physical
+ * copy than the one the plugin augments).
+ */
+export interface UploadedFile {
+    filename?: string;
+    mimetype?: string;
+    toBuffer(): Promise<Buffer>;
+}
+/** A streamed multipart part (issue #328 upload): a file or a form field. */
+export interface MultipartPart {
+    type: "file" | "field";
+    filename?: string;
+    mimetype?: string;
+    toBuffer(): Promise<Buffer>;
+}
+export interface MultipartLimits {
+    limits?: {
+        fileSize?: number;
+        files?: number;
+    };
+}
+export type MultipartRequest = FastifyRequest & {
+    file(): Promise<UploadedFile | undefined>;
+    parts(opts?: MultipartLimits): AsyncIterableIterator<MultipartPart>;
+};
+export interface RouteDeps {
+    projects: ProjectStore;
+    herdctl: HerdctlService;
+    git: GitService;
+    githubAuth: GithubAuth;
+    transcriber: Transcriber;
+    archive: ArchiveStore;
+    /** Per-chat starred/pinned-flag sidecar (#373). Orthogonal to `archive`. */
+    star: StarStore;
+    readState: ReadStateStore;
+    /**
+     * Per-user MANUAL "unread" override sidecar (#458): an explicit "mark unread"
+     * flag layered on top of the derived read-state, so a chat can resurface its
+     * unread cue even after its last turn was seen. Cleared when the chat is marked
+     * seen (opened / focused / marked read).
+     */
+    unread: UnreadStore;
+    /**
+     * Explicit "this chat was detached from its parent" sidecar (#508). Consulted
+     * by `makeParentResolver` AHEAD of the recorded and inferred parent tiers, so a
+     * detach can't be undone by the inference that re-derives an unrecorded edge.
+     */
+    parentDetach: ParentDetachStore;
+    runProvenance: RunProvenanceStore;
+    /**
+     * Per-MESSAGE provenance sidecar (issue #290): who injected each machine-added
+     * turn. Joined into a chat's message DTO so the history can attribute injected
+     * turns ("↩ sent by …" / "⏰ scheduled by …"). Absence ⇒ human (the default).
+     */
+    messageProvenance: MessageProvenanceStore;
+    attachments: AttachmentStore;
+    /**
+     * Manually fire a project's TRIGGER now (Epic T follow-up / #327), backing the
+     * `POST …/triggers/:name/run` "Run now" route + the `run_trigger` self-MCP verb.
+     * Supplied by the chat handler (`makeChatHandler(...).fireTrigger`) so a manual run
+     * goes through the SAME hub path a cron / event fire uses — a first-class, badged
+     * chat, indistinguishable from an automatic fire. Fires ANY trigger type regardless
+     * of its `enabled` flag. Resolves the started chat's session id, or `null` if the
+     * project/trigger is gone or nothing started. Optional so tests that don't exercise
+     * triggers can omit it.
+     */
+    fireTrigger?: (slug: string, triggerName: string) => Promise<string | null>;
+    /**
+     * The shared Management API ops context (issue #312 M1) — the SAME bag the
+     * in-process self-MCP is built from (`makeChatHandler(...).managementOpsContext`).
+     * Handed to the route layer so a non-socket caller can build the management ops
+     * for itself via `buildManagementOps` + `enforceManagementPolicy`: the `/mcp`
+     * transport in M2, and the turn-spawning REST endpoints in #465, which is why
+     * this is threaded now rather than when the transport lands. Optional so tests
+     * that don't exercise the management API can omit it.
+     */
+    managementOpsContext?: ChatHandlerContext;
+    /**
+     * In-process lifecycle event bus (Epic T). The archive route emits `onArchive`
+     * on it AFTER the archive commits, so the trigger dispatcher (wired in the chat
+     * handler) fires the project's enabled onArchive event triggers. Optional so tests
+     * that don't exercise triggers can omit it.
+     */
+    events?: PaddockEventBus;
+    /**
+     * Unified trigger CRUD service (Epic T "Unify Triggers" / T3). Backs the
+     * `/api/projects/:slug/triggers[/:name]` REST surface the Triggers tab (T4) will
+     * drive — list (with the capability-picker catalog), create/replace, edit,
+     * enable/disable (just `set` with `enabled` flipped — GG-3), delete. Delegates
+     * persistence to `project.yaml`'s single `triggers` block + herdctl arming to
+     * {@link TriggerService}. Optional so tests that don't exercise triggers can omit it.
+     */
+    triggers?: TriggerService;
+    cfg: PaddockConfig;
+}
+/**
+ * `RouteDeps` plus the shared helper closures built once by
+ * {@link buildRouteContext}. This is what every `registerXRoutes(app, ctx)` group
+ * receives.
+ */
+export interface RouteCtx extends RouteDeps {
+    /**
+     * Resolve the read-state key's user segment from the authenticated principal:
+     * a REAL identity (trusted-header / jwt) keys read-state by username; an
+     * anonymous principal (`none` mode) uses the shared bucket (null → no user
+     * segment). This is the ONLY place user identity is consumed — read-state is
+     * user-keyed-when-present; chat VISIBILITY is deliberately not gated (#189).
+     */
+    readStateUser(req: FastifyRequest): string | null;
+    /** Resolve a slug to the agent name whose sessions back it. */
+    agentForSlug(slug: string): Promise<string>;
+    /** Resolve a slug to the on-disk project directory holding its `.chats/`. */
+    projectDirForSlug(slug: string): Promise<string>;
+    /**
+     * Remove the attachments a chat referenced, before its transcript is deleted
+     * (we read the transcript to find the ids). Best-effort — a failure here must
+     * never block the chat delete.
+     */
+    cleanupAttachments(agent: string, sessionId: string): Promise<void>;
+    /**
+     * A per-session usage lookup for building a chat list's usage rings (issue
+     * #77) + cumulative token/cost figures (issue #152, incl. sub-agents #242):
+     * reads each session's transcript plus its sub-agent transcripts (both memoized
+     * on mtime) and pairs the parsed totals with the model. Returns null for a
+     * session with no usage data yet — the ring simply hides. Keyed on `projectDir`
+     * (not the agent name) because paddock resolves transcripts directly under
+     * `<projectDir>/.chats/`.
+     */
+    chatUsageResolver(projectDir: string, model: string): (s: DiscoveredSession) => Promise<ChatUsage | null>;
+}
+/** Construct the shared route context (deps + the helper closures) once. */
+export declare function buildRouteContext(deps: RouteDeps): RouteCtx;

package/packages/server/dist/route-context.js

@@ -0,0 +1,39 @@
+import { collectAttachmentIds } from "./attachments.js";
+import { keeperAgentName } from "./herdctl.js";
+import { readSessionTokenUsageWithSubagents } from "./subagents.js";
+import { toChatUsage } from "./chat-dto.js";
+/** Construct the shared route context (deps + the helper closures) once. */
+export function buildRouteContext(deps) {
+    const { projects, herdctl, attachments } = deps;
+    const readStateUser = (req) => req.user && !req.user.anonymous ? req.user.username : null;
+    async function agentForSlug(slug) {
+        await projects.get(slug); // throws not_found for unknown slug
+        return keeperAgentName(slug);
+    }
+    async function projectDirForSlug(slug) {
+        return (await projects.get(slug)).dir;
+    }
+    async function cleanupAttachments(agent, sessionId) {
+        try {
+            const messages = await herdctl.sessionMessages(agent, sessionId);
+            await attachments.remove(collectAttachmentIds(messages));
+        }
+        catch {
+            /* best-effort: orphaned attachment files are harmless */
+        }
+    }
+    function chatUsageResolver(projectDir, model) {
+        return async (s) => {
+            const u = await readSessionTokenUsageWithSubagents(projectDir, s.sessionId).catch(() => null);
+            return u ? toChatUsage(u, model) : null;
+        };
+    }
+    return {
+        ...deps,
+        readStateUser,
+        agentForSlug,
+        projectDirForSlug,
+        cleanupAttachments,
+        chatUsageResolver,
+    };
+}

package/packages/server/dist/route-errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared REST error helper. `sendProjectError` maps a {@link ProjectError} onto
+ * the right HTTP status (404 not_found / 409 exists|not_directory / 400 else) and
+ * falls back to a logged 500 for anything unexpected. Used by nearly every
+ * handler, so it lands in its own module and is imported everywhere.
+ */
+import type { FastifyReply } from "fastify";
+export declare function sendProjectError(reply: FastifyReply, err: unknown): FastifyReply<import("fastify").RawServerDefault, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, import("fastify").RouteGenericInterface, unknown, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown>;

package/packages/server/dist/route-errors.js

@@ -0,0 +1,13 @@
+import { ProjectError } from "./projects.js";
+export function sendProjectError(reply, err) {
+    if (err instanceof ProjectError) {
+        const code = err.code === "not_found"
+            ? 404
+            : err.code === "exists" || err.code === "not_directory"
+                ? 409
+                : 400;
+        return reply.code(code).send({ error: err.message, code: err.code });
+    }
+    reply.log.error({ err }, "route error");
+    return reply.code(500).send({ error: err.message ?? "internal error" });
+}

package/packages/server/dist/routes/chats.d.ts

@@ -0,0 +1,12 @@
+import type { FastifyInstance } from "fastify";
+import type { RouteCtx } from "../route-context.js";
+/**
+ * Workspace-scoped chat routes: paths are declared RELATIVE to the workspace
+ * (e.g. `/chats/:sessionId`), and this plugin is mounted TWICE — once at
+ * `/api/root` and once at `/api/projects/:slug` (see `workspace-mount.ts`).
+ *
+ * Handlers still read `req.params.slug`; the root mount injects `slug: ""` in an
+ * `onRequest` hook, which runs before params validation, so the `required:
+ * ["slug"]` schemas below keep validating unchanged on both mounts.
+ */
+export declare function registerChatWorkspaceRoutes(app: FastifyInstance, ctx: RouteCtx): void;