@timqi/pier 0.0.1

package/dist/tasks/runs.js

@@ -0,0 +1,104 @@
+import { randomUUID } from "node:crypto";
+import { logger } from "../log.js";
+import { TaskCallbacks } from "./callbacks.js";
+import { TaskStore } from "./store.js";
+const log = logger("tasks");
+const MAX_DEPTH = 2;
+const MAX_CHILDREN_PER_ROOT = 16;
+export class TaskRunQueue {
+    store;
+    callbacks;
+    getRun;
+    execute;
+    changed;
+    constructor(store, callbacks, getRun, execute, changed) {
+        this.store = store;
+        this.callbacks = callbacks;
+        this.getRun = getRun;
+        this.execute = execute;
+        this.changed = changed;
+    }
+    enqueue(definition, input, source, parentRunId, provenance) {
+        const id = randomUUID();
+        const parent = parentRunId ? this.getRun(parentRunId) : null;
+        const depth = provenance.depth ?? (parent ? parent.depth + 1 : 0);
+        const rootRunId = provenance.rootRunId ?? parent?.rootRunId ?? id;
+        if (depth > MAX_DEPTH)
+            throw new Error(`subagent depth limit is ${MAX_DEPTH}`);
+        if (depth > 0 && this.store.listRunsByRoot(rootRunId, MAX_CHILDREN_PER_ROOT + 1).filter((run) => run.depth > 0).length >= MAX_CHILDREN_PER_ROOT) {
+            throw new Error(`subagent child limit is ${MAX_CHILDREN_PER_ROOT} per root run`);
+        }
+        const invokedBySessionId = provenance.invokedBySessionId ?? null;
+        const sourceSessionId = provenance.sourceSessionId ?? invokedBySessionId;
+        const sessionMode = definition.action.type === "agent"
+            ? provenance.sessionMode ?? definition.action.session.mode
+            : null;
+        if (sessionMode === "fork" && !sourceSessionId)
+            throw new Error("fork requires a source session");
+        if (sessionMode === "fork" && (source === "cron" || source === "watch")) {
+            throw new Error("scheduled and watch runs cannot fork a caller session");
+        }
+        const targetSessionId = provenance.targetSessionId ?? (definition.action.type === "agent" && sessionMode === "reuse" && definition.action.session.mode === "reuse"
+            ? definition.action.session.sessionId
+            : null);
+        const callbackSessionId = provenance.callbackSessionId !== undefined
+            ? provenance.callbackSessionId
+            : this.callbacks.target(definition.callback, invokedBySessionId);
+        // Overlap is derived from the durable run store — no parallel bookkeeping.
+        const interactiveAgent = definition.action.type === "agent" && source !== "cron" && source !== "watch";
+        const overlapped = !interactiveAgent && this.store.findActiveRun(definition.id) !== undefined;
+        const now = Date.now();
+        const run = {
+            id,
+            taskId: definition.id,
+            taskRevision: definition.revision,
+            parentRunId,
+            groupId: provenance.groupId ?? null,
+            rootRunId,
+            depth,
+            resumedFromRunId: provenance.resumedFromRunId ?? null,
+            triggerSource: source,
+            invokedBySessionId,
+            sourceSessionId,
+            targetSessionId,
+            sessionMode,
+            callbackSessionId,
+            background: provenance.background ?? false,
+            callbackState: overlapped && callbackSessionId ? "pending" : null,
+            callbackAttempts: 0,
+            callbackError: null,
+            callbackNextAttemptAt: null,
+            state: overlapped ? "skipped" : "queued",
+            input,
+            context: {
+                definition: structuredClone(definition),
+                ...(provenance.resumePrompt ? { resumePrompt: provenance.resumePrompt } : {}),
+            },
+            probe: null,
+            matched: null,
+            result: null,
+            error: null,
+            skipReason: overlapped ? "overlap" : null,
+            queuedAt: now,
+            startedAt: null,
+            finishedAt: overlapped ? now : null,
+        };
+        this.store.saveRun(run);
+        this.changed(run);
+        // Why a run exists is the first question asked of a surprising one, and it
+        // is answerable only here: the row keeps the ids, not the reason. A watch
+        // probe queues on every interval and mostly matches nothing, so it says so
+        // at debug and lets its settled line (execution.ts) carry the news.
+        const queued = `run ${id} ${run.state}: ${definition.name} via ${source}` +
+            `${overlapped ? " (overlapped)" : ""}${depth > 0 ? ` depth ${String(depth)}` : ""}`;
+        if (source === "watch" && !overlapped)
+            log.debug(queued);
+        else
+            log.info(queued);
+        if (run.state === "queued")
+            this.execute(run);
+        else if (run.callbackState === "pending")
+            void this.callbacks.deliver(run);
+        return run;
+    }
+}

