@tt-a1i/hive 1.4.4 → 1.5.0

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 {};

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

@@ -0,0 +1,401 @@
+import { randomUUID } from 'node:crypto';
+import { cpus } from 'node:os';
+import { dirname, join } from 'node:path';
+import { assertWindowsSafeFilename } from './windows-filename.js';
+import { resolveWorkflowCli } from './workflow-cli-policy.js';
+import { loadWorkflowScriptFile, loadWorkflowScriptSource } from './workflow-script-loader.js';
+import { getWorkflowAgentId } from './workspace-store-support.js';
+// TIER 2 #2 + #11 — runtime caps. Match Claude Code's documented caps
+// (1000 lifetime calls, min(16, cores-2) concurrent) so scripts copied
+// from CC docs behave the same way. The duration default is Hive's own
+// choice; CC docs don't specify one but workflows that run >60min are
+// almost always a runaway loop in practice.
+const DEFAULT_MAX_AGENTS_PER_RUN = 1000;
+const DEFAULT_MAX_DURATION_MS = 60 * 60 * 1000;
+const DEFAULT_MAX_CONCURRENT_AGENTS = Math.min(16, Math.max(2, cpus().length - 2));
+const BUILT_IN_WORKER_ROLES = new Set(['coder', 'reviewer', 'tester', 'custom']);
+const isBuiltInWorkerRole = (value) => BUILT_IN_WORKER_ROLES.has(value);
+const buildModelArgs = (_cli, model) => {
+    if (!model?.trim())
+        return [];
+    /* All four supported CLIs (claude / codex / opencode / gemini) accept
+       `--model <id>` as a positional flag. Keeping the mapping centralised
+       here so future CLI quirks (e.g. opencode wanting `-m` instead) can
+       be patched without touching the runner body. */
+    return ['--model', model];
+};
+const toNestedWorkflowFilename = (scriptName) => {
+    const trimmed = scriptName.trim();
+    if (!trimmed)
+        throw new Error('workflow(scriptName): scriptName must be a non-empty string');
+    const filename = trimmed.toLowerCase().endsWith('.ts') ? trimmed : `${trimmed}.ts`;
+    assertWindowsSafeFilename(filename);
+    return filename;
+};
+export const createWorkflowRunner = (deps) => {
+    const { store, workflowRunStore, awaiter, dispatchPort, resolveWorkspacePath, roleTemplateResolver, logStore, getWorkflowCliPolicy, } = deps;
+    const stoppedRuns = new Set();
+    // In-memory map: runId → triggering agent. Lost on restart; the spec already
+    // doesn't auto-resume interrupted runs, so this is consistent.
+    const triggeringAgentByRun = new Map();
+    const executeWorkflow = async (run, loaded, args, hivePort) => {
+        const workspaceId = run.workspaceId;
+        const workflowAgentId = getWorkflowAgentId(workspaceId);
+        let stepCounter = 0;
+        const spawnedWorkers = [];
+        // Read the CLI policy once per run so a 1000-way fan-out doesn't hit the
+        // app_state table per agent() call.
+        const cliPolicy = getWorkflowCliPolicy();
+        // TIER 2 #2 + #11 — runtime caps. Per-run agent ceiling, per-call
+        // concurrency throttle, and a hard wall-clock budget. meta can
+        // override the defaults per script. The budget timer arms here and
+        // gets cleared in the finally branch so a fast-completing run
+        // doesn't leave a dangling timer in the event loop.
+        const maxAgents = typeof loaded.meta.maxAgentCalls === 'number' && loaded.meta.maxAgentCalls > 0
+            ? loaded.meta.maxAgentCalls
+            : DEFAULT_MAX_AGENTS_PER_RUN;
+        const maxDurationMs = typeof loaded.meta.maxDurationMs === 'number' && loaded.meta.maxDurationMs > 0
+            ? loaded.meta.maxDurationMs
+            : DEFAULT_MAX_DURATION_MS;
+        // Simple semaphore — a FIFO queue of resolvers. Each acquire() returns
+        // a release() callback that pumps the next waiter. Default
+        // concurrency is min(16, cores-2), matching CC's documented cap;
+        // intentionally shared across all parallel/pipeline calls in this
+        // run so nested fan-outs don't blow through the cap.
+        const concurrencyLimit = DEFAULT_MAX_CONCURRENT_AGENTS;
+        let inFlight = 0;
+        const waitQueue = [];
+        const acquireSlot = async () => {
+            if (inFlight < concurrencyLimit) {
+                inFlight++;
+                return () => {
+                    inFlight--;
+                    waitQueue.shift()?.();
+                };
+            }
+            await new Promise((resolve) => waitQueue.push(resolve));
+            inFlight++;
+            return () => {
+                inFlight--;
+                waitQueue.shift()?.();
+            };
+        };
+        // R1/R2 auto-rounding: a phase('Find') called twice in the same run gets
+        // rendered as "Find" then "Find R2" etc. Mirrors Claude Code's /workflows
+        // view — keeps the UI readable when a workflow loops phases.
+        const phaseEntryCount = new Map();
+        let currentPhaseTitle = null;
+        const phase = (title) => {
+            const trimmed = (title ?? '').toString().trim() || 'default';
+            const next = (phaseEntryCount.get(trimmed) ?? 0) + 1;
+            phaseEntryCount.set(trimmed, next);
+            currentPhaseTitle = next > 1 ? `${trimmed} R${next}` : trimmed;
+            workflowRunStore.updateRun(run.id, { phase: currentPhaseTitle });
+        };
+        const agent = async (prompt, opts = {}) => {
+            // TIER 2 #11 — hard ceiling so a runaway `while (true) await agent()`
+            // can't spawn unbounded PTY subprocesses. The check is BEFORE the
+            // step counter increments so the error message names the cap, not
+            // the over-cap step.
+            if (stepCounter >= maxAgents) {
+                throw new Error(`Workflow agent cap exceeded: ${maxAgents} calls (set meta.maxAgentCalls to raise)`);
+            }
+            const myStep = ++stepCounter;
+            // TIER 2 #4 — resolve agentType. If it's a built-in WorkerRole
+            // (coder/reviewer/tester/custom) we honour it directly with the
+            // CLI default. Otherwise look up a workspace custom role template
+            // by name: on hit we clone its command + args; on miss we throw a
+            // clear error (silent fallback to 'coder' would mask typos and
+            // make the Hive-distinctive custom-role library invisible).
+            const requestedType = opts.agentType ?? 'coder';
+            let role;
+            let command;
+            let templateArgs = [];
+            if (typeof requestedType === 'string' && !isBuiltInWorkerRole(requestedType)) {
+                const template = roleTemplateResolver.findByName(requestedType);
+                if (!template) {
+                    throw new Error(`Workflow agentType '${requestedType}' is not a built-in role (coder/reviewer/tester/custom) and no matching role template exists in this workspace. ` +
+                        `Create one via Add Worker → custom role, or use a built-in role.`);
+                }
+                /* Templates can carry roleType='orchestrator' for the system-level
+                   Orchestrator template; that's not a valid workflow worker role,
+                   so we collapse it to 'custom'. Anything else maps through as-is. */
+                role = template.roleType === 'orchestrator' ? 'custom' : template.roleType;
+                command = resolveWorkflowCli({
+                    ...(opts.cli !== undefined ? { requestedCli: opts.cli } : {}),
+                    isCustomTemplate: true,
+                    templateDefaultCommand: template.defaultCommand,
+                    policy: cliPolicy,
+                });
+                templateArgs = template.defaultArgs;
+            }
+            else {
+                role = requestedType;
+                command = resolveWorkflowCli({
+                    ...(opts.cli !== undefined ? { requestedCli: opts.cli } : {}),
+                    isCustomTemplate: false,
+                    policy: cliPolicy,
+                });
+            }
+            const name = opts.label ?? `${requestedType}-${myStep}-${randomUUID()}`;
+            /* Model flag goes AFTER the template's own args so an explicit
+               opts.model overrides any --model the template baked in. */
+            const launchArgs = [...templateArgs, ...buildModelArgs(command, opts.model)];
+            // TIER 2 #2 — semaphore. Holding the slot across the full
+            // dispatch+await means a parallel(100) fan-out gets paced at
+            // min(16, cores-2) concurrent PTYs instead of 100 simultaneous
+            // process spawns.
+            const releaseSlot = await acquireSlot();
+            const worker = store.addWorkerWithLaunch(workspaceId, { name, role, ephemeral: true, spawnedBy: 'workflow' }, { command, args: launchArgs });
+            spawnedWorkers.push(worker.id);
+            try {
+                await store.startAgent(workspaceId, worker.id, { hivePort });
+                const dispatch = await store.dispatchTaskByWorkerName(workspaceId, name, prompt, {
+                    fromAgentId: workflowAgentId,
+                    hivePort,
+                    workflowRunId: run.id,
+                    stepIndex: myStep,
+                    ...(currentPhaseTitle ? { phase: currentPhaseTitle } : {}),
+                    label: opts.label ?? name,
+                });
+                const report = await awaiter.awaitReport(dispatch.id, opts.timeoutMs);
+                return report.text;
+            }
+            finally {
+                try {
+                    store.deleteWorker(workspaceId, worker.id);
+                }
+                catch {
+                    /* idempotent — worker may already be gone via cascade or boot cleanup */
+                }
+                const idx = spawnedWorkers.indexOf(worker.id);
+                if (idx !== -1)
+                    spawnedWorkers.splice(idx, 1);
+                releaseSlot();
+            }
+        };
+        // TIER 1 #3 — per-item rejections become null (preserves the
+        // documented contract: callers use `.filter(Boolean)` patterns), BUT
+        // if the run is being stopped we re-throw so the outer catch handles
+        // it as `status='stopped'` instead of silently completing with a
+        // result array full of nulls. Per-item failures still get logged so
+        // they're not entirely invisible (TIER 2 #3 will pipe these into the
+        // run timeline via log()).
+        const catchPerItem = (value) => {
+            if (stoppedRuns.has(run.id))
+                throw value;
+            console.warn(`[workflow ${loaded.meta.name}] item failed:`, value);
+            return null;
+        };
+        const parallel = async (thunks) => {
+            return Promise.all(thunks.map((thunk) => thunk().catch((err) => catchPerItem(err))));
+        };
+        const pipeline = async (items, ...stages) => {
+            return Promise.all(items.map((item, index) => {
+                let chain = Promise.resolve(item);
+                for (const stage of stages) {
+                    chain = chain.then((prev) => stage(prev, item, index));
+                }
+                return chain.catch((err) => catchPerItem(err));
+            }));
+        };
+        const log = (message) => {
+            // TIER 2 #3 — persist + still echo to stdout for server-log
+            // visibility. Authors expect `log()` to surface in the Drawer's
+            // narrator lane and in the orchestrator's completion reminder.
+            // The console.log retains the server-side breadcrumb for ops.
+            const text = typeof message === 'string' ? message : String(message);
+            try {
+                logStore.append(run.id, text);
+            }
+            catch (error) {
+                console.error('[hive] swallowed:workflow.log.append', error);
+            }
+            console.log(`[workflow ${loaded.meta.name}] ${text}`);
+        };
+        // Nested workflow: look up a sibling script in the same .hive/workflows/
+        // directory and run it through THIS runner instance. The child run gets
+        // its own row in workflow_runs and shares the dispatch-await machinery
+        // (so its `agent()` calls work the same way the parent's do).
+        //
+        // TIER 1 #7 — when the parent was fired inline (`team workflow run
+        // --stdin`), its scriptPath is the synthetic token `<inline>` /
+        // `<inline:name>`. `dirname('<inline>')` collapses to `.` and the
+        // child would resolve against the runtime's CWD — wrong directory,
+        // reliably broken. Detect the synthetic prefix and fall back to the
+        // workspace's `.hive/workflows/` directory, which is the canonical
+        // sibling-script location.
+        const isSyntheticParentPath = run.scriptPath.startsWith('<inline');
+        const workflow = async (scriptName, childArgs) => {
+            if (typeof scriptName !== 'string' || !scriptName.trim()) {
+                throw new Error('workflow(scriptName): scriptName must be a non-empty string');
+            }
+            const filename = toNestedWorkflowFilename(scriptName);
+            const childPath = isSyntheticParentPath
+                ? join(resolveWorkspacePath(workspaceId), '.hive', 'workflows', filename)
+                : join(dirname(run.scriptPath), filename);
+            return runWorkflow({
+                workspaceId,
+                scriptPath: childPath,
+                hivePort,
+                // TIER 2 #5 — stamp the parent run id so the UI can render the
+                // nested workflow tree.
+                parentRunId: run.id,
+                ...(childArgs !== undefined ? { args: childArgs } : {}),
+            });
+        };
+        // TIER 2 #11 — wall-clock budget timer. Triggers stopRun on
+        // expiry, which routes through the same path as a user-initiated
+        // stop (in-flight awaiters reject; outer catch records 'stopped').
+        // The setTimeout is unref'd so a forgotten timer can't keep the
+        // Node process alive after shutdown. stopRun is declared further
+        // down the file but exists by the time this timer fires, so the
+        // closure reference is safe.
+        const budgetTimer = setTimeout(() => {
+            log(`[hive] maxDurationMs (${maxDurationMs}ms) exceeded — stopping run`);
+            stopRun(run.id);
+        }, maxDurationMs);
+        budgetTimer.unref?.();
+        try {
+            const factory = new Function(`${loaded.compiledFunctionSource}; return __wf`);
+            const fn = factory();
+            const returnValue = await fn(agent, parallel, pipeline, phase, log, workflow, args);
+            // TIER 1 #2 — if stop was called DURING the run, parallel/pipeline may
+            // have caught the cancel rejections (one per in-flight thunk) before
+            // the per-item catch could re-throw, e.g. when the user stops AFTER
+            // the inner Promise.all has already started but BEFORE any thunk
+            // rejects. In that race we'd otherwise write 'completed' with a
+            // degraded result (often a list of nulls), which both lies to the UI
+            // and lies to the orchestrator's completion notification. Check the
+            // marker after fn returns and record the truth instead.
+            if (stoppedRuns.has(run.id)) {
+                stoppedRuns.delete(run.id);
+                workflowRunStore.updateRun(run.id, {
+                    status: 'stopped',
+                    finishedAt: Date.now(),
+                    error: 'Stopped by user',
+                });
+            }
+            else {
+                stoppedRuns.delete(run.id);
+                // M10: capture the script's return value so the UI can render a single
+                // canonical "Result" panel and the orchestrator notification can quote
+                // it. `undefined` (no explicit return) stays null on the row.
+                workflowRunStore.updateRun(run.id, {
+                    status: 'completed',
+                    finishedAt: Date.now(),
+                    ...(returnValue !== undefined ? { result: returnValue } : {}),
+                });
+            }
+        }
+        catch (error) {
+            const wasStopped = stoppedRuns.has(run.id);
+            const message = error instanceof Error ? error.message : String(error);
+            workflowRunStore.updateRun(run.id, {
+                status: wasStopped ? 'stopped' : 'failed',
+                finishedAt: Date.now(),
+                error: wasStopped ? 'Stopped by user' : message,
+            });
+            stoppedRuns.delete(run.id);
+        }
+        finally {
+            clearTimeout(budgetTimer);
+            // Belt-and-suspenders: dismiss any ephemeral worker still alive. The
+            // per-call try/finally should already have cleaned each one up; this is
+            // an idempotent safety net for unexpected paths.
+            for (const workerId of spawnedWorkers.splice(0)) {
+                try {
+                    store.deleteWorker(workspaceId, workerId);
+                }
+                catch {
+                    /* swallow */
+                }
+            }
+            // Notify the triggering agent (orchestrator) that the run reached a
+            // terminal state. Mirrors Claude Code's <task-notification> envelope.
+            const triggeredByAgentId = triggeringAgentByRun.get(run.id);
+            triggeringAgentByRun.delete(run.id);
+            if (triggeredByAgentId && deps.onRunFinished) {
+                const finalRecord = workflowRunStore.getRun(run.id);
+                if (finalRecord) {
+                    try {
+                        deps.onRunFinished({ runId: run.id, triggeredByAgentId, finalRecord });
+                    }
+                    catch (error) {
+                        console.error('[hive] swallowed:workflow.onRunFinished', error);
+                    }
+                }
+            }
+        }
+    };
+    const buildCreateInput = (input, loaded) => {
+        const createInput = {
+            workspaceId: input.workspaceId,
+            scriptPath: input.scriptPath,
+            name: loaded.meta.name,
+            scriptHash: loaded.scriptHash,
+        };
+        if (input.args !== undefined)
+            createInput.args = input.args;
+        if (input.parentRunId !== undefined)
+            createInput.parentRunId = input.parentRunId;
+        return createInput;
+    };
+    const rememberTrigger = (runId, triggeredByAgentId) => {
+        if (triggeredByAgentId)
+            triggeringAgentByRun.set(runId, triggeredByAgentId);
+    };
+    const runWorkflow = async (input) => {
+        const loaded = await loadWorkflowScriptFile(input.scriptPath);
+        const run = workflowRunStore.createRun(buildCreateInput(input, loaded));
+        rememberTrigger(run.id, input.triggeredByAgentId);
+        await executeWorkflow(run, loaded, input.args, input.hivePort);
+        const finalized = workflowRunStore.getRun(run.id);
+        if (!finalized)
+            throw new Error(`workflow run vanished mid-flight: ${run.id}`);
+        return finalized;
+    };
+    const startWorkflow = async (input) => {
+        const loaded = await loadWorkflowScriptFile(input.scriptPath);
+        const run = workflowRunStore.createRun(buildCreateInput(input, loaded));
+        rememberTrigger(run.id, input.triggeredByAgentId);
+        queueMicrotask(() => {
+            executeWorkflow(run, loaded, input.args, input.hivePort).catch((error) => {
+                console.error('[hive] swallowed:workflow.background', error);
+            });
+        });
+        return run;
+    };
+    const startWorkflowInline = async (input) => {
+        const scriptPath = input.scriptPath ?? '<inline>';
+        const loaded = await loadWorkflowScriptSource(input.source, scriptPath);
+        const run = workflowRunStore.createRun(buildCreateInput({ ...input, scriptPath }, loaded));
+        rememberTrigger(run.id, input.triggeredByAgentId);
+        queueMicrotask(() => {
+            executeWorkflow(run, loaded, input.args, input.hivePort).catch((error) => {
+                console.error('[hive] swallowed:workflow.background', error);
+            });
+        });
+        return run;
+    };
+    const stopRun = (runId) => {
+        const current = workflowRunStore.getRun(runId);
+        if (!current || current.status !== 'running')
+            return false;
+        stoppedRuns.add(runId);
+        // Cancel every open workflow dispatch tied to this run; this rejects the
+        // runner's pending `awaitReport` promises, which propagates up the
+        // executeWorkflow try → its catch sets status='stopped'.
+        for (const dispatchId of dispatchPort.listOpenDispatchIdsForRun(runId)) {
+            awaiter.notifyCancel(dispatchId, 'Stopped by user');
+        }
+        // If the script had no in-flight agent() call when stop was requested,
+        // the workflow may simply continue to its natural end. We still record
+        // the intent so a subsequent agent() call rejects immediately. To make
+        // single-step or no-agent() scripts also reflect 'stopped', mark the row
+        // synchronously as a hint to UI — the runner will overwrite to 'stopped'
+        // (or 'completed' if it really did finish) when executeWorkflow exits.
+        return true;
+    };
+    return { runWorkflow, startWorkflow, startWorkflowInline, stopRun };
+};

