@timqi/pier 0.1.0 → 0.1.1

package/dist/tasks/callbacks.js

@@ -1,15 +1,10 @@
 // What a finished run says to the session that delegated it. Delivery itself
 // belongs to outbox.ts; this file owns the run vocabulary and the batching.
 import { Outbox } from "./outbox.js";
-/** How a run is named to the session that gets its result: the run id, and the
- *  session that did the work — a relayer's next move is a deep link to it
- *  (`#/session/<id>`), and without this line that costs a second tool call.
- *  Shared with the group callback, which has always carried both. */
+/** The run id and the session that did the work: a relayer's next move is a
+ *  deep link to it, and without this that costs a second tool call. */
 export const runRef = (run) => `Run: ${run.id}${run.targetSessionId ? ` / Session: ${run.targetSessionId}` : ""}`;
-/** What the card in the recipient's transcript says the input came from. Part
- *  of the run vocabulary for the same reason `runRef` is: the callback, the
- *  subagent messages and the delegation prompt all name a run, and three
- *  spellings of "which task, on what model" would be three cards. */
+/** What the card in the recipient's transcript says the input came from. */
 export const runSource = (run) => ({
     taskName: run.context.definition.name,
     ...(run.context.model ? { model: run.context.model } : {}),
@@ -47,15 +42,13 @@ export class TaskCallbacks {
                     runId: runs[0].id,
                     sourceSessionId: runs[0].targetSessionId,
                     runIds: runs.map((run) => run.id),
-                    // Only when the input is about one run: a batch is several tasks in
-                    // one delivery, and the first one's name and model as the card's
-                    // caption would attribute every other result to it. The text names
-                    // each run; the card says nothing rather than something false.
+                    // Only for one run: a batch's caption would attribute every result
+                    // to the first run's name and model.
                     ...(runs.length === 1 ? { source: runSource(runs[0]), state: runs[0].state } : {}),
                 },
             }),
-            describe: (run) => `the result of "${run.context.definition.name}"`,
-        }, unreachable);
+            abandoned: (run, sessionId, why) => unreachable(sessionId, `the result of "${run.context.definition.name}"`, why),
+        });
     }
     target(callback, origin) {
         if (callback.type === "session")
@@ -75,8 +68,7 @@ export class TaskCallbacks {
         if (!first?.callbackSessionId || (first.callbackState !== "pending" && first.callbackState !== "failed"))
             return;
         const sessionId = first.callbackSessionId;
-        // Retry due-times are ignored when sweeping the batch: once one callback is
-        // deliverable, everything pending for the session rides along.
+        // Once one callback is deliverable, everything pending for the session rides along.
         const batch = this.store.listPendingCallbacks(Number.MAX_SAFE_INTEGER)
             .filter((run) => run.callbackSessionId === sessionId);
         if (!batch.some((run) => run.id === first.id))

package/dist/tasks/command.js

@@ -93,12 +93,8 @@ export function runBash(script, cwd, input, signal) {
                 stderrTruncated: stderr.truncated,
             });
         });
