@timqi/pier 0.1.3 → 0.1.5

package/dist/main.js

@@ -15,37 +15,36 @@ import { defaultBoardsDir, registerBoardRoutes } from "./boards/boards.js";
 import { ChannelStore } from "./channels/config.js";
 import { createControl } from "./channels/control.js";
 import { ConversationStore, resolveConversation } from "./channels/conversations.js";
+import { createHandoff } from "./channels/handoff.js";
 import { registerChannelRoutes } from "./channels/routes.js";
 import { ChannelRuntime } from "./channels/runtime.js";
-import { SlackApi } from "./channels/slack-api.js";
-import { SlackDirectory } from "./channels/slack-directory.js";
-import { handleSlackTool, slackToolAvailable, slackToolSpec } from "./channels/slack-tool.js";
-import { parseConversation as parseSlackConversation } from "./channels/slack.js";
 import { EventHub } from "./core/hub.js";
 import { splitSpeaker } from "./core/identity.js";
 import { pierDb } from "./db.js";
 import { deliverLedger, drainForRestart, RestartLedger } from "./drain.js";
-import { BUNDLED } from "./extensions/index.js";
 import { surfacePrompt } from "./core/reply.js";
 import { Router } from "./core/router.js";
 import { acquireInstanceLock } from "./lock.js";
+import { parseWebParams, runWeb } from "./websearch/run.js";
 import { logger } from "./log.js";
 import { registerTaskRoutes } from "./tasks/routes.js";
 import { TaskService } from "./tasks/service.js";
 import { TaskStore } from "./tasks/store.js";
-import { taskToolSpec } from "./tasks/tool.js";
 import { PIER_HOME, pierPath, resolveAgentDir } from "./paths.js";
-import { CUSTOM_TOOL_RULES, MANAGED, ManagedTools, normalizeCustomTools, prependPath } from "./tools.js";
+import { CUSTOM_TOOL_RULES, MANAGED, ManagedTools, normalizeCustomTools, prependPath, writePierShim } from "./tools.js";
 import { toolsTask } from "./tools-task.js";
 import { Secrets } from "./secrets.js";
 import { startUpdate, unitPath, updaterProblem } from "./service.js";
 import { SettingsStore } from "./settings.js";
 import { currentVersion, startAutoUpdate, UpdateCheck } from "./update.js";
+import { Vault } from "./vault.js";
+import { servePier } from "./socket.js";
 import { AuthStore, registerAuthRoutes, requireAuth } from "./web/auth.js";
 import { registerConfigShareRoute, registerConfigSyncRoutes } from "./web/config-sync.js";
 import { PushStore, registerPushRoutes } from "./web/push.js";
 import { SessionStateStore } from "./web/session-state.js";
 import { createServer } from "./web/server.js";
+import { registerVaultRoutes } from "./web/vault.js";
 const log = logger("pier");
 // Before any SDK call resolves a path, so everything Pi derives from its agent
 // dir lands under PIER_HOME. PIER_AGENT_DIR marks the value as ours: a second
@@ -54,6 +53,7 @@ const log = logger("pier");
 process.env.PI_CODING_AGENT_DIR = resolveAgentDir(process.env);
 process.env.PIER_AGENT_DIR = process.env.PI_CODING_AGENT_DIR;
 prependPath(process.env);
+writePierShim();
 // Before the database and before task recovery, which would mark the running
 // instance's queued and active runs interrupted; the port is discovered far too
 // late, and a second Pier on another port would never notice at all.
@@ -77,12 +77,11 @@ const settings = new SettingsStore(db);
 // Unlocked below: vt mode waits on a human approval, and nothing that needs a
 // token may run before the key arrives.
 const secrets = new Secrets();
+const vault = new Vault(secrets, db);
 let tasks;
 const conversations = new ConversationStore(db);
 let resolveIm;
 let channelStore;
-// Shared by the adapter and the tool: one display-name lookup per process.
-const slackDirectory = new SlackDirectory((m) => logger("slack").warn(m));
 let readyForConfigReload = false;
 const piConfig = new PiConfigStore();
 // Before anything reads settings.json: a first boot gets Pier's seed file.
