@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/whatsapp-bridge.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Reading a WhatsApp thread for the session context rail.
+ *
+ * WhatsApp has no readable web URL for a conversation, and no public API this
+ * daemon could call. What exists on an operator's machine is a CLI holding an
+ * authenticated session (`wacli`, usually behind a `kubectl exec`). So this
+ * bridge is a **subprocess**, not a fetch, and that shape drives every decision
+ * below.
+ *
+ * Two rules make a subprocess safe here:
+ *
+ * 1. **The command is operator-configured, never derived from a reference.**
+ *    `PASEO_WHATSAPP_READ_CMD` sits in the daemon's environment beside the
+ *    GitLab and Jira tokens and carries the same trust. A URL scraped out of
+ *    tool output can only ever supply the chat id: it can never say what to run
+ *    or where to run it. Same stance as the GitLab host allowlist, for the same
+ *    reason. See docs/session-context-rail.md.
+ * 2. **Never a shell.** The chat id is one element of an argv array, so there is
+ *    nothing to inject into. The residual risk is ARGUMENT injection (an id that
+ *    starts with a dash and is read as a flag), which `isSafeChatId` refuses.
+ */
+/**
+ * Configured as an argv prefix, whitespace-separated. The bridge appends
+ * `--chat <id> --limit <n> --json`, which is exactly `wacli messages list`:
+ *
+ *   PASEO_WHATSAPP_READ_CMD="kubectl exec -n wacli -c wacli deploy/wacli -- wacli messages list"
+ *
+ * Whitespace splitting means a path containing spaces cannot be expressed. That
+ * is a deliberate simplification over parsing shell quoting, which would drag
+ * shell semantics back into a design whose whole point is to avoid them.
+ */
+export interface WhatsAppBridgeEnv {
+    PASEO_WHATSAPP_READ_CMD?: string;
+}
+export interface WhatsAppMessage {
+    sender: string;
+    text: string;
+    timestamp: string | null;
+    fromMe: boolean;
+}
+export interface WhatsAppThread {
+    chatName: string | null;
+    messages: WhatsAppMessage[];
+}
+/**
+ * Refuses an id that could be read as a flag, or that carries control
+ * characters. Deliberately NOT a charset allowlist: real group names carry
+ * brackets, accents, emoji and punctuation, so a tidy word-character allowlist
+ * would reject `[IntegraHR][BTG] Tech` while adding no safety. Since the id is a
+ * single argv element and no shell is involved, a leading dash is the actual
+ * attack.
+ */
+export declare function isSafeChatId(chatId: string): boolean;
+export declare function parseCommand(raw: string | undefined): string[];
+/**
+ * `wacli --json` wraps everything in `{success, data}`. `DisplayText` is the
+ * rendered form (it carries reactions and media captions); `Text` is the raw
+ * body and is empty for those. Preferring DisplayText is what makes a reaction
+ * read as "Reacted to X" instead of as a blank line.
+ */
+export declare function parseThread(stdout: string): WhatsAppThread | null;
+export interface WhatsAppBridgeDeps {
+    env: WhatsAppBridgeEnv;
+    /** Injected so tests never spawn a process. */
+    run?: (command: string, args: string[]) => Promise<string | null>;
+}
+/**
+ * Reads one thread. Returns null for every failure: no bridge configured, an
+ * unsafe id, a command that is not installed, a timeout, unparseable output.
+ * The caller turns null into a card that says what it could not see; nothing
+ * here throws into the enrichment path.
+ */
+export declare function readWhatsAppThread(chatId: string, limit: number, deps: WhatsAppBridgeDeps): Promise<WhatsAppThread | null>;
+//# sourceMappingURL=whatsapp-bridge.d.ts.map

package/dist/server/server/whatsapp-bridge.js

