@timqi/pier 0.1.14 → 0.3.0

package/dist/tasks/routes.js

@@ -1,258 +1,28 @@
-// The area's HTTP surface. A route names the caller and hands the decision to
-// TaskService: policy here would be policy `pier task` does not get.
-import { record, requiredString } from "./definitions.js";
-/** Reject malformed filters instead of silently widening a global query. */
-function runQuery(params) {
-    const query = {};
-    const states = ["queued", "running", "succeeded", "failed", "cancelled", "interrupted", "skipped"];
-    const sources = ["manual", "cron", "watch", "agent", "task"];
-    if (params.state) {
-        if (!states.includes(params.state))
-            throw new Error("invalid state");
-        query.state = params.state;
-    }
-    if (params.source) {
-        if (!sources.includes(params.source))
-            throw new Error("invalid source");
-        query.source = params.source;
-    }
-    if (params.taskId)
-        query.taskId = params.taskId;
-    for (const key of ["since", "until", "limit"]) {
-        if (params[key] === undefined)
-            continue;
-        const value = Number(params[key]);
-        if (!params[key] || !Number.isSafeInteger(value) || value < 0 || (key === "limit" && (value < 1 || value > 200)))
-            throw new Error(`invalid ${key}`);
-        query[key] = value;
-    }
-    if (query.since !== undefined && query.until !== undefined && query.since > query.until)
-        throw new Error("since exceeds until");
-    if (params.showUnmatched !== undefined) {
-        if (!["true", "false"].includes(params.showUnmatched))
-            throw new Error("invalid showUnmatched");
-        query.showUnmatched = params.showUnmatched === "true";
-    }
-    if (params.cursor) {
-        const cursor = JSON.parse(params.cursor);
-        const value = record(cursor);
-        if (!value || !Number.isSafeInteger(value.queuedAt) || Number(value.queuedAt) < 0 || typeof value.id !== "string" || !value.id)
-            throw new Error("invalid cursor");
-        query.cursor = { queuedAt: Number(value.queuedAt), id: value.id };
-    }
-    return query;
-}
-const jsonBody = async (req) => req.json().catch(() => null);
-export function registerTaskRoutes(app, tasks, activity) {
-    if (activity)
-        app.get("/api/activity", async (c) => {
-            const now = Date.now();
-            const recent = c.req.query("scope") === "recent";
-            const windowStart = now - 24 * 60 * 60 * 1000;
-            const runs = tasks.activityRuns(recent ? windowStart : undefined);
-            const listed = await activity.factory.list();
-            const byId = new Map(listed.map((session) => [session.id, session]));
-            const linkedIds = new Set();
-            for (const run of runs) {
-                for (const id of [run.invokedBySessionId, run.targetSessionId, run.callbackSessionId]) {
-                    if (id)
-                        linkedIds.add(id);
-                }
-            }
-            for (const session of listed) {
-                if (activity.router.stateOf(session.id) === "streaming")
-                    linkedIds.add(session.id);
-            }
-            const messages = tasks.recentMessages(windowStart)
-                .filter((message) => runs.some((run) => run.id === message.runId));
-            for (const message of messages) {
-                if (message.fromSessionId !== "console")
-                    linkedIds.add(message.fromSessionId);
-                if (message.toSessionId !== "console")
-                    linkedIds.add(message.toSessionId);
-            }
-            return c.json({
-                sessions: [...linkedIds].map((id) => {
-                    const session = byId.get(id);
-                    return {
-                        id,
-                        cwd: session?.cwd ?? "",
-                        createdAt: session?.createdAt ?? null,
-                        title: session?.title,
-                        state: activity.router.stateOf(id) ?? "idle",
-                        stateSince: activity.router.stateSinceOf(id) ?? null,
-                    };
-                }),
-                runs,
-                messages,
-            });
-        });
-    app.get("/api/task-runs", (c) => {
-        try {
-            return c.json(tasks.queryRuns(runQuery(c.req.query())));
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 400);
-        }
-    });
-    app.get("/api/tasks", (c) => {
-        const trigger = c.req.query("trigger");
-        const state = c.req.query("state");
-        const kind = c.req.query("kind");
-        let rows = tasks.list();
-        // Subagent one-shots are hidden unless explicitly requested via ?kind=subagent.
-        rows = rows.filter((task) => task.kind === (kind ?? "task"));
-        if (trigger)
-            rows = rows.filter((task) => task.trigger.type === trigger);
-        if (state === "archived")
-            rows = rows.filter((task) => task.archived);
-        else if (state === "active")
-            rows = rows.filter((task) => !task.archived);
-        return c.json(rows.map((task) => ({
-            ...task,
-            lastRun: tasks.listRuns(task.id, 1)[0] ?? null,
-        })));
-    });
-    app.post("/api/tasks", async (c) => {
-        const body = await jsonBody(c.req);
-        const runNow = typeof body === "object" && body !== null && "runNow" in body && body.runNow === true;
-        const definition = typeof body === "object" && body !== null && "task" in body ? body.task : body;
-        try {
-            const task = await tasks.create(definition);
-            const run = runNow ? tasks.run(task.id) : null;
-            return c.json({ task, runId: run?.id ?? null }, 201);
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 400);
-        }
-    });
+// Settings → Tasks' HTTP surface: the list, pause/resume, a task's runs. A
+// route names the caller and hands the decision to TaskService: policy here
+// would be policy `pier task` does not get.
+const RUNS_LIMIT = 20;
+export function registerTaskRoutes(app, tasks) {
+    // Subagent one-shots and archived tasks are history, not something to manage.
+    app.get("/api/tasks", (c) => c.json(tasks.list()
+        .filter((task) => task.kind === "task" && !task.archived)
+        .map((task) => ({ ...task, lastRun: tasks.listRuns(task.id, 1)[0] ?? null }))));
     app.get("/api/tasks/:id/runs", (c) => {
         try {
-            const limit = Number(c.req.query("limit") ?? 50);
-            const offset = Number(c.req.query("offset") ?? 0);
-            return c.json(tasks.listRuns(c.req.param("id"), limit, offset));
+            return c.json(tasks.listRuns(tasks.get(c.req.param("id")).id, RUNS_LIMIT));
         }
         catch (err) {
             return c.json({ error: String(err) }, 404);
         }
     });
-    app.get("/api/task-runs/:id", (c) => {
-        try {
-            return c.json(tasks.getRunView(c.req.param("id")));
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 404);
-        }
-    });
-    app.get("/api/task-groups/:id", (c) => {
-        try {
-            return c.json(tasks.getGroup(c.req.param("id")));
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 404);
-        }
-    });
-    app.get("/api/task-runs/:id/messages", (c) => {
-        try {
-            return c.json(tasks.listMessages(c.req.param("id")));
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 404);
-        }
-    });
-    app.post("/api/task-runs/:id/steer", async (c) => {
-        const body = record(await jsonBody(c.req));
-        try {
-            return c.json(await tasks.control(c.req.param("id"), typeof body?.sourceSessionId === "string" ? body.sourceSessionId : "console", body?.mode === "followUp" ? "follow_up" : "steer", requiredString(body?.message, "message")), 202);
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 400);
-        }
-    });
-    app.post("/api/task-runs/:id/resume", async (c) => {
-        const body = record(await jsonBody(c.req));
-        try {
-            const wait = body?.wait === true;
-            const source = typeof body?.sourceSessionId === "string" ? body.sourceSessionId : null;
-            const run = tasks.resume(c.req.param("id"), requiredString(body?.message, "message"), {
-                invokedBySessionId: source,
-                callbackSessionId: wait ? null : source,
-                background: !wait,
-            });
-            return c.json(wait ? await tasks.waitForRun(run.id) : run, wait ? 200 : 202);
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 400);
-        }
-    });
-    app.post("/api/task-runs/:id/cancel", (c) => {
-        try {
-            return c.json(tasks.cancel(c.req.param("id")), 202);
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 404);
-        }
-    });
-    app.get("/api/tasks/:id", (c) => {
-        try {
-            return c.json(tasks.get(c.req.param("id")));
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 404);
-        }
-    });
-    app.patch("/api/tasks/:id", async (c) => {
-        try {
-            return c.json(await tasks.update(c.req.param("id"), await jsonBody(c.req)));
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 400);
-        }
-    });
-    app.post("/api/tasks/:id/run", async (c) => {
-        const body = record(await jsonBody(c.req));
-        const input = body && "input" in body ? body.input : null;
-        try {
-            // Dropping an unsupported override would run the definition's own policy
-            // instead — on a reuse definition, work injected into a live session.
-            if (body?.sessionMode !== undefined && body.sessionMode !== "fresh") {
-                throw new Error(`unsupported sessionMode: ${String(body.sessionMode)}`);
+    for (const [verb, enabled] of [["pause", false], ["resume", true]]) {
+        app.post(`/api/tasks/:id/${verb}`, (c) => {
+            try {
+                return c.json(tasks.setEnabled(c.req.param("id"), enabled));
             }
-            const sessionMode = body?.sessionMode;
-            const sourceSessionId = typeof body?.sourceSessionId === "string" && body.sourceSessionId ? body.sourceSessionId : null;
-            const task = tasks.get(c.req.param("id"));
-            return c.json({ runId: tasks.run(task.id, input, "manual", null, {
-                    invokedBySessionId: sourceSessionId,
-                    sourceSessionId,
-                    sessionMode,
-                }).id }, 202);
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 400);
-        }
-    });
-    app.post("/api/tasks/:id/pause", (c) => {
-        try {
-            return c.json(tasks.setEnabled(c.req.param("id"), false));
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 400);
-        }
-    });
-    app.post("/api/tasks/:id/resume", (c) => {
-        try {
-            return c.json(tasks.setEnabled(c.req.param("id"), true));
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 400);
-        }
-    });
-    app.post("/api/tasks/:id/archive", (c) => {
-        try {
-            return c.json(tasks.archive(c.req.param("id")));
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 400);
-        }
-    });
+            catch (err) {
+                return c.json({ error: String(err) }, 400);
+            }
+        });
+    }
 }

