@timqi/pier 0.0.29 → 0.1.1

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,13 +1,7 @@
-// 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 { AgentTaskRunner } from "./agent.js";
-import { TaskCallbacks } from "./callbacks.js";
 import { runBash } from "./command.js";
-import { TaskDefinitions } from "./definitions.js";
-import { TaskStore } from "./store.js";
 const log = logger("tasks");
 export class TaskExecution {
     store;
@@ -39,15 +33,27 @@ export class TaskExecution {
         this.controllers.set(run.id, controller);
         let timedOut = false;
         let cause;
-        const timeout = setTimeout(() => {
-            timedOut = true;
-            controller.abort();
-        }, run.context.definition.timeoutSeconds * 1000);
-        timeout.unref();
+        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;
+            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);
@@ -57,19 +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);
@@ -80,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)
@@ -99,22 +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; });
@@ -143,6 +153,8 @@ export class TaskExecution {
                 rejectWait(new Error("cancelled"));
             };
             signal.addEventListener("abort", onAbort, { once: true });
+            if (signal.aborted)
+                onAbort();
             try {
                 const done = await Promise.race([this.host.waitForRun(child.id), aborted]);
                 if (done.state !== "succeeded")
@@ -153,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,13 +1,9 @@
-// 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.
-import { Router } from "../core/router.js";
+// 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";
 import { Outbox } from "./outbox.js";
-import { TaskStore } from "./store.js";
 import { isTerminal } from "./types.js";
 const log = logger("tasks");
 /** Core-owned fan-out join: members run detached, the group delivers one
@@ -16,43 +12,44 @@ export class TaskGroups {
     store;
     host;
     changed;
+    unreachable;
     outbox;
     constructor(store, router, host, changed, unreachable) {
         this.store = store;
         this.host = host;
         this.changed = changed;
+        this.unreachable = unreachable;
         this.outbox = new Outbox(router, {
             id: (group) => group.id,
             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. */
-    runAll(definitions, join, callerSessionId, parentRunId, callbackSessionId) {
-        const group = this.create(join, callerSessionId, callbackSessionId);
-        const runs = [];
-        try {
-            for (const definition of definitions) {
-                runs.push(this.host.startMember(definition.id, group.id, callerSessionId, parentRunId));
-            }
-        }
-        catch (error) {
-            log.warn(`group ${group.id} rolled back after ${String(runs.length)} members`, error);
-            for (const run of runs)
-                this.host.cancel(run.id);
-            throw error;
-        }
-        this.setMembers(group, runs.map((run) => run.id));
+    runAll(definitions, join, callerSessionId, parentRunId, callbackSessionId, callbackMode) {
+        if (definitions.length < 2)
+            throw new Error("a task group needs at least 2 members");
+        const { group, runs } = this.store.transact(() => {
+            const group = this.create(join, callerSessionId, callbackSessionId, callbackMode);
+            const runs = definitions.map((definition) => this.host.prepareMember(definition.id, group.id, callerSessionId, parentRunId));
+            group.memberRunIds = runs.map((run) => run.id);
+            this.store.saveGroup(group);
+            return { group, runs };
+        });
+        this.changed(group);
+        for (const run of runs)
+            this.host.startMember(run);
+        // Skipped members do not pass through execution's settled hook.
+        this.evaluate(this.get(group.id));
         return { group: this.get(group.id), runs };
     }
     members(id) {
@@ -64,12 +61,13 @@ export class TaskGroups {
             this.host.cancel(runId);
         return this.get(id);
     }
-    create(join, invokedBySessionId, callbackSessionId) {
-        const group = {
+    create(join, invokedBySessionId, callbackSessionId, callbackMode) {
+        return {
             id: newId(),
             join,
             invokedBySessionId,
             callbackSessionId,
+            ...(callbackMode === "steer" ? { callbackMode } : {}),
             memberRunIds: [],
             winnerRunId: null,
             callbackState: null,
@@ -79,13 +77,6 @@ export class TaskGroups {
             createdAt: Date.now(),
             finishedAt: null,
         };
-        this.store.saveGroup(group);
-        return group;
-    }
-    setMembers(group, runIds) {
-        group.memberRunIds = runIds;
-        this.store.saveGroup(group);
-        this.changed(group);
     }
     get(id) {
         const group = this.store.getGroup(id);
@@ -109,6 +100,21 @@ export class TaskGroups {
         }
     }
     evaluate(group) {
+        if (group.finishedAt !== null)
+            return;
+        // 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;
+            group.callbackError = "group admission failed before its members were recorded";
+            this.store.saveGroup(group);
+            this.changed(group);
+            log.error(`group ${group.id}: ${group.callbackError}`);
+            if (group.callbackSessionId)
+                this.unreachable(group.callbackSessionId, `task group ${group.id}`, group.callbackError);
+            return;
+        }
         const members = group.memberRunIds.map((id) => this.host.getRun(id));
         if (group.join === "first") {
             const winner = members.find((run) => isTerminal(run.state));