@timqi/pier 0.0.9 → 0.0.16

package/dist/tasks/messages.js

@@ -1,7 +1,14 @@
-import { randomUUID } from "node:crypto";
+// What a parent and a child say to each other while a run is going: steer,
+// follow-up and resume in one direction, progress and decision questions in
+// the other. Every message is a durable row before it is a delivery, because
+// the two ends are different sessions and either may be mid-turn, gone, or
+// finished — an undelivered message is retried, expired and *said*, never
+// dropped (§5b).
 import { EventHub } from "../core/hub.js";
 import { Router } from "../core/router.js";
 import { logger } from "../log.js";
+import { runSource } from "./callbacks.js";
+import { newId } from "./definitions.js";
 import { TaskStore } from "./store.js";
 import { isTerminal, MAX_DELIVERY_ATTEMPTS, retryDelay, undeliverable } from "./types.js";
 const log = logger("tasks");
@@ -152,7 +159,7 @@ export class TaskMessenger {
     }
     create(run, kind, fromSessionId, toSessionId, content, replyTo) {
         const message = {
-            id: randomUUID(),
+            id: newId(),
             runId: run.id,
             kind,
             fromSessionId,
@@ -319,6 +326,7 @@ export class TaskMessenger {
             sourceSessionId: message.fromSessionId,
             messageId: message.id,
             messageKind: message.kind,
+            source: runSource(run),
         };
     }
     require(id) {

package/dist/tasks/routes.js

@@ -1,3 +1,7 @@
+// The area's HTTP surface: tasks, runs, group and message routes for the
+// Console, plus the Activity snapshot it draws its graph from. A route reads
+// its body, names the caller and hands the decision to TaskService — policy
+// that lives here would be policy the task tool does not get.
 import { record, requiredString } from "./definitions.js";
 const jsonBody = async (req) => req.json().catch(() => null);
 export function registerTaskRoutes(app, tasks, activity) {

package/dist/tasks/runs.js

@@ -1,6 +1,11 @@
-import { randomUUID } from "node:crypto";
+// A definition plus an input becomes a queued run: where it came from, how
+// deep in a subagent chain it sits, whether it overlaps a run already going,
+// and which session hears about it. The limits that keep a chain from
+// exploding (depth, children per root) are decided here, once, because every
+// caller — scheduler, tool, HTTP — enqueues through this one door.
 import { logger } from "../log.js";
 import { TaskCallbacks } from "./callbacks.js";
+import { newId } from "./definitions.js";
 import { TaskStore } from "./store.js";
 const log = logger("tasks");
 const MAX_DEPTH = 2;
@@ -19,7 +24,7 @@ export class TaskRunQueue {
         this.changed = changed;
     }
     enqueue(definition, input, source, parentRunId, provenance) {
-        const id = randomUUID();
+        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;

package/dist/tasks/service.js

@@ -1,3 +1,9 @@
+// The one object the rest of Pier talks to about tasks, and the clock behind
+// it: the tick that finds what is due, the boot recovery that writes off runs
+// a restart interrupted, and the pause a drain needs. Every decision it looks
+// like it makes belongs to a file beside it (definitions, runs, execution,
+// groups, messages, callbacks) — what is genuinely here is scheduling and the
+// facade, so the HTTP routes and the task tool cannot drift apart.
 import { EventHub } from "../core/hub.js";
 import { Router } from "../core/router.js";
 import { logger } from "../log.js";
@@ -130,6 +136,14 @@ export class TaskService {
     activeRunCount() {
         return this.store.countActiveRuns();
     }
+    /** The run this task has in flight, if any. The store already answers this
+     *  for the overlap guard (runs.ts); a caller that has just been refused as
+     *  an overlap needs the same answer to know what to wait for, and scanning
+     *  run history for it finds nothing once the skipped rows outnumber the
+     *  window. */
+    activeRun(taskId) {
+        return this.store.findActiveRun(taskId);
+    }
     list() {
         return this.definitions.list();
     }
@@ -139,14 +153,16 @@ export class TaskService {
     create(raw, creator = "http") {
         return this.definitions.create(raw, creator);
     }
-    update(id, raw) {
-        return this.definitions.update(id, raw);
+    /** `by` is how the code that owns a definition says so; the HTTP routes and
+     *  the task tool have none, which is what closes both (definitions.ts). */
+    update(id, raw, by) {
+        return this.definitions.update(id, raw, by);
     }
-    setEnabled(id, enabled) {
-        return this.definitions.setEnabled(id, enabled);
+    setEnabled(id, enabled, by) {
+        return this.definitions.setEnabled(id, enabled, by);
     }
-    archive(id) {
-        return this.definitions.archive(id);
+    archive(id, by) {
+        return this.definitions.archive(id, by);
     }
     sessionExists(sessionId) {
         return this.definitions.sessionExists(sessionId);

package/dist/tasks/store.js

@@ -1,3 +1,7 @@
+// Every query this area makes against pier.db, and nothing else: definitions,
+// runs, groups and messages are rows here, read and written through one
+// connection db.ts opened. A store owns its queries, never its own tables or
+// its own handle — the schema is db.ts's migration list.
 import { pierDb } from "../db.js";
 const clamp = (limit, cap) => Math.min(Math.max(limit, 1), cap);
 export class TaskStore {

package/dist/tasks/tool.js

@@ -82,9 +82,6 @@ const DraftSchema = Type.Object({
                 Type.Object({ mode: Type.Literal("reuse"), sessionId: Type.String() }),
             ]),
             prompt: Type.String(),
-            // No `capabilities` here on purpose: a child gets the same tools as any
-            // Pier session, so the model never spends a decision on it. Read-only
-            // children stay configurable through the Console and HTTP.
             launch: Type.Optional(Type.Object({
                 model: Type.Optional(Type.Object({ provider: Type.String(), id: Type.String() })),
                 thinking: Type.Optional(Type.String()),
@@ -152,9 +149,6 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
         return definitions.update(requiredString(input.task_id, "task_id"), input.task);
     }
     if (input.operation === "run") {
-        if (active && active.context.definition.action.type === "agent" && active.context.definition.action.launch?.capabilities === "read") {
-            throw new Error("read-only subagents cannot delegate nested work");
-        }
         if (Array.isArray(input.tasks)) {
             // Core-joined fan-out: members run detached, one aggregated callback.
             if (input.task !== undefined || input.task_id !== undefined)
@@ -253,12 +247,6 @@ async function resolveDraft(definitions, draft, active, callerSessionId) {
     if (draft.trigger !== undefined && record(draft.trigger)?.type !== "manual") {
         throw new Error("inline subagent tasks must use a manual trigger");
     }
-    // The draft parser accepts `capabilities` for Console/HTTP definitions; from
-    // the tool it is rejected rather than silently honoured, so a model working
-    // from stale memory learns the field is gone.
-    if (record(record(draft.action)?.launch)?.capabilities !== undefined) {
-        throw new Error("launch.capabilities is configured in Console or HTTP, not by the task tool");
-    }
     if (active) {
         const action = record(draft.action);
         if (action?.type !== "agent")

package/dist/tasks/types.js

@@ -1,3 +1,7 @@
+// The vocabulary every file in this area shares: what a task, a run, a group
+// and a control message *are*, plus the delivery constants the outbox and the
+// messenger must agree on. Owner-defined and browser-importable type-only
+// (architecture.md), so nothing here may reach for a runtime or a node builtin.
 export const retryDelay = (attempts) => Math.min(60_000, 1000 * 2 ** Math.min(attempts, 6));
 /** Attempts before a delivery is given up on and reported. With the backoff
  *  above that is ~4 minutes: long enough to outlast a busy or restarting

package/dist/tools-task.js

@@ -0,0 +1,155 @@
+// One reason: a tools switch has to become exactly one run of the one task
+// Pier owns — which takes knowing what that task runs, keeping it the task
+// Pier wrote, and turning a burst of switches into one run of it.
+//
+// It lives beside tools.ts rather than inside it because tools.ts may not
+// import tasks/, and outside main.ts because main.ts is wiring: this is the
+// only rule in the instance layer that is neither construction nor a callback.
+// The task's run history *is* the tools status surface — the install, the daily
+// update and every failure are runs with output, so there is no second place to
+// look (§5b).
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { logger } from "./log.js";
+import { PIER_HOME } from "./paths.js";
+import { isTerminal } from "./tasks/types.js";
+import { coalescedSync } from "./tools.js";
+/** Marks the daily update task as Pier's own — this file finds the one it owns
+ *  rather than one a person wrote, and names itself with it when it writes the
+ *  definition back (the owner guard in tasks/definitions.ts). */
+const TOOLS_TASK_CREATOR = "tools";
+// The area these lines have always logged under: the move must not rename
+// anything an operator greps the journal for.
+const log = logger("pier");
+/** POSIX single quotes: `$`, a backtick and a backslash mean things inside
+ *  double quotes, and this string is run by bash months from now. */
+const shellQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
+/**
+ * How this Pier runs `pier tools sync`. Installed, that is the built CLI beside
+ * main.js. From a source checkout there is no `cli.js` and node cannot strip
+ * types through imports that still say `.js`, so it is the same command under
+ * tsx — which is what a source checkout has. Neither available is a refusal
+ * with a reason, never a task whose script cannot run.
+ */
+const toolsSyncScript = () => {
+    const built = fileURLToPath(new URL("./cli.js", import.meta.url));
+    if (existsSync(built))
+        return { script: `${shellQuote(process.execPath)} ${shellQuote(built)} tools sync` };
+    const source = fileURLToPath(new URL("./cli.ts", import.meta.url));
+    if (!existsSync(source))
+        return { problem: `no CLI to run: neither ${built} nor ${source} exists` };
+    try {
+        return {
+            script: `${shellQuote(process.execPath)} --import ${shellQuote(import.meta.resolve("tsx"))}` +
+                ` ${shellQuote(source)} tools sync`,
+        };
+    }
+    catch {
+        return { problem: `running from source (${source}) and tsx is not installed — run npm install, or npm run build` };
+    }
+};
+export function toolsTask(tasks) {
+    /** Which task is Pier's, and the id every managed run goes through. */
+    let toolsTaskId = null;
+    /**
+     * The one task Pier owns, brought in line with what it should be.
+     *
+     * Created once and never retired: a task that comes and goes is a state class
+     * of its own (two boots racing to create it, a retirement racing a switch),
+     * and the run it would have been retired for already says "no tools switched
+     * on".
+     *
+     * It repairs rather than trusts because of what came before the owner guard
+     * (tasks/definitions.ts): a definition edited by an older Pier, or by a
+     * release where the routes could still write it, is brought back to the one
+     * Pier owns here. Nothing can edit it any more — so this is a boot-time
+     * repair of state that already exists, not a defence.
+     */
+    const ensureToolsTask = async () => {
+        const command = toolsSyncScript();
+        if ("problem" in command)
+            return { problem: command.problem };
+        const draft = {
+            name: "tools: daily update",
+            description: "Installs the CLI tools switched on in Settings → Agent and keeps them current.",
+            trigger: {
+                type: "cron",
+                expression: "17 4 * * *",
+                timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
+            },
+            // PIER_HOME as cwd: the command belongs to the instance, not to a project.
+            action: { type: "bash", script: command.script, cwd: PIER_HOME },
+            timeoutSeconds: 1800,
+        };
+        const draftShape = [draft.name, draft.description, true, draft.trigger, draft.action, { type: "none" }, draft.timeoutSeconds];
+        // Archived is not "owned but edited": nothing can un-archive a task, so the
+        // replacement is a new one and the old one keeps its history.
+        const owned = tasks.list().filter((task) => task.creator === TOOLS_TASK_CREATOR && !task.archived);
+        // One per creator. Two would fight over ubix's state lock every night, each
+        // reporting the other's run as an overlap.
+        for (const extra of owned.slice(1)) {
+            log.warn(`archiving a second tools update task (${extra.id})`);
+            tasks.archive(extra.id, TOOLS_TASK_CREATOR);
+        }
+        const task = owned[0];
+        // Every field Pier owns, not just the command: a paused task, a renamed one
+        // or one pointed at a callback still claims to be keeping the tools current
+        // while the daily run never happens.
+        const current = task &&
+            JSON.stringify([task.name, task.description, task.enabled, task.trigger, task.action, task.callback, task.timeoutSeconds]);
+        if (task && current !== JSON.stringify(draftShape)) {
+            log.warn("the tools update task was edited — restoring the definition Pier owns");
+            // Named as the owner: this is the one path allowed to write it back
+            // (tasks/definitions.ts).
+            await tasks.update(task.id, { ...draft, enabled: true, callback: { type: "none" } }, TOOLS_TASK_CREATOR);
+        }
+        const id = task ? task.id : (await tasks.create(draft, TOOLS_TASK_CREATOR)).id;
+        toolsTaskId = id;
+        return { id };
+    };
+    /** The half of `coalescedSync` (tools.ts, which has the rule and why) that
+     *  knows what a task is: start a run, and hand back what to wait for — our own
+     *  run, or the one already in flight that made ours a `skipped` row. */
+    const requestSync = coalescedSync(() => {
+        if (!toolsTaskId)
+            throw new Error("no tools update task to run");
+        const settled = (id) => tasks.waitForRun(id).then(() => undefined);
+        // Bounded, because the only way round this loop is a run that finished
+        // between being in flight and being asked about: real, rare, and not
+        // something to spin on. Three refusals in a row with nothing running is a
+        // bug, and it is reported as one rather than retried forever.
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const mine = tasks.run(toolsTaskId, null, "manual");
+            if (!isTerminal(mine.state))
+                return { ran: "started", settled: settled(mine.id) };
+            const active = tasks.activeRun(toolsTaskId);
+            if (active)
+                return { ran: "overlapped", settled: settled(active.id) };
+        }
+        throw new Error("the tools sync was refused as an overlap three times with nothing running");
+    }, (err) => log.error("the tools sync could not be run", err));
+    /** A switch was flipped: make sure the task is the one Pier means, then ask
+     *  for a sync. Answers with what that switch should say about it. */
+    const toolsChanged = async () => {
+        try {
+            const task = await ensureToolsTask();
+            if ("problem" in task) {
+                log.error(`tools cannot be managed: ${task.problem}`);
+                return { state: "refused", reason: task.problem };
+            }
+            return { state: requestSync() };
+        }
+        catch (err) {
+            log.error("the tools update task could not be reconciled", err);
+            return { state: "refused", reason: err instanceof Error ? err.message : String(err) };
+        }
+    };
+    return {
+        /** Reconcile now. At boot, before any route exists: two first flips could
+         *  otherwise both find no task and create one each. */
+        reconcile: ensureToolsTask,
+        /** The task whose runs are the status surface, null until there is one. */
+        id: () => toolsTaskId,
+        changed: toolsChanged,
+    };
+}