package/dist/tasks/service.js

@@ -3,11 +3,12 @@
 // drain needs. Decisions belong to the files beside it.
 import { logger } from "../log.js";
 import { AgentTaskRunner } from "./agent.js";
-import { TaskCallbacks } from "./callbacks.js";
+import { DESIGN_FINAL, LEAD_TURN, MILESTONE, runCwd, settleCallback, 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 { openItems, recordOpenItems } from "./open-items.js";
 import { TaskRunQueue } from "./runs.js";
 import { handleTask } from "./operations.js";
 import { isTerminal } from "./types.js";
@@ -36,17 +37,23 @@ export class TaskService {
     runs;
     execution;
     constructor(store, factory, router, hub, 
-    /** Structural: tasks/ must not import settings.ts. Absent in bare test rigs. */
+    /** Structural: tasks/ must not import settings.ts. */
     instance) {
         this.store = store;
         this.factory = factory;
         this.router = router;
         this.hub = hub;
         this.instance = instance;
+        const headOf = (id) => instance.continuous.chainOf(id)?.[0] ?? id;
+        const conversation = () => instance.continuous.members()[0]?.sessionId ?? null;
         const unreachable = (sessionId, what, why) => this.unreachable(sessionId, what, why);
-        this.messages = new TaskMessenger(store, router, hub, unreachable);
-        this.definitions = new TaskDefinitions(store, factory, router, hub, instance?.systemActions);
-        this.callbacks = new TaskCallbacks(store, router, (run) => this.changed(run), unreachable);
+        this.messages = new TaskMessenger(store, router, hub, unreachable, (runId) => {
+            const run = store.getRun(runId);
+            if (run)
+                this.status(run);
+        });
+        this.definitions = new TaskDefinitions(store, factory, router, hub, instance.systemActions);
+        this.callbacks = new TaskCallbacks(store, router, (run) => this.changed(run), unreachable, headOf, this.milestone, conversation);
         this.groups = new TaskGroups(store, router, {
             getRun: (id) => this.getRun(id),
             cancel: (id) => { this.cancel(id); },
@@ -58,7 +65,7 @@ export class TaskService {
                 groupId,
             }),
             startMember: (run) => this.runs.start(run),
-        }, (group) => this.hub.emitWorkspace({ type: "task-group-changed", groupId: group.id }), unreachable);
+        }, (group) => this.hub.emitWorkspace({ type: "task-group-changed", groupId: group.id }), unreachable, headOf, this.milestone);
         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, {
@@ -73,6 +80,84 @@ export class TaskService {
             changed: (run) => this.changed(run),
         });
         this.runs = new TaskRunQueue(store, this.callbacks, (run) => this.execution.start(run), (run) => this.changed(run));
