hivehq 2.0.0

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

@@ -0,0 +1,15 @@
+/**
+ * Workflow experimental feature gate.
+ *
+ * Workflows (`team workflow run`, the scheduler, the UI drawer, and the chunk
+ * of orchestrator guidance that teaches them) are a power feature with sharp
+ * edges — runaway fan-outs, authoring footguns, no run-resume yet. They ship
+ * OFF by default; a user opts in from Settings. While off, the orchestrator is
+ * not even taught about workflows, which also keeps its always-on prompt lean.
+ *
+ * Stored GLOBALLY in `app_state` under WORKFLOW_ENABLED_KEY. Absent / anything
+ * other than the exact string "true" reads back as DISABLED.
+ */
+export const WORKFLOW_ENABLED_KEY = 'workflow.enabled';
+export const readWorkflowEnabled = (raw) => raw === 'true';
+export const serializeWorkflowEnabled = (enabled) => (enabled ? 'true' : 'false');

package/dist/src/server/workflow-http-serializers.d.ts

@@ -0,0 +1,64 @@
+import type { LiveAgentRun } from './agent-runtime-types.js';
+import type { DispatchRecord } from './dispatch-ledger-store.js';
+import type { WorkflowRunRecord } from './workflow-run-store.js';
+import type { WorkflowScheduleRecord } from './workflow-schedule-store.js';
+export declare const serializeLiveAgentRun: (run: LiveAgentRun) => {
+    agent_id: string;
+    exit_code: number | null;
+    output: string;
+    pid: number | null;
+    run_id: string;
+    started_at: number;
+    status: import("./agent-manager.js").RunStatus;
+};
+export declare const serializeWorkflowRun: (run: WorkflowRunRecord) => {
+    agent_count: number;
+    args: unknown;
+    created_at: number;
+    error: string | null;
+    finished_at: number | null;
+    id: string;
+    name: string;
+    parent_run_id: string | null;
+    phase: string | null;
+    result: unknown;
+    script_hash: string | null;
+    script_path: string;
+    started_at: number;
+    status: import("./workflow-run-store.js").WorkflowRunStatus;
+    workspace_id: string;
+};
+export declare const serializeWorkflowDispatch: (dispatch: DispatchRecord & {
+    lastPtyLine?: string;
+}) => {
+    artifacts: string[];
+    created_at: number;
+    delivered_at: number | null;
+    from_agent_id: string | null;
+    id: string;
+    label: string | null;
+    last_pty_line: string | null;
+    phase: string | null;
+    reported_at: number | null;
+    report_text: string | null;
+    sequence: number | null;
+    status: import("./dispatch-ledger-store.js").DispatchStatus;
+    step_index: number | null;
+    submitted_at: number | null;
+    text: string;
+    to_agent_id: string;
+    workflow_run_id: string | null;
+    workspace_id: string;
+};
+export declare const serializeWorkflowSchedule: (schedule: WorkflowScheduleRecord) => {
+    args: unknown;
+    created_at: number;
+    cron: string;
+    enabled: boolean;
+    id: string;
+    last_run_at: number | null;
+    next_run_at: number;
+    script_path: string;
+    updated_at: number;
+    workspace_id: string;
+};

package/dist/src/server/workflow-http-serializers.js