-        // A script that never reads stdin is ordinary (`exit 0`, a one-line curl),
-        // and writing the input to a pipe nobody is holding raises EPIPE *here*.
-        // Unhandled, that is an `error` event on a stream, which is an uncaught
-        // exception, which is main.ts exiting the process: one task script could
-        // take every session and every other run down with it. The input not being
-        // wanted is not a failure of the run — anything else still gets said.
+        // A script that never reads stdin raises EPIPE here; unhandled, that is an
+        // uncaught exception that exits the process. Not wanting the input is not a failure.
         child.stdin.on("error", (err) => {
             if (err.code !== "EPIPE")
                 log.warn(`run input could not be written: ${err.message}`);

package/dist/tasks/definitions.js

@@ -9,47 +9,25 @@ import { isThinkingLevel } from "../core/types.js";
 import { EventHub } from "../core/hub.js";
 import { Router } from "../core/router.js";
 import { TaskStore } from "./store.js";
-const DEFAULT_TIMEOUT = 900;
+// An agent run that implements, tests and commits one concern takes 15–60
+// minutes; the default is the runaway ceiling, not the pace of normal work.
+const DEFAULT_TIMEOUT = 3600;
 const MIN_WATCH_SECONDS = 5;
-/** Crockford's base32, lowercased: i, l, o and u are gone — the three that
- *  misread as 1/0 and the one that completes most accidental words — and one
- *  case throughout, so a model re-types an id it read verbatim. */
+/** Crockford's base32, lowercased: i, l, o and u are gone, and one case
+ *  throughout, so a model re-types an id it read verbatim. */
 const ID_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
-/** The one byte → symbol step, exported only so a test can walk all 256 byte
- *  values: a repeated or omitted character in the alphabet above biases every
- *  id ever minted, and no sample of finished ids can show it. */
+/** Exported only so a test can walk all 256 byte values for alphabet bias. */
 export const idSymbol = (byte) => ID_ALPHABET.charAt(byte & 31);
-/** The id every task record is minted with — runs, definitions, groups and
- *  messages alike — because these ids ride through model context constantly:
- *  every run summary, callback, get, steer and reply echoes one, and a UUID
- *  spends ~12 tokens where this spends ~6. Nothing parses or orders by them —
- *  every comparison in the area is string equality and every listing orders by
- *  a timestamp column — so rows minted as UUIDs before this keep working
- *  untouched; there is nothing to migrate. It lives here rather than in
- *  types.ts because the browser type-checks that file and it stays node-free.
- *
- *  Sixteen characters, 80 bits (`& 31` is unbiased because 256 is a multiple
- *  of 32). Sixty would have read the same and cost a token less, but a watch
- *  task on a 5-second interval mints ~6M runs a year, and a collision here is
- *  not an error: `saveRun`'s ON CONFLICT DO UPDATE would quietly overwrite the
- *  older run with the newer one. Four more characters buy ~16 million times
- *  the headroom for four bytes — cheaper than the alternative fix, which is a
- *  strict INSERT and a retry loop on every one of the four mint sites. */
+/** Every task record's id. These ride through model context constantly, and a
+ *  UUID spends ~12 tokens where this spends ~6. Sixteen characters (80 bits;
+ *  `& 31` is unbiased): a watch task mints ~6M runs a year, and a collision is
+ *  not an error — `saveRun`'s ON CONFLICT DO UPDATE would quietly overwrite. */
 export const newId = () => Array.from(randomBytes(16), idSymbol).join("");
-/**
- * Seam decision (tasks/): a definition Pier's own code created is reconciled by
- * that code, and edited by nobody.
- *
- * `creator` is `"http"` for the Console and `session:<id>` for the task tool.
- * Anything else is an instance-layer owner — today the tools update task
- * (src/tools-task.ts), whose script a switch in Settings runs on demand and
- * cron runs nightly. Both
- * public surfaces could rename it, point it at another script, pause it or
- * archive it, and the switch would go on claiming Pier keeps the tools current
- * while the run did something else entirely. The owner names itself in `by`;
- * neither the routes nor the tool has a `by` to pass, so this one function
- * closes both.
- */
+/** A definition Pier's own code created is reconciled by that code and edited
+ *  by nobody: `creator` is `"http"` (Console) or `session:<id>` (task tool);
+ *  anything else is an instance-layer owner, which names itself in `by`.
+ *  Otherwise a public surface could repoint the tools task while its switch
+ *  went on claiming Pier keeps the tools current. */
 const ownerOf = (task) => task.creator === "http" || task.creator.startsWith("session:") ? null : task.creator;
 export const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
     ? value
@@ -143,9 +121,8 @@ export class TaskDefinitions {
         return task;
     }
     async create(raw, creator = "http", kind = "task") {
-        // The tool schema marks trigger optional, so a trigger-less new definition
-        // means manual. Update keeps requiring it: replacing a cron task with a
-        // draft that forgot its trigger must not silently unschedule it.
+        // A trigger-less new definition means manual. Update keeps requiring it:
+        // a draft that forgot its trigger must not silently unschedule a cron task.
         const value = record(raw);
         const draft = await this.parseDraft(value && value.trigger === undefined ? { ...value, trigger: { type: "manual" } } : raw, creator);
         const now = Date.now();
@@ -176,19 +153,24 @@ export class TaskDefinitions {
     async update(id, raw, by) {
         const old = this.get(id);
         this.assertOwner(old, by, "edited");
-        if (old.archived)
-            throw new Error("archived tasks cannot be edited");
         const draft = await this.parseDraft(raw, ownerOf(old) ? by : undefined);
+        // Validation awaits, so the record read above is a guess by now: archive()
+        // or another edit may have landed, and the spread below would restore it.
+        const current = this.get(id);
+        if (current.archived)
+            throw new Error("archived tasks cannot be edited");
+        if (current.revision !== old.revision)
+            throw new Error("task was edited while this draft was validated");
         const now = Date.now();
         const task = {
-            ...old,
+            ...current,
             name: draft.name,
             description: draft.description ?? "",
-            enabled: draft.enabled ?? old.enabled,
-            revision: old.revision + 1,
+            enabled: draft.enabled ?? current.enabled,
+            revision: current.revision + 1,
             trigger: draft.trigger,
             action: draft.action,
-            callback: draft.callback ?? old.callback,
+            callback: draft.callback ?? current.callback,
             timeoutSeconds: draft.timeoutSeconds ?? DEFAULT_TIMEOUT,
             nextRunAt: null,
             updatedAt: now,
@@ -228,20 +210,16 @@ export class TaskDefinitions {
             this.store.saveTask(task);
         }
     }
-    claimDue(now) {
-        const due = [];
-        // The store narrows to the tasks with a next run at or before `now`; the
-        // JSON is still the record, so its own fields decide.
-        for (const task of this.store.listDueTasks(now)) {
-            if (!task.enabled || task.archived || task.nextRunAt === null || task.nextRunAt > now)
-                continue;
-            task.nextRunAt = nextRunAt(task.trigger, now);
-            this.store.saveTask(task);
-            due.push(task);
-        }
-        if (due.length)
-            this.changed();
-        return due;
+    /** The store narrows by index; the JSON is still the record, so its fields decide. */
+    due(now) {
+        return this.store.listDueTasks(now)
+            .filter((task) => task.enabled && !task.archived && task.nextRunAt !== null && task.nextRunAt <= now);
+    }
+    /** Committed with the run this occurrence queues: a failed enqueue rolls the
+     *  advance back, so the occurrence stays due instead of being skipped. */
+    advance(task, now) {
+        task.nextRunAt = nextRunAt(task.trigger, now);
+        this.store.saveTask(task);
     }
     async sessionExists(sessionId) {
         return this.router.stateOf(sessionId) !== undefined ||
@@ -332,8 +310,7 @@ export class TaskDefinitions {
             session = { mode: "fresh", cwd };
         }
         else {
-            // Validation never mutates: a dedicated session is created explicitly
-            // (POST /api/sessions) and then referenced with mode:"reuse".
+            // Validation never mutates: a session is created explicitly and then reused.
             throw new Error('agent session policy required, e.g. {"mode":"fresh","cwd":"/abs/path"} or {"mode":"reuse","sessionId":"..."}');
         }
         if (session.mode === "reuse" && launch)

package/dist/tasks/execution.js

@@ -1,7 +1,5 @@
-// One queued run carried to a result: dispatched by action kind (a bash
-// script, an agent session, another task or an owned system action), abortable
-// while it goes, settled exactly once. Command and agent work lives in
-// command.ts and agent.ts; this file owns the lifecycle they share.
+// One queued run carried to a result: dispatched by action kind, abortable,
+// settled exactly once. The lifecycle command.ts and agent.ts share.
 import { logger } from "../log.js";
 import { runBash } from "./command.js";
 const log = logger("tasks");
@@ -35,17 +33,27 @@ export class TaskExecution {
         this.controllers.set(run.id, controller);
         let timedOut = false;
         let cause;
-        const timeout = setTimeout(() => {
-            if (controller.signal.aborted)
+        let timeout;
+        // The budget is the run's own: waiting for an agent slot or a busy session
+        // (agent.ts) is bounded by cancellation and restart, never by the timeout.
+        const start = () => {
+            timeout ??= setTimeout(() => {
+                if (controller.signal.aborted)
+                    return;
+                timedOut = true;
+                controller.abort();
+            }, run.context.definition.timeoutSeconds * 1000).unref();
+            if (run.state === "running")
                 return;
-            timedOut = true;
-            controller.abort();
-        }, run.context.definition.timeoutSeconds * 1000);
-        timeout.unref();
+            run.state = "running";
+            run.startedAt = Date.now();
+            this.store.saveRun(run);
+            this.host.changed(run);
+        };
         try {
             const { definition } = run.context;
             if (definition.trigger.type === "watch" && !run.resumedFromRunId) {
-                this.markRunning(run);
+                start();
                 run.probe = await runBash(definition.trigger.script, definition.trigger.cwd, run.input, controller.signal);
                 run.matched = run.probe.exitCode === 0;
                 this.store.saveRun(run);
@@ -55,20 +63,17 @@ export class TaskExecution {
                     throw new Error(`watch probe exited ${String(run.probe.exitCode)}`);
             }
             if (run.matched !== false)
-                run.result = await this.executeAction(run, controller.signal);
+                run.result = await this.executeAction(run, controller.signal, start);
             controller.signal.throwIfAborted();
             run.state = "succeeded";
             if (definition.trigger.type === "watch" && !run.resumedFromRunId && definition.trigger.mode === "once" && run.matched) {
-                // As the definition's own creator: a one-shot watch retiring itself is
-                // the task layer keeping its own promise, not a surface editing
-                // somebody's task, and the owner guard (definitions.ts) would
-                // otherwise fail the run that had just succeeded.
+                // As the definition's own creator, or the owner guard (definitions.ts)
+                // would fail the run that just succeeded.
                 this.definitions.setEnabled(definition.id, false, definition.creator);
             }
         }
         catch (error) {
-            // A killed child reports `exited null`, not `cancelled`: report why we
-            // aborted instead of how the corpse looked.
+            // A killed child reports `exited null`; report why we aborted instead.
             const aborted = controller.signal.aborted;
             run.state = aborted ? (timedOut ? "failed" : "cancelled") : "failed";
             run.error = timedOut ? "task timed out" : aborted ? "cancelled" : String(error);
@@ -79,10 +84,8 @@ export class TaskExecution {
             run.finishedAt = Date.now();
             const seconds = ((run.finishedAt - (run.startedAt ?? run.queuedAt)) / 1000).toFixed(1);
             const settled = `run ${run.id} (${run.context.definition.name}) ${run.state} in ${seconds}s`;
-            // A scheduled run has no one watching it: the run row is the only other
-            // place this exists, and nobody opens the Console to find out it failed.
-            // A watch probe that did not match is the opposite case — it fires on
-            // every interval and at info would be most of the journal.
+            // Nobody opens the Console to find out a scheduled run failed. A watch
+            // probe that did not match fires every interval and would be most of the journal.
             if (run.state === "failed")
                 log.error(settled, cause);
             else if (run.matched === false)
@@ -98,23 +101,30 @@ export class TaskExecution {
                 this.store.saveRun(run);
             }
             catch (err) {
-                // Waiters settle from the in-memory run below; the callback and any
-                // group join read the stale row and wait — the next boot's interrupt
-                // sweep re-marks it and delivers then. Named here so that delay has
-                // an explanation.
+                // Waiters settle from the in-memory run; the callback reads the stale
+                // row and waits for the next boot's interrupt sweep.
                 log.error(`run ${run.id} final save failed — callback/join deferred to next boot`, err);
             }
+            if (run.matched === false) {
+                try {
+                    this.store.pruneUnmatchedProbes(run.taskId);
+                }
+                catch (err) {
+                    // Housekeeping: a waiter on this run is owed its settlement regardless.
+                    log.warn(`run ${run.id} probe retention failed`, err);
+                }
+            }
             this.host.changed(run);
             this.host.settled(run);
             if (run.callbackState === "pending")
                 void this.callbacks.deliver(run);
         }
     }
-    async executeAction(run, signal) {
+    async executeAction(run, signal, start) {
         signal.throwIfAborted();
         const action = run.context.definition.action;
         if (action.type === "bash") {
-            this.markRunning(run);
+            start();
             run.context.cwd = action.cwd;
             this.store.saveRun(run);
             const result = await runBash(action.script, action.cwd, run.input, signal);
@@ -126,7 +136,7 @@ export class TaskExecution {
             return output;
         }
         if (action.type === "system") {
-            this.markRunning(run);
+            start();
             const handler = this.definitions.systemAction(action.name, run.context.definition.creator);
             signal.throwIfAborted();
             const text = await handler(signal);
@@ -134,7 +144,7 @@ export class TaskExecution {
             return { type: "system", text };
         }
         if (action.type === "task") {
-            this.markRunning(run);
+            start();
             const child = this.host.runChild(action.taskId, run);
             let rejectWait = (reason) => { void reason; };
             const aborted = new Promise((_, reject) => { rejectWait = reject; });
@@ -155,14 +165,6 @@ export class TaskExecution {
                 signal.removeEventListener("abort", onAbort);
             }
         }
-        return this.agent.execute(run, action, signal, () => this.markRunning(run));
-    }
-    markRunning(run) {
-        if (run.state === "running")
-            return;
-        run.state = "running";
-        run.startedAt = Date.now();
-        this.store.saveRun(run);
-        this.host.changed(run);
+        return this.agent.execute(run, action, signal, start);
     }
 }

package/dist/tasks/groups.js

@@ -1,7 +1,5 @@
-// The fan-out join: members start detached, and the group is what turns their
-// separate endings into one answer — when the join condition is met, which
-// members are cancelled, and the single aggregated callback that goes back.
-// Delivering it is the outbox's job; deciding it is this file's.
+// The fan-out join: when the join condition is met, which members are
+// cancelled, and the single aggregated callback. Delivering it is the outbox's job.
 import { logger } from "../log.js";
 import { runRef, runResultText } from "./callbacks.js";
 import { newId } from "./definitions.js";
@@ -26,15 +24,14 @@ export class TaskGroups {
             reload: (id) => this.store.getGroup(id),
             save: (group) => { this.store.saveGroup(group); },
             changed,
-            // A group names itself in the origin where a run names its run id, so the
-            // engine's transcript proof works unchanged; the console's run route
-            // resolves that id to the group's members (web/ui/task-runs.ts).
+            // A group names itself where a run names its run id, so the engine's
+            // transcript proof works unchanged.
             input: (groups) => ({
                 text: this.text(groups[0]),
                 origin: { kind: "task-callback", taskId: groups[0].id, runId: groups[0].id, sourceSessionId: null },
             }),
-            describe: (group) => `the result of a ${String(group.memberRunIds.length)}-run group`,
-        }, unreachable);
+            abandoned: (group, sessionId, why) => unreachable(sessionId, `the result of a ${String(group.memberRunIds.length)}-run group`, why),
+        });
     }
     /** Enqueues every member or none: a partially started group is worse than
      * a rejected one. */
@@ -105,8 +102,8 @@ export class TaskGroups {
     evaluate(group) {
         if (group.finishedAt !== null)
             return;
-        // Old versions could leave an empty group when admission failed. Retire
-        // that broken record without inventing a successful zero-member join.
+        // An empty group is a broken record; retire it without inventing a
+        // successful zero-member join.
         if (group.memberRunIds.length === 0) {
             group.finishedAt = Date.now();
             group.callbackState = group.callbackSessionId ? "abandoned" : null;