@timqi/pier 0.0.29 → 0.1.1

package/dist/tasks/routes.js

@@ -1,7 +1,5 @@
-// The area's HTTP surface: tasks, runs, group and message routes for the
-// Console, plus the Activity snapshot it draws its graph from. A route reads
-// its body, names the caller and hands the decision to TaskService — policy
-// that lives here would be policy the task tool does not get.
+// The area's HTTP surface. A route names the caller and hands the decision to
+// TaskService: policy here would be policy the task tool does not get.
 import { record, requiredString } from "./definitions.js";
 /** Reject malformed filters instead of silently widening a global query. */
 function runQuery(params) {
@@ -51,10 +49,7 @@ export function registerTaskRoutes(app, tasks, activity) {
             const now = Date.now();
             const recent = c.req.query("scope") === "recent";
             const windowStart = now - 24 * 60 * 60 * 1000;
-            // "recent" is a superset of "active": a run still going is part of the
-            // last 24h no matter when it was queued, so it never drops a live run.
-            const runs = tasks.recentRuns(200).filter((run) => run.state === "queued" || run.state === "running" ||
-                (recent && run.queuedAt >= windowStart));
+            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();
@@ -227,9 +222,8 @@ export function registerTaskRoutes(app, tasks, activity) {
         const body = record(await jsonBody(c.req));
         const input = body && "input" in body ? body.input : null;
         try {
-            // A caller that names a mode gets an answer about it: dropping an
-            // unsupported override would run the definition's own policy instead —
-            // on a reuse definition, work injected into a live session.
+            // 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)}`);
             }

package/dist/tasks/runs.js

@@ -1,12 +1,7 @@
-// A definition plus an input becomes a queued run: where it came from, how
-// deep in a subagent chain it sits, whether it overlaps a run already going,
-// and which session hears about it. The limits that keep a chain from
-// exploding (depth, children per root) are decided here, once, because every
-// caller — scheduler, tool, HTTP — enqueues through this one door.
+// A definition plus an input becomes a queued run. The depth and per-root
+// limits are decided here because every caller enqueues through this one door.
 import { logger } from "../log.js";
-import { TaskCallbacks } from "./callbacks.js";
 import { newId } from "./definitions.js";
-import { TaskStore } from "./store.js";
 const log = logger("tasks");
 const MAX_DEPTH = 2;
 const MAX_CHILDREN_PER_ROOT = 16;
@@ -23,7 +18,8 @@ export class TaskRunQueue {
         this.execute = execute;
         this.changed = changed;
     }
-    enqueue(definition, input, source, parentRunId, provenance) {
+    /** Validate and persist only; callers may stage several runs in a transaction. */
+    prepare(definition, input, source, parentRunId, provenance) {
         const id = newId();
         const parent = parentRunId ? this.getRun(parentRunId) : null;
         const depth = provenance.depth ?? (parent ? parent.depth + 1 : 0);
@@ -63,6 +59,7 @@ export class TaskRunQueue {
             targetSessionId,
             sessionMode,
             callbackSessionId,
+            ...(provenance.callbackMode === "steer" ? { callbackMode: "steer" } : {}),
             background: provenance.background ?? false,
             callbackState: overlapped && callbackSessionId ? "pending" : null,
             callbackAttempts: 0,
@@ -84,11 +81,16 @@ export class TaskRunQueue {
             finishedAt: overlapped ? now : null,
         };
         this.store.saveRun(run);
+        return run;
+    }
+    /** Publish and execute only after all records this run relies on committed. */
+    start(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 { id, depth, triggerSource: source } = run;
+        const overlapped = run.skipReason === "overlap";
+        const definition = run.context.definition;
+        // Why a run exists is answerable only here: the row keeps the ids, not the
+        // reason. A watch probe queues every interval, so it logs at debug.
         const queued = `run ${id} ${run.state}: ${definition.name} via ${source}` +
             `${overlapped ? " (overlapped)" : ""}${depth > 0 ? ` depth ${String(depth)}` : ""}`;
         if (source === "watch" && !overlapped)
@@ -99,6 +101,5 @@ export class TaskRunQueue {
             this.execute(run);
         else if (run.callbackState === "pending")
             void this.callbacks.deliver(run);
-        return run;
     }
 }

package/dist/tasks/service.js

@@ -1,11 +1,6 @@
-// The one object the rest of Pier talks to about tasks, and the clock behind
-// it: the tick that finds what is due, the boot recovery that writes off runs
-// a restart interrupted, and the pause a drain needs. Every decision it looks
-// like it makes belongs to a file beside it (definitions, runs, execution,
-// groups, messages, callbacks) — what is genuinely here is scheduling and the
-// facade, so the HTTP routes and the task tool cannot drift apart.
-import { EventHub } from "../core/hub.js";
-import { Router } from "../core/router.js";
+// The facade the rest of Pier talks to about tasks, and the clock behind it:
+// the tick, the boot recovery that writes off interrupted runs, and the pause a
+// drain needs. Decisions belong to the files beside it.
 import { logger } from "../log.js";
 import { AgentTaskRunner } from "./agent.js";
 import { TaskCallbacks } from "./callbacks.js";
@@ -14,13 +9,11 @@ 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");
-/** The text a run was given, as the operator wrote it: a resume's follow-up,
- *  else the action's own prompt or script. Not `renderedPrompt` — that is the
- *  preamble and the input wrapper, which the delegating session did not send. */
+/** Not `renderedPrompt`: that carries the preamble and input wrapper, which the
+ *  delegating session did not send. */
 const runPrompt = (run) => {
     if (run.context.resumePrompt)
         return run.context.resumePrompt;
@@ -43,8 +36,7 @@ export class TaskService {
     runs;
     execution;
     constructor(store, factory, router, hub, 
-    /** Structural on purpose: tasks/ must not import settings.ts — main.ts
-     *  hands in a closure over the store instead. Absent in bare test rigs. */
+    /** Structural: tasks/ must not import settings.ts. Absent in bare test rigs. */
     instance) {
         this.store = store;
         this.factory = factory;
@@ -52,20 +44,21 @@ export class TaskService {
         this.hub = hub;
         this.instance = instance;
         const unreachable = (sessionId, what, why) => this.unreachable(sessionId, what, why);
-        this.messages = new TaskMessenger(store, router, hub, (runId, prompt, fromSessionId) => this.resume(runId, prompt, { invokedBySessionId: fromSessionId, callbackSessionId: fromSessionId, background: true }), unreachable);
+        this.messages = new TaskMessenger(store, router, hub, (runId, prompt, fromSessionId) => this.prepareResume(runId, prompt, { invokedBySessionId: fromSessionId, callbackSessionId: fromSessionId, background: true }), unreachable, (run) => this.runs.start(run));
         this.definitions = new TaskDefinitions(store, factory, router, hub, instance?.systemActions);
         this.callbacks = new TaskCallbacks(store, router, (run) => this.changed(run), unreachable);
         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, {
+            prepareMember: (taskId, groupId, callerSessionId, parentRunId) => this.prepareRun(taskId, null, "agent", parentRunId, {
                 invokedBySessionId: callerSessionId,
                 sourceSessionId: callerSessionId,
                 callbackSessionId: null,
                 background: true,
                 groupId,
             }),
+            startMember: (run) => this.runs.start(run),
         }, (group) => this.hub.emitWorkspace({ type: "task-group-changed", groupId: group.id }), unreachable);
         const agent = new AgentTaskRunner(factory, router, store, this.messages, (run) => this.changed(run));
         this.execution = new TaskExecution(store, this.definitions, this.callbacks, agent, {
@@ -110,10 +103,8 @@ export class TaskService {
         }, tickMs);
         this.timer.unref();
     }
-    /** Undo a `pause()` that was not followed by an exit — the auto-updater
-     *  drains before handing over, and a handover that never started must not
-     *  leave the scheduler switched off. Deliberately not `start()`: the boot
-     *  recovery in there would write off runs this process is still running. */
+    /** For a handover that never started. Not `start()`: its boot recovery would
+     *  write off runs this process is still running. */
     unpause(tickMs = 1000) {
         if (this.timer)
             return;
@@ -124,11 +115,8 @@ export class TaskService {
         this.pause();
         this.execution.stop();
     }
-    /** Stop taking new work but leave running runs alone — a graceful restart
-     *  (src/drain.ts) waits for them, where stop() would abort them. The
-     *  scheduler timer goes, and new root runs are refused; children of a run
-     *  that is still finishing stay allowed, because refusing them would fail
-     *  the very work the drain is waiting for. */
+    /** New root runs are refused, running ones left for the drain to wait on;
+     *  children of a finishing run stay allowed, or the drain fails its own work. */
     pause() {
         this.paused = true;
         if (this.timer)
@@ -145,11 +133,8 @@ export class TaskService {
     activeRunCount() {
         return this.store.countActiveRuns();
     }
-    /** The run this task has in flight, if any. The store already answers this
-     *  for the overlap guard (runs.ts); a caller that has just been refused as
-     *  an overlap needs the same answer to know what to wait for, and scanning
-     *  run history for it finds nothing once the skipped rows outnumber the
-     *  window. */
+    /** A caller refused as an overlap needs this to know what to wait for;
+     *  scanning run history finds nothing once skipped rows outnumber the window. */
     activeRun(taskId) {
         return this.store.findActiveRun(taskId);
     }
@@ -162,8 +147,7 @@ export class TaskService {
     create(raw, creator = "http") {
         return this.definitions.create(raw, creator);
     }
-    /** `by` is how the code that owns a definition says so; the HTTP routes and
-     *  the task tool have none, which is what closes both (definitions.ts). */
+    /** `by` is how owning code says so; the routes and the tool have none (definitions.ts). */
     update(id, raw, by) {
         return this.definitions.update(id, raw, by);
     }
@@ -198,22 +182,19 @@ export class TaskService {
     queryRuns(query = {}) {
         return this.store.queryRuns(query);
     }
-    recentRuns(limit = 100) {
-        return this.store.listRecentRuns(limit);
+    activityRuns(since) {
+        return this.store.activityRuns(since);
     }
     recentMessages(since) {
         return this.messages.recent(since);
     }
-    /** Every run this session delegated: the card is the message that started
-     *  it, and a message does not leave the transcript because the run ended. */
+    /** Every run, not the last hour's: the card is a message in the transcript. */
     backgroundRuns(sessionId) {
         return this.store.listRunsForSession(sessionId, 200)
             .filter((run) => run.background)
             .reverse()
             .map((run) => this.backgroundRun(run));
     }
-    /** The same runs `backgroundRuns` reports as in flight, counted per session
-     *  in one query — a list needs the number, not the runs. */
     activeBackgroundRunCounts() {
         return this.store.countActiveBackgroundRunsBySession();
     }
@@ -222,13 +203,18 @@ export class TaskService {
         return this.store.taskOwnedSessionIds();
     }
     run(taskId, input = null, source = "manual", parentRunId = null, provenance = {}) {
+        const run = this.prepareRun(taskId, input, source, parentRunId, provenance);
+        this.runs.start(run);
+        return run;
+    }
+    prepareRun(taskId, input, source, parentRunId, provenance) {
         this.refusePaused(parentRunId);
         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);
+        return this.runs.prepare(task, input, source, parentRunId, provenance);
     }
     async waitForRun(id) {
         const current = this.getRun(id);
@@ -256,9 +242,9 @@ export class TaskService {
     getGroup(id) {
         return this.groups.members(id);
     }
-    runGroup(definitions, join, callerSessionId, parentRunId, callbackSessionId) {
+    runGroup(definitions, join, callerSessionId, parentRunId, callbackSessionId, callbackMode) {
         this.refusePaused(parentRunId);
-        return this.groups.runAll(definitions, join, callerSessionId, parentRunId, callbackSessionId);
+        return this.groups.runAll(definitions, join, callerSessionId, parentRunId, callbackSessionId, callbackMode);
     }
     descendants(run) {
         const byParent = new Map();
@@ -291,6 +277,16 @@ export class TaskService {
         return this.messages.reply(messageId, fromSessionId, message);
     }
     resume(id, message, provenance = {}) {
+        const { run, expired } = this.store.transact(() => ({
+            run: this.prepareResume(id, message, provenance),
+            expired: this.messages.expireDecisions(id, "superseded by a manual resume"),
+        }));
+        for (const message of expired)
+            this.messages.changed(message);
+        this.runs.start(run);
+        return run;
+    }
+    prepareResume(id, message, provenance) {
         this.refusePaused();
         const prior = this.getRun(id);
         if (!isTerminal(prior.state))
@@ -299,8 +295,7 @@ export class TaskService {
             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, {
+        return this.runs.prepare(prior.context.definition, null, "agent", null, {
             ...provenance,
             sourceSessionId: provenance.invokedBySessionId ?? prior.invokedBySessionId,
             targetSessionId: prior.targetSessionId,
@@ -314,9 +309,7 @@ export class TaskService {
     tool(raw, callerSessionId) {
         return handleTaskTool(this, this.definitions, this.store, this.messages, raw, callerSessionId);
     }
-    /** The deployment's model advice: the operator's pinned menu when one is
-     * set, the curated live catalog otherwise — an agent picks from names that
-     * exist right now, never from memory. */
+    /** An agent picks from names that exist right now, never from memory. */
     async models() {
         const menu = this.instance?.modelMenu() ?? [];
         if (menu.length)
@@ -330,8 +323,17 @@ export class TaskService {
         try {
             const now = Date.now();
             this.sweep("schedule", () => {
-                for (const task of this.definitions.claimDue(now)) {
-                    this.run(task.id, null, task.trigger.type === "watch" ? "watch" : "cron");
+                // Per task: one enqueue that throws must not spend the other due tasks'
+                // occurrence, and its own stays due for the next tick.
+                for (const task of this.definitions.due(now)) {
+                    this.sweep(`schedule ${task.name}`, () => {
+                        const run = this.store.transact(() => {
+                            this.definitions.advance(task, now);
+                            return this.prepareRun(task.id, null, task.trigger.type === "watch" ? "watch" : "cron", null, {});
+                        });
+                        this.hub.emitWorkspace({ type: "tasks-changed" });
+                        this.runs.start(run);
+                    });
                 }
             });
             this.sweep("run callbacks", () => this.callbacks.recover(now));
@@ -342,16 +344,13 @@ export class TaskService {
             this.ticking = false;
         }
     }
-    /** A delivery nobody can complete. Retrying it forever costs the same
-     * silence as dropping it, so it stops here and says so on three surfaces:
-     * the operator's log, the record the tool and Console read, and the event
-     * stream of the session that was supposed to receive it (§5b). */
+    /** Retrying forever costs the same silence as dropping, so it stops and says
+     *  so on the log, the record and the recipient's event stream (§5). */
     unreachable(sessionId, what, why) {
         log.error(`gave up delivering ${what} to session ${sessionId}: ${why}`);
         this.router.reportTo(sessionId, `${what} could not be delivered — ${why}`);
     }
-    /** Four independent sweeps, isolated: one throwing (a group whose member row
-     * is gone throws on every pass) must not starve the retries behind it. */
+    /** Isolated: one sweep throwing on every pass must not starve the others. */
     sweep(what, run) {
         try {
             run();

package/dist/tasks/store.js

@@ -1,9 +1,10 @@
-// Every query this area makes against pier.db, and nothing else: definitions,
-// runs, groups and messages are rows here, read and written through one
-// connection db.ts opened. A store owns its queries, never its own tables or
-// its own handle — the schema is db.ts's migration list.
-import { pierDb, statements } from "../db.js";
+// Every query this area makes against pier.db, and nothing else; the schema is
+// db.ts's migration list.
+import { pierDb, statements, transact } from "../db.js";
 const clamp = (limit, cap) => Math.min(Math.max(limit, 1), cap);
+/** Kept unmatched probes per watch: one page of history, which is all any
+ *  surface lists of a probe that found nothing. */
+const KEPT_PROBES = 50;
 export class TaskStore {
     db;
     /** Every query below is a fixed string, so each is compiled once. */
@@ -12,9 +13,11 @@ export class TaskStore {
         this.db = db;
         this.sql = statements(db);
     }
-    // Every table is one JSON column plus query columns; these two are the only
-    // readers, and the one seam where a future schema change normalizes old rows
-    // (pre-v1 databases are refused outright in db.ts).
+    /** Commit related task records before publishing events or starting work. */
+    transact(work) {
+        return transact(this.db, work);
+    }
+    // The only readers of the JSON columns, and where a schema change normalizes old rows.
     #one(sql, ...params) {
         const row = this.sql(sql).get(...params);
         return row ? JSON.parse(row.json) : undefined;
@@ -35,9 +38,7 @@ export class TaskStore {
       ON CONFLICT(id) DO UPDATE SET updated_at=excluded.updated_at, json=excluded.json
     `).run(task.id, task.updatedAt, JSON.stringify(task));
     }
-    /** The tick's whole question, asked of the index rather than of every
-     *  document: a task with no next run (disabled, archived, manual) is not in
-     *  it, so an idle second reads no row. */
+    /** Asked of the index, not every document: an idle second reads no row. */
     listDueTasks(now) {
         return this.#many("SELECT json FROM tasks WHERE next_run_at IS NOT NULL AND next_run_at <= ?", now);
     }
@@ -58,9 +59,28 @@ export class TaskStore {
         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));
     }
-    /** The global list: filters precede the limit, and the id breaks timestamp
-     *  ties so a page boundary never repeats or skips a row. The statement is
-     *  built per call and not cached — the filter set makes it. */
+    /** A watch at the five-second floor mints 17k rows a day, ~1.6 kB each, that
+     *  no list shows; only rows nothing can dangle from are dropped — a child
+     *  run is named in its parent's stored result. */
+    pruneUnmatchedProbes(taskId) {
+        this.sql(`
+      DELETE FROM task_runs WHERE id IN (
+        SELECT r.id FROM task_runs r
+        WHERE r.task_id = ? AND r.state = 'succeeded' AND json_extract(r.json, '$.matched') IS 0
+          AND r.callback_state IS NULL AND json_extract(r.json, '$.groupId') IS NULL
+          AND json_extract(r.json, '$.parentRunId') IS NULL
+          AND NOT EXISTS (SELECT 1 FROM task_messages m WHERE m.run_id = r.id)
+          -- A NULL in this list would make NOT IN unknown for every candidate.
+          AND r.id NOT IN (
+            SELECT json_extract(c.json, '$.resumedFromRunId') FROM task_runs c
+            WHERE c.task_id = ? AND json_extract(c.json, '$.resumedFromRunId') IS NOT NULL
+          )
+        ORDER BY r.queued_at DESC, r.id DESC LIMIT -1 OFFSET ?
+      )
+    `).run(taskId, taskId, KEPT_PROBES);
+    }
+    /** The id breaks timestamp ties so a page boundary never repeats or skips a
+     *  row. Built per call, not cached: the filter set makes it. */
     queryRuns(query = {}) {
         const where = [];
         const params = [];
@@ -101,8 +121,18 @@ export class TaskStore {
             nextCursor: rows.length > limit && last ? { queuedAt: last.queuedAt, id: last.id } : null,
         };
     }
-    listRecentRuns(limit = 100) {
-        return this.#many("SELECT json FROM task_runs ORDER BY queued_at DESC LIMIT ?", clamp(limit, 500));
+    /** Activity never limits live work; only its optional history is bounded. */
+    activityRuns(since) {
+        const active = this.#many("SELECT json FROM task_runs WHERE state IN ('queued', 'running') ORDER BY queued_at DESC, id DESC");
+        if (since === undefined)
+            return active;
+        const recent = this.#many(`
+      SELECT json FROM task_runs
+      WHERE state NOT IN ('queued', 'running') AND queued_at >= ?
+        AND NOT (state = 'succeeded' AND json_extract(json, '$.matched') IS 0)
+      ORDER BY queued_at DESC, id DESC LIMIT 200
+    `, since);
+        return [...active, ...recent].sort((a, b) => b.queuedAt - a.queuedAt || b.id.localeCompare(a.id));
     }
     listRunsByRoot(rootRunId, limit = 100) {
         return this.#many(`
@@ -129,9 +159,7 @@ export class TaskStore {
       ORDER BY CASE state WHEN 'running' THEN 0 ELSE 1 END, queued_at DESC LIMIT 1
     `, sessionId);
     }
-    /** How many background runs each session has in flight, for a list that
-     *  draws one dot per row: the state column narrows the scan to the handful
-     *  of live runs, and no row's JSON is parsed. */
+    /** The state column narrows the scan to live runs; no JSON is parsed. */
     countActiveBackgroundRunsBySession() {
         const rows = this.sql(`
       SELECT json_extract(json, '$.invokedBySessionId') AS session_id, COUNT(*) AS n
@@ -143,10 +171,8 @@ export class TaskStore {
     `).all();
         return new Map(rows.map((row) => [row.session_id, row.n]));
     }
-    /** Every session a run created for itself — `fresh` is the one mode that
-     *  makes a session rather than borrowing one, and a resumed run reuses the
-     *  session its `fresh` predecessor already stamped. These are the agent's
-     *  conversations with itself, which the rail does not list. */
+    /** `fresh` is the one mode that makes a session rather than borrowing one;
+     *  these are the agent's conversations with itself, which the rail does not list. */
     taskOwnedSessionIds() {
         const rows = this.sql(`
       SELECT DISTINCT json_extract(json, '$.context.sessionId') AS id
@@ -200,10 +226,8 @@ export class TaskStore {
     listRecentMessages(since) {
         return this.#many("SELECT json FROM task_messages WHERE created_at >= ? ORDER BY created_at DESC LIMIT 200", since);
     }
-    /** Messages whose injection never landed, each beside the run it belongs to:
-     *  the delivery sweep needs both, and fetching the run per message made one
-     *  sweep cost a query per undelivered message. A message whose run is gone
-     *  comes back with `run: undefined` — the sweep drops it. */
+    /** Each beside its run, so the sweep costs one query. A message whose run is
+     *  gone comes back with `run: undefined`. */
     listUndeliveredMessages() {
         const rows = this.sql(`
       SELECT m.json AS json, r.json AS run_json
@@ -223,9 +247,8 @@ export class TaskStore {
       WHERE state = 'pending' AND json_extract(json, '$.kind') != 'decision'
     `).map((message) => {
             message.state = "expired";
-            // "Confirmed", not "completed": the input may well have been read — the
-            // proof of it lives in the recipient's transcript, which this layer
-            // cannot see, and the run it steered is interrupted by the same restart.
+            // "Confirmed", not "completed": the proof lives in a transcript this
+            // layer cannot see.
             message.error = "Pier restarted before delivery could be confirmed";
             this.saveMessage(message);
             return message;