package/dist/tasks/service.js

@@ -0,0 +1,282 @@
+import { EventHub } from "../core/hub.js";
+import { Router } from "../core/router.js";
+import { logger } from "../log.js";
+import { AgentTaskRunner } from "./agent.js";
+import { TaskCallbacks } from "./callbacks.js";
+import { TaskDefinitions, requiredString } from "./definitions.js";
+import { TaskExecution } from "./execution.js";
+import { TaskGroups } from "./groups.js";
+import { TaskMessenger } from "./messages.js";
+import { TaskRunQueue } from "./runs.js";
+import { TaskStore } from "./store.js";
+import { handleTaskTool } from "./tool.js";
+import { isTerminal } from "./types.js";
+const log = logger("tasks");
+export class TaskService {
+    store;
+    hub;
+    timer = null;
+    ticking = false;
+    waiters = new Map();
+    messages;
+    definitions;
+    callbacks;
+    groups;
+    runs;
+    execution;
+    constructor(store, factory, router, hub) {
+        this.store = store;
+        this.hub = hub;
+        this.messages = new TaskMessenger(store, router, hub, (runId, prompt, fromSessionId) => this.resume(runId, prompt, { invokedBySessionId: fromSessionId, callbackSessionId: fromSessionId, background: true }));
+        this.definitions = new TaskDefinitions(store, factory, router, hub);
+        this.callbacks = new TaskCallbacks(store, router, (run) => this.changed(run));
+        this.groups = new TaskGroups(store, router, {
+            getRun: (id) => this.getRun(id),
+            cancel: (id) => { this.cancel(id); },
+            openDecisionId: (runId) => this.messages.openDecisionId(runId),
+            startMember: (taskId, groupId, callerSessionId, parentRunId) => this.run(taskId, null, "agent", parentRunId, {
+                invokedBySessionId: callerSessionId,
+                sourceSessionId: callerSessionId,
+                callbackSessionId: null,
+                background: true,
+                groupId,
+            }),
+        }, (group) => this.hub.emitWorkspace({ type: "task-group-changed", groupId: group.id }));
+        const agent = new AgentTaskRunner(factory, router, store, this.messages, (run) => this.changed(run));
+        this.execution = new TaskExecution(store, this.definitions, this.callbacks, agent, {
+            runChild: (taskId, parent) => this.run(taskId, parent.input, "task", parent.id, {
+                invokedBySessionId: parent.invokedBySessionId,
+                sourceSessionId: parent.sourceSessionId,
+                callbackSessionId: null,
+                background: false,
+            }),
+            waitForRun: (id) => this.waitForRun(id),
+            cancel: (id) => { this.cancel(id); },
+            settled: (run) => this.settled(run),
+            changed: (run) => this.changed(run),
+            openDecisionId: (runId) => this.messages.openDecisionId(runId),
+        });
+        this.runs = new TaskRunQueue(store, this.callbacks, (id) => this.getRun(id), (run) => this.execution.start(run), (run) => this.changed(run));
+    }
+    start(tickMs = 1000) {
+        if (this.timer)
+            return;
+        const now = Date.now();
+        // A run that was running when the process died: it is being written off
+        // here, and the previous boot's log is where its work stopped.
+        for (const run of this.store.interruptRunning(now)) {
+            log.warn(`run ${run.id} (${run.context.definition.name}) interrupted by a restart`);
+            this.changed(run);
+        }
+        this.messages.expirePending();
+        this.definitions.resetNextRuns(now);
+        this.callbacks.recover(now);
+        this.groups.recover(now);
+        this.timer = setInterval(() => {
+            // The scheduler's own loop: a throw here would stop nothing (the next
+            // tick still fires) and say nothing, so due tasks would just stop.
+            void this.tick().catch((err) => log.error("scheduler tick failed", err));
+        }, tickMs);
+        this.timer.unref();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        this.execution.stop();
+    }
+    list() {
+        return this.definitions.list();
+    }
+    get(id) {
+        return this.definitions.get(id);
+    }
+    create(raw, creator = "http") {
+        return this.definitions.create(raw, creator);
+    }
+    update(id, raw) {
+        return this.definitions.update(id, raw);
+    }
+    setEnabled(id, enabled) {
+        return this.definitions.setEnabled(id, enabled);
+    }
+    archive(id) {
+        return this.definitions.archive(id);
+    }
+    sessionExists(sessionId) {
+        return this.definitions.sessionExists(sessionId);
+    }
+    listRuns(taskId, limit = 50, offset = 0) {
+        this.get(taskId);
+        return this.store.listRuns(taskId, Math.min(Math.max(limit, 1), 200), Math.max(offset, 0));
+    }
+    getRun(id) {
+        const run = this.store.getRun(id);
+        if (!run)
+            throw new Error(`unknown task run: ${id}`);
+        return run;
+    }
+    listMessages(runId) {
+        this.getRun(runId);
+        return this.messages.list(runId);
+    }
+    openDecisionId(runId) {
+        return this.messages.openDecisionId(runId);
+    }
+    recentRuns(limit = 100) {
+        return this.store.listRecentRuns(limit);
+    }
+    recentMessages(since, limit = 200) {
+        return this.messages.recent(since, limit);
+    }
+    backgroundRuns(sessionId) {
+        const cutoff = Date.now() - 60 * 60 * 1000;
+        return this.store.listRunsForSession(sessionId, 50)
+            .filter((run) => run.background && (!isTerminal(run.state) || run.queuedAt >= cutoff))
+            .slice(0, 20)
+            .reverse()
+            .map((run) => this.backgroundRun(run));
+    }
+    run(taskId, input = null, source = "manual", parentRunId = null, provenance = {}) {
+        const task = this.get(taskId);
+        // `enabled:false` pauses scheduling only; manual and agent triggers still
+        // run a paused task on demand. Archiving is the terminal state.
+        if (task.archived)
+            throw new Error("archived tasks cannot run");
+        return this.runs.enqueue(task, input, source, parentRunId, provenance);
+    }
+    async waitForRun(id, signal) {
+        const current = this.getRun(id);
+        if (isTerminal(current.state))
+            return current;
+        if (signal?.aborted)
+            throw new Error("wait cancelled");
+        return new Promise((resolve, reject) => {
+            let set = this.waiters.get(id);
+            if (!set)
+                this.waiters.set(id, (set = new Set()));
+            set.add(resolve);
+            // An aborted caller must not leave its waiter behind forever.
+            signal?.addEventListener("abort", () => {
+                set.delete(resolve);
+                reject(new Error("wait cancelled"));
+            }, { once: true });
+        });
+    }
+    /** Cascades: orphans must not outlive the delegation that wanted them. */
+    cancel(id) {
+        const run = this.getRun(id);
+        for (const target of [run, ...this.descendants(run)]) {
+            if (!isTerminal(target.state))
+                this.execution.cancel(target.id);
+        }
+        return this.getRun(id);
+    }
+    cancelGroup(id) {
+        return this.groups.cancelAll(id);
+    }
+    getGroup(id) {
+        return this.groups.members(id);
+    }
+    runGroup(definitions, join, callerSessionId, parentRunId, callbackSessionId) {
+        return this.groups.runAll(definitions, join, callerSessionId, parentRunId, callbackSessionId);
+    }
+    descendants(run) {
+        const byParent = new Map();
+        for (const member of this.store.listRunsByRoot(run.rootRunId, 500)) {
+            if (!member.parentRunId)
+                continue;
+            const siblings = byParent.get(member.parentRunId) ?? [];
+            siblings.push(member);
+            byParent.set(member.parentRunId, siblings);
+        }
+        const collected = [];
+        const queue = [run.id];
+        while (queue.length > 0) {
+            for (const child of byParent.get(queue.shift()) ?? []) {
+                collected.push(child);
+                queue.push(child.id);
+            }
+        }
+        return collected;
+    }
+    async control(id, fromSessionId, mode, message) {
+        const run = this.getRun(id);
+        if (run.context.definition.action.type !== "agent")
+            throw new Error("only Agent runs can be steered");
+        if (isTerminal(run.state))
+            throw new Error("terminal run cannot be steered; resume it instead");
+        return this.messages.control(run, fromSessionId, mode, message);
+    }
+    reply(messageId, fromSessionId, message) {
+        return this.messages.reply(messageId, fromSessionId, message);
+    }
+    resume(id, message, provenance = {}) {
+        const prior = this.getRun(id);
+        if (!isTerminal(prior.state))
+            throw new Error("run must be terminal before resume");
+        if (prior.context.definition.action.type !== "agent" || !prior.targetSessionId) {
+            throw new Error("only persisted Agent runs can be resumed");
+        }
+        const prompt = requiredString(message, "message");
+        this.messages.expireDecisions(prior.id, "superseded by a manual resume");
+        return this.runs.enqueue(prior.context.definition, null, "agent", null, {
+            ...provenance,
+            sourceSessionId: provenance.invokedBySessionId ?? prior.invokedBySessionId,
+            targetSessionId: prior.targetSessionId,
+            sessionMode: "reuse",
+            resumedFromRunId: prior.id,
+            rootRunId: prior.rootRunId,
+            depth: prior.depth,
+            resumePrompt: prompt,
+        });
+    }
+    tool(raw, callerSessionId) {
+        return handleTaskTool(this, this.definitions, this.store, this.messages, raw, callerSessionId);
+    }
+    async tick() {
+        if (this.ticking)
+            return;
+        this.ticking = true;
+        try {
+            const now = Date.now();
+            for (const task of this.definitions.claimDue(now)) {
+                this.run(task.id, null, task.trigger.type === "watch" ? "watch" : "cron");
+            }
+            this.callbacks.recover(now);
+            this.groups.recover(now);
+            this.messages.retryUndelivered(now);
+        }
+        finally {
+            this.ticking = false;
+        }
+    }
+    settled(run) {
+        const waiters = this.waiters.get(run.id);
+        if (waiters)
+            for (const resolve of waiters)
+                resolve(run);
+        this.waiters.delete(run.id);
+        this.groups.onSettled(run);
+    }
+    backgroundRun(run) {
+        return {
+            runId: run.id,
+            taskId: run.taskId,
+            taskName: run.context.definition.name,
+            state: run.state,
+            targetSessionId: run.targetSessionId,
+            sessionMode: run.sessionMode,
+            depth: run.depth,
+            queuedAt: run.queuedAt,
+            startedAt: run.startedAt,
+            finishedAt: run.finishedAt,
+        };
+    }
+    changed(run) {
+        this.hub.emitWorkspace({ type: "task-run-changed", taskId: run.taskId, runId: run.id });
+        if (run.background && run.invokedBySessionId) {
+            this.hub.emit(run.invokedBySessionId, { type: "task-status", run: this.backgroundRun(run) });
+        }
+    }
+}

