@timqi/pier 0.1.3 → 0.1.4

package/dist/tasks/messages.js

@@ -1,15 +1,15 @@
-// What a parent and a child say to each other while a run is going. Every
-// message is a durable row before it is a delivery: either end may be mid-turn
-// or gone, and an undelivered message is retried, expired and said, never
-// dropped (§5). Delivery itself belongs to outbox.ts.
+// What a parent says to a child while a run is going. Every message is a
+// durable row before it is a delivery: the child may be mid-turn or gone, and
+// an undelivered message is retried, expired and said, never dropped (§5).
+// Delivery itself belongs to outbox.ts.
 import { runSource } from "./callbacks.js";
 import { newId } from "./definitions.js";
 import { Outbox } from "./outbox.js";
 import { isTerminal } from "./types.js";
 const MAX_MESSAGE_LENGTH = 16 * 1024;
-/** `answered` is a delivery that was read; `expired` is one given up on. */
+/** `expired` is a delivery given up on. */
 const ENGINE_STATE = {
-    pending: "pending", failed: "failed", delivered: "delivered", answered: "delivered", expired: "abandoned",
+    pending: "pending", failed: "failed", delivered: "delivered", expired: "abandoned",
 };
 function bounded(content) {
     const text = content.trim();
@@ -22,20 +22,14 @@ function bounded(content) {
 export class TaskMessenger {
     store;
     hub;
-    prepareResume;
     unreachable;
-    startRun;
     outbox;
     constructor(store, router, hub, 
-    /** Prepares a continuation; it starts only after the reply commits. */
-    prepareResume, 
     /** Reports a delivery nobody can complete (service.ts owns the surfaces). */
-    unreachable, startRun) {
+    unreachable) {
         this.store = store;
         this.hub = hub;
-        this.prepareResume = prepareResume;
         this.unreachable = unreachable;
-        this.startRun = startRun;
         this.outbox = new Outbox(router, {
             id: ({ message }) => message.id,
             reload: (id) => {
@@ -50,10 +44,8 @@ export class TaskMessenger {
                     message.state = "delivered";
                     message.deliveredAt = Date.now();
                 }
-                else if (callbackState === "abandoned") {
+                else if (callbackState === "abandoned")
                     message.state = "expired";
-                    message.answeredAt = Date.now();
-                }
                 else
                     message.state = callbackState ?? "pending";
                 this.store.saveMessage(message);
@@ -76,25 +68,6 @@ export class TaskMessenger {
         for (const message of this.store.expirePendingMessages())
             this.changed(message);
     }
-    /** The unanswered decision on a run, if any. */
-    openDecisionId(runId) {
-        return this.store.listMessages(runId).find((m) => m.kind === "decision" && (m.state === "pending" || m.state === "delivered"))?.id ?? null;
-    }
-    /** A manual continuation supersedes an unanswered decision (design 04):
-     * one continuation per run, never two racing ones. */
-    expireDecisions(runId, reason) {
-        const expired = [];
-        for (const message of this.store.listMessages(runId)) {
-            if (message.kind !== "decision" || (message.state !== "pending" && message.state !== "delivered"))
-                continue;
-            message.state = "expired";
-            message.error = reason;
-            message.answeredAt = Date.now();
-            this.store.saveMessage(message);
-            expired.push(message);
-        }
-        return expired;
-    }
     list(runId) {
         return this.store.listMessages(runId);
     }
@@ -102,7 +75,7 @@ export class TaskMessenger {
         return this.store.listRecentMessages(since);
     }
     async control(run, fromSessionId, kind, content) {
-        const message = this.create(run, kind, fromSessionId, run.targetSessionId ?? "", content, null);
+        const message = this.create(run, kind, fromSessionId, run.targetSessionId ?? "", content);
         this.changed(message);
         if (run.targetSessionId)
             this.deliver(message, run.targetSessionId);
@@ -112,9 +85,8 @@ export class TaskMessenger {
         if (!run.targetSessionId)
             return;
         for (const message of this.store.listMessages(run.id)) {
-            if (message.state !== "pending" || (message.kind !== "steer" && message.kind !== "follow_up"))
-                continue;
-            this.deliver(message, run.targetSessionId);
+            if (message.state === "pending")
+                this.deliver(message, run.targetSessionId);
         }
     }
     /** Delivery is fire-and-forget, so this sweep is what closes a failed one.
@@ -124,30 +96,13 @@ export class TaskMessenger {
             if (!run)
                 continue;
             // Expiring a dead control is not a retry, so it ignores the backoff.
-            if ((message.kind === "steer" || message.kind === "follow_up") && isTerminal(run.state)) {
+            if (isTerminal(run.state)) {
                 message.state = "expired";
                 message.error = "run finished before delivery completed";
                 this.store.saveMessage(message);
                 this.changed(message);
                 continue;
             }
-            // A reply that resumed a terminal run is the continuation's prompt, not a
-            // system input: the transcript read would re-inject it and start a turn no
-            // run owns. The continuation's `startedAt` is the proof instead.
-            if (message.kind === "reply" && isTerminal(run.state)) {
-                const resumed = message.resumeRunId ? this.store.getRun(message.resumeRunId) : undefined;
-                if (resumed?.startedAt)
-                    this.delivered(message);
-                else if (!resumed)
-                    this.abandon(message, `continuation ${message.resumeRunId ?? "(none)"} is gone`);
-                else if (isTerminal(resumed.state)) {
-                    // Never started and never will: said now, not four minutes later at
-                    // the ceiling. A duplicate report beats a special case that could
-                    // suppress the only one.
-                    this.abandon(message, `continuation ${resumed.id} ${resumed.state} before it started`);
-                }
-                continue;
-            }
             if ((message.nextAttemptAt ?? 0) > now)
                 continue;
             const target = message.toSessionId || run.targetSessionId;
@@ -155,76 +110,17 @@ export class TaskMessenger {
                 this.deliver(message, target);
         }
     }
-    /** Returns the receipt immediately; the reply arrives as a follow-up (active
-     *  run) or resumes the session (terminal run). A decision steers the
-     *  supervisor, or a blocked child would wait out its whole turn. */
-    async contact(run, fromSessionId, reason, content) {
-        if (!run.invokedBySessionId)
-            throw new Error("run has no supervisor session");
-        if (reason === "decision" && this.openDecisionId(run.id)) {
-            throw new Error("run already has a pending supervisor decision");
-        }
-        const message = this.create(run, reason, fromSessionId, run.invokedBySessionId, content, null);
-        this.changed(message);
-        this.deliver(message, run.invokedBySessionId);
-        return this.require(message.id);
-    }
-    async reply(questionId, fromSessionId, content) {
-        const question = this.require(questionId);
-        if (question.kind !== "decision")
-            throw new Error("message is not a decision request");
-        if (question.toSessionId !== fromSessionId)
-            throw new Error("only the addressed supervisor may reply");
-        const existing = this.store.listMessages(question.runId).find((m) => m.kind === "reply" && m.replyTo === question.id);
-        const text = bounded(content);
-        if (existing) {
-            if (existing.content !== text)
-                throw new Error("decision already answered with different content");
-            return existing;
-        }
-        if (question.state !== "delivered" && question.state !== "pending") {
-            throw new Error(`decision is ${question.state}`);
-        }
-        const run = this.store.getRun(question.runId);
-        if (!run)
-            throw new Error(`unknown task run: ${question.runId}`);
-        // A rejected continuation must leave the question answerable. Persist the
-        // answer and its queued run together, before either publishes or executes.
-        const { reply, continuation } = this.store.transact(() => {
-            const reply = this.create(run, "reply", fromSessionId, question.fromSessionId, text, question.id);
-            question.state = "answered";
-            question.answeredAt = Date.now();
-            this.store.saveMessage(question);
-            const continuation = isTerminal(run.state)
-                ? this.prepareResume(run.id, this.format(reply, run), fromSessionId)
-                : undefined;
-            if (continuation) {
-                reply.resumeRunId = continuation.id;
-                this.store.saveMessage(reply);
-            }
-            return { reply, continuation };
-        });
-        this.changed(question);
-        this.changed(reply);
-        if (continuation)
-            this.startRun(continuation);
-        else if (run.targetSessionId)
-            this.deliver(reply, run.targetSessionId);
-        return this.require(reply.id);
-    }
-    create(run, kind, fromSessionId, toSessionId, content, replyTo) {
+    create(run, kind, fromSessionId, toSessionId, content) {
         const message = {
             id: newId(),
             runId: run.id,
             kind,
             fromSessionId,
             toSessionId,
-            replyTo,
             state: "pending",
             content: bounded(content),
             createdAt: Date.now(),
             deliveredAt: null,
-            answeredAt: null,
             error: null,
             attempts: 0,
             nextAttemptAt: null,
@@ -247,56 +143,20 @@ export class TaskMessenger {
             callbackAttempts: message.attempts,
             callbackError: message.error,
             callbackNextAttemptAt: message.nextAttemptAt,
-            // Steer whatever someone is blocked on: a follow-up lands only once the
-            // recipient runs out of tool calls. Progress is a follow-up because nobody waits.
-            ...(message.kind === "follow_up" || message.kind === "progress" ? {} : { callbackMode: "steer" }),
+            // A steer interrupts; a follow-up lands only once the recipient runs out
+            // of tool calls.
+            ...(message.kind === "follow_up" ? {} : { callbackMode: "steer" }),
         };
     }
-    /** Proven by something other than the recipient's transcript. */
-    delivered(message) {
-        message.state = "delivered";
-        message.deliveredAt = Date.now();
-        message.error = null;
-        message.nextAttemptAt = null;
-        this.store.saveMessage(message);
-        this.changed(message);
-    }
-    abandon(message, why) {
-        message.state = "expired";
-        message.error = why;
-        message.answeredAt = Date.now();
-        message.nextAttemptAt = null;
-        this.store.saveMessage(message);
-        this.changed(message);
-        this.told(message, why);
-    }
-    /** Both ends are told, and an expired decision stops suppressing its run's
-     *  completion callback, which `execution.ts` decided once and never revisits. */
+    /** Both ends are told. */
     told(message, why) {
         this.unreachable(message.toSessionId, `a ${message.kind} from run ${message.runId}`, why);
         if (message.fromSessionId && message.fromSessionId !== message.toSessionId) {
             this.unreachable(message.fromSessionId, `your ${message.kind} on run ${message.runId}`, why);
         }
-        const run = this.store.getRun(message.runId);
-        if (message.kind !== "decision" || !run?.callbackSessionId)
-            return;
-        if (run.callbackState === null && isTerminal(run.state)) {
-            run.callbackState = "pending"; // the tick sweep delivers it
-            this.store.saveRun(run);
-        }
     }
     format(message, run) {
-        const title = run.context.definition.name;
-        if (message.kind === "progress") {
-            return `Subagent progress for task "${title}"\nRun: ${run.id}\nMessage: ${message.id}\n\n${message.content}`;
-        }
-        if (message.kind === "decision") {
-            return `Subagent needs a decision for task "${title}"\nRun: ${run.id}\nMessage: ${message.id}\nReply with the Task reply operation.\n\n${message.content}`;
-        }
-        if (message.kind === "reply") {
-            return `Supervisor reply for task "${title}"\nRun: ${run.id}\nReply to: ${message.replyTo ?? "-"}\n\n${message.content}`;
-        }
-        return `Task guidance for "${title}"\nRun: ${run.id}\nMessage: ${message.id}\n\n${message.content}`;
+        return `Task guidance for "${run.context.definition.name}"\nRun: ${run.id}\nMessage: ${message.id}\n\n${message.content}`;
     }
     origin(message, run) {
         return {

package/dist/tasks/operations.js

@@ -0,0 +1,323 @@
+// 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 === "?")
+            return host.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 nameFromPrompt(prompt) {
+    const line = prompt.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 line = (pin) => `${full(pin)}${pin.thinking ? ` · ${pin.thinking}` : ""}${pin.note ? ` — ${pin.note}` : ""}`;
+    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) } };
+    const lines = (hits.length ? hits : menu).map(line).join("\n") || "(no model is pinned or available)";
+    throw new Error(`model "${name}" matches ${String(hits.length)} of the menu:\n${lines}`);
+}
+/** 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);
+    if (action?.type === "agent" && session?.mode === "fresh" && (session.cwd === undefined || (typeof session.cwd === "string" && !isAbsolute(session.cwd)))) {
+        const base = await definitions.sessionCwd(callerSessionId);
+        if (!base)
+            throw new Error(`cwd ${session.cwd === undefined ? "omitted" : `"${session.cwd}" is relative`} and the calling session has no working directory; give an absolute path`);
+        draft = { ...draft, action: { ...action, session: { ...session, cwd: resolve(base, session.cwd ?? ".") } } };
+    }
+    if (draft.name === undefined && typeof action?.prompt === "string")
+        draft = { ...draft, name: nameFromPrompt(action.prompt) };
+    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);