@timqi/pier 0.1.3 → 0.1.5

package/dist/tasks/operations.js

@@ -0,0 +1,335 @@
+// The `/task` socket route: every `pier task` operation — run, message, save,
+// list, cancel, recover — validated here once, answered with the summaries a
+// model reads. Scheduling and delivery stay in the service; this file decides
+// who may ask for what.
+import { isAbsolute, resolve } from "node:path";
+import { logger } from "../log.js";
+import { record, requiredString } from "./definitions.js";
+import { isTerminal } from "./types.js";
+const log = logger("tasks");
+/** Absent instead of `null`: a model reads both the same way, and on a group
+ *  summary the nulls are a third of the payload. The input names every field
+ *  so a summary that forgot one cannot pass as "empty". */
+const defined = (value) => Object.fromEntries(Object.entries(value).filter(([, v]) => v !== null && v !== undefined));
+const summarize = (run) => defined({
+    runId: run.id,
+    taskId: run.taskId,
+    taskName: run.context.definition.name,
+    state: run.state,
+    triggerSource: run.triggerSource,
+    groupId: run.groupId,
+    sessionMode: run.sessionMode,
+    targetSessionId: run.targetSessionId,
+    callbackSessionId: run.callbackSessionId,
+    callbackState: run.callbackState,
+    callbackMode: run.callbackMode ?? null,
+    queuedAt: run.queuedAt,
+    startedAt: run.startedAt,
+    finishedAt: run.finishedAt,
+    result: run.result,
+    error: run.error,
+    skipReason: run.skipReason,
+    next: null,
+});
+/** The receipt says the callback is the whole answer, or a model that just
+ *  launched work reaches for a status call. */
+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 typo in an enum field must not silently mean its default. */
+const oneOf = (input, key, values) => {
+    const value = input[key];
+    if (value === undefined || values.includes(value))
+        return value;
+    throw new Error(`${key} must be one of ${values.join(", ")}`);
+};
+const callbackModeOf = (input) => oneOf(input, "callback", ["origin", "none", "steer"]) === "steer" ? "steer" : "followUp";
+/** Who a new run's result goes to — the caller, nobody, or a named session that
+ *  must exist. Shared by `run` and `message` on a finished run: a resumed run is a new run. */
+const callbackTarget = async (input, definitions, callerSessionId) => {
+    if (input.callback_session_id === undefined)
+        return input.callback === "none" ? null : callerSessionId;
+    if (input.callback === "none")
+        throw new Error("callback none and callback_session_id conflict: pick one delivery target");
+    const target = requiredString(input.callback_session_id, "callback_session_id");
+    if (!(await definitions.sessionExists(target)))
+        throw new Error(`unknown session: ${target}`);
+    return target;
+};
+/** 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;
+    return {
+        ...summary,
+        result: {
+            ...summary.result,
+            text: `${summary.result.text.slice(0, 2000)}\n[truncated — pier task recover --run ${summary.runId} --reason … for the full text]`,
+        },
+    };
+};
+/** Delivered, given up on and reported, or never owed (`callback:"none"`).
+ *  Anything else is still on its way, and reading it here would be reading it twice. */
+const settled = (callback) => callback.callbackState === null || callback.callbackState === "delivered" || callback.callbackState === "abandoned";
+/** The same words for queued, running, pending and retrying: a refusal that
+ *  named the state would be the status query this surface refuses. */
+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) => 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))),
+    next: null,
+});
+const CANCEL_WAIT_MS = 2000;
+/** The run once terminal, or as it stands after `ms`. */
+function cancelledOrCurrent(host, id, ms) {
+    return Promise.race([
+        host.waitForRun(id),
+        new Promise((resolve) => setTimeout(() => resolve(host.getRun(id)), ms).unref()),
+    ]);
+}
+export async function handleTask(host, definitions, store, raw, callerSessionId) {
+    const input = record(raw);
+    if (!input)
+        throw new Error("task parameters required");
+    // Delegation is one level (docs/design/09-tasks-cli.md §Two levels, no tree):
+    // what a supervised run launched would report to a session no run owns. A
+    // queued run has not taken the session's turn, so it gates nothing yet.
+    const active = store.findActiveRunForTarget(callerSessionId);
+    if (active?.state === "running" && store.supervised(active))
+        throw new Error("a delegated run cannot delegate; ask in your result and let your supervisor run it");
+    const menu = () => host.models().then((listed) => listed.models);
+    if (input.operation === "list")
+        return definitions.list().filter((task) => task.kind !== "subagent");
+    if (input.operation === "save") {
+        const draft = await expandDraft(definitions, menu, input.task, callerSessionId);
+        if (input.task_id === undefined)
+            return definitions.create(draft, `session:${callerSessionId}`);
+        const id = requiredString(input.task_id, "task_id");
+        // A one-shot's hidden definition is a run's record, not a task anyone filed.
+        if (definitions.get(id).kind === "subagent")
+            throw new Error(`${id} is a one-shot run's own definition; save without --task-id to file a task`);
+        return definitions.update(id, draft);
+    }
+    if (input.operation === "run") {
+        // `--model ?`: the menu instead of a run, the one lookup the common case never pays.
+        if (record(input.launch)?.model === "?") {
+            const { source, models } = await host.models();
+            const head = source === "menu" ? "the operator's menu" : "the live catalog (no model pinned)";
+            return `${head} — --model takes a provider/id or a unique substring of one:\n${menuLines(models)}`;
+        }
+        const callbackMode = callbackModeOf(input);
+        if (Array.isArray(input.tasks)) {
+            // Core-joined fan-out: members run detached, one aggregated callback.
+            if (input.task !== undefined || input.task_id !== undefined)
+                throw new Error("use either task/task_id or tasks[]");
+            if (input.callback_session_id !== undefined)
+                throw new Error("callback_session_id applies to a single run only");
+            if (input.tasks.length < 2)
+                throw new Error("tasks[] needs at least 2 entries; use task for a single run");
+            const resolved = [];
+            for (const rawEntry of input.tasks) {
+                const entry = typeof rawEntry === "string" ? { prompt: rawEntry } : record(rawEntry);
+                if (!entry)
+                    throw new Error("invalid tasks[] entry");
+                resolved.push(entry.task_id === undefined
+                    ? await resolveDraft(definitions, menu, entry, callerSessionId)
+                    : definitions.get(requiredString(entry.task_id, "task_id")));
+            }
+            const groupCallbackSessionId = input.callback === "none" ? null : callerSessionId;
+            const { group, runs } = host.runGroup(resolved, oneOf(input, "join", ["all", "first"]) ?? "all", callerSessionId, groupCallbackSessionId, callbackMode);
+            return receipt(summarizeGroup(group, runs), groupCallbackSessionId, callbackMode, callerSessionId);
+        }
+        const draft = input.task_id === undefined ? inlineDraft(input) : undefined;
+        const task = draft
+            ? await resolveDraft(definitions, menu, draft, callerSessionId)
+            : definitions.get(requiredString(input.task_id, "task_id"));
+        const callbackSessionId = await callbackTarget(input, definitions, callerSessionId);
+        const run = host.run(task.id, null, "agent", null, {
+            invokedBySessionId: callerSessionId,
+            sourceSessionId: callerSessionId,
+            callbackSessionId,
+            callbackMode,
+            background: true,
+        });
+        return receipt(summarize(run), callbackSessionId, callbackMode, callerSessionId);
+    }
+    if (input.operation === "recover") {
+        // History only, never status: readable once the callback has said its last
+        // word. The required reason is the friction, and the operator sees it.
+        const reason = requiredString(input.reason, "reason");
+        // A race winner need not wait for losing members to finish cancelling.
+        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 ${group.winnerRunId ?? "<id from the callback>"} and a reason`);
+            }
+            log.info(`recover group ${group.id} by ${callerSessionId}: ${reason}`);
+            return summarizeGroup(group, members);
+        }
+        const run = host.getRun(requiredString(input.run_id, "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);
+        }
+        log.info(`recover run ${run.id} by ${callerSessionId}: ${reason}`);
+        return summarize(run);
+    }
+    if (input.operation === "cancel") {
+        if (typeof input.group_id === "string") {
+            const { group, members } = host.getGroup(input.group_id);
+            for (const member of members)
+                assertOwns(callerSessionId, member);
+            const cancelled = host.cancelGroup(group.id);
+            return summarizeGroup(cancelled, cancelled.memberRunIds.map((id) => host.getRun(id)));
+        }
+        const run = host.getRun(requiredString(input.run_id, "run_id"));
+        assertOwns(callerSessionId, run);
+        // cancel() only aborts; the row flips ~100 ms later. A receipt still saying
+        // `running` reads as "cancel failed", so wait for the flip, briefly.
+        host.cancel(run.id);
+        return summarize(await cancelledOrCurrent(host, run.id, CANCEL_WAIT_MS));
+    }
+    if (input.operation === "message") {
+        // The one request `pier task run --run` sends: the run's state, not the
+        // caller, decides whether the text steers, queues or resumes, so a status
+        // query never has to exist.
+        const run = host.getRun(requiredString(input.run_id, "run_id"));
+        assertOwns(callerSessionId, run);
+        const message = requiredString(input.message, "message");
+        if (isTerminal(run.state)) {
+            // A resumed run is a new run with its own callback.
+            const callbackMode = callbackModeOf(input);
+            const callbackSessionId = await callbackTarget(input, definitions, callerSessionId);
+            const resumed = host.resume(run.id, message, { invokedBySessionId: callerSessionId, callbackSessionId, callbackMode, background: true });
+            return { delivery: "resume", run: receipt(summarize(resumed), callbackSessionId, callbackMode, callerSessionId) };
+        }
+        if (input.callback !== undefined || input.callback_session_id !== undefined) {
+            throw new Error(`run ${run.id} is ${run.state}: callback options apply to a resumed run only; drop them to steer or follow up`);
+        }
+        const delivery = input.after === true ? "follow_up" : "steer";
+        return { delivery, message: await host.control(run.id, callerSessionId, delivery, message) };
+    }
+    throw new Error("unknown task operation");
+}
+/** A single run's draft: the top-level shorthand (`prompt` …) or `task`, never both. */
+function inlineDraft(input) {
+    const { prompt, cwd, launch, name, timeoutSeconds } = input;
+    if (prompt === undefined)
+        return record(input.task) ?? undefined;
+    if (input.task !== undefined)
+        throw new Error("use either prompt or task");
+    return { prompt, cwd, launch, name, timeoutSeconds };
+}
+/** A label for the Console, not an identifier. */
+function nameFrom(text) {
+    const line = text.split("\n")
+        .map((l) => l.replace(/^[\s#>*-]+/, "").replace(/[*_`]/g, "").replace(/\s+/g, " ").trim())
+        .find(Boolean) ?? "subagent";
+    return line.length > 60 ? `${line.slice(0, 59).trimEnd()}…` : line;
+}
+/** `launch.model` by name (docs/design/09-tasks-cli.md §Models). Anything but
+ *  one pin or an unpinned `provider/id` is refused with the lines to pick
+ *  from, so the agent never guesses an id. */
+function resolveModel(name, menu) {
+    const needle = name.trim().toLowerCase();
+    const full = (pin) => `${pin.provider}/${pin.id}`;
+    const exact = menu.find((pin) => full(pin).toLowerCase() === needle);
+    const hits = exact ? [exact] : menu.filter((pin) => `${full(pin)} ${pin.note ?? ""}`.toLowerCase().includes(needle));
+    if (hits.length === 1)
+        return { model: { provider: hits[0].provider, id: hits[0].id }, thinking: hits[0].thinking };
+    const slash = name.indexOf("/");
+    if (!hits.length && slash > 0 && slash < name.length - 1)
+        return { model: { provider: name.slice(0, slash), id: name.slice(slash + 1) } };
+    throw new Error(`model "${name}" matches ${String(hits.length)} of the menu:\n${menuLines(hits.length ? hits : menu)}`);
+}
+/** One pin per line, the only shape a menu is ever printed in. */
+const menuLines = (menu) => menu.map((pin) => `${pin.provider}/${pin.id}${pin.thinking ? ` · ${pin.thinking}` : ""}${pin.note ? ` — ${pin.note}` : ""}`).join("\n")
+    || "(no model is pinned or available)";
+/** A `prompt` shorthand becomes a fresh Agent action in the caller's own
+ *  directory; everything the caller did spell out passes through to parseDraft. */
+async function expandDraft(definitions, menu, raw, callerSessionId) {
+    let draft = record(raw);
+    if (!draft)
+        return raw;
+    if (typeof draft.prompt === "string") {
+        if (draft.action !== undefined)
+            throw new Error("use either prompt (shorthand) or action");
+        const { prompt, cwd, launch, name, ...rest } = draft;
+        draft = { ...rest, name, action: { type: "agent", session: { mode: "fresh", cwd }, prompt, launch } };
+    }
+    const action = record(draft.action);
+    const session = record(action?.session);
+    const absolute = async (cwd) => {
+        const base = await definitions.sessionCwd(callerSessionId);
+        if (!base)
+            throw new Error(`cwd ${cwd === undefined ? "omitted" : `"${String(cwd)}" is relative`} and the calling session has no working directory; give an absolute path`);
+        return resolve(base, typeof cwd === "string" ? cwd : ".");
+    };
+    const relative = (cwd) => cwd === undefined || (typeof cwd === "string" && !isAbsolute(cwd));
+    if (action?.type === "agent" && session?.mode === "fresh" && relative(session.cwd)) {
+        draft = { ...draft, action: { ...action, session: { ...session, cwd: await absolute(session.cwd) } } };
+    }
+    if (action?.type === "bash" && relative(action.cwd)) {
+        draft = { ...draft, action: { ...action, cwd: await absolute(action.cwd) } };
+    }
+    const label = action?.prompt ?? action?.script;
+    if (draft.name === undefined && typeof label === "string")
+        draft = { ...draft, name: nameFrom(label) };
+    const launch = record(action?.launch);
+    if (typeof launch?.model === "string") {
+        const { model, thinking } = resolveModel(launch.model, await menu());
+        const resolved = { ...launch, model, ...(launch.thinking === undefined && thinking ? { thinking } : {}) };
+        draft = { ...draft, action: { ...record(draft.action), launch: resolved } };
+    }
+    return draft;
+}
+/** Persisted like any task (kind "subagent", filtered from default lists) so
+ *  runs stay auditable and resumable. */
+async function resolveDraft(definitions, menu, raw, callerSessionId) {
+    const draft = record(await expandDraft(definitions, menu, raw, callerSessionId));
+    if (!draft)
+        throw new Error("task definition required");
+    if (draft.trigger !== undefined && record(draft.trigger)?.type !== "manual") {
+        throw new Error("inline subagent tasks must use a manual trigger");
+    }
+    // Delivery of a one-off run is the top-level fields' business; a nested
+    // callback only means anything on a stored definition's schedule.
+    if (draft.callback !== undefined || draft.callback_session_id !== undefined) {
+        throw new Error("an inline task draft cannot set callback; use the top-level callback / callback_session_id");
+    }
+    return definitions.create({ ...draft, trigger: { type: "manual" } }, `session:${callerSessionId}`, "subagent");
+}
+/** The session that launched a run controls it, and so does the run's own
+ *  session; a `task` action's child inherits its parent's launcher. */
+function assertOwns(callerSessionId, target) {
+    if (target.invokedBySessionId !== callerSessionId && target.targetSessionId !== callerSessionId) {
+        throw new Error("session does not own this run");
+    }
+}