@@ -0,0 +1,58 @@
+export const serializeLiveAgentRun = (run) => ({
+    agent_id: run.agentId,
+    exit_code: run.exitCode,
+    output: run.output,
+    pid: run.pid,
+    run_id: run.runId,
+    started_at: run.startedAt,
+    status: run.status,
+});
+export const serializeWorkflowRun = (run) => ({
+    agent_count: run.agentCount,
+    args: run.args,
+    created_at: run.createdAt,
+    error: run.error,
+    finished_at: run.finishedAt,
+    id: run.id,
+    name: run.name,
+    parent_run_id: run.parentRunId,
+    phase: run.phase,
+    result: run.result,
+    script_hash: run.scriptHash,
+    script_path: run.scriptPath,
+    started_at: run.startedAt,
+    status: run.status,
+    workspace_id: run.workspaceId,
+});
+export const serializeWorkflowDispatch = (dispatch) => ({
+    artifacts: dispatch.artifacts,
+    created_at: dispatch.createdAt,
+    delivered_at: dispatch.deliveredAt,
+    from_agent_id: dispatch.fromAgentId,
+    id: dispatch.id,
+    label: dispatch.label,
+    last_pty_line: dispatch.lastPtyLine ?? null,
+    phase: dispatch.phase,
+    reported_at: dispatch.reportedAt,
+    report_text: dispatch.reportText,
+    sequence: dispatch.sequence,
+    status: dispatch.status,
+    step_index: dispatch.stepIndex,
+    submitted_at: dispatch.submittedAt,
+    text: dispatch.text,
+    to_agent_id: dispatch.toAgentId,
+    workflow_run_id: dispatch.workflowRunId,
+    workspace_id: dispatch.workspaceId,
+});
+export const serializeWorkflowSchedule = (schedule) => ({
+    args: schedule.args,
+    created_at: schedule.createdAt,
+    cron: schedule.cron,
+    enabled: schedule.enabled,
+    id: schedule.id,
+    last_run_at: schedule.lastRunAt,
+    next_run_at: schedule.nextRunAt,
+    script_path: schedule.scriptPath,
+    updated_at: schedule.updatedAt,
+    workspace_id: schedule.workspaceId,
+});