@@ -0,0 +1,142 @@
+import { spawn } from "node:child_process";
+/** Nothing on this rail is worth blocking a render on. */
+const READ_TIMEOUT_MS = 8000;
+const MAX_STDOUT_BYTES = 2000000;
+const LAST_CONTROL_CODE = 0x1f;
+const DELETE_CODE = 0x7f;
+function hasControlCharacter(value) {
+    for (const character of value) {
+        const code = character.codePointAt(0) ?? 0;
+        if (code <= LAST_CONTROL_CODE || code === DELETE_CODE) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Refuses an id that could be read as a flag, or that carries control
+ * characters. Deliberately NOT a charset allowlist: real group names carry
+ * brackets, accents, emoji and punctuation, so a tidy word-character allowlist
+ * would reject `[IntegraHR][BTG] Tech` while adding no safety. Since the id is a
+ * single argv element and no shell is involved, a leading dash is the actual
+ * attack.
+ */
+export function isSafeChatId(chatId) {
+    if (chatId.length === 0 || chatId.length > 120) {
+        return false;
+    }
+    if (chatId.startsWith("-")) {
+        return false;
+    }
+    return !hasControlCharacter(chatId);
+}
+export function parseCommand(raw) {
+    return (raw ?? "")
+        .trim()
+        .split(/\s+/)
+        .filter((part) => part.length > 0);
+}
+function str(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+ * `wacli --json` wraps everything in `{success, data}`. `DisplayText` is the
+ * rendered form (it carries reactions and media captions); `Text` is the raw
+ * body and is empty for those. Preferring DisplayText is what makes a reaction
+ * read as "Reacted to X" instead of as a blank line.
+ */
+export function parseThread(stdout) {
+    let payload;
+    try {
+        payload = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (typeof payload !== "object" || payload === null) {
+        return null;
+    }
+    const data = payload.data;
+    if (typeof data !== "object" || data === null) {
+        return null;
+    }
+    const raw = data.messages;
+    if (!Array.isArray(raw)) {
+        return null;
+    }
+    const messages = [];
+    let chatName = null;
+    for (const entry of raw) {
+        if (typeof entry !== "object" || entry === null) {
+            continue;
+        }
+        chatName = chatName ?? str(entry.ChatName);
+        messages.push({
+            sender: str(entry.SenderName) ?? str(entry.SenderJID) ?? "unknown",
+            text: str(entry.DisplayText) ?? str(entry.Text) ?? "",
+            timestamp: str(entry.Timestamp),
+            fromMe: entry.FromMe === true,
+        });
+    }
+    return { chatName, messages };
+}
+async function runCommand(command, args) {
+    return new Promise((resolve) => {
+        // A single nulled-out resolver rather than a `settled` boolean: every path
+        // below (timeout, error, close, oversized output) races the others, and this
+        // shape makes "resolve exactly once" checkable by reading it, and by lint.
+        let settle = resolve;
+        const finish = (value) => {
+            const pending = settle;
+            if (!pending) {
+                return;
+            }
+            settle = null;
+            clearTimeout(timer);
+            child?.kill("SIGKILL");
+            pending(value);
+        };
+        let child = null;
+        const timer = setTimeout(() => finish(null), READ_TIMEOUT_MS);
+        try {
+            child = spawn(command, args, { stdio: ["ignore", "pipe", "ignore"] });
+        }
+        catch {
+            finish(null);
+            return;
+        }
+        let out = "";
+        child.stdout?.on("data", (chunk) => {
+            out += chunk.toString("utf8");
+            if (out.length > MAX_STDOUT_BYTES) {
+                finish(null);
+            }
+        });
+        child.on("error", () => finish(null));
+        child.on("close", (code) => finish(code === 0 ? out : null));
+    });
+}
+/**
+ * Reads one thread. Returns null for every failure: no bridge configured, an
+ * unsafe id, a command that is not installed, a timeout, unparseable output.
+ * The caller turns null into a card that says what it could not see; nothing
+ * here throws into the enrichment path.
+ */
+export async function readWhatsAppThread(chatId, limit, deps) {
+    const argv = parseCommand(deps.env.PASEO_WHATSAPP_READ_CMD);
+    if (argv.length === 0 || !isSafeChatId(chatId)) {
+        return null;
+    }
+    const [command, ...prefix] = argv;
+    const run = deps.run ?? runCommand;
+    const stdout = await run(command, [
+        ...prefix,
+        "--chat",
+        chatId,
+        "--limit",
+        String(limit),
+        "--json",
+    ]);
+    return stdout === null ? null : parseThread(stdout);
+}
+//# sourceMappingURL=whatsapp-bridge.js.map

package/dist/server/server/workflow/workflow-agent-resolution.d.ts

@@ -0,0 +1,82 @@
+import type { WorkflowAgentPreset } from "@hyperdrive.bot/fleet-protocol/messages";
+import type { AgentSessionConfig } from "../agent/agent-sdk-types.js";
+import type { TaskGraph, TaskNode } from "./workflow-manager.js";
+/**
+ * workflow-agent-resolution — Epic 2, Story 2.1.
+ *
+ * Per-step agent selection. Before this module every child of a workflow was spawned
+ * with the one graph-level `baseConfig`, so `TaskNode.agentType` was a declared field
+ * with no reader: delegation to a different agent per step was simply not supported.
+ * This module is that reader.
+ *
+ * Why it is PURE and lives outside `workflow-manager.ts` (the `workflow-progress.ts`
+ * precedent):
+ * - **Unit-testable with no harness.** Precedence is a function of three plain objects;
+ *   proving it should not require an `AgentManager`, a temp dir or a spawned child.
+ * - **The manager stays an orchestrator, not a calculator.** One helper serves BOTH
+ *   spawn call sites (`startWorkflow`'s readiness loop and `continueWorkflow`), so the
+ *   precedence rule exists exactly once.
+ * - **No runtime cycle.** Every import above is type-only and therefore erased, so the
+ *   manager can import this module as a VALUE. `WorkflowUnknownAgentError` is declared
+ *   here (the leaf) and re-exported from the manager, exactly as `WorkflowCycleError`
+ *   is declared in `workflow-progress.ts` and re-exported.
+ *
+ * Why the merge copies only DEFINED keys rather than spreading:
+ * `{ ...base, ...preset, ...override }` lets an explicit `undefined` in a higher tier
+ * ERASE a defined lower-tier value — `{ model: undefined }` on a task would blank the
+ * workflow's model instead of leaving it alone. A tier states what it overrides; a key
+ * it does not set must be invisible.
+ *
+ * Why `cwd` is forced back to `baseConfig.cwd` as the final statement:
+ * the working directory is workflow-owned. A step relocating its own child would break
+ * the containment every other surface assumes. There are two independent guards, on
+ * purpose: `WorkflowAgentPresetSchema` rejects `cwd` at parse time (so it can never
+ * arrive over the wire), and this assignment wins over any hand-built object literal
+ * that bypassed the schema.
+ *
+ * Determinism rules, mirroring `workflow-progress.ts`: synchronous, no I/O, no
+ * `Date.now()` / `new Date()`, no snapshot read, no module-level mutable state.
+ */
+/** Thrown when a task's `agentType` names an agent absent from the workflow's presets. */
+export declare class WorkflowUnknownAgentError extends Error {
+    readonly workflowId: string | undefined;
+    readonly taskId: string;
+    readonly agentName: string;
+    readonly knownAgents: string[];
+    constructor(workflowId: string | undefined, taskId: string, agentName: string, knownAgents: string[]);
+}
+/**
+ * Create-time validation: reject a graph whose any task names an agent nobody defined.
+ *
+ * Reports the FIRST offender in `graph.tasks` array order, so the error is stable for
+ * a given graph rather than dependent on object-key iteration. The message names the
+ * task id, the unknown name and the known names, because both launch boundaries
+ * (`session.ts` RPC, `mcp-server.ts` tool) forward `error.message` verbatim to the
+ * operator and that string is the whole diagnosis.
+ *
+ * Own-key lookup, never a bare `in`: a preset named `toString` or `constructor` must
+ * not be satisfied by `Object.prototype`.
+ */
+export declare function assertKnownAgents(args: {
+    graph: TaskGraph;
+    agentPresets: Record<string, WorkflowAgentPreset>;
+    workflowId?: string;
+}): void;
+/**
+ * Resolve the `AgentSessionConfig` one task's child is spawned with.
+ *
+ * Precedence, lowest to highest: `baseConfig`, then `agentPresets[node.agentType]`,
+ * then `node.agentConfig`. Only keys whose value is `!== undefined` are copied from a
+ * higher tier, so a preset that sets only `model` leaves `baseConfig.provider` intact.
+ *
+ * TOTAL by design: an `agentType` naming a missing preset returns `{ ...baseConfig }`
+ * rather than throwing. That path is unreachable after `assertKnownAgents` runs at
+ * create time, and a helper that threw on it would convert a validation gap into a
+ * mid-graph spawn crash.
+ */
+export declare function resolveTaskConfig(args: {
+    node: TaskNode;
+    baseConfig: AgentSessionConfig;
+    agentPresets: Record<string, WorkflowAgentPreset>;
+}): AgentSessionConfig;
+//# sourceMappingURL=workflow-agent-resolution.d.ts.map

package/dist/server/server/workflow/workflow-agent-resolution.js

@@ -0,0 +1,105 @@
+/**
+ * workflow-agent-resolution — Epic 2, Story 2.1.
+ *
+ * Per-step agent selection. Before this module every child of a workflow was spawned
+ * with the one graph-level `baseConfig`, so `TaskNode.agentType` was a declared field
+ * with no reader: delegation to a different agent per step was simply not supported.
+ * This module is that reader.
+ *
+ * Why it is PURE and lives outside `workflow-manager.ts` (the `workflow-progress.ts`
+ * precedent):
+ * - **Unit-testable with no harness.** Precedence is a function of three plain objects;
+ *   proving it should not require an `AgentManager`, a temp dir or a spawned child.
+ * - **The manager stays an orchestrator, not a calculator.** One helper serves BOTH
+ *   spawn call sites (`startWorkflow`'s readiness loop and `continueWorkflow`), so the
+ *   precedence rule exists exactly once.
+ * - **No runtime cycle.** Every import above is type-only and therefore erased, so the
+ *   manager can import this module as a VALUE. `WorkflowUnknownAgentError` is declared
+ *   here (the leaf) and re-exported from the manager, exactly as `WorkflowCycleError`
+ *   is declared in `workflow-progress.ts` and re-exported.
+ *
+ * Why the merge copies only DEFINED keys rather than spreading:
+ * `{ ...base, ...preset, ...override }` lets an explicit `undefined` in a higher tier
+ * ERASE a defined lower-tier value — `{ model: undefined }` on a task would blank the
+ * workflow's model instead of leaving it alone. A tier states what it overrides; a key
+ * it does not set must be invisible.
+ *
+ * Why `cwd` is forced back to `baseConfig.cwd` as the final statement:
+ * the working directory is workflow-owned. A step relocating its own child would break
+ * the containment every other surface assumes. There are two independent guards, on
+ * purpose: `WorkflowAgentPresetSchema` rejects `cwd` at parse time (so it can never
+ * arrive over the wire), and this assignment wins over any hand-built object literal
+ * that bypassed the schema.
+ *
+ * Determinism rules, mirroring `workflow-progress.ts`: synchronous, no I/O, no
+ * `Date.now()` / `new Date()`, no snapshot read, no module-level mutable state.
+ */
+/** Thrown when a task's `agentType` names an agent absent from the workflow's presets. */
+export class WorkflowUnknownAgentError extends Error {
+    constructor(workflowId, taskId, agentName, knownAgents) {
+        super(`Task ${taskId} names unknown agent '${agentName}'. Known agents: ${knownAgents.length > 0 ? [...knownAgents].sort().join(", ") : "none"}.`);
+        this.workflowId = workflowId;
+        this.taskId = taskId;
+        this.agentName = agentName;
+        this.knownAgents = knownAgents;
+        this.name = "WorkflowUnknownAgentError";
+    }
+}
+/**
+ * Create-time validation: reject a graph whose any task names an agent nobody defined.
+ *
+ * Reports the FIRST offender in `graph.tasks` array order, so the error is stable for
+ * a given graph rather than dependent on object-key iteration. The message names the
+ * task id, the unknown name and the known names, because both launch boundaries
+ * (`session.ts` RPC, `mcp-server.ts` tool) forward `error.message` verbatim to the
+ * operator and that string is the whole diagnosis.
+ *
+ * Own-key lookup, never a bare `in`: a preset named `toString` or `constructor` must
+ * not be satisfied by `Object.prototype`.
+ */
+export function assertKnownAgents(args) {
+    for (const task of args.graph.tasks) {
+        const agentName = task.agentType;
+        if (!agentName) {
+            continue;
+        }
+        if (!Object.prototype.hasOwnProperty.call(args.agentPresets, agentName)) {
+            throw new WorkflowUnknownAgentError(args.workflowId, task.id, agentName, Object.keys(args.agentPresets));
+        }
+    }
+}
+/**
+ * Resolve the `AgentSessionConfig` one task's child is spawned with.
+ *
+ * Precedence, lowest to highest: `baseConfig`, then `agentPresets[node.agentType]`,
+ * then `node.agentConfig`. Only keys whose value is `!== undefined` are copied from a
+ * higher tier, so a preset that sets only `model` leaves `baseConfig.provider` intact.
+ *
+ * TOTAL by design: an `agentType` naming a missing preset returns `{ ...baseConfig }`
+ * rather than throwing. That path is unreachable after `assertKnownAgents` runs at
+ * create time, and a helper that threw on it would convert a validation gap into a
+ * mid-graph spawn crash.
+ */
+export function resolveTaskConfig(args) {
+    const resolved = { ...args.baseConfig };
+    // Keyed write surface for the tier copy below. `AgentSessionConfig` has no index
+    // signature, so a per-key assignment needs this widening; the preset schema is a
+    // closed subset of that interface, so every key copied is a real config key.
+    const target = resolved;
+    const preset = args.node.agentType ? args.agentPresets[args.node.agentType] : undefined;
+    for (const tier of [preset, args.node.agentConfig]) {
+        if (!tier) {
+            continue;
+        }
+        for (const [key, value] of Object.entries(tier)) {
+            if (value !== undefined) {
+                target[key] = value;
+            }
+        }
+    }
+    // `cwd` is workflow-owned and never overridable. Two independent guards: the schema
+    // rejects `cwd` at parse time, and this assignment wins over any hand-built object.
+    resolved.cwd = args.baseConfig.cwd;
+    return resolved;
+}
+//# sourceMappingURL=workflow-agent-resolution.js.map

package/dist/server/server/workflow/workflow-feature.d.ts

@@ -0,0 +1,2 @@
+export declare const WORKFLOWS_FEATURE_ENABLED = true;
+//# sourceMappingURL=workflow-feature.d.ts.map

package/dist/server/server/workflow/workflow-feature.js

@@ -0,0 +1,8 @@
+// COMPAT(workflows): added in v0.1.X, remove gate after 2026-12-17.
+//
+// Single source of truth for the `workflows` capability. Both the `server_info`
+// handshake flag (`buildServerInfoStatusPayload()` in websocket-server.ts) and the
+// HTTP route gate (`registerWorkflowHttpRoutes` `featureEnabled`) read THIS constant,
+// so the advertised capability and the actually-served routes can never drift.
+export const WORKFLOWS_FEATURE_ENABLED = true;
+//# sourceMappingURL=workflow-feature.js.map

package/dist/server/server/workflow/workflow-http-routes.d.ts

@@ -0,0 +1,27 @@
+import type express from "express";
+import type pino from "pino";
+import type { WorkflowManager } from "./workflow-manager.js";
+/**
+ * Dependencies for the read-only `/api/workflows/*` HTTP surface.
+ *
+ * `featureEnabled` is the SAME boolean advertised as `server_info.features.workflows`
+ * (see `workflow-feature.ts`) — when it is `false`, every route 404s and no SSE
+ * stream is ever opened, so the advertised capability and the served routes cannot
+ * drift.
+ */
+export interface WorkflowHttpRoutesDeps {
+    manager: WorkflowManager;
+    featureEnabled: boolean;
+}
+/**
+ * Register the daemon's read-only workflow HTTP routes on the existing Express app,
+ * mirroring the `registerPushRoutes` / `registerWorkspaceSessionsRoute` convention.
+ * No second listener or port — these attach to the shared `app`.
+ *
+ * Routes:
+ * - `GET /api/workflows/status`      → JSON array of workflow summaries.
+ * - `GET /api/workflows/:id`         → single workflow JSON, 404 on unknown id.
+ * - `GET /api/workflows/:id/events`  → SSE stream of phase transitions for that id.
+ */
+export declare function registerWorkflowHttpRoutes(app: express.Express, deps: WorkflowHttpRoutesDeps, logger: pino.Logger): void;
+//# sourceMappingURL=workflow-http-routes.d.ts.map

package/dist/server/server/workflow/workflow-http-routes.js

@@ -0,0 +1,97 @@
+import { WorkflowNotFoundError } from "./workflow-manager.js";
+/**
+ * Register the daemon's read-only workflow HTTP routes on the existing Express app,
+ * mirroring the `registerPushRoutes` / `registerWorkspaceSessionsRoute` convention.
+ * No second listener or port — these attach to the shared `app`.
+ *
+ * Routes:
+ * - `GET /api/workflows/status`      → JSON array of workflow summaries.
+ * - `GET /api/workflows/:id`         → single workflow JSON, 404 on unknown id.
+ * - `GET /api/workflows/:id/events`  → SSE stream of phase transitions for that id.
+ */
+export function registerWorkflowHttpRoutes(app, deps, logger) {
+    const { manager, featureEnabled } = deps;
+    const routeLogger = logger.child({ component: "workflow-http-routes" });
+    // GET /api/workflows/status — array of summaries (empty list ⇒ []). Registered
+    // before `/:id` so the literal path wins over the param route.
+    app.get("/api/workflows/status", (_req, res) => {
+        if (!featureEnabled) {
+            res.status(404).json({ error: "workflows feature not enabled" });
+            return;
+        }
+        void (async () => {
+            try {
+                const workflows = await manager.listWorkflows();
+                res.json(workflows);
+            }
+            catch (err) {
+                routeLogger.error({ err }, "failed to list workflows");
+                res.status(500).json({ error: "failed to list workflows" });
+            }
+        })();
+    });
+    // GET /api/workflows/:id — single workflow; unknown id ⇒ 404 JSON (never 5xx).
+    app.get("/api/workflows/:id", (req, res) => {
+        if (!featureEnabled) {
+            res.status(404).json({ error: "workflows feature not enabled" });
+            return;
+        }
+        void (async () => {
+            const { id } = req.params;
+            try {
+                const workflow = await manager.getWorkflow(id);
+                res.json(workflow);
+            }
+            catch (err) {
+                if (err instanceof WorkflowNotFoundError) {
+                    res.status(404).json({ error: "workflow not found" });
+                    return;
+                }
+                routeLogger.error({ err, id }, "failed to get workflow");
+                res.status(500).json({ error: "failed to get workflow" });
+            }
+        })();
+    });
+    // GET /api/workflows/:id/events — SSE phase-transition stream. The single
+    // load-bearing rule: every subscribe() has a matching unsubscribe() in the
+    // "close" handler (the leak guard).
+    app.get("/api/workflows/:id/events", (req, res) => {
+        if (!featureEnabled) {
+            res.status(404).json({ error: "workflows feature not enabled" });
+            return;
+        }
+        void (async () => {
+            const { id } = req.params;
+            // Resolve first — an unknown id 404s BEFORE any stream is opened.
+            try {
+                await manager.getWorkflow(id);
+            }
+            catch (err) {
+                if (err instanceof WorkflowNotFoundError) {
+                    res.status(404).json({ error: "workflow not found" });
+                    return;
+                }
+                routeLogger.error({ err, id }, "failed to resolve workflow for SSE");
+                res.status(500).json({ error: "failed to get workflow" });
+                return;
+            }
+            res.setHeader("Content-Type", "text/event-stream");
+            res.setHeader("Cache-Control", "no-cache");
+            res.setHeader("Connection", "keep-alive");
+            res.flushHeaders();
+            const unsubscribe = manager.subscribe((event) => {
+                // The route is id-scoped — only stream transitions for THIS workflow.
+                if (event.workflow.id !== id) {
+                    return;
+                }
+                res.write(`data: ${JSON.stringify(event)}\n\n`);
+            });
+            req.on("close", () => {
+                unsubscribe();
+                res.end();
+            });
+        })();
+    });
+    routeLogger.info("Registered GET /api/workflows/status, /api/workflows/:id, /api/workflows/:id/events");
+}
+//# sourceMappingURL=workflow-http-routes.js.map