package/dist/src/server/workflow-schedule-create.d.ts

@@ -0,0 +1,14 @@
+import type { createWorkflowScheduleStore } from './workflow-schedule-store.js';
+type ScheduleStore = ReturnType<typeof createWorkflowScheduleStore>;
+export interface PersistWorkflowScheduleInput {
+    workspacePath: string;
+    scheduleStore: ScheduleStore;
+    workspaceId: string;
+    source: string;
+    name: string;
+    cron: string;
+    nextRunAt: number;
+    args?: unknown;
+}
+export declare const persistWorkflowSchedule: (input: PersistWorkflowScheduleInput) => Promise<import("./workflow-schedule-store.js").WorkflowScheduleRecord>;
+export {};

package/dist/src/server/workflow-schedule-create.js

@@ -0,0 +1,41 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { BadRequestError } from './http-errors.js';
+import { getWindowsFilenameError } from './windows-filename.js';
+// Agent-scheduled workflows persist their inline source to a file under
+// <workspace>/.hive/workflows/ so the existing file-based scheduler can load
+// it at fire time — no orchestrator is in the loop when cron fires, so the
+// source must outlive the request. The file is agent-managed and is
+// intentionally NOT surfaced in the UI (workflows are agent-authored, not a
+// human script library).
+const toScriptFilename = (nameRaw) => {
+    const slug = nameRaw
+        .trim()
+        .toLowerCase()
+        .replace(/\.ts$/, '')
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!slug) {
+        throw new BadRequestError('schedule name must contain at least one alphanumeric character');
+    }
+    const windowsNameProbe = `${slug}.ts`;
+    const filenameError = getWindowsFilenameError(windowsNameProbe);
+    if (filenameError)
+        throw new BadRequestError(`Invalid workflow schedule name: ${filenameError}`);
+    return `${slug}-${randomUUID()}.ts`;
+};
+export const persistWorkflowSchedule = async (input) => {
+    const filename = toScriptFilename(input.name);
+    const dir = join(input.workspacePath, '.hive', 'workflows');
+    await mkdir(dir, { recursive: true });
+    const scriptPath = join(dir, filename);
+    await writeFile(scriptPath, input.source, 'utf8');
+    return input.scheduleStore.create({
+        workspaceId: input.workspaceId,
+        scriptPath,
+        cron: input.cron,
+        nextRunAt: input.nextRunAt,
+        ...(input.args !== undefined ? { args: input.args } : {}),
+    });
+};

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