package/dist/tasks/routes.js

@@ -1,5 +1,5 @@
 // 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.
+// TaskService: policy here would be policy `pier task` does not get.
 import { record, requiredString } from "./definitions.js";
 /** Reject malformed filters instead of silently widening a global query. */
 function runQuery(params) {
@@ -184,16 +184,6 @@ export function registerTaskRoutes(app, tasks, activity) {
             return c.json({ error: String(err) }, 400);
         }
     });
-    app.post("/api/task-messages/:id/reply", async (c) => {
-        const body = record(await jsonBody(c.req));
-        try {
-            const source = requiredString(body?.sourceSessionId, "sourceSessionId");
-            return c.json(await tasks.reply(c.req.param("id"), source, requiredString(body?.message, "message")), 202);
-        }
-        catch (err) {
-            return c.json({ error: String(err) }, 400);
-        }
-    });
     app.post("/api/task-runs/:id/cancel", (c) => {
         try {
             return c.json(tasks.cancel(c.req.param("id")), 202);

package/dist/tasks/runs.js

@@ -1,34 +1,22 @@
-// 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.
+// A definition plus an input becomes a queued run; every caller enqueues
+// through this one door.
 import { logger } from "../log.js";
 import { newId } from "./definitions.js";
 const log = logger("tasks");
-const MAX_DEPTH = 2;
-const MAX_CHILDREN_PER_ROOT = 16;
 export class TaskRunQueue {
     store;
     callbacks;
-    getRun;
     execute;
     changed;
-    constructor(store, callbacks, getRun, execute, changed) {
+    constructor(store, callbacks, execute, changed) {
         this.store = store;
         this.callbacks = callbacks;
-        this.getRun = getRun;
         this.execute = execute;
         this.changed = changed;
     }
     /** 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);
-        const rootRunId = provenance.rootRunId ?? parent?.rootRunId ?? id;
-        if (depth > MAX_DEPTH)
-            throw new Error(`subagent depth limit is ${MAX_DEPTH}`);
-        if (depth > 0 && this.store.listRunsByRoot(rootRunId, MAX_CHILDREN_PER_ROOT + 1).filter((run) => run.depth > 0).length >= MAX_CHILDREN_PER_ROOT) {
-            throw new Error(`subagent child limit is ${MAX_CHILDREN_PER_ROOT} per root run`);
-        }
         const invokedBySessionId = provenance.invokedBySessionId ?? null;
         const sourceSessionId = provenance.sourceSessionId ?? invokedBySessionId;
         const sessionMode = definition.action.type === "agent"
@@ -50,8 +38,6 @@ export class TaskRunQueue {
             taskRevision: definition.revision,
             parentRunId,
             groupId: provenance.groupId ?? null,
-            rootRunId,
-            depth,
             resumedFromRunId: provenance.resumedFromRunId ?? null,
             triggerSource: source,
             invokedBySessionId,
@@ -86,13 +72,12 @@ export class TaskRunQueue {
     /** Publish and execute only after all records this run relies on committed. */
     start(run) {
         this.changed(run);
-        const { id, depth, triggerSource: source } = run;
+        const { id, 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)}` : ""}`;
+        const queued = `run ${id} ${run.state}: ${definition.name} via ${source}${overlapped ? " (overlapped)" : ""}`;
         if (source === "watch" && !overlapped)
             log.debug(queued);
         else

package/dist/tasks/service.js

@@ -9,7 +9,7 @@ import { TaskExecution } from "./execution.js";
 import { TaskGroups } from "./groups.js";
 import { TaskMessenger } from "./messages.js";
 import { TaskRunQueue } from "./runs.js";
-import { handleTaskTool } from "./tool.js";
+import { handleTask } from "./operations.js";
 import { isTerminal } from "./types.js";
 const log = logger("tasks");
 /** Not `renderedPrompt`: that carries the preamble and input wrapper, which the
@@ -44,14 +44,13 @@ 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.prepareResume(runId, prompt, { invokedBySessionId: fromSessionId, callbackSessionId: fromSessionId, background: true }), unreachable, (run) => this.runs.start(run));
+        this.messages = new TaskMessenger(store, router, hub, unreachable);
         this.definitions = new TaskDefinitions(store, factory, router, hub, instance?.systemActions);
         this.callbacks = new TaskCallbacks(store, router, (run) => this.changed(run), unreachable);
         this.groups = new TaskGroups(store, router, {
             getRun: (id) => this.getRun(id),
             cancel: (id) => { this.cancel(id); },
-            openDecisionId: (runId) => this.messages.openDecisionId(runId),
-            prepareMember: (taskId, groupId, callerSessionId, parentRunId) => this.prepareRun(taskId, null, "agent", parentRunId, {
+            prepareMember: (taskId, groupId, callerSessionId) => this.prepareRun(taskId, null, "agent", null, {
                 invokedBySessionId: callerSessionId,
                 sourceSessionId: callerSessionId,
                 callbackSessionId: null,
@@ -72,9 +71,8 @@ export class TaskService {
             cancel: (id) => { this.cancel(id); },
             settled: (run) => this.settled(run),
             changed: (run) => this.changed(run),
-            openDecisionId: (runId) => this.messages.openDecisionId(runId),
         });
-        this.runs = new TaskRunQueue(store, this.callbacks, (id) => this.getRun(id), (run) => this.execution.start(run), (run) => this.changed(run));
+        this.runs = new TaskRunQueue(store, this.callbacks, (run) => this.execution.start(run), (run) => this.changed(run));
     }
     start(tickMs = 1000) {
         if (this.timer)
@@ -147,7 +145,7 @@ export class TaskService {
     create(raw, creator = "http") {
         return this.definitions.create(raw, creator);
     }
-    /** `by` is how owning code says so; the routes and the tool have none (definitions.ts). */
+    /** `by` is how owning code says so; the routes and `pier task` have none (definitions.ts). */
     update(id, raw, by) {
         return this.definitions.update(id, raw, by);
     }
@@ -169,16 +167,13 @@ export class TaskService {
     }
     getRunView(id) {
         const run = this.getRun(id);
-        return { ...run, pendingDecisionId: this.openDecisionId(id),
+        return { ...run,
             groupCallbackState: run.groupId ? this.store.getGroup(run.groupId)?.callbackState ?? null : null };
     }
     listMessages(runId) {
         this.getRun(runId);
         return this.messages.list(runId);
     }
-    openDecisionId(runId) {
-        return this.messages.openDecisionId(runId);
-    }
     queryRuns(query = {}) {
         return this.store.queryRuns(query);
     }
@@ -227,7 +222,8 @@ export class TaskService {
             set.add(resolve);
         });
     }
-    /** Cascades: orphans must not outlive the delegation that wanted them. */
+    /** Cascades down a `task` action's chain: a child must not outlive the run
+     *  that waits on it. */
     cancel(id) {
         const run = this.getRun(id);
         for (const target of [run, ...this.descendants(run)]) {
@@ -242,23 +238,15 @@ export class TaskService {
     getGroup(id) {
         return this.groups.members(id);
     }
-    runGroup(definitions, join, callerSessionId, parentRunId, callbackSessionId, callbackMode) {
-        this.refusePaused(parentRunId);
-        return this.groups.runAll(definitions, join, callerSessionId, parentRunId, callbackSessionId, callbackMode);
+    runGroup(definitions, join, callerSessionId, callbackSessionId, callbackMode) {
+        this.refusePaused();
+        return this.groups.runAll(definitions, join, callerSessionId, callbackSessionId, callbackMode);
     }
     descendants(run) {
-        const byParent = new Map();
-        for (const member of this.store.listRunsByRoot(run.rootRunId, 500)) {
-            if (!member.parentRunId)
-                continue;
-            const siblings = byParent.get(member.parentRunId) ?? [];
-            siblings.push(member);
-            byParent.set(member.parentRunId, siblings);
-        }
         const collected = [];
         const queue = [run.id];
         while (queue.length > 0) {
-            for (const child of byParent.get(queue.shift()) ?? []) {
+            for (const child of this.store.listChildRuns(queue.shift())) {
                 collected.push(child);
                 queue.push(child.id);
             }
@@ -273,20 +261,7 @@ export class TaskService {
             throw new Error("terminal run cannot be steered; resume it instead");
         return this.messages.control(run, fromSessionId, mode, message);
     }
-    reply(messageId, fromSessionId, message) {
-        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))
@@ -295,19 +270,20 @@ export class TaskService {
             throw new Error("only persisted Agent runs can be resumed");
         }
         const prompt = requiredString(message, "message");
-        return this.runs.prepare(prior.context.definition, null, "agent", null, {
+        const run = this.runs.prepare(prior.context.definition, null, "agent", null, {
             ...provenance,
             sourceSessionId: provenance.invokedBySessionId ?? prior.invokedBySessionId,
             targetSessionId: prior.targetSessionId,
             sessionMode: "reuse",
             resumedFromRunId: prior.id,
-            rootRunId: prior.rootRunId,
-            depth: prior.depth,
             resumePrompt: prompt,
         });
+        this.runs.start(run);
+        return run;
     }
-    tool(raw, callerSessionId) {
-        return handleTaskTool(this, this.definitions, this.store, this.messages, raw, callerSessionId);
+    /** What `pier task` asks, under the calling session's identity. */
+    handle(raw, callerSessionId) {
+        return handleTask(this, this.definitions, this.store, raw, callerSessionId);
     }
     /** An agent picks from names that exist right now, never from memory. */
     async models() {
@@ -375,7 +351,6 @@ export class TaskService {
             state: run.state,
             targetSessionId: run.targetSessionId,
             sessionMode: run.sessionMode,
-            depth: run.depth,
             prompt: runPrompt(run),
             queuedAt: run.queuedAt,
             startedAt: run.startedAt,

package/dist/tasks/store.js

@@ -104,16 +104,13 @@ export class TaskStore {
         }
         const limit = clamp(query.limit ?? 50, 200);
         const rows = this.db.prepare(`
-      SELECT r.json, g.callback_state AS group_callback_state,
-        (SELECT m.id FROM task_messages m WHERE m.run_id = r.id
-          AND m.state IN ('pending', 'delivered') AND json_extract(m.json, '$.kind') = 'decision'
-          ORDER BY m.created_at, m.id LIMIT 1) AS decision_id
+      SELECT r.json, g.callback_state AS group_callback_state
       FROM task_runs r LEFT JOIN task_groups g ON g.id = json_extract(r.json, '$.groupId')
       ${where.length ? `WHERE ${where.join(" AND ")}` : ""}
       ORDER BY r.queued_at DESC, r.id DESC LIMIT ?
     `).all(...params, limit + 1);
         const runs = rows.slice(0, limit).map((row) => ({
-            ...JSON.parse(row.json), pendingDecisionId: row.decision_id, groupCallbackState: row.group_callback_state,
+            ...JSON.parse(row.json), groupCallbackState: row.group_callback_state,
         }));
         const last = runs.at(-1);
         return {
@@ -134,12 +131,20 @@ export class TaskStore {
     `, since);
         return [...active, ...recent].sort((a, b) => b.queuedAt - a.queuedAt || b.id.localeCompare(a.id));
     }
-    listRunsByRoot(rootRunId, limit = 100) {
+    /** A `task` action's child runs; a cancel walks them. */
+    listChildRuns(parentRunId) {
         return this.#many(`
       SELECT json FROM task_runs
-      WHERE json_extract(json, '$.rootRunId') = ?
-      ORDER BY queued_at LIMIT ?
-    `, rootRunId, clamp(limit, 500));
+      WHERE json_extract(json, '$.parentRunId') = ?
+      ORDER BY queued_at LIMIT 500
+    `, parentRunId);
+    }
+    /** Someone waits on this run's result — its own callback or its group's — so
+     *  the run is one turn of its session and may not delegate (design 09). */
+    supervised(run) {
+        if (run.callbackSessionId !== null)
+            return true;
+        return run.groupId !== null && (this.getGroup(run.groupId)?.callbackSessionId ?? null) !== null;
     }
     countActiveRuns() {
         const row = this.sql("SELECT COUNT(*) AS n FROM task_runs WHERE state IN ('queued', 'running')").get();
@@ -239,13 +244,8 @@ export class TaskStore {
             run: row.run_json === null ? undefined : JSON.parse(row.run_json),
         }));
     }
-    /** Decisions are excluded: they have no timeout and stay answerable across
-     * restarts — a reply to a terminal run resumes it. */
     expirePendingMessages() {
-        return this.#many(`
-      SELECT json FROM task_messages
-      WHERE state = 'pending' AND json_extract(json, '$.kind') != 'decision'
-    `).map((message) => {
+        return this.#many("SELECT json FROM task_messages WHERE state = 'pending'").map((message) => {
             message.state = "expired";
             // "Confirmed", not "completed": the proof lives in a transcript this
             // layer cannot see.