@@ -92,28 +91,7 @@ const configSync = new ConfigSync({
     reload: () => readyForConfigReload ? reloadInstance() : Promise.resolve(),
 });
 const skillsDir = fileURLToPath(new URL("../skills", import.meta.url));
-const agentTools = [
-    taskToolSpec((params, callerSessionId) => tasks.tool(params, callerSessionId)),
-    slackToolSpec((params, callerSessionId) => handleSlackTool({
-        store: channelStore,
-        directory: slackDirectory,
-        // Per call: the Console can change the token underneath us.
-        client: () => {
-            const config = channelStore.get("slack");
-            return config.token ? new SlackApi(config.token, config.appToken) : null;
-        },
-        // Per call: the mapping is durable, the session is not.
-        here: (sessionId) => {
-            const key = router.conversationOf(sessionId);
-            if (key?.channelId !== "slack")
-                return null;
-            const { channel, threadTs } = parseSlackConversation(key.conversationId);
-            return channel && threadTs ? { channel, threadTs } : null;
-        },
-        log: (m) => logger("slack.tool").warn(m),
-    }, params, callerSessionId), () => slackToolAvailable(channelStore)),
-];
-const factory = new PiAgentFactory(agentTools, 
+const factory = new PiAgentFactory(
 // Getters, read per session open: a Console change reaches the next session
 // without a restart.
 () => surfacePrompt({ boardsDir: defaultBoardsDir(), publicUrl: settings.get().publicUrl }), 
@@ -129,7 +107,7 @@ const router = new Router(hub, (key) => {
         return factory.resume(key.conversationId);
     }
     return resolveIm(key);
-}, (key) => conversations.get(key));
+}, (key) => conversations.get(key), (id) => conversations.keyOf(id));
 const stopEviction = router.startIdleEviction();
 tasks = new TaskService(new TaskStore(db), factory, router, hub, {
     modelMenu: () => settings.get().modelMenu,
@@ -142,13 +120,38 @@ const toolsUpdate = toolsTask(tasks);
 const reconciled = await toolsUpdate.reconcile();
 if ("problem" in reconciled)
     log.error(`tools cannot be managed: ${reconciled.problem}`);
-const packages = new PiPackageStore(piConfig, { version: currentVersion(), settings, tools: agentTools }, [skillsDir]);
+const packages = new PiPackageStore(piConfig, { version: currentVersion(), settings }, [skillsDir]);
 // At boot, not lazily: the answer waits for the next Console open (update.ts).
 packages.watchUpdates();
-channelStore = new ChannelStore(db, secrets);
-const control = createControl({ router, factory, conversations, store: channelStore });
-const channels = new ChannelRuntime(channelStore, router, control);
-resolveIm = resolveConversation(conversations, factory, control.launchFor, (message) => logger("channels").warn(message));
+channelStore = new ChannelStore(db, vault);
+const sessionState = new SessionStateStore(db);
+const control = createControl({
+    router, factory, conversations, store: channelStore,
+    modelMenu: () => settings.get().modelMenu,
+});
+// The panel pulls through the handoff and the handoff posts through the
+// runtime: the runtime's half is reached lazily so both can be built.
+const handoff = createHandoff({
+    store: channelStore,
+    runtime: {
+        running: () => channels.running(),
+        openThread: (platform, chatId, note) => channels.openThread(platform, chatId, note),
+    },
+    conversations,
+    factory,
+    router,
+    hub,
+    publicUrl: () => settings.get().publicUrl,
+    taskSessions: () => tasks.taskSessions(),
+    workingSet: () => sessionState.flags(),
+    log: (m) => logger("channels").info(m),
+});
+const channels = new ChannelRuntime(channelStore, router, control, handoff);
+resolveIm = resolveConversation(conversations, factory, control.launchFor, (key, message) => {
+    logger("channels").warn(`${key.channelId}:${key.conversationId} ${message}`);
+    void channels.notify(key.channelId, key.conversationId, message)
+        .catch((err) => log.error(`could not tell ${key.channelId} about its re-routed session`, err));
+});
 // Channels connect once tokens are readable; a refused unlock must not take
 // down the web surface, which is where the operator repairs it. The chats a
 // previous restart cut off are told as soon as channels are up (drain.ts).
@@ -271,9 +274,9 @@ registerConfigSyncRoutes(app, {
     run: configurationSync.run,
 });
 registerTaskRoutes(app, tasks, { factory, router });
-registerChannelRoutes(app, channelStore, channels);
+registerChannelRoutes(app, channelStore, channels, handoff);
+registerVaultRoutes(app, { vault, doctor: () => secrets.doctor() });
 registerBoardRoutes(app);
-const sessionState = new SessionStateStore(db);
 registerPushRoutes(app, {
     store: new PushStore(db, secrets),
     hub,
@@ -301,7 +304,7 @@ app.route("/", createServer({
     names: MANAGED.map((tool) => tool.name),
     onToolsChanged: toolsUpdate.changed,
     validateCustomTools: (raw) => {
-        const validated = normalizeCustomTools(raw, BUNDLED.map((ext) => ext.name));
+        const validated = normalizeCustomTools(raw);
         return validated ? { tools: validated } : { error: CUSTOM_TOOL_RULES };
     },
     secrets,
@@ -312,10 +315,27 @@ app.route("/", createServer({
     backgroundRuns: (id) => tasks.backgroundRuns(id),
     activeBackgroundRunCounts: () => tasks.activeBackgroundRunCounts(),
     taskSessions: () => tasks.taskSessions(),
-    channelOf: (id) => conversations.channelOf(id),
+    channelOf: (id) => conversations.keyOf(id)?.channelId,
 }));
 const port = Number(process.env.PORT ?? 3141);
 const hostname = process.env.HOST ?? "127.0.0.1";
+servePier({
+    vault,
+    // The deep link an agent's "no secret named X" error carries; loopback when
+    // no public URL is set, since nothing in the process can discover one.
+    fileUrl: (name) => `${settings.get().publicUrl || `http://127.0.0.1:${String(port)}`}/#/settings/vault?name=${name}`,
+    task: (params, callerSessionId) => tasks.handle(params, callerSessionId),
+    // Progress and cost go to the log: the CLI's answer is the text alone.
+    web: async (params, callerSessionId) => {
+        const parsed = parseWebParams(params);
+        const note = (text) => log.info(`web ${callerSessionId}: ${text}`);
+        const result = await runWeb(parsed, await factory.webContext(router.modelOf(callerSessionId)), note);
+        note(`done ${JSON.stringify(result.details)}`);
+        return result;
+    },
+    // Live in the router, or on disk: the same two places a callback target is looked for.
+    knows: async (id) => router.stateOf(id) !== undefined || (await factory.find(id)) !== undefined,
+});
 // Every command a turn runs inherits this env: `NODE_ENV=production` makes an
 // agent's `npm install` skip devDependencies, and PORT/HOST would aim its dev
 // server at Pier's socket.

package/dist/paths.js

@@ -12,6 +12,9 @@ export const PIER_DB = pierPath("db", "pier.db");
 /** At the root of PIER_HOME: the claim is the whole instance directory, not the
  *  database (lock.ts). */
 export const PIER_LOCK = pierPath("pier.lock");
+/** Where the `pier` CLI reaches the running Pier; the CLI needs the name
+ *  without opening the database (socket.ts). */
+export const PIER_SOCK = pierPath("pier.sock");
 /** `PI_CODING_AGENT_DIR` is an operator override — unless it equals
  *  `PIER_AGENT_DIR`, the value Pier itself set: then a Pier spawned from inside
  *  another inherited it, and a leak is not an instruction. */

package/dist/secrets.js

@@ -146,7 +146,8 @@ function open(key, sealed, aad) {
     decipher.setAuthTag(tag);
     return Buffer.concat([decipher.update(ct), decipher.final()]);
 }
-const vtCli = {
+/** The real vt; vault.ts creates its `approve` records through the same client. */
+export const vtCli = {
     read: (record) => run("vt", ["read", record]),
     create: async (plaintext) => {
         const out = await run("vt", ["create"], plaintext);

package/dist/settings.js

@@ -63,12 +63,8 @@ export function normalizeModelRef(raw) {
         return null;
     return { provider: provider.trim(), id: id.trim() };
 }
-/** Shape only: the catalog is code behind the Pi SDK, and an unknown name is
- *  ignored there, so a downgrade cannot lose a setting it cannot explain. */
-export function normalizeExtensions(raw) {
-    return normalizeNames(raw);
-}
-/** Shape only, for the same reason: tools.ts owns the catalog. */
+/** Shape only: tools.ts owns the catalog, and an unknown name is ignored
+ *  there, so a downgrade cannot lose a setting it cannot explain. */
 export function normalizeTools(raw) {
     return normalizeNames(raw);
 }
@@ -98,11 +94,10 @@ export class SettingsStore {
             modelMenu: this.#json("modelMenu", normalizeModelMenu, "a valid menu") ?? [],
             ...(titleModel ? { titleModel } : {}),
             autoUpdate: this.#value("autoUpdate") === "1",
-            extensions: this.#json("extensions", normalizeExtensions, "a list of names") ?? [],
             skillsOff: this.#json("skillsOff", normalizeNames, "a list of names") ?? [],
             tools: this.#json("tools", normalizeTools, "a list of names") ?? [],
             // `"drop"`: a row the bundled catalog has since taken is redundant, not malformed.
-            customTools: this.#json("customTools", (raw) => normalizeCustomTools(raw, [], "drop"), "a list of {name, toml}") ?? [],
+            customTools: this.#json("customTools", (raw) => normalizeCustomTools(raw, "drop"), "a list of {name, toml}") ?? [],
         };
     }
     /** A malformed row is named, not silently served as the empty value (§5). */
@@ -141,10 +136,6 @@ export class SettingsStore {
         this.#set("autoUpdate", on ? "1" : "0");
         return this.get();
     }
-    setExtensions(names) {
-        this.#set("extensions", JSON.stringify(names));
-        return this.get();
-    }
     setSkillsOff(names) {
         this.#set("skillsOff", JSON.stringify(names));
         return this.get();

package/dist/socket.js

@@ -0,0 +1,99 @@
+// The local socket the `pier` CLI reaches the running instance through: one
+// route per verb the CLI has, the socket's permission bits as the whole auth.
+// Not a workbench route — that server sits behind a proxy at a public
+// hostname — so plaintext crosses this socket into a local process of Pier's
+// user and nowhere else.
+import { chmodSync, rmSync } from "node:fs";
+import { createServer } from "node:http";
+import { logger } from "./log.js";
+import { PIER_SOCK } from "./paths.js";
+import { isVaultName, UnknownSecret, VaultLocked } from "./vault.js";
+const log = logger("socket");
+/** Generous for a task draft; a `--prompt -` past it is told so, not hung up on. */
+const MAX_BODY = 64 * 1024;
+const ROUTES = {
+    async "/resolve"({ vault, fileUrl }, { names }, sessionId, answer) {
+        if (!Array.isArray(names) || !names.length || !names.every((n) => typeof n === "string" && isVaultName(n))) {
+            return answer(400, { error: "names must be a non-empty list of vault names" });
+        }
+        try {
+            answer(200, { values: vault.resolve(names, `session ${sessionId}`) });
+        }
+        catch (err) {
+            if (err instanceof UnknownSecret)
+                return answer(404, { error: err.message, file: fileUrl(err.secret) });
+            if (err instanceof VaultLocked)
+                return answer(423, { error: err.message });
+            log.error(`resolve ${names.join(",")} failed`, err);
+            answer(500, { error: String(err) });
+        }
+    },
+    "/task": operation("task"),
+    "/web": operation("web"),
+};
+/** A CLI verb's params under the caller's session. 422, not 400: the request
+ *  was well-formed; what the operation refused is the caller's to read. */
+function operation(name) {
+    return async (hosts, { params }, sessionId, answer) => {
+        try {
+            answer(200, { result: await hosts[name](params, sessionId) });
+        }
+        catch (err) {
+            answer(422, { error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+}
+export function servePier(hosts, path = PIER_SOCK) {
+    const server = createServer((req, res) => void handle(hosts, req, res).catch((err) => {
+        log.error(`${req.method ?? "?"} ${req.url ?? "?"} failed`, err);
+        if (!res.headersSent)
+            res.writeHead(500).end(JSON.stringify({ error: String(err) }));
+    }));
+    // A crash leaves the old socket file behind, and listen() on it is EADDRINUSE.
+    rmSync(path, { force: true });
+    // bind() runs inside listen(): the umask covers the instant the file exists
+    // with default bits; the chmod sets the exact mode once it is bound. A bind
+    // that failed reports through the error event and left no file to chmod.
+    const umask = process.umask(0o077);
+    try {
+        server.listen(path, () => log.info(`cli socket at ${path}`));
+    }
+    finally {
+        process.umask(umask);
+    }
+    if (server.listening)
+        chmodSync(path, 0o600);
+    server.on("error", (err) => log.error(`cli socket ${path} failed`, err));
+    process.once("exit", () => rmSync(path, { force: true }));
+    return server;
+}
+async function handle(hosts, req, res) {
+    const answer = (status, body) => {
+        res.writeHead(status, { "content-type": "application/json" });
+        res.end(JSON.stringify(body));
+    };
+    const route = req.method === "POST" ? ROUTES[req.url ?? ""] : undefined;
+    if (!route)
+        return answer(404, { error: `POST ${Object.keys(ROUTES).join(" | ")} only` });
+    let raw = "";
+    for await (const chunk of req) {
+        raw += chunk.toString();
+        // Answered before the body is drained: leaving the loop destroys the
+        // request stream, and the response already queued still reaches the client.
+        if (raw.length > MAX_BODY)
+            return answer(413, { error: `body exceeds ${String(MAX_BODY / 1024)} KiB` });
+    }
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        return answer(400, { error: "body must be a JSON object" });
+    }
+    const { sessionId, ...fields } = typeof body === "object" && body !== null ? body : {};
+    if (typeof sessionId !== "string" || !sessionId)
+        return answer(400, { error: "PIER_SESSION_ID is required" });
+    if (!(await hosts.knows(sessionId)))
+        return answer(403, { error: `${sessionId} is not a session of this Pier` });
+    await route(hosts, fields, sessionId, answer);
+}

package/dist/tasks/agent.js

@@ -10,19 +10,18 @@ const MAX_ACTIVE_AGENTS = 6;
 const log = logger("tasks");
 /** Every session gets the chat-surface contract, task runs included, so the
  *  delegation prompt says which of it does not apply. Skipped on resume. */
-const preamble = (run) => {
+const preamble = (run, supervised) => {
     // A cron/watch task with a session callback is read by an agent too.
     const audience = run.invokedBySessionId
         ? "read by the agent that delegated this run"
         : run.callbackSessionId
             ? "read by the agent session it is delivered to"
             : "read by the operator";
-    const contact = run.invokedBySessionId
-        ? ' Mid-run, the task tool\'s contact operation reaches that agent: reason "progress" is fire-and-forget, "decision" waits for a reply — state what you await and end your turn.'
-        : "";
     return `[Pier task run ${run.id} — "${run.context.definition.name}"] ` +
         `Your final reply is recorded verbatim as the run result, ${audience}; ` +
-        `next-step buttons and file:// attachments do not render there.${contact}\n\n`;
+        `next-step buttons and file:// attachments do not render there. A question only that reader can answer is your result: state it and end your turn; the answer resumes this session.` +
+        (supervised ? " You cannot delegate from here — `pier task` is refused; if the work needs another agent, say so in your result and your supervisor will run it." : "") +
+        "\n\n";
 };
 export class AgentTaskRunner {
     factory;
@@ -62,7 +61,7 @@ export class AgentTaskRunner {
                 const input = run.input === undefined || run.input === null
                     ? ""
                     : `\n\n<task_input>\n${JSON.stringify(run.input).replaceAll("</task_input>", "<\\/task_input>")}\n</task_input>`;
-                const prompt = run.context.resumePrompt ?? `${preamble(run)}${action.prompt}${input}`;
+                const prompt = run.context.resumePrompt ?? `${preamble(run, this.store.supervised(run))}${action.prompt}${input}`;
                 run.context.sessionId = session.id;
                 run.context.model = session.model;
                 // The level the session settled on: an unspecified effort inherits the caller's.

package/dist/tasks/callbacks.js

@@ -2,7 +2,7 @@
 // belongs to outbox.ts; this file owns the run vocabulary and the batching.
 import { Outbox } from "./outbox.js";
 /** The run id and the session that did the work: a relayer's next move is a
- *  deep link to it, and without this that costs a second tool call. */
+ *  deep link to it, and without this that costs a second call. */
 export const runRef = (run) => `Run: ${run.id}${run.targetSessionId ? ` / Session: ${run.targetSessionId}` : ""}`;
 /** What the card in the recipient's transcript says the input came from. */
 export const runSource = (run) => ({
@@ -21,7 +21,7 @@ export function runResultText(run) {
     if (run.result?.type === "watch")
         result = "Watch condition did not match";
     if (result.length > 8000)
-        result = `${result.slice(0, 8000)}\n[truncated — task tool recover run_id ${run.id} with a reason returns the full text]`;
+        result = `${result.slice(0, 8000)}\n[truncated — pier task recover --run ${run.id} --reason … returns the full text]`;
     return result;
 }
 export class TaskCallbacks {

package/dist/tasks/cli.js

@@ -0,0 +1,225 @@
+// `pier task <command> …`: argv → the params object `/task` takes. Argv shape
+// is the only thing checked here; the server validates the operation, and its
+// answer comes back verbatim.
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+const OPTIONS = {
+    prompt: { type: "string" }, run: { type: "string" }, after: { type: "boolean" },
+    "task-id": { type: "string" }, session: { type: "string" },
+    model: { type: "string" }, thinking: { type: "string" }, cwd: { type: "string" }, name: { type: "string" },
+    timeout: { type: "string" }, callback: { type: "string" }, "callback-session": { type: "string" }, join: { type: "string" },
+    bash: { type: "string" }, cron: { type: "string" }, tz: { type: "string" },
+    watch: { type: "string" }, every: { type: "string" }, repeat: { type: "boolean" },
+    group: { type: "string" }, reason: { type: "string" },
+    help: { type: "boolean", short: "h" },
+};
+/** The usage line is the contract (docs/design/09-tasks-cli.md); the flags a
+ *  command accepts are read off it, so the two cannot drift. */
+const COMMANDS = {
+    run: {
+        usage: "run [--prompt <text|-> | --bash <script>] [--run <id> [--after]] [--task-id <id>] [--session <id>]\n" +
+            "        [--model <name|?>] [--thinking <level>] [--cwd <dir>] [--name <text>] [--timeout <seconds>]\n" +
+            "        [--callback origin|none|steer] [--callback-session <id>] [--join all|first] [--member <flags…>]…",
+        help: "a new run (--prompt | --bash | --task-id | --session … --prompt), a batch (--member), or a prompt on an existing one (--run)",
+    },
+    save: {
+        usage: "save [--task-id <id>] --name <text> (--prompt <text|-> | --bash <script>)\n" +
+            "        [--cron \"<expr>\" --tz <zone> | --watch <script> --every <seconds> [--repeat]]\n" +
+            "        [--cwd <dir>] [--timeout <seconds>] [--model <name>] [--thinking <level>] [--callback-session <id>]",
+        help: "file a definition the operator sees, or update one by --task-id; no trigger means manual",
+    },
+    list: { usage: "list", help: "stored definitions, as JSON" },
+    cancel: { usage: "cancel (--run <id> | --group <id>)", help: "a run or a group, descendants included" },
+    recover: { usage: "recover (--run <id> | --group <id>) --reason <text>", help: "a finished result after its callback settled; never a progress check" },
+};
+const USAGE = [
+    "usage: pier task <command> … — subagents and scheduled tasks (skills/pier-tasks)",
+    ...Object.values(COMMANDS).map(({ usage, help }) => `  ${usage}\n      ${help}`),
+    "`--prompt -` reads stdin. The receipt is one line of JSON (`--model ?` one pin per line), exit 0; a refusal is one `task:` line, exit 1.",
+].join("\n");
+/** Flags that belong to the batch, never to one member. */
+const GROUP_FLAGS = ["join", "callback", "callback-session"];
+const processIo = {
+    stdout: (line) => process.stdout.write(`${line}\n`),
+    stderr: (line) => process.stderr.write(`${line}\n`),
+    stdin: () => readFileSync(0, "utf8"),
+};
+class ArgvError extends Error {
+}
+const refuse = (message) => {
+    throw new ArgvError(message);
+};
+const compact = (value) => Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+const flagsOf = (values) => Object.keys(values).filter((flag) => flag !== "help");
+const seconds = (flag, raw) => {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) ? n : refuse(`--${flag} must be a whole number of seconds`);
+};
+/** `launch` as the server takes it: `model` is a menu name it resolves. */
+const launchOf = (v) => v.model === undefined && v.thinking === undefined ? undefined : compact({ model: v.model, thinking: v.thinking });
+/** Argv is split at each bare `--member`; a value equal to it is unreachable,
+ *  since parseArgs (strict) refuses option-like values anyway. */
+function segments(argv) {
+    const out = [[]];
+    for (const arg of argv) {
+        if (arg === "--member")
+            out.push([]);
+        else
+            out.at(-1).push(arg);
+    }
+    return out;
+}
+export async function runTaskCli(argv, post, io = processIo) {
+    const [name, ...rest] = argv;
+    if (!name || name === "--help" || name === "-h") {
+        io.stdout(USAGE);
+        return name ? 0 : 2;
+    }
+    const cmd = COMMANDS[name];
+    const usage = (message) => {
+        io.stderr(`task: ${message}\n${cmd ? `pier task ${cmd.usage}` : USAGE}`);
+        return 2;
+    };
+    if (!cmd)
+        return usage(`unknown command "${name}"`);
+    const allowed = new Set((cmd.usage.match(/--[a-z-]+/g) ?? []).map((flag) => flag.slice(2)));
+    let params;
+    try {
+        const parsed = (name === "run" ? segments(rest) : [rest]).map((args) => {
+            const values = parseArgs({ args, options: OPTIONS, allowPositionals: false, strict: true }).values;
+            const stray = flagsOf(values).find((flag) => !allowed.has(flag));
+            return stray ? refuse(`--${stray} is not an option of ${name}`) : values;
+        });
+        if (parsed.some((values) => values.help)) {
+            io.stdout(`pier task ${cmd.usage}\n    ${cmd.help}`);
+            return 0;
+        }
+        params = build(name, parsed, io);
+    }
+    catch (err) {
+        return usage(err instanceof Error ? err.message : String(err));
+    }
+    const { status, body } = await post(params);
+    if (status === 200) {
+        // Compact: the reader is a model, and the ids are what it keeps; an answer
+        // the server already wrote in lines (`--model ?`) is printed as it came.
+        io.stdout(typeof body.result === "string" ? body.result : JSON.stringify(body.result));
+        return 0;
+    }
+    io.stderr(`task: ${body.error ?? `socket answered ${String(status)}`}`);
+    return 1;
+}
+/** Argv → the exact params object, or an ArgvError before the socket is touched. */
+function build(name, parsed, io) {
+    let stdinReads = 0;
+    const text = (raw) => {
+        if (raw !== "-")
+            return raw === undefined ? undefined : String(raw);
+        if (stdinReads++)
+            refuse("only one --prompt may read stdin (-)");
+        // An agent's shell has no TTY: a `-` with nothing piped is an empty prompt, named here rather than by the server.
+        return io.stdin() || refuse("--prompt - read nothing from stdin");
+    };
+    if (parsed.some((v) => v.model === "?"))
+        return { operation: "run", launch: { model: "?" } };
+    const [values, ...members] = parsed;
+    if (name === "list")
+        return { operation: "list" };
+    if (name === "cancel" || name === "recover") {
+        if ((values.run === undefined) === (values.group === undefined))
+            refuse(`${name} takes exactly one of --run or --group`);
+        if (name === "recover" && values.reason === undefined)
+            refuse("recover needs --reason");
+        return compact({ operation: name, run_id: values.run, group_id: values.group, reason: values.reason });
+    }
+    if (name === "save")
+        return saveParams(values, text);
+    /** One new run, in the three shapes `tasks[]` accepts. A saved
+     *  definition runs as is: batch defaults pass it by, its own flags are refused. */
+    const entry = (v, own = v) => {
+        const launch = launchOf(v);
+        const timeoutSeconds = seconds("timeout", v.timeout);
+        if (v["task-id"] !== undefined) {
+            const extra = flagsOf(own).find((flag) => ["prompt", "bash", "session", "cwd", "model", "thinking", "name", "timeout"].includes(flag));
+            if (extra)
+                refuse(`--${extra} does not apply to a saved definition (--task-id)`);
+            return { task_id: v["task-id"] };
+        }
+        if (v.bash !== undefined) {
+            if (v.prompt !== undefined)
+                refuse("a run takes exactly one of --prompt or --bash");
+            if (launch)
+                refuse("--model/--thinking apply to a prompt, not --bash");
+            if (v.session !== undefined)
+                refuse("--session continues an agent session; --bash is a command, not a turn");
+            return compact({ name: v.name, timeoutSeconds, action: compact({ type: "bash", script: v.bash, cwd: v.cwd }) });
+        }
+        const prompt = text(v.prompt) ?? refuse("a new run needs --prompt, --bash or --task-id");
+        if (v.session === undefined)
+            return compact({ prompt, cwd: v.cwd, launch, name: v.name, timeoutSeconds });
+        if (v.cwd !== undefined)
+            refuse("--cwd applies to a fresh session, not --session");
+        return compact({ name: v.name, timeoutSeconds, action: compact({ type: "agent", session: { mode: "reuse", sessionId: v.session }, prompt, launch }) });
+    };
+    const delivery = compact({ callback: values.callback, callback_session_id: values["callback-session"] });
+    if (values.run !== undefined) {
+        if (members.length)
+            refuse("--run addresses one existing run; --member starts new ones");
+        const extra = flagsOf(values).find((flag) => !["run", "after", "prompt", "callback", "callback-session"].includes(flag));
+        if (extra)
+            refuse(`--${extra} does not apply to an existing run (--run)`);
+        const message = text(values.prompt) ?? refuse("--run needs --prompt");
+        return compact({ operation: "message", run_id: values.run, message, after: values.after || undefined, ...delivery });
+    }
+    if (values.after)
+        refuse("--after applies to --run only");
+    if (members.length) {
+        if (members.length < 2)
+            refuse("a batch needs at least two --member");
+        if (values["task-id"] !== undefined)
+            refuse("--task-id names one member's definition; put it after a --member");
+        const grouped = members.find((m) => flagsOf(m).some((flag) => GROUP_FLAGS.includes(flag)));
+        if (grouped)
+            refuse(`--${flagsOf(grouped).find((flag) => GROUP_FLAGS.includes(flag))} belongs before the first --member`);
+        const defaults = Object.fromEntries(Object.entries(values).filter(([flag]) => !GROUP_FLAGS.includes(flag)));
+        return compact({ operation: "run", tasks: members.map((m) => entry({ ...defaults, ...m }, m)), join: values.join, ...delivery });
+    }
+    if (values.join !== undefined)
+        refuse("--join applies to a batch (--member)");
+    const single = entry(values);
+    if (single.task_id !== undefined || single.action === undefined)
+        return { operation: "run", ...single, ...delivery };
+    return { operation: "run", task: single, ...delivery };
+}
+function saveParams(v, text) {
+    if ((v.prompt === undefined) === (v.bash === undefined))
+        refuse("save takes exactly one of --prompt or --bash");
+    const cron = v.cron !== undefined || v.tz !== undefined;
+    const watch = v.watch !== undefined || v.every !== undefined || v.repeat !== undefined;
+    if (cron && watch)
+        refuse("a task has one trigger: --cron/--tz or --watch/--every/--repeat");
+    if (cron && (v.cron === undefined || v.tz === undefined))
+        refuse("--cron and --tz go together");
+    if (watch && (v.watch === undefined || v.every === undefined))
+        refuse("--watch and --every go together");
+    const launch = launchOf(v);
+    if (launch && v.bash !== undefined)
+        refuse("--model/--thinking apply to a prompt, not --bash");
+    const trigger = cron
+        ? { type: "cron", expression: v.cron, timezone: v.tz }
+        : watch
+            ? compact({ type: "watch", script: v.watch, cwd: v.cwd, intervalSeconds: seconds("every", v.every), mode: v.repeat ? "repeat" : "once" })
+            : { type: "manual" };
+    const task = compact({
+        name: v.name,
+        timeoutSeconds: seconds("timeout", v.timeout),
+        trigger,
+        callback: v["callback-session"] === undefined ? undefined : { type: "session", sessionId: v["callback-session"] },
+        ...(v.bash === undefined
+            ? { prompt: text(v.prompt), cwd: v.cwd, launch }
+            : { action: compact({ type: "bash", script: v.bash, cwd: v.cwd }) }),
+    });
+    return compact({ operation: "save", task_id: v["task-id"], task });
+}