+        router.onTurnEnd((sessionId, text) => {
+            // Only the head's turns write the list.
+            if (instance.continuous.members()[0]?.sessionId === sessionId) {
+                try {
+                    if (recordOpenItems(store, text, Date.now()))
+                        hub.emitWorkspace({ type: "open-items-changed" });
+                }
+                catch (err) {
+                    log.warn(`open items: the markers in ${sessionId}'s reply could not be written`, err);
+                }
+            }
+            if (!DESIGN_FINAL.test(text))
+                return;
+            // On Pi's dispatch stack, which must not unwind.
+            try {
+                this.designFinal(sessionId, text);
+            }
+            catch (err) {
+                log.error(`lead ${sessionId}: a Design final: outside any run could not be recorded; main was not told`, err);
+            }
+        });
+    }
+    /** A design lead finalized in its own session, a turn outside any run (the
+     *  user confirmed there): recorded as a finished run of the lead whose result
+     *  is that reply, so it reports to the lead's supervisor, and the session list and
+     *  `/status` see it, exactly as a run's `Design final:` does. */
+    designFinal(sessionId, text) {
+        // A run's own turn reports through the run.
+        if (this.store.leadPhaseOf(sessionId) !== "design" || this.store.findActiveRunForTarget(sessionId)?.state === "running")
+            return;
+        const last = this.store.latestRunForTarget(sessionId);
+        if (!last)
+            return;
+        const run = this.store.transact(() => {
+            const run = this.runs.prepare(last.context.definition, null, "agent", null, {
+                invokedBySessionId: last.invokedBySessionId,
+                sourceSessionId: last.invokedBySessionId,
+                targetSessionId: sessionId,
+                sessionMode: "reuse",
+                resumedFromRunId: last.id,
+                callbackSessionId: last.callbackSessionId,
+                callbackMode: last.callbackMode,
+                background: last.background,
+            });
+            const now = Date.now();
+            run.state = "succeeded";
+            run.startedAt = run.finishedAt = now;
+            run.result = { type: "agent", text, sessionId };
+            run.context.sessionId = sessionId;
+            settleCallback(run, this.store);
+            this.store.saveRun(run);
+            return run;
+        });
+        if (run.callbackSessionId === null)
+            log.warn(`lead ${sessionId}: Design final: recorded as run ${run.id}; the lead reports to no one`);
+        else
+            log.info(`lead ${sessionId}: Design final: outside any run, recorded as run ${run.id} for ${run.callbackSessionId}`);
+        this.runs.start(run);
+        this.designLead(run);
+    }
+    /** What a settled run of a design lead means to whoever shows the lead to
+     *  the user (channels/runtime.ts); a reporter that throws must not unwind the settle. */
+    designLead(run) {
+        const lead = run.targetSessionId;
+        if (!this.instance.designLead || lead === null || this.store.leadPhaseOf(lead) !== "design")
+            return;
+        const state = run.callbackError === LEAD_TURN ? "waiting"
+            : run.state !== "succeeded" ? "failed"
+                : run.result?.type === "agent" && DESIGN_FINAL.test(run.result.text) ? "final"
+                    : undefined;
+        if (!state)
+            return;
+        try {
+            this.instance.designLead(run, state);
+        }
+        catch (err) {
+            log.error(`lead ${lead}: its ${state} state could not be reported`, err);
+        }
     }
     start(tickMs = 1000) {
         if (this.timer)
@@ -145,7 +230,7 @@ export class TaskService {
     create(raw, creator = "http") {
         return this.definitions.create(raw, creator);
     }
-    /** `by` is how owning code says so; the routes and `pier task` have none (definitions.ts). */
+    /** `by` is how owning code says so; `pier task` has none (definitions.ts). */
     update(id, raw, by) {
         return this.definitions.update(id, raw, by);
     }
@@ -155,9 +240,9 @@ export class TaskService {
     archive(id, by) {
         return this.definitions.archive(id, by);
     }
-    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));
+    /** `pier task list`'s last run: the newest `limit` of a definition's runs. */
+    listRuns(taskId, limit = 1) {
+        return this.store.listRuns(taskId, limit);
     }
     getRun(id) {
         const run = this.store.getRun(id);
@@ -165,24 +250,6 @@ export class TaskService {
             throw new Error(`unknown task run: ${id}`);
         return run;
     }
-    getRunView(id) {
-        const run = this.getRun(id);
-        return { ...run,
-            groupCallbackState: run.groupId ? this.store.getGroup(run.groupId)?.callbackState ?? null : null };
-    }
-    listMessages(runId) {
-        this.getRun(runId);
-        return this.messages.list(runId);
-    }
-    queryRuns(query = {}) {
-        return this.store.queryRuns(query);
-    }
-    activityRuns(since) {
-        return this.store.activityRuns(since);
-    }
-    recentMessages(since) {
-        return this.messages.recent(since);
-    }
     /** Every run, not the last hour's: the card is a message in the transcript. */
     backgroundRuns(sessionId) {
         return this.store.listRunsForSession(sessionId, 200)
@@ -190,6 +257,28 @@ export class TaskService {
             .reverse()
             .map((run) => this.backgroundRun(run));
     }
+    /** What the session's queue shows beside Pi's own: follow-ups waiting for it to idle. */
+    parkedMessages(sessionId) {
+        return this.store.pendingFollowUpsTo(sessionId).map((message) => ({
+            messageId: message.id,
+            runName: this.store.getRun(message.runId)?.context.definition.name ?? message.runId,
+            text: message.content,
+        }));
+    }
+    /** The run ledger: runs any of `sessionIds` launched, in flight or finished since `since`, at most 200. */
+    ledger(sessionIds, since) {
+        return this.store.ledgerRuns(sessionIds, since).map(ledgerRun);
+    }
+    /** Design leads no run of which has reported `Design final:`, by their creating run: the user's to finalize. */
+    openDesigns() {
+        return [...this.store.leads().values()].flatMap((lead) => {
+            const run = lead.designOpen ? this.store.getRun(lead.runId) : undefined;
+            return run ? [ledgerRun(run)] : [];
+        });
+    }
+    openItems(now = Date.now()) {
+        return openItems(this, this.router, this.instance.continuous.members().map((m) => m.sessionId), this.openDesigns(), now);
+    }
     activeBackgroundRunCounts() {
         return this.store.countActiveBackgroundRunsBySession();
     }
@@ -262,15 +351,19 @@ export class TaskService {
         return this.messages.control(run, fromSessionId, mode, message);
     }
     resume(id, message, provenance = {}) {
+        const run = this.prepareResume(this.getRun(id), message, provenance);
+        this.runs.start(run);
+        return run;
+    }
+    prepareResume(prior, message, provenance) {
         this.refusePaused();
-        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");
-        const run = this.runs.prepare(prior.context.definition, null, "agent", null, {
+        return this.runs.prepare(prior.context.definition, null, "agent", null, {
             ...provenance,
             sourceSessionId: provenance.invokedBySessionId ?? prior.invokedBySessionId,
             targetSessionId: prior.targetSessionId,
@@ -278,16 +371,46 @@ export class TaskService {
             resumedFromRunId: prior.id,
             resumePrompt: prompt,
         });
-        this.runs.start(run);
-        return run;
     }
+    /** A lead reports once per wave (docs/design/10-continuous-session.md
+     *  §Feature lead): the result that leaves nothing owed to it in flight
+     *  resumes its last run, whose own callback reaches its supervisor. */
+    milestone = (sessionId, text, settle) => {
+        if (this.store.roleOf(sessionId) !== "lead" || this.store.countOwedTo(sessionId) > 0)
+            return "plain";
+        const last = this.store.latestRunForTarget(sessionId);
+        if (!last || last.callbackSessionId === null)
+            return "plain";
+        // A running turn reports upstream when it ends; a drain leaves the result to the next boot.
+        if (!isTerminal(last.state) || this.paused)
+            return "wait";
+        try {
+            // One transaction: a crash between the resume and the marks would resume twice.
+            const run = this.store.transact(() => {
+                const run = this.prepareResume(last, `${MILESTONE}\n\n${text()}`, {
+                    invokedBySessionId: last.invokedBySessionId,
+                    callbackSessionId: last.callbackSessionId,
+                    callbackMode: last.callbackMode,
+                    background: last.background,
+                });
+                settle();
+                return run;
+            });
+            this.runs.start(run);
+            return "resumed";
+        }
+        catch (err) {
+            log.error(`lead ${sessionId}: the wave's last result could not resume run ${last.id}; delivering it as a plain callback`, err);
+            return "plain";
+        }
+    };
     /** What `pier task` asks, under the calling session's identity. */
     handle(raw, callerSessionId) {
-        return handleTask(this, this.definitions, this.store, raw, callerSessionId);
+        return handleTask(this, this.definitions, this.store, raw, callerSessionId, this.instance.continuous);
     }
     /** An agent picks from names that exist right now, never from memory. */
     async models() {
-        const menu = this.instance?.modelMenu() ?? [];
+        const menu = this.instance.modelMenu();
         if (menu.length)
             return { source: "menu", models: menu };
         return { source: "catalog", models: await this.factory.availableModels() };
@@ -342,6 +465,7 @@ export class TaskService {
                 resolve(run);
         this.waiters.delete(run.id);
         this.groups.onSettled(run);
+        this.designLead(run);
     }
     backgroundRun(run) {
         return {
@@ -355,12 +479,20 @@ export class TaskService {
             queuedAt: run.queuedAt,
             startedAt: run.startedAt,
             finishedAt: run.finishedAt,
+            // A finished run's pending messages only wait for the sweep to expire them.
+            queuedMessages: isTerminal(run.state) ? 0 : this.store.countPendingFollowUps(run.id),
         };
     }
     changed(run) {
         this.hub.emitWorkspace({ type: "task-run-changed", taskId: run.taskId, runId: run.id });
+        this.status(run);
+    }
+    status(run) {
         if (run.background && run.invokedBySessionId) {
             this.hub.emit(run.invokedBySessionId, { type: "task-status", run: this.backgroundRun(run) });
         }
     }
 }
+function ledgerRun(run) {
+    return { runId: run.id, name: run.context.definition.name, state: run.state, targetSessionId: run.targetSessionId, cwd: runCwd(run), queuedAt: run.queuedAt, finishedAt: run.finishedAt };
+}