@timqi/pier 0.0.28 → 0.1.0

package/dist/tasks/outbox.js

@@ -3,10 +3,12 @@
 // this logic was written twice and the two copies drifted — the ceiling was
 // checked in one order here and another there, and only one of them counted a
 // failed attempt.
-import { Router } from "../core/router.js";
 import { logger } from "../log.js";
 import { MAX_DELIVERY_ATTEMPTS, retryDelay, undeliverable } from "./types.js";
 const log = logger("tasks");
+/** The records a delivery names, from either side of the seam: a batch names
+ *  every one of them, a group names itself. */
+const callbackIds = (origin) => origin?.kind === "task-callback" ? origin.runIds ?? [origin.runId] : [];
 export class Outbox {
     router;
     kind;
@@ -35,6 +37,7 @@ export class Outbox {
             return;
         for (const record of mine)
             this.delivering.add(this.kind.id(record));
+        const counted = new Set();
         try {
             const session = await this.router.ensure({ channelId: "task", conversationId: sessionId });
             // The transcript read is both the crash-window dedupe and the proof.
@@ -46,40 +49,64 @@ export class Outbox {
                 return;
             // Waiting for a busy target is not a delivery attempt: counting it would
             // inflate the attempts once per second and skip the failure backoff
-            // straight to its ceiling.
-            if (session.state === "streaming") {
+            // straight to its ceiling. A record delegated with `steer` is the
+            // exception it asked for — it joins the running turn instead, and the
+            // rest of the batch keeps waiting for the turn to end. But only once:
+            // handed over, a steer sits in Pi's in-memory queue, invisible in the
+            // transcript until the turn drains it, so the queue is the second place
+            // this has to look before deciding nothing arrived (messages.ts:340).
+            const streaming = session.state === "streaming";
+            let sending = live;
+            if (streaming) {
+                const handedOver = await this.queued(session);
+                const steerNow = (record) => record.callbackMode === "steer" && !handedOver.has(this.kind.id(record));
+                sending = live.filter(steerNow);
                 for (const record of live)
-                    this.defer(record);
-                return;
+                    if (!steerNow(record))
+                        this.defer(record);
+                if (sending.length === 0)
+                    return;
             }
-            for (const record of live)
+            for (const record of sending) {
                 this.sent(record);
-            const { text, origin } = this.kind.input(live);
-            log.debug(`callback for ${live.map((r) => this.kind.id(r)).join(", ")} → session ${sessionId}`);
+                counted.add(this.kind.id(record));
+            }
+            const { text, origin } = this.kind.input(sending);
+            log.debug(`callback for ${sending.map((r) => this.kind.id(r)).join(", ")} → session ${sessionId}`);
             // Not awaited: `systemInput` settles with the recipient's whole turn, and
             // holding the delivery lock that long would keep the proof from ever
             // being read — which is the only thing that marks this delivered.
-            session.systemInput(text, origin, "followUp")
-                .catch((error) => this.retry(sessionId, live, error));
+            session.systemInput(text, origin, streaming ? "steer" : "followUp")
+                .catch((error) => this.retry(sessionId, sending, error, counted));
             // Pi records the input as it starts the turn, so the proof is usually
             // here already; the tick sweep is the backstop when it is not.
-            await this.settle(live, session);
+            await this.settle(sending, session);
         }
         catch (error) {
-            this.retry(sessionId, mine, error);
+            this.retry(sessionId, mine, error, counted);
         }
         finally {
             for (const record of mine)
                 this.delivering.delete(this.kind.id(record));
         }
     }
+    /** Handed over and waiting in the recipient's queue for the running turn to
+     *  drain it — what the transcript cannot answer yet. Empty unless the
+     *  session is streaming: Pi drops the list when the turn ends. */
+    async queued(session) {
+        const ids = new Set();
+        for (const origin of await session.pendingSystemInputs())
+            for (const id of callbackIds(origin))
+                ids.add(id);
+        return ids;
+    }
     /** Marks every record the transcript proves; returns the ones it does not. */
     async settle(records, session) {
         const seen = new Set();
         for (const turn of await session.history()) {
-            if (turn.role !== "system" || turn.origin?.kind !== "task-callback")
+            if (turn.role !== "system")
                 continue;
-            for (const id of turn.origin.runIds ?? [turn.origin.runId])
+            for (const id of callbackIds(turn.origin))
                 seen.add(id);
         }
         const unproven = [];
@@ -95,14 +122,15 @@ export class Outbox {
     /** The recipient is waiting for an answer that is now late: the retry itself
      *  is silent, so this line is the only sign it is being retried — and the
      *  ceiling is what ends the retrying out loud. */
-    retry(sessionId, batch, error) {
+    retry(sessionId, batch, error, counted) {
         log.warn(`callback to session ${sessionId} failed, will retry`, error);
         for (const stale of batch) {
             const record = this.kind.reload(this.kind.id(stale));
             // Already proven delivered, or already given up on: not a failure.
             if (!record || (record.callbackState !== "pending" && record.callbackState !== "failed"))
                 continue;
-            this.failed(record, error);
+            this.failed(record, error, counted.has(this.kind.id(record)));
+            counted.add(this.kind.id(record));
             this.spent(record, sessionId);
         }
     }
@@ -140,11 +168,10 @@ export class Outbox {
         record.callbackNextAttemptAt = null;
         this.write(record);
     }
-    /** Counts the attempt too: a target that fails before anything is sent (a
-     *  transcript that no longer exists) would otherwise retry at attempt 0 for
-     *  as long as the process lives, never reaching the ceiling. */
-    failed(record, error) {
-        record.callbackAttempts += 1;
+    /** A failed pass costs one attempt, whether it died before or after send. */
+    failed(record, error, counted) {
+        if (!counted)
+            record.callbackAttempts += 1;
         record.callbackState = "failed";
         record.callbackError = String(error);
         record.callbackNextAttemptAt = Date.now() + retryDelay(record.callbackAttempts);

package/dist/tasks/routes.js

@@ -51,10 +51,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();

package/dist/tasks/runs.js

@@ -4,9 +4,7 @@
 // exploding (depth, children per root) are decided here, once, because every
 // caller — scheduler, tool, HTTP — 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 +21,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 +62,7 @@ export class TaskRunQueue {
             targetSessionId,
             sessionMode,
             callbackSessionId,
+            ...(provenance.callbackMode === "steer" ? { callbackMode: "steer" } : {}),
             background: provenance.background ?? false,
             callbackState: overlapped && callbackSessionId ? "pending" : null,
             callbackAttempts: 0,
@@ -84,7 +84,14 @@ 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);
+        const { id, depth, triggerSource: source } = run;
+        const overlapped = run.skipReason === "overlap";
+        const definition = run.context.definition;
         // 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
@@ -99,6 +106,5 @@ export class TaskRunQueue {
             this.execute(run);
         else if (run.callbackState === "pending")
             void this.callbacks.deliver(run);
-        return run;
     }
 }

package/dist/tasks/service.js

@@ -4,8 +4,6 @@
 // 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";
 import { logger } from "../log.js";
 import { AgentTaskRunner } from "./agent.js";
 import { TaskCallbacks } from "./callbacks.js";
@@ -14,7 +12,6 @@ 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");
@@ -52,20 +49,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, {
@@ -198,8 +196,8 @@ 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);
@@ -222,13 +220,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 +259,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 +294,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 +312,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,

package/dist/tasks/store.js

@@ -2,7 +2,7 @@
 // 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";
+import { pierDb, statements, transact } from "../db.js";
 const clamp = (limit, cap) => Math.min(Math.max(limit, 1), cap);
 export class TaskStore {
     db;
@@ -12,6 +12,10 @@ export class TaskStore {
         this.db = db;
         this.sql = statements(db);
     }
+    /** Commit related task records before publishing events or starting work. */
+    transact(work) {
+        return transact(this.db, work);
+    }
     // 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).
@@ -101,8 +105,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(`

package/dist/tasks/tool.js

@@ -1,16 +1,17 @@
 import { isAbsolute, resolve } from "node:path";
 import { Type } from "typebox";
-import { TaskDefinitions, record, requiredString } from "./definitions.js";
-import { TaskMessenger } from "./messages.js";
-import { TaskStore } from "./store.js";
+import { logger } from "../log.js";
+import { record, requiredString } from "./definitions.js";
+import { isTerminal } from "./types.js";
+const log = logger("tasks");
 // JSON-Schema enum emits ~1/3 the tokens of typebox's anyOf-of-consts.
 const strEnum = (...values) => Type.Unsafe({ type: "string", enum: [...values] });
 /**
  * Drop the fields with nothing in them instead of sending `null`.
  *
  * A run summary has eighteen fields and most are empty for most of a run's
- * life; a model reads "absent" and "null" the same way. On a `get` that lists
- * several runs this is a third of the payload.
+ * life; a model reads "absent" and "null" the same way. On a group summary
+ * that lists several runs this is a third of the payload.
  *
  * The input names every field — a summary that forgot one would otherwise pass
  * as "that field was empty" — and the result is the type with the empty ones
@@ -28,6 +29,7 @@ const summarize = (run, pendingDecisionId) => defined({
     targetSessionId: run.targetSessionId,
     callbackSessionId: run.callbackSessionId,
     callbackState: run.callbackState,
+    callbackMode: run.callbackMode ?? null,
     pendingDecisionId,
     depth: run.depth,
     queuedAt: run.queuedAt,
@@ -36,9 +38,23 @@ const summarize = (run, pendingDecisionId) => defined({
     result: run.result,
     error: run.error,
     skipReason: run.skipReason,
+    next: null,
 });
-/** A list echoes many results at once, so each is capped; a single-run `get`
- * stays whole — it is the escape hatch every truncation note points at. */
+/** What a run receipt says happens next. The callback is the whole answer, so
+ *  the receipt says so — a model that just launched work otherwise reaches
+ *  for a status call. `none` is stated as what it is: no delivery at all. */
+const receipt = (summary, callbackSessionId, mode, callerSessionId) => ({
+    ...summary,
+    next: callbackSessionId === null
+        ? "callback none: the result is not delivered to anyone"
+        : callbackSessionId !== callerSessionId
+            ? `the result is delivered to session ${callbackSessionId}; this session will not receive a callback`
+            : mode === "steer"
+                ? "the result interrupts your running turn as a steer message; nothing to query"
+                : "the result arrives as a callback message once your turn ends; nothing to query",
+});
+/** A group echoes many results at once, so each is capped; a single-run
+ * `recover` stays whole — it is the escape hatch every truncation note points at. */
 const trimResult = (summary) => {
     if (summary.result?.type !== "agent" || summary.result.text.length <= 2000)
         return summary;
@@ -46,17 +62,32 @@ const trimResult = (summary) => {
         ...summary,
         result: {
             ...summary.result,
-            text: `${summary.result.text.slice(0, 2000)}\n[truncated — get run_id ${summary.runId} for the full text]`,
+            text: `${summary.result.text.slice(0, 2000)}\n[truncated — recover run_id ${summary.runId} with a reason for the full text]`,
         },
     };
 };
+/** Whether a callback record has said its last word: the input is in the
+ *  recipient's transcript, delivery was given up on and reported, or there
+ *  was never one to wait for (`callback:"none"`). Anything else is still on
+ *  its way, and reading the result here would be reading it twice. */
+const settled = (callback) => callback.callbackState === null || callback.callbackState === "delivered" || callback.callbackState === "abandoned";
+/** The one refusal `recover` gives before a result is readable. Deliberately
+ *  the same words for queued, running, pending and retrying: a refusal that
+ *  named the state would be the status query this operation replaced. */
+const notRecoverable = (what, callback) => {
+    throw new Error(callback.callbackSessionId === null
+        ? `${what} is not recoverable yet: it was launched with callback none, so nothing will be delivered; recover reads finished results only and cannot wait for work`
+        : `${what} is not recoverable yet: wait for automatic delivery to session ${callback.callbackSessionId}; recover cannot wait for work`);
+};
 const summarizeGroup = (group, members, messages) => defined({
     groupId: group.id,
     join: group.join,
     state: group.finishedAt ? "finished" : "running",
     callbackState: group.callbackState,
+    callbackMode: group.callbackMode ?? null,
     winnerRunId: group.winnerRunId,
     members: members.map((run) => trimResult(summarize(run, messages.openDecisionId(run.id)))),
+    next: null,
 });
 const LaunchSchema = Type.Object({
     model: Type.Optional(Type.Object({ provider: Type.String(), id: Type.String() })),
@@ -103,15 +134,15 @@ export function taskToolSpec(execute) {
     return {
         name: "task",
         label: "Pier Task",
-        description: "Manage durable Pier tasks and subagents. Agent tasks run in a fresh session or a reused one. create files a definition the operator sees in the Console — only for schedules or roles you will run again; a one-off is run with a prompt. Run executes a stored task by task_id, a one-shot subagent from a prompt (shorthand: prompt + optional cwd/launch/name — cwd defaults to your own directory, relative paths resolve against it, name comes from the prompt) or from a full inline task draft, or a core-joined fan-out via tasks[] with join all|first. Get accepts run_id, group_id, or task_id for that task's recent runs. Every operation returns immediately: results, group joins, and decision replies arrive as callback messages. Use steer/follow_up/resume for child control and contact/reply for supervisor decisions. models lists the deployment's model menu (operator pins with intent notes, else the live catalog).",
+        description: "Manage durable Pier tasks and subagents. Agent tasks run in a fresh session or a reused one. create files a definition the operator sees in the Console — only for schedules or roles you will run again; a one-off is run with a prompt. Run executes a stored task by task_id, a one-shot subagent from a prompt (shorthand: prompt + optional cwd/launch/name — cwd defaults to your own directory, relative paths resolve against it, name comes from the prompt) or from a full inline task draft, or a core-joined fan-out via tasks[] with join all|first. Every operation returns immediately: results, group joins, and decision replies arrive as callback messages once your turn ends — there is no status query; pass callback 'steer' to have a result interrupt your running turn instead, or 'none' for no callback at all. recover (run_id or group_id, plus a reason) re-reads a finished result after its callback has settled — for truncated text or lost context, never to check progress. Use steer/follow_up/resume for child control and contact/reply for supervisor decisions. models lists the deployment's model menu (operator pins with intent notes, else the live catalog).",
         parameters: Type.Object({
-            operation: strEnum("list", "create", "update", "run", "get", "cancel", "steer", "follow_up", "resume", "contact", "reply", "models"),
+            operation: strEnum("list", "create", "update", "run", "recover", "cancel", "steer", "follow_up", "resume", "contact", "reply", "models"),
             task_id: Type.Optional(Type.String()),
             run_id: Type.Optional(Type.String()),
             group_id: Type.Optional(Type.String()),
             message_id: Type.Optional(Type.String()),
             message: Type.Optional(Type.String()),
-            reason: Type.Optional(strEnum("progress", "decision")),
+            reason: Type.Optional(Type.String({ description: "contact: progress | decision. recover: why the delivered callback is not enough (required)." })),
             session_mode: Type.Optional(strEnum("fresh")),
             // The one-shot shorthand: a prompt is the whole delegation, and the
             // fresh session in the caller's own directory is what it means.
@@ -130,7 +161,7 @@ export function taskToolSpec(execute) {
             })),
             join: Type.Optional(strEnum("all", "first")),
             input: Type.Optional(Type.Unknown()),
-            callback: Type.Optional(strEnum("origin", "none")),
+            callback: Type.Optional(strEnum("origin", "none", "steer")),
             callback_session_id: Type.Optional(Type.String()),
         }),
         execute,
@@ -156,6 +187,9 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
         return definitions.update(requiredString(input.task_id, "task_id"), await expandDraft(definitions, input.task, callerSessionId));
     }
     if (input.operation === "run") {
+        // One reading of `callback` for both shapes below: a run and a fan-out
+        // choose the same way, and two readings are two things to keep in step.
+        const callbackMode = input.callback === "steer" ? "steer" : "followUp";
         if (Array.isArray(input.tasks)) {
             // Core-joined fan-out: members run detached, one aggregated callback.
             if (input.task !== undefined || input.task_id !== undefined)
@@ -173,8 +207,9 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
                     ? await resolveDraft(definitions, entry, active, callerSessionId)
                     : resolveStored(definitions, entry.task_id, active));
             }
-            const { group, runs } = host.runGroup(resolved, input.join === "first" ? "first" : "all", callerSessionId, active?.id ?? null, input.callback === "none" ? null : callerSessionId);
-            return summarizeGroup(group, runs, messages);
+            const groupCallbackSessionId = input.callback === "none" ? null : callerSessionId;
+            const { group, runs } = host.runGroup(resolved, input.join === "first" ? "first" : "all", callerSessionId, active?.id ?? null, groupCallbackSessionId, callbackMode);
+            return receipt(summarizeGroup(group, runs, messages), groupCallbackSessionId, callbackMode, callerSessionId);
         }
         const draft = input.task_id === undefined ? inlineDraft(input) : undefined;
         const task = draft
@@ -196,23 +231,55 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
             invokedBySessionId: callerSessionId,
             sourceSessionId: callerSessionId,
             callbackSessionId,
+            callbackMode,
             background: true,
             sessionMode,
         });
-        return summarize(run, null);
+        return receipt(summarize(run, null), callbackSessionId, callbackMode, callerSessionId);
     }
-    if (input.operation === "get") {
+    if (input.operation === "recover") {
+        // History only, never status: a result is readable here once its callback
+        // has said its last word, so nothing a caller could learn by asking is
+        // something it would not have been told. The reason is the friction — a
+        // caller states why the callback did not suffice, and the operator sees it.
+        const reason = requiredString(input.reason, "reason");
+        // A finished run with an open decision sends no completion callback — the
+        // question is the notification, and the reply's continuation reports.
+        const decisionOpen = (run) => {
+            throw new Error(`run ${run.id} finished awaiting your decision ${messages.openDecisionId(run.id) ?? ""}; reply to it — the continuation's callback brings the result`);
+        };
+        // A member waits for its group's callback, but a race winner need not
+        // wait for losing members to finish cancelling before recovering its text.
+        const groupReady = (group) => {
+            if (!group.finishedAt || !settled(group))
+                notRecoverable(`group ${group.id}`, group);
+        };
         if (typeof input.group_id === "string") {
             const { group, members } = host.getGroup(input.group_id);
+            groupReady(group);
+            if (!members.every((run) => isTerminal(run.state))) {
+                throw new Error(`recover cannot inspect active members; the race has settled — recover its winning result with run_id ${group.winnerRunId ?? "from the callback"} and a reason`);
+            }
+            const asking = members.find((run) => messages.openDecisionId(run.id));
+            if (asking)
+                decisionOpen(asking);
+            log.info(`recover group ${group.id} by ${callerSessionId}: ${reason}`);
             return summarizeGroup(group, members, messages);
         }
-        // Run history by task: without it, checking what a task did (or whether a
-        // cascade landed) means leaving the tool for the database.
-        if (input.run_id === undefined && typeof input.task_id === "string") {
-            return host.listRuns(input.task_id, 10).map((run) => trimResult(summarize(run, messages.openDecisionId(run.id))));
-        }
         const run = host.getRun(requiredString(input.run_id, "run_id"));
-        return summarize(run, messages.openDecisionId(run.id));
+        if (run.groupId) {
+            const { group } = host.getGroup(run.groupId);
+            groupReady(group);
+            if (!isTerminal(run.state))
+                throw new Error("the group has reported its outcome; recover reads finished results only and cannot wait for this member");
+        }
+        else if (!isTerminal(run.state) || !settled(run)) {
+            notRecoverable(`run ${run.id}`, run);
+        }
+        if (messages.openDecisionId(run.id))
+            decisionOpen(run);
+        log.info(`recover run ${run.id} by ${callerSessionId}: ${reason}`);
+        return summarize(run, null);
     }
     if (input.operation === "cancel") {
         if (typeof input.group_id === "string") {
@@ -235,17 +302,22 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
     if (input.operation === "resume") {
         const prior = host.getRun(requiredString(input.run_id, "run_id"));
         assertOwns(store, callerSessionId, active, prior);
+        const callbackSessionId = input.callback === "none" ? null : callerSessionId;
         const run = host.resume(prior.id, requiredString(input.message, "message"), {
             invokedBySessionId: callerSessionId,
-            callbackSessionId: input.callback === "none" ? null : callerSessionId,
+            callbackSessionId,
             background: true,
         });
-        return summarize(run, null);
+        return receipt(summarize(run, null), callbackSessionId, "followUp", callerSessionId);
     }
     if (input.operation === "contact") {
         if (!active)
             throw new Error("contact is only available inside an active Agent run");
-        const reason = input.reason === "decision" ? "decision" : "progress";
+        // The schema no longer narrows `reason` (recover shares the field), so the
+        // two names contact accepts are checked here.
+        const reason = input.reason === undefined ? "progress" : input.reason;
+        if (reason !== "progress" && reason !== "decision")
+            throw new Error(`contact reason must be progress or decision, got ${String(reason)}`);
         return messages.contact(active, callerSessionId, reason, requiredString(input.message, "message"));
     }
     if (input.operation === "reply") {

package/dist/tools.js

@@ -186,10 +186,10 @@ managedName = "reject") {
     return tools;
 }
 /** `~/.pier/tools/…` — install target, generated ubix config, ubix state. */
-export const toolsDir = (...parts) => pierPath("tools", ...parts);
+const toolsDir = (...parts) => pierPath("tools", ...parts);
 /** The one directory that goes on PATH: ubix installs into it, and everything
  *  Pier spawns inherits it. */
-export const toolsBin = () => toolsDir("bin");
+const toolsBin = () => toolsDir("bin");
 /**
  * First on PATH, once, at boot. First rather than last on purpose: a tool
  * switched on in the Console is Pier's copy at Pier's version, whatever the

package/dist/update.js

@@ -129,7 +129,7 @@ export function startAutoUpdate(check, auto, pollMs = AUTO_POLL_MS) {
     timer.unref(); // a pending check must never be what keeps the process alive
     return () => clearInterval(timer);
 }
-export async function fetchLatestVersion() {
+async function fetchLatestVersion() {
     // Plain JSON: the abbreviated-packument content type npm uses for a whole
     // package is a 406 on this endpoint, which answers one version already.
     const res = await fetch(ENDPOINT, {

package/dist/web/instance.js

@@ -2,7 +2,7 @@
 // layer-1 secrets control, the browser's error reports. Nothing here touches
 // a session; server.ts stays the session/event surface.
 import { logger } from "../log.js";
-import { normalizeModelMenu, normalizePublicUrl, } from "../settings.js";
+import { normalizeModelMenu, normalizeModelRef, normalizePublicUrl, } from "../settings.js";
 /** A rule that failed inside the transaction — its own class so the route can
  *  tell it from a real fault. 400 when the request named something this Pier
  *  does not have, 409 when it collided with the state as it stands. */
@@ -131,11 +131,11 @@ export function registerInstanceRoutes(app, deps) {
     app.put("/api/settings", async (c) => {
         const body = await c.req.json().catch(() => null);
         const fields = body
-            ? [body.publicUrl, body.modelMenu, body.autoUpdate, body.customTools, body.extension, body.tool]
+            ? [body.publicUrl, body.modelMenu, body.titleModel, body.autoUpdate, body.customTools, body.extension, body.tool]
             : [];
         if (!fields.some((v) => v !== undefined)) {
             return c.json({
-                error: "publicUrl, modelMenu, autoUpdate, customTools, extension or tool required",
+                error: "publicUrl, modelMenu, titleModel, autoUpdate, customTools, extension or tool required",
             }, 400);
         }
         // Everything is validated before anything is written, and everything is
@@ -157,6 +157,13 @@ export function registerInstanceRoutes(app, deps) {
                 return refuse("modelMenu must be [{provider, id, note?}] (≤32 entries)");
             writes.push(() => settings.setModelMenu(menu));
         }
+        if (body?.titleModel !== undefined) {
+            // null is the off switch; anything else has to be a model.
+            const ref = body.titleModel === null ? null : normalizeModelRef(body.titleModel);
+            if (ref === null && body.titleModel !== null)
+                return refuse("titleModel must be {provider, id} or null");
+            writes.push(() => settings.setTitleModel(ref));
+        }
         if (body?.autoUpdate !== undefined) {
             const { autoUpdate } = body;
             if (typeof autoUpdate !== "boolean")