@@ -0,0 +1,43 @@
+import type { Database } from 'better-sqlite3';
+export interface WorkflowScheduleRecord {
+    id: string;
+    workspaceId: string;
+    scriptPath: string;
+    cron: string;
+    args: unknown;
+    enabled: boolean;
+    lastRunAt: number | null;
+    nextRunAt: number;
+    createdAt: number;
+    updatedAt: number;
+}
+interface CreateInput {
+    workspaceId: string;
+    scriptPath: string;
+    cron: string;
+    nextRunAt: number;
+    args?: unknown;
+    enabled?: boolean;
+}
+interface UpdateInput {
+    cron?: string;
+    args?: unknown;
+    enabled?: boolean;
+    lastRunAt?: number;
+    nextRunAt?: number;
+}
+export declare const createWorkflowScheduleStore: (db: Database) => {
+    create: (input: CreateInput) => WorkflowScheduleRecord;
+    update: (id: string, input: UpdateInput) => void;
+    get: (id: string) => WorkflowScheduleRecord | undefined;
+    listForWorkspace: (workspaceId: string) => WorkflowScheduleRecord[];
+    listDueSchedules: (now: number) => WorkflowScheduleRecord[];
+    deleteSchedule: (id: string) => void;
+    claimDueSchedule: (input: {
+        id: string;
+        expectedNextRunAt: number;
+        newNextRunAt: number;
+        lastRunAt: number;
+    }) => boolean;
+};
+export {};