package/dist/src/server/workflow-output-schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Opt-in structured output for the workflow DSL `agent()` call. When a script
+ * passes `outputSchema`, the runner appends an instruction asking the worker to
+ * end its report with a fenced ```json block, then parses that block so the
+ * script gets an object instead of brittle free-text. Kept deliberately LIGHT:
+ * no schema validation library, no retry — the keys are advisory, and a parse
+ * miss falls back to `{ text }` in the runner so a script can always branch on
+ * a missing field (the documented safe-default discipline).
+ */
+/**
+ * Extract and parse the LAST fenced json block in a report. Workers often emit
+ * a reasoning block then a final answer block, so the last one wins. Returns
+ * null on no block / invalid JSON / a non-object payload (so the caller's
+ * `?? { text }` fallback fires) rather than throwing.
+ */
+export declare const extractJsonBlock: (text: string) => Record<string, unknown> | null;
+/** The terse instruction appended to the worker prompt when a schema is set. */
+export declare const buildSchemaInstruction: (schema: Record<string, unknown>) => string;

package/dist/src/server/workflow-output-schema.js

@@ -0,0 +1,41 @@
+/**
+ * Opt-in structured output for the workflow DSL `agent()` call. When a script
+ * passes `outputSchema`, the runner appends an instruction asking the worker to
+ * end its report with a fenced ```json block, then parses that block so the
+ * script gets an object instead of brittle free-text. Kept deliberately LIGHT:
+ * no schema validation library, no retry — the keys are advisory, and a parse
+ * miss falls back to `{ text }` in the runner so a script can always branch on
+ * a missing field (the documented safe-default discipline).
+ */
+/**
+ * Extract and parse the LAST fenced json block in a report. Workers often emit
+ * a reasoning block then a final answer block, so the last one wins. Returns
+ * null on no block / invalid JSON / a non-object payload (so the caller's
+ * `?? { text }` fallback fires) rather than throwing.
+ */
+export const extractJsonBlock = (text) => {
+    const matches = [...text.matchAll(/```(?:json)?[ \t]*\r?\n?([\s\S]*?)```/g)];
+    const last = matches.at(-1)?.[1];
+    if (last === undefined)
+        return null;
+    try {
+        const parsed = JSON.parse(last.trim());
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** The terse instruction appended to the worker prompt when a schema is set. */
+export const buildSchemaInstruction = (schema) => {
+    const keys = Object.keys(schema);
+    const keyList = keys.length > 0 ? keys.join(', ') : '(see the task)';
+    return [
+        '',
+        'When you are done, end your report with a single fenced ```json block as the LAST thing in your message.',
+        `That JSON object should use these keys: ${keyList}.`,
+        'If you cannot determine a field, omit it — the caller treats a missing field as the safe default.',
+    ].join('\n');
+};

package/dist/src/server/workflow-run-log-store.d.ts

@@ -0,0 +1,19 @@
+import type { Database } from 'better-sqlite3';
+export interface WorkflowRunLogRecord {
+    id: number;
+    runId: string;
+    ts: number;
+    message: string;
+}
+export declare const createWorkflowRunLogStore: (db: Database) => {
+    append(runId: string, message: string, ts?: number): void;
+    listForRun(runId: string): WorkflowRunLogRecord[];
+    /** Last `n` log messages for the run, oldest-first. Used by the
+     *  onRunFinished reminder to include a short narrator tail in the
+     *  orchestrator's completion notification without overwhelming it. */
+    tailForRun(runId: string, n: number): string[];
+    deleteForRun(runId: string): void;
+    /** Cascade hook: deleted alongside workflow_runs when a workspace
+     *  is removed (TIER 1 #4 cascade). */
+    deleteForWorkspace(workspaceId: string): void;
+};

package/dist/src/server/workflow-run-log-store.js

@@ -0,0 +1,45 @@
+/* TIER 2 #3 — narrator lane storage. `log()` calls from a workflow script
+ * append here; the Drawer polls listForRun(runId) alongside the dispatch
+ * timeline; the orchestrator's completion reminder splices in the last
+ * few lines so a run that finished with a long sequence of `log()` calls
+ * can be summarised back to the user.
+ *
+ * Append-only. No retention policy yet — TIER 3 work if log volume grows
+ * to where it matters; CC's Workflow tool keeps logs for the run's
+ * lifetime so we mirror that. */
+export const createWorkflowRunLogStore = (db) => {
+    const insert = db.prepare('INSERT INTO workflow_run_logs (run_id, ts, message) VALUES (?, ?, ?)');
+    const listStmt = db.prepare('SELECT id, run_id, ts, message FROM workflow_run_logs WHERE run_id = ? ORDER BY id');
+    const tailStmt = db.prepare('SELECT message FROM workflow_run_logs WHERE run_id = ? ORDER BY id DESC LIMIT ?');
+    const deleteForRunStmt = db.prepare('DELETE FROM workflow_run_logs WHERE run_id = ?');
+    const deleteForWorkspaceStmt = db.prepare(`DELETE FROM workflow_run_logs
+     WHERE run_id IN (SELECT id FROM workflow_runs WHERE workspace_id = ?)`);
+    return {
+        append(runId, message, ts = Date.now()) {
+            insert.run(runId, ts, message);
+        },
+        listForRun(runId) {
+            return listStmt.all(runId).map((row) => ({
+                id: row.id,
+                runId: row.run_id,
+                ts: row.ts,
+                message: row.message,
+            }));
+        },
+        /** Last `n` log messages for the run, oldest-first. Used by the
+         *  onRunFinished reminder to include a short narrator tail in the
+         *  orchestrator's completion notification without overwhelming it. */
+        tailForRun(runId, n) {
+            const rows = tailStmt.all(runId, n);
+            return rows.map((r) => r.message).reverse();
+        },
+        deleteForRun(runId) {
+            deleteForRunStmt.run(runId);
+        },
+        /** Cascade hook: deleted alongside workflow_runs when a workspace
+         *  is removed (TIER 1 #4 cascade). */
+        deleteForWorkspace(workspaceId) {
+            deleteForWorkspaceStmt.run(workspaceId);
+        },
+    };
+};

package/dist/src/server/workflow-run-store.d.ts

@@ -0,0 +1,50 @@
+import type { Database } from 'better-sqlite3';
+export type WorkflowRunStatus = 'running' | 'completed' | 'failed' | 'interrupted' | 'stopped';
+export interface WorkflowRunRecord {
+    id: string;
+    workspaceId: string;
+    scriptPath: string;
+    scriptHash: string | null;
+    name: string;
+    status: WorkflowRunStatus;
+    phase: string | null;
+    args: unknown;
+    result: unknown;
+    startedAt: number;
+    finishedAt: number | null;
+    error: string | null;
+    createdAt: number;
+    /** Count of `agent()` calls dispatched by this run. TIER 1 #14 — lets the
+     *  Drawer show "12 agents" on the row without an extra round-trip per
+     *  expand. Cheap subquery against the indexed workflow_run_id column. */
+    agentCount: number;
+    /** TIER 2 #5: parent workflow run id for nested workflow() calls.
+     *  Null on top-level runs. The Drawer uses this to render a child run
+     *  indented under its parent (and to collapse/expand together). */
+    parentRunId: string | null;
+}
+interface CreateRunInput {
+    workspaceId: string;
+    scriptPath: string;
+    name: string;
+    scriptHash?: string;
+    args?: unknown;
+    /** TIER 2 #5 — set when this run is being created from a nested
+     *  workflow() call. Null/omitted for top-level runs. */
+    parentRunId?: string | null;
+}
+interface UpdateRunInput {
+    status?: WorkflowRunStatus;
+    phase?: string;
+    finishedAt?: number;
+    error?: string;
+    result?: unknown;
+}
+export declare const createWorkflowRunStore: (db: Database) => {
+    createRun: (input: CreateRunInput) => WorkflowRunRecord;
+    updateRun: (id: string, input: UpdateRunInput) => void;
+    getRun: (id: string) => WorkflowRunRecord | undefined;
+    listWorkspaceRuns: (workspaceId: string) => WorkflowRunRecord[];
+    markUnfinishedRunsInterrupted: () => void;
+};
+export {};

package/dist/src/server/workflow-run-store.js

@@ -0,0 +1,103 @@
+import { randomUUID } from 'node:crypto';
+const parseArgs = (value) => {
+    if (!value)
+        return null;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+};
+const toRecord = (row) => ({
+    id: row.id,
+    workspaceId: row.workspace_id,
+    scriptPath: row.script_path,
+    scriptHash: row.script_hash,
+    name: row.name,
+    status: row.status,
+    phase: row.phase,
+    args: parseArgs(row.args),
+    result: parseArgs(row.result),
+    startedAt: row.started_at,
+    finishedAt: row.finished_at,
+    error: row.error,
+    createdAt: row.created_at,
+    agentCount: Number(row.agent_count ?? 0),
+    parentRunId: row.parent_run_id ?? null,
+});
+// Selects every workflow_runs column plus the agent_count subquery; used by
+// both getRun and listWorkspaceRuns so the WorkflowRunRecord shape is
+// uniform regardless of which path produced it.
+const SELECT_RUN_COLUMNS = 'workflow_runs.*, ' +
+    '(SELECT COUNT(*) FROM dispatches WHERE dispatches.workflow_run_id = workflow_runs.id) AS agent_count';
+export const createWorkflowRunStore = (db) => {
+    const createRun = (input) => {
+        const now = Date.now();
+        const record = {
+            id: randomUUID(),
+            workspaceId: input.workspaceId,
+            scriptPath: input.scriptPath,
+            scriptHash: input.scriptHash ?? null,
+            name: input.name,
+            status: 'running',
+            phase: null,
+            args: input.args ?? null,
+            result: null,
+            startedAt: now,
+            finishedAt: null,
+            error: null,
+            createdAt: now,
+            agentCount: 0,
+            parentRunId: input.parentRunId ?? null,
+        };
+        db.prepare(`INSERT INTO workflow_runs (
+        id, workspace_id, script_path, script_hash, name, status, phase, args,
+        started_at, finished_at, error, created_at, parent_run_id
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(record.id, record.workspaceId, record.scriptPath, record.scriptHash, record.name, record.status, record.phase, record.args === null ? null : JSON.stringify(record.args), record.startedAt, record.finishedAt, record.error, record.createdAt, record.parentRunId);
+        return record;
+    };
+    const updateRun = (id, input) => {
+        const sets = [];
+        const values = [];
+        if (input.status !== undefined) {
+            sets.push('status = ?');
+            values.push(input.status);
+        }
+        if (input.phase !== undefined) {
+            sets.push('phase = ?');
+            values.push(input.phase);
+        }
+        if (input.finishedAt !== undefined) {
+            sets.push('finished_at = ?');
+            values.push(input.finishedAt);
+        }
+        if (input.error !== undefined) {
+            sets.push('error = ?');
+            values.push(input.error);
+        }
+        if (input.result !== undefined) {
+            sets.push('result = ?');
+            values.push(input.result === null ? null : JSON.stringify(input.result));
+        }
+        if (sets.length === 0)
+            return;
+        values.push(id);
+        db.prepare(`UPDATE workflow_runs SET ${sets.join(', ')} WHERE id = ?`).run(...values);
+    };
+    const getRun = (id) => {
+        const row = db
+            .prepare(`SELECT ${SELECT_RUN_COLUMNS} FROM workflow_runs WHERE id = ?`)
+            .get(id);
+        return row ? toRecord(row) : undefined;
+    };
+    const listWorkspaceRuns = (workspaceId) => db
+        .prepare(`SELECT ${SELECT_RUN_COLUMNS} FROM workflow_runs WHERE workspace_id = ? ORDER BY created_at DESC, id DESC`)
+        .all(workspaceId).map(toRecord);
+    // Boot sweep: a run still 'running' after a restart can never resume, so mark
+    // it interrupted (spec §13 — the UI offers Resume; we never auto-resume).
+    const markUnfinishedRunsInterrupted = () => {
+        db.prepare("UPDATE workflow_runs SET status = 'interrupted', finished_at = ? WHERE status = 'running'").run(Date.now());
+    };
+    return { createRun, updateRun, getRun, listWorkspaceRuns, markUnfinishedRunsInterrupted };
+};

package/dist/src/server/workflow-runner.d.ts

@@ -0,0 +1,147 @@
+import type { WorkerRole } from '../shared/types.js';
+import type { AgentLaunchConfigInput } from './agent-run-store.js';
+import { type WorkflowCliPolicy } from './workflow-cli-policy.js';
+import type { WorkflowDispatchAwaiter } from './workflow-dispatch-awaiter.js';
+import type { WorkflowRunRecord, WorkflowRunStatus } from './workflow-run-store.js';
+export interface RunWorkflowInput {
+    workspaceId: string;
+    scriptPath: string;
+    hivePort: string;
+    args?: unknown;
+    /** Agent (usually the orchestrator) that fired this workflow; the runner
+     *  notifies its PTY when the run finishes. Optional — workflows fired by
+     *  cron / UI have no triggering agent. */
+    triggeredByAgentId?: string;
+    /** TIER 2 #5 — set internally when the runner is spawning a nested
+     *  workflow() from inside another run. External callers leave it
+     *  undefined; the row goes in as a top-level run. */
+    parentRunId?: string | null;
+}
+export interface RunInlineWorkflowInput {
+    workspaceId: string;
+    source: string;
+    /** Synthetic path stamped into workflow_runs.script_path for display only;
+     *  no file is read or written. Defaults to `<inline>` if omitted. */
+    scriptPath?: string;
+    hivePort: string;
+    args?: unknown;
+    triggeredByAgentId?: string;
+}
+/** TIER 2 #4 — narrow port the runner needs to clone a custom role
+ *  into an ephemeral worker. Returns `undefined` if the name doesn't
+ *  match any template (built-in or custom); the runner falls back to
+ *  built-in-role semantics in that case. */
+export interface RoleTemplateResolver {
+    findByName(name: string): {
+        name: string;
+        roleType: WorkerRole | 'orchestrator';
+        defaultCommand: string;
+        defaultArgs: string[];
+    } | undefined;
+}
+interface RunnerStorePort {
+    addWorkerWithLaunch: (workspaceId: string, input: {
+        name: string;
+        role: WorkerRole;
+        ephemeral: true;
+        spawnedBy: 'workflow';
+    }, launchConfig: AgentLaunchConfigInput) => {
+        id: string;
+        name: string;
+    };
+    startAgent: (workspaceId: string, agentId: string, input: {
+        hivePort: string;
+    }) => Promise<unknown>;
+    dispatchTaskByWorkerName: (workspaceId: string, workerName: string, text: string, input: {
+        fromAgentId: string;
+        hivePort: string;
+        workflowRunId: string;
+        stepIndex: number;
+        phase?: string;
+        label?: string;
+    }) => Promise<{
+        id: string;
+    }>;
+    deleteWorker: (workspaceId: string, workerId: string) => void;
+}
+/** TIER 2 #3 — narrator lane sink. The runner calls append(runId, message)
+ *  every time the script invokes log(). Implementation lives in
+ *  workflow-run-log-store; the port keeps the runner free of DB types. */
+export interface WorkflowRunLogPort {
+    append(runId: string, message: string, ts?: number): void;
+}
+interface WorkflowRunStorePort {
+    createRun: (input: {
+        workspaceId: string;
+        scriptPath: string;
+        name: string;
+        scriptHash?: string;
+        args?: unknown;
+        parentRunId?: string | null;
+    }) => WorkflowRunRecord;
+    updateRun: (id: string, input: {
+        status?: WorkflowRunStatus;
+        phase?: string;
+        finishedAt?: number;
+        error?: string;
+        result?: unknown;
+    }) => void;
+    getRun: (id: string) => WorkflowRunRecord | undefined;
+}
+export interface WorkflowRunner {
+    /** Runs the script to completion; returns the FINAL record. Used by tests
+     *  and any caller that wants to wait synchronously. */
+    runWorkflow: (input: RunWorkflowInput) => Promise<WorkflowRunRecord>;
+    /** Creates the run row + kicks off execution in the background; returns the
+     *  INITIAL ('running') record. Used by the HTTP route so the response is
+     *  fast — clients poll `getWorkflowRun(id)` for progress. */
+    startWorkflow: (input: RunWorkflowInput) => Promise<WorkflowRunRecord>;
+    /** Like startWorkflow but takes raw source (no file). Used by `team workflow
+     *  run --stdin/--inline` so the orchestrator can fire workflows from a PTY
+     *  without writing a file first — matches Claude Code's Workflow tool
+     *  invocation model. */
+    startWorkflowInline: (input: RunInlineWorkflowInput) => Promise<WorkflowRunRecord>;
+    /** Cancel any in-flight `agent()` calls for `runId` (rejects their awaiters)
+     *  and mark the next executeWorkflow catch as 'stopped' instead of 'failed'.
+     *  Returns true if the run was running and got stopped, false otherwise. */
+    stopRun: (runId: string) => boolean;
+}
+interface ListDispatchesForStopPort {
+    listOpenDispatchIdsForRun: (runId: string) => string[];
+}
+export declare const createWorkflowRunner: (deps: {
+    store: RunnerStorePort;
+    workflowRunStore: WorkflowRunStorePort;
+    awaiter: WorkflowDispatchAwaiter;
+    dispatchPort: ListDispatchesForStopPort;
+    /** Resolves the workspace's on-disk path. The nested `workflow(name)` DSL
+     *  call needs it to locate sibling scripts when the parent run was fired
+     *  inline via `team workflow run --stdin` (TIER 1 #7) — its scriptPath is
+     *  a synthetic `<inline>` token that dirname() can't traverse. */
+    resolveWorkspacePath: (workspaceId: string) => string;
+    /** TIER 2 #4 — used when agent() opts.agentType isn't a built-in role.
+     *  The runner asks the resolver for a matching custom template; on hit
+     *  the template's command + args replace the defaults, on miss the
+     *  runner throws a clear error rather than silently spawning claude. */
+    roleTemplateResolver: RoleTemplateResolver;
+    /** TIER 2 #3 — sink for the script's `log()` calls. The runner used
+     *  to drop them on server stdout; routing through this port lets the
+     *  Drawer render them as a narrator lane and the completion
+     *  reminder splice the tail into the orchestrator's notification. */
+    logStore: WorkflowRunLogPort;
+    /** Global workflow CLI policy (default + allowlist). Replaces the old
+     *  hard-coded `claude` default: an `agent()` that omits `cli` now uses
+     *  the user's configured default, and an explicit `cli` outside the
+     *  allowlist fails the call with a clear, fixable error. */
+    getWorkflowCliPolicy: () => WorkflowCliPolicy;
+    /** Called when a run reaches a terminal state (completed/failed/stopped).
+     *  The runtime uses this to inject a `<hive-system-reminder>` into the
+     *  triggering agent's PTY so the orchestrator picks the result back up,
+     *  mirroring Claude Code's `<task-notification>` flow. */
+    onRunFinished?: (input: {
+        runId: string;
+        triggeredByAgentId: string;
+        finalRecord: WorkflowRunRecord;
+    }) => void;
+}) => WorkflowRunner;
+export {};