@timqi/pier 0.1.3 → 0.1.4

package/dist/socket.js

@@ -0,0 +1,95 @@
+// 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) });
+        }
+    },
+    // 422, not 400: the request was well-formed; what the operation refused is
+    // the caller's to read.
+    async "/task"({ task }, { params }, sessionId, answer) {
+        try {
+            answer(200, { result: await task(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,215 @@
+// `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|->] [--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 prompt on a run: a new one (--prompt | --task-id | --session … --prompt), a batch (--member), or 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, 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.
+        io.stdout(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", "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"] };
+        }
+        const prompt = text(v.prompt) ?? refuse("a new run needs --prompt 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 });
+}

package/dist/tasks/definitions.js

@@ -1,6 +1,6 @@
 // What a task *is* before it ever runs: the id it is minted with, the draft
 // validated into a definition, and when its trigger is next due. Every way a
-// definition can be created — HTTP, the task tool, Pier's own owned task —
+// definition can be created — HTTP, `pier task`, Pier's own owned task —
 // arrives here, so a field is checked in one place or nowhere.
 import { randomBytes } from "node:crypto";
 import { stat } from "node:fs/promises";
@@ -24,7 +24,7 @@ export const idSymbol = (byte) => ID_ALPHABET.charAt(byte & 31);
  *  not an error — `saveRun`'s ON CONFLICT DO UPDATE would quietly overwrite. */
 export const newId = () => Array.from(randomBytes(16), idSymbol).join("");
 /** A definition Pier's own code created is reconciled by that code and edited
- *  by nobody: `creator` is `"http"` (Console) or `session:<id>` (task tool);
+ *  by nobody: `creator` is `"http"` (Console) or `session:<id>` (`pier task`);
  *  anything else is an instance-layer owner, which names itself in `by`.
  *  Otherwise a public surface could repoint the tools task while its switch
  *  went on claiming Pier keeps the tools current. */
@@ -258,7 +258,7 @@ export class TaskDefinitions {
         if (trigger.type === "watch")
             await this.assertDirectory(trigger.cwd);
         const actionRaw = record(value.action);
-        // Self-documenting: tool callers (models) recover from this in one retry.
+        // Self-documenting: a model recovers from this in one retry.
         if (!actionRaw) {
             throw new Error('action required, e.g. {"type":"agent","session":{"mode":"fresh","cwd":"/abs/path"},"prompt":"..."}');
         }

package/dist/tasks/execution.js

@@ -92,9 +92,7 @@ export class TaskExecution {
                 log.debug(`${settled} (watch did not match)`);
             else
                 log.info(settled);
-            // A run that ends awaiting a supervisor decision suppresses its
-            // completion callback: the pending question is the notification.
-            if (run.callbackSessionId && !this.host.openDecisionId(run.id))
+            if (run.callbackSessionId)
                 run.callbackState = "pending";
             this.controllers.delete(run.id);
             try {

package/dist/tasks/groups.js

@@ -35,12 +35,12 @@ export class TaskGroups {
     }
     /** Enqueues every member or none: a partially started group is worse than
      * a rejected one. */
-    runAll(definitions, join, callerSessionId, parentRunId, callbackSessionId, callbackMode) {
+    runAll(definitions, join, callerSessionId, callbackSessionId, callbackMode) {
         if (definitions.length < 2)
             throw new Error("a task group needs at least 2 members");
         const { group, runs } = this.store.transact(() => {
             const group = this.create(join, callerSessionId, callbackSessionId, callbackMode);
-            const runs = definitions.map((definition) => this.host.prepareMember(definition.id, group.id, callerSessionId, parentRunId));
+            const runs = definitions.map((definition) => this.host.prepareMember(definition.id, group.id, callerSessionId));
             group.memberRunIds = runs.map((run) => run.id);
             this.store.saveGroup(group);
             return { group, runs };
@@ -150,9 +150,6 @@ export class TaskGroups {
                 `- "${run.context.definition.name}" \u2014 state: ${run.state}`,
                 `  ${runRef(run)}`,
             ];
-            const decision = this.host.openDecisionId(run.id);
-            if (decision)
-                head.push(`  Needs a decision: reply to message ${decision}`);
             if (group.join === "first" && run.id !== group.winnerRunId) {
                 head.push("  Cancelled after the winning run; resume its session to recover partial work.");
                 return head.join("\n");