package/dist/tasks/store.js

@@ -0,0 +1,168 @@
+import { pierDb } from "../db.js";
+const parseTask = (json) => JSON.parse(json);
+const parseRun = (json) => JSON.parse(json);
+export class TaskStore {
+    db;
+    constructor(db = pierDb()) {
+        this.db = db;
+    }
+    listTasks() {
+        return this.db.prepare("SELECT json FROM tasks ORDER BY updated_at DESC").all()
+            .map((r) => parseTask(r.json));
+    }
+    getTask(id) {
+        const row = this.db.prepare("SELECT json FROM tasks WHERE id = ?").get(id);
+        return row ? parseTask(row.json) : undefined;
+    }
+    saveTask(task) {
+        this.db.prepare(`
+      INSERT INTO tasks(id, updated_at, json) VALUES (?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET updated_at=excluded.updated_at, json=excluded.json
+    `).run(task.id, task.updatedAt, JSON.stringify(task));
+    }
+    listRuns(taskId, limit = 50, offset = 0) {
+        return this.db.prepare(`
+      SELECT json FROM task_runs WHERE task_id = ?
+      ORDER BY queued_at DESC LIMIT ? OFFSET ?
+    `).all(taskId, limit, offset)
+            .map((r) => parseRun(r.json));
+    }
+    getRun(id) {
+        const row = this.db.prepare("SELECT json FROM task_runs WHERE id = ?").get(id);
+        return row ? parseRun(row.json) : undefined;
+    }
+    saveRun(run) {
+        this.db.prepare(`
+      INSERT INTO task_runs(id, task_id, queued_at, state, callback_state, json)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        state=excluded.state, callback_state=excluded.callback_state, json=excluded.json
+    `).run(run.id, run.taskId, run.queuedAt, run.state, run.callbackState, JSON.stringify(run));
+    }
+    listRecentRuns(limit = 100) {
+        return this.db.prepare(`
+      SELECT json FROM task_runs ORDER BY queued_at DESC LIMIT ?
+    `).all(Math.min(Math.max(limit, 1), 500))
+            .map((row) => parseRun(row.json));
+    }
+    listRunsByRoot(rootRunId, limit = 100) {
+        return this.db.prepare(`
+      SELECT json FROM task_runs
+      WHERE json_extract(json, '$.rootRunId') = ?
+      ORDER BY queued_at LIMIT ?
+    `).all(rootRunId, Math.min(Math.max(limit, 1), 500))
+            .map((row) => parseRun(row.json));
+    }
+    findActiveRun(taskId) {
+        const row = this.db.prepare(`
+      SELECT json FROM task_runs
+      WHERE task_id = ? AND state IN ('queued', 'running') LIMIT 1
+    `).get(taskId);
+        return row ? parseRun(row.json) : undefined;
+    }
+    findActiveRunForTarget(sessionId) {
+        const row = this.db.prepare(`
+      SELECT json FROM task_runs
+      WHERE state IN ('queued', 'running')
+        AND json_extract(json, '$.targetSessionId') = ?
+      ORDER BY CASE state WHEN 'running' THEN 0 ELSE 1 END, queued_at DESC LIMIT 1
+    `).get(sessionId);
+        return row ? parseRun(row.json) : undefined;
+    }
+    listRunsForSession(sessionId, limit = 50) {
+        return this.db.prepare(`
+      SELECT json FROM task_runs
+      WHERE json_extract(json, '$.invokedBySessionId') = ?
+      ORDER BY queued_at DESC LIMIT ?
+    `).all(sessionId, Math.min(Math.max(limit, 1), 200))
+            .map((row) => parseRun(row.json));
+    }
+    saveGroup(group) {
+        this.db.prepare(`
+      INSERT INTO task_groups(id, created_at, callback_state, finished_at, json)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        callback_state=excluded.callback_state, finished_at=excluded.finished_at, json=excluded.json
+    `).run(group.id, group.createdAt, group.callbackState, group.finishedAt, JSON.stringify(group));
+    }
+    getGroup(id) {
+        const row = this.db.prepare("SELECT json FROM task_groups WHERE id = ?").get(id);
+        return row ? JSON.parse(row.json) : undefined;
+    }
+    /** Unfinished joins plus deliverable group callbacks, for settle and recovery. */
+    listOpenGroups(now = Date.now()) {
+        return this.db.prepare(`
+      SELECT json FROM task_groups
+      WHERE finished_at IS NULL
+        OR (callback_state IN ('pending', 'failed')
+          AND (json_extract(json, '$.callbackNextAttemptAt') IS NULL
+            OR json_extract(json, '$.callbackNextAttemptAt') <= ?))
+      ORDER BY created_at
+    `).all(now).map((row) => JSON.parse(row.json));
+    }
+    saveMessage(message) {
+        this.db.prepare(`
+      INSERT INTO task_messages(id, run_id, state, created_at, json)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET state=excluded.state, json=excluded.json
+    `).run(message.id, message.runId, message.state, message.createdAt, JSON.stringify(message));
+    }
+    getMessage(id) {
+        const row = this.db.prepare("SELECT json FROM task_messages WHERE id = ?").get(id);
+        return row ? JSON.parse(row.json) : undefined;
+    }
+    listMessages(runId) {
+        return this.db.prepare(`
+      SELECT json FROM task_messages WHERE run_id = ? ORDER BY created_at
+    `).all(runId).map((row) => JSON.parse(row.json));
+    }
+    listRecentMessages(since, limit = 200) {
+        return this.db.prepare(`
+      SELECT json FROM task_messages WHERE created_at >= ? ORDER BY created_at DESC LIMIT ?
+    `).all(since, Math.min(Math.max(limit, 1), 500))
+            .map((row) => JSON.parse(row.json));
+    }
+    /** Messages whose injection never landed: the delivery sweep retries these. */
+    listUndeliveredMessages() {
+        return this.db.prepare(`
+      SELECT json FROM task_messages WHERE state IN ('pending', 'failed') ORDER BY created_at
+    `).all().map((row) => JSON.parse(row.json));
+    }
+    /** Decisions are excluded: they have no timeout and stay answerable across
+     * restarts — a reply to a terminal run resumes it. */
+    expirePendingMessages() {
+        const rows = this.db.prepare(`
+      SELECT json FROM task_messages
+      WHERE state = 'pending' AND json_extract(json, '$.kind') != 'decision'
+    `).all();
+        return rows.map((row) => {
+            const message = JSON.parse(row.json);
+            message.state = "expired";
+            message.error = "Pier restarted before delivery completed";
+            this.saveMessage(message);
+            return message;
+        });
+    }
+    listPendingCallbacks(now = Date.now()) {
+        return this.db.prepare(`
+      SELECT json FROM task_runs
+      WHERE callback_state IN ('pending', 'failed')
+        AND (json_extract(json, '$.callbackNextAttemptAt') IS NULL
+          OR json_extract(json, '$.callbackNextAttemptAt') <= ?)
+      ORDER BY queued_at
+    `).all(now).map((row) => parseRun(row.json));
+    }
+    interruptRunning(now = Date.now()) {
+        const rows = this.db.prepare("SELECT json FROM task_runs WHERE state IN ('queued', 'running')").all();
+        return rows.map((row) => {
+            const run = parseRun(row.json);
+            run.state = "interrupted";
+            run.error = "Pier restarted while the run was active";
+            run.finishedAt = now;
+            if (run.callbackSessionId)
+                run.callbackState = "pending";
+            this.saveRun(run);
+            return run;
+        });
+    }
+}