@timqi/pier 0.0.8 → 0.0.15

package/dist/settings.js

@@ -9,6 +9,11 @@
 import { isThinkingLevel } from "./core/types.js";
 import { pierDb } from "./db.js";
 import { logger } from "./log.js";
+// The one place the custom-tool vocabulary lives (names, ubix sources, the
+// names Pier already owns). Imported rather than copied: a second validator
+// would be the third-copy bug one release later, and tools.ts is root-layer
+// like this file, so nothing crosses a seam.
+import { normalizeCustomTools } from "./tools.js";
 const log = logger("settings");
 /**
  * `""` clears it, `null` rejects it. Rejecting rather than repairing: a
@@ -66,6 +71,56 @@ export function normalizeModelMenu(raw) {
     }
     return menu;
 }
+/**
+ * One line, typed into a shell. Same reject-don't-repair contract: a command
+ * silently truncated at a newline would run half of what the operator wrote,
+ * in every project shell, with no sign of what was dropped.
+ */
+export function normalizeTerminalInitCommand(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const text = raw.trim();
+    if (!text)
+        return "";
+    if (text.length > 500)
+        return null;
+    // A tty reads these as keys, not text: an embedded newline is a second
+    // command nobody would see in the field it was typed in.
+    for (const ch of text)
+        if (ch < " " || ch === "\u007f")
+            return null;
+    return text;
+}
+/**
+ * Shape only — an unknown name is not an error here. This file must not know
+ * what Pier bundles (that catalog is code, and importing it would drag the Pi
+ * SDK into the instance layer); agent/ matches the names it recognizes and
+ * ignores the rest, which is also what keeps a downgrade from losing a
+ * setting it cannot currently explain.
+ */
+export function normalizeExtensions(raw) {
+    return normalizeNames(raw);
+}
+/** Same shape, same contract, same cap — the managed-tool set (src/tools.ts).
+ *  Shape only again: tools.ts owns the catalog, and a name it does not know is
+ *  ignored there rather than rejected here, so a downgrade cannot lose one. */
+export function normalizeTools(raw) {
+    return normalizeNames(raw);
+}
+function normalizeNames(raw) {
+    if (!Array.isArray(raw) || raw.length > 32)
+        return null;
+    const names = new Set();
+    for (const item of raw) {
+        if (typeof item !== "string")
+            return null;
+        const name = item.trim();
+        if (!name || name.length > 64)
+            return null;
+        names.add(name);
+    }
+    return [...names];
+}
 export class SettingsStore {
     #db;
     constructor(db = pierDb()) {
@@ -74,29 +129,35 @@ export class SettingsStore {
     get() {
         return {
             publicUrl: this.#value("publicUrl") ?? "",
-            modelMenu: this.#menu(),
+            modelMenu: this.#json("modelMenu", normalizeModelMenu, "a valid menu") ?? [],
             autoUpdate: this.#value("autoUpdate") === "1",
+            terminalInitCommand: this.#value("terminalInitCommand") ?? "",
+            extensions: this.#json("extensions", normalizeExtensions, "a list of names") ?? [],
+            tools: this.#json("tools", normalizeTools, "a list of names") ?? [],
+            customTools: this.#json("customTools", normalizeCustomTools, "a list of {name, spec}") ?? [],
         };
     }
-    #menu() {
-        const raw = this.#value("modelMenu");
+    /**
+     * A JSON-valued row, validated on the way out. Only a hand-edited row can be
+     * malformed, and it is named rather than silently served as the empty value:
+     * a setting that stopped applying without saying so is the bug this logs.
+     */
+    #json(key, normalize, expected) {
+        const raw = this.#value(key);
         if (!raw)
-            return [];
+            return null;
         let parsed;
         try {
             parsed = JSON.parse(raw);
         }
         catch {
-            // Only a hand-edited row can get here; named, not silently served as [].
-            log.warn("settings.modelMenu is not JSON — ignoring it");
-            return [];
-        }
-        const menu = normalizeModelMenu(parsed);
-        if (!menu) {
-            log.warn("settings.modelMenu is not a valid menu — ignoring it");
-            return [];
+            log.warn(`settings.${key} is not JSON — ignoring it`);
+            return null;
         }
-        return menu;
+        const value = normalize(parsed);
+        if (value === null)
+            log.warn(`settings.${key} is not ${expected} — ignoring it`);
+        return value;
     }
     /** Store an already-normalized value — validation belongs at the boundary
      *  that received it, so this never has to guess what the caller meant. */
@@ -109,10 +170,48 @@ export class SettingsStore {
         this.#set("modelMenu", JSON.stringify(menu));
         return this.get();
     }
+    /** Same contract again: hand this `normalizeTerminalInitCommand`'s output. */
+    setTerminalInitCommand(command) {
+        this.#set("terminalInitCommand", command);
+        return this.get();
+    }
     setAutoUpdate(on) {
         this.#set("autoUpdate", on ? "1" : "0");
         return this.get();
     }
+    /** Same contract again: hand this `normalizeExtensions`'s output. */
+    setExtensions(names) {
+        this.#set("extensions", JSON.stringify(names));
+        return this.get();
+    }
+    /** Same contract again: hand this `normalizeTools`'s output. */
+    setTools(names) {
+        this.#set("tools", JSON.stringify(names));
+        return this.get();
+    }
+    /** Same contract again: hand this `normalizeCustomTools`'s output. */
+    setCustomTools(tools) {
+        this.#set("customTools", JSON.stringify(tools));
+        return this.get();
+    }
+    /**
+     * Several setters as one write. A request that declares a tool *and* the
+     * switch that turns it on must not be able to store one without the other:
+     * half of that pair is a switch nobody can explain — on and undeclared, or
+     * declared and invisible.
+     */
+    transact(work) {
+        this.#db.exec("BEGIN IMMEDIATE");
+        try {
+            const result = work();
+            this.#db.exec("COMMIT");
+            return result;
+        }
+        catch (err) {
+            this.#db.exec("ROLLBACK");
+            throw err;
+        }
+    }
     #set(key, value) {
         this.#db.prepare(`
       INSERT INTO settings(key, value) VALUES (?, ?)

package/dist/tasks/agent.js

@@ -1,5 +1,6 @@
 import { quietLabel, splitReply } from "../core/reply.js";
 import { Router } from "../core/router.js";
+import { runSource } from "./callbacks.js";
 import { TaskMessenger } from "./messages.js";
 import { TaskStore } from "./store.js";
 const MAX_ACTIVE_AGENTS = 4;
@@ -44,6 +45,12 @@ export class AgentTaskRunner {
             const session = await this.resolveSession(run, action);
             return await this.withSession(session.id, async () => {
                 await this.waitUntilIdle(session, signal);
+                // Task requests come seconds apart — the 1h Anthropic cache-write premium
+                // never earns its 2× back, so task runs use the 5m TTL. Set here, not in
+                // resolveSession: this covers create, fork, reuse and resume alike, on
+                // every attempt — and only after the session is idle, so a reused
+                // interactive session's in-flight turn keeps its 1h writes.
+                session.setCacheRetention("short");
                 start();
                 // No input is no block: `<task_input>\nnull\n</task_input>` is four
                 // lines telling the agent nothing, on every run that has no input.
@@ -55,6 +62,10 @@ export class AgentTaskRunner {
                 const prompt = run.context.resumePrompt ?? `${preamble(run)}${action.prompt}${input}`;
                 run.context.sessionId = session.id;
                 run.context.model = session.model;
+                // The level the session settled on, not the one the task asked for:
+                // an unspecified effort inherits the caller's, and the card in the
+                // subagent's own transcript should say which one that was.
+                run.context.thinking = session.thinkingLevel;
                 run.context.renderedPrompt = prompt;
                 this.store.saveRun(run);
                 let text = "";
@@ -83,6 +94,7 @@ export class AgentTaskRunner {
                         taskId: run.taskId,
                         runId: run.id,
                         sourceSessionId: run.sourceSessionId,
+                        source: runSource(run),
                     }, "prompt");
                     await Promise.resolve();
                     this.messages.deliverPendingControls(run);
@@ -102,6 +114,10 @@ export class AgentTaskRunner {
                     return { type: "agent", text: reply.text || quietLabel(reply.silence), sessionId: session.id };
                 }
                 finally {
+                    // The run is what earns "short"; a reused interactive session goes
+                    // back to chat afterwards. For task-created sessions this is moot —
+                    // idle until the next run downgrades them again.
+                    session.setCacheRetention("long");
                     signal.removeEventListener("abort", abort);
                     unsubscribe();
                 }
@@ -115,9 +131,8 @@ export class AgentTaskRunner {
         if (run.targetSessionId) {
             return this.router.ensure({ channelId: "task", conversationId: run.targetSessionId });
         }
-        const listed = await this.factory.list();
         const source = run.sourceSessionId
-            ? listed.find((session) => session.id === run.sourceSessionId)
+            ? await this.factory.find(run.sourceSessionId)
             : undefined;
         const policy = action.session;
         let cwd;
@@ -130,7 +145,7 @@ export class AgentTaskRunner {
             cwd = policy.cwd;
         }
         else if (policy.mode === "reuse") {
-            cwd = listed.find((session) => session.id === policy.sessionId)?.cwd ?? "";
+            cwd = (await this.factory.find(policy.sessionId))?.cwd ?? "";
         }
         else {
             cwd = policy.cwd ?? source?.cwd ?? "";
@@ -145,7 +160,6 @@ export class AgentTaskRunner {
             model: action.launch?.model ??
                 (run.sourceSessionId ? this.router.modelOf(run.sourceSessionId) : undefined),
             thinking: action.launch?.thinking,
-            capabilities: action.launch?.capabilities,
         };
         const session = run.sessionMode === "fork"
             ? await this.factory.fork(run.sourceSessionId, opts)

package/dist/tasks/callbacks.js

@@ -3,6 +3,20 @@
 import { Router } from "../core/router.js";
 import { Outbox } from "./outbox.js";
 import { TaskStore } from "./store.js";
+/** How a run is named to the session that gets its result: the run id, and the
+ *  session that did the work — a relayer's next move is a deep link to it
+ *  (`#/session/<id>`), and without this line that costs a second tool call.
+ *  Shared with the group callback, which has always carried both. */
+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. Part
+ *  of the run vocabulary for the same reason `runRef` is: the callback, the
+ *  subagent messages and the delegation prompt all name a run, and three
+ *  spellings of "which task, on what model" would be three cards. */
+export const runSource = (run) => ({
+    taskName: run.context.definition.name,
+    ...(run.context.model ? { model: run.context.model } : {}),
+    ...(run.context.thinking ? { thinking: run.context.thinking } : {}),
+});
 export function runResultText(run) {
     let result = run.error ?? "No result";
     if (run.result?.type === "agent")
@@ -35,6 +49,11 @@ export class TaskCallbacks {
                     runId: runs[0].id,
                     sourceSessionId: runs[0].targetSessionId,
                     runIds: runs.map((run) => run.id),
+                    // Only when the input is about one run: a batch is several tasks in
+                    // one delivery, and the first one's name and model as the card's
+                    // caption would attribute every other result to it. The text names
+                    // each run; the card says nothing rather than something false.
+                    ...(runs.length === 1 ? { source: runSource(runs[0]) } : {}),
                 },
             }),
             describe: (run) => `the result of "${run.context.definition.name}"`,
@@ -69,7 +88,7 @@ export class TaskCallbacks {
     text(runs) {
         const sections = runs.map((run) => [
             `Task "${run.context.definition.name}" finished with state: ${run.state}`,
-            `Run: ${run.id}`,
+            runRef(run),
             "",
             runResultText(run),
         ].join("\n"));

package/dist/tasks/definitions.js

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { randomBytes } from "node:crypto";
 import { stat } from "node:fs/promises";
 import { Cron } from "croner";
 import { isThinkingLevel } from "../core/types.js";
@@ -7,6 +7,46 @@ import { Router } from "../core/router.js";
 import { TaskStore } from "./store.js";
 const DEFAULT_TIMEOUT = 900;
 const MIN_WATCH_SECONDS = 5;
+/** Crockford's base32, lowercased: i, l, o and u are gone — the three that
+ *  misread as 1/0 and the one that completes most accidental words — and one
+ *  case throughout, so a model re-types an id it read verbatim. */
+const ID_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+/** The one byte → symbol step, exported only so a test can walk all 256 byte
+ *  values: a repeated or omitted character in the alphabet above biases every
+ *  id ever minted, and no sample of finished ids can show it. */
+export const idSymbol = (byte) => ID_ALPHABET.charAt(byte & 31);
+/** The id every task record is minted with — runs, definitions, groups and
+ *  messages alike — because these ids ride through model context constantly:
+ *  every run summary, callback, get, steer and reply echoes one, and a UUID
+ *  spends ~12 tokens where this spends ~6. Nothing parses or orders by them —
+ *  every comparison in the area is string equality and every listing orders by
+ *  a timestamp column — so rows minted as UUIDs before this keep working
+ *  untouched; there is nothing to migrate. It lives here rather than in
+ *  types.ts because the browser type-checks that file and it stays node-free.
+ *
+ *  Sixteen characters, 80 bits (`& 31` is unbiased because 256 is a multiple
+ *  of 32). Sixty would have read the same and cost a token less, but a watch
+ *  task on a 5-second interval mints ~6M runs a year, and a collision here is
+ *  not an error: `saveRun`'s ON CONFLICT DO UPDATE would quietly overwrite the
+ *  older run with the newer one. Four more characters buy ~16 million times
+ *  the headroom for four bytes — cheaper than the alternative fix, which is a
+ *  strict INSERT and a retry loop on every one of the four mint sites. */
+export const newId = () => Array.from(randomBytes(16), idSymbol).join("");
+/**
+ * Seam decision (tasks/): a definition Pier's own code created is reconciled by
+ * that code, and edited by nobody.
+ *
+ * `creator` is `"http"` for the Console and `session:<id>` for the task tool.
+ * Anything else is an instance-layer owner — today the tools update task
+ * (src/tools-task.ts), whose script a switch in Settings runs on demand and
+ * cron runs nightly. Both
+ * public surfaces could rename it, point it at another script, pause it or
+ * archive it, and the switch would go on claiming Pier keeps the tools current
+ * while the run did something else entirely. The owner names itself in `by`;
+ * neither the routes nor the tool has a `by` to pass, so this one function
+ * closes both.
+ */
+const ownerOf = (task) => task.creator === "http" || task.creator.startsWith("session:") ? null : task.creator;
 export const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
     ? value
     : null;
@@ -76,12 +116,6 @@ function parseLaunch(raw) {
         }
         launch.thinking = value.thinking;
     }
-    if (value.capabilities !== undefined) {
-        if (value.capabilities !== "read" && value.capabilities !== "write") {
-            throw new Error("agent capabilities must be read or write");
-        }
-        launch.capabilities = value.capabilities;
-    }
     return Object.keys(launch).length ? launch : undefined;
 }
 export class TaskDefinitions {
@@ -110,7 +144,7 @@ export class TaskDefinitions {
         const draft = await this.parseDraft(value && value.trigger === undefined ? { ...value, trigger: { type: "manual" } } : raw);
         const now = Date.now();
         const task = {
-            id: randomUUID(),
+            id: newId(),
             kind,
             name: draft.name,
             description: draft.description ?? "",
@@ -133,8 +167,9 @@ export class TaskDefinitions {
         this.changed();
         return task;
     }
-    async update(id, raw) {
+    async update(id, raw, by) {
         const old = this.get(id);
+        this.assertOwner(old, by, "edited");
         if (old.archived)
             throw new Error("archived tasks cannot be edited");
         const draft = await this.parseDraft(raw);
@@ -158,8 +193,9 @@ export class TaskDefinitions {
         this.changed();
         return task;
     }
-    setEnabled(id, enabled) {
+    setEnabled(id, enabled, by) {
         const task = this.get(id);
+        this.assertOwner(task, by, enabled ? "resumed" : "paused");
         if (task.archived && enabled)
             throw new Error("archived tasks cannot be resumed");
         task.enabled = enabled;
@@ -169,8 +205,9 @@ export class TaskDefinitions {
         this.changed();
         return task;
     }
-    archive(id) {
+    archive(id, by) {
         const task = this.get(id);
+        this.assertOwner(task, by, "archived");
         task.archived = true;
         task.enabled = false;
         task.nextRunAt = null;
@@ -200,7 +237,14 @@ export class TaskDefinitions {
     }
     async sessionExists(sessionId) {
         return this.router.stateOf(sessionId) !== undefined ||
-            (await this.factory.list()).some((session) => session.id === sessionId);
+            (await this.factory.find(sessionId)) !== undefined;
+    }
+    /** The guard `ownerOf` exists for, on the three ways a definition changes. */
+    assertOwner(task, by, what) {
+        const owner = ownerOf(task);
+        if (owner && by !== owner) {
+            throw new Error(`"${task.name}" is Pier's own ${owner} task: it is reconciled by Pier, not ${what}`);
+        }
     }
     async parseDraft(raw) {
         const value = record(raw);

package/dist/tasks/execution.js

@@ -56,7 +56,11 @@ export class TaskExecution {
                 run.result = await this.executeAction(run, controller.signal);
             run.state = "succeeded";
             if (definition.trigger.type === "watch" && !run.resumedFromRunId && definition.trigger.mode === "once" && run.matched) {
-                this.definitions.setEnabled(definition.id, false);
+                // As the definition's own creator: a one-shot watch retiring itself is
+                // the task layer keeping its own promise, not a surface editing
+                // somebody's task, and the owner guard (definitions.ts) would
+                // otherwise fail the run that had just succeeded.
+                this.definitions.setEnabled(definition.id, false, definition.creator);
             }
         }
         catch (error) {

package/dist/tasks/groups.js

@@ -1,7 +1,7 @@
-import { randomUUID } from "node:crypto";
 import { Router } from "../core/router.js";
 import { logger } from "../log.js";
-import { runResultText } from "./callbacks.js";
+import { runRef, runResultText } from "./callbacks.js";
+import { newId } from "./definitions.js";
 import { Outbox } from "./outbox.js";
 import { TaskStore } from "./store.js";
 import { isTerminal } from "./types.js";
@@ -61,7 +61,7 @@ export class TaskGroups {
     }
     create(join, invokedBySessionId, callbackSessionId) {
         const group = {
-            id: randomUUID(),
+            id: newId(),
             join,
             invokedBySessionId,
             callbackSessionId,
@@ -137,7 +137,7 @@ export class TaskGroups {
         const sections = members.map((run) => {
             const head = [
                 `- "${run.context.definition.name}" \u2014 state: ${run.state}`,
-                `  Run: ${run.id}${run.targetSessionId ? ` / Session: ${run.targetSessionId}` : ""}`,
+                `  ${runRef(run)}`,
             ];
             const decision = this.host.openDecisionId(run.id);
             if (decision)

package/dist/tasks/messages.js

@@ -1,7 +1,8 @@
-import { randomUUID } from "node:crypto";
 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 +153,7 @@ export class TaskMessenger {
     }
     create(run, kind, fromSessionId, toSessionId, content, replyTo) {
         const message = {
-            id: randomUUID(),
+            id: newId(),
             runId: run.id,
             kind,
             fromSessionId,
@@ -319,6 +320,7 @@ export class TaskMessenger {
             sourceSessionId: message.fromSessionId,
             messageId: message.id,
             messageKind: message.kind,
+            source: runSource(run),
         };
     }
     require(id) {

package/dist/tasks/runs.js

@@ -1,6 +1,6 @@
-import { randomUUID } from "node:crypto";
 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 +19,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

@@ -130,6 +130,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 +147,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/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")