@timqi/pier 0.0.15 → 0.0.17

package/README.md

@@ -2,7 +2,7 @@
 
 A self-hosted workspace for coding agents. Pier puts a web workbench and your
 IM channels in front of [Pi](https://github.com/earendil-works/pi) sessions:
-you talk to the same agent from a browser, from Slack or from Telegram, steer a
+you talk to the same agent from a browser, from Slack, Telegram or Lark, steer a
 running turn, schedule tasks, watch what every session is doing, and publish a
 static page when something is worth showing.
 
@@ -89,6 +89,11 @@ Console → Settings is the normal setup path:
   `web_search` on an authenticated Anthropic or OpenAI model, `web_fetch` on an
   Anthropic one (OpenAI hosts no fetch tool), and no other key or service. The
   page says which tools a switch adds and what each needs before you flip it.
+  Below it, the same tab switches on the command-line tools Pier manages —
+  `rtk`, `rg`, `fd`, `wt`, `jq`, or a tool of your own written as a
+  [ubix](https://github.com/timqi/ubix) block. A switch installs the binary
+  into `~/.pier/tools/bin`, which is first on the PATH every session, task and
+  terminal inherits, and a task you can read keeps them current.
 
 On first credential access, Pier imports an existing `auth.json` into its sealed
 store and renames the source to `auth.json.imported`. Literal provider keys left
@@ -111,6 +116,7 @@ pier restart             # drain running work, then restart
 pier reload              # re-read channel config and recycle idle sessions
 pier backup              # snapshot the database before a manual update
 pier update              # latest release, then hard-stop/restart the service
+pier tools sync          # install/update the managed CLI tools by hand
 ```
 
 `pier restart` refuses new work, waits up to five minutes for active turns and

package/dist/agent/pi.js

@@ -42,12 +42,22 @@ const PIER_SYSTEM_PROMPT = `You are a general-purpose agent with a live workspac
 # Communication
 These rules govern conversational replies. When the reply *is* the deliverable — a report that was asked for, a review, a task run whose result another agent reads — the work sets the length: complete beats brief, and nothing below caps it.
 - Answer with the conclusion only. Reasons, process, trade-offs, alternatives: only when asked.
-- Cap per reply: 100 words (or 100 Chinese chars), max 3 bullets; 300 when explicitly asked why or how. Code blocks, diffs and commands don't count.
+- Cap per reply: 60 words (90 Chinese chars), max 3 bullets; 180 words (270 Chinese chars) when explicitly asked why or how. Code blocks, diffs and commands don't count.
+- Reply in the language of the request; code, paths, identifiers and quoted output stay verbatim.
 - Never: preamble, restating the question, closing summaries, "I'm going to..." narration, listing changes already visible in the diff.
 - After edits, say only: file(s) touched + one line on the result. Don't explain self-evident code.
-- Show file paths as \`path:line\`.
+- Show file paths as \`path:line\`, or the path alone when no single line is the point — never invent a number.
 - If the honest answer needs more than the cap, give the conclusion plus one short "want the details?" — don't dump it.
-- Blocked on a decision only the person you work for can make? Ask one short question. Otherwise pick the sensible default and note it.`;
+- Blocked on a decision only the person you work for can make? Ask one short question. Otherwise pick the sensible default and note it.
+
+# Working style (any machine)
+These hold wherever Pier runs; a user's SYSTEM.md adds the local ones (which tools exist, which hosts, which paths).
+- Orient first — list and search before you act. Never guess a path.
+- Read before you edit. Match the surrounding code's style, naming, and comment density.
+- Do exactly what was asked. No unrequested refactors, no extra files, no README updates.
+- Destructive or irreversible actions (rm, force push, migrations, deploys): ask first.
+- Say plainly when something failed, was skipped, or is unverified. Never claim a test passed without running it.
+- Every bash call already runs in the working directory this prompt names — don't prefix \`cd <cwd> &&\`, \`cd\` only to go somewhere else. Each call is a fresh shell: \`cd\`, \`export\`, \`source\` never carry over, so chain what must share state into one command.`;
 export const pierSystemPrompt = (userPrompt) => userPrompt ? `${PIER_SYSTEM_PROMPT}\n\n${userPrompt}` : PIER_SYSTEM_PROMPT;
 /** Patching the call is cheaper than replacing the tool: the built-in keeps its
  * shell settings, and the agent spends no tokens deciding a timeout. */

package/dist/db.js

@@ -253,8 +253,63 @@ const MIGRATIONS = [
     token TEXT NOT NULL,
     heartbeat_at INTEGER NOT NULL
   );
+  `,
+    // 13 — a signed-in browser can be signed out on its own (web/auth.ts).
+    `
+  -- One row per signed-in browser. The cookie carries "<id>.<token>" and only
+  -- the token's SHA-256 is stored, so a copy of this database cannot be turned
+  -- into a session — and deleting a row is what revocation is. seen_at is the
+  -- whole lifetime: the session ends one TTL after it, so there is no second
+  -- column that can disagree about when.
+  CREATE TABLE web_sessions (
+    id TEXT PRIMARY KEY,
+    token_hash TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    seen_at INTEGER NOT NULL,
+    ip TEXT NOT NULL,
+    agent TEXT NOT NULL
+  );
+  `,
+    // 14 — signing a browser out also stops notifying it (web/push.ts).
+    `
+  -- A subscription belongs to the web session that made it, and dies with it:
+  -- the cascade is the rule, so no code has to remember to run it — revoking a
+  -- session, changing the password and recovering it all reach here for free.
+  -- Rebuilt rather than altered because a foreign key cannot be added to an
+  -- existing table; nothing is carried over, since migration 13 invalidated
+  -- every cookie and each of these rows belongs to a browser that is now
+  -- signed out. A browser re-subscribes on its next load.
+  DROP TABLE push_subscriptions;
+  CREATE TABLE push_subscriptions (
+    endpoint TEXT PRIMARY KEY,
+    p256dh TEXT NOT NULL,
+    auth TEXT NOT NULL,
+    label TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    session_id TEXT NOT NULL REFERENCES web_sessions(id) ON DELETE CASCADE
+  );
   `,
 ];
+/**
+ * Several writes as one, or none. `BEGIN IMMEDIATE` because every writer here
+ * competes with another Pier process on the same file: taking the write lock
+ * up front turns a race into a wait, where deferred would turn it into
+ * SQLITE_BUSY halfway through. The rollback is the reason this is shared —
+ * three modules had written the same seven lines, and a `catch` that forgets
+ * to roll back leaves the connection in a transaction forever.
+ */
+export function transact(db, work) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const result = work();
+        db.exec("COMMIT");
+        return result;
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+}
 let shared;
 /**
  * The process's one connection, opened and migrated on first use. Every store
@@ -295,6 +350,12 @@ export function openDb(path, migrations = MIGRATIONS) {
     // file, and SQLite refuses to change it inside one.
     db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
     db.exec("PRAGMA journal_mode = WAL");
+    // Off by default in SQLite, and a declared relationship nothing enforces is
+    // a comment. Set before migrate(): it is a per-connection switch and a no-op
+    // inside a transaction. Nothing older declares a key, so this changes the
+    // behaviour of exactly one table — push_subscriptions, whose rows must not
+    // outlive the session that made them.
+    db.exec("PRAGMA foreign_keys = ON");
     migrate(db, path, migrations);
     if (path !== ":memory:")
         restrict(path);

package/dist/extensions/web/content.js

@@ -1,3 +1,8 @@
+// What a provider's answer becomes on the way to the model: sources, results,
+// the queries actually searched, usage, and the text of a fetched document.
+// One shape for both backends, so a tool renders its answer once instead of
+// per wire format — anthropic.ts and openai.ts parse into these, and nothing
+// past this file knows which one replied.
 import { isObject } from "./json.js";
 import { languageLabel } from "./language.js";
 /**

package/dist/extensions/web/language.js

@@ -1,3 +1,8 @@
+// The language-preservation policy in words: what the model is told to search
+// in, and how to tell afterwards whether it did. This is the reason the
+// extension exists at all — a hosted search that quietly translates a Chinese
+// query answers a question nobody asked — so the policy is one file, and the
+// audit that checks it reads from the same one.
 export function searchPrompt(query, mode) {
     const policy = mode === "preserve"
         ? "Use only the original language. Later searches may refine wording in that language, but must not translate or transliterate it."

package/dist/extensions/web/tools.js

@@ -1,3 +1,8 @@
+// The two tools as the model sees them: web_search and web_fetch — their
+// parameters, which backend answers a call, and what comes back when one
+// cannot. Every parameter is context the model pays for on every turn, so the
+// surface is deliberately small; the wire formats behind it are anthropic.ts
+// and openai.ts, and the answer's shape is content.ts.
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { callNativeTool } from "./anthropic.js";

package/dist/settings.js

@@ -7,7 +7,7 @@
 // too" — the agent is told the URL in its system prompt (core/reply.ts), and
 // nothing outside this process ever opened that file.
 import { isThinkingLevel } from "./core/types.js";
-import { pierDb } from "./db.js";
+import { pierDb, transact } 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
@@ -201,16 +201,7 @@ export class SettingsStore {
      * 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;
-        }
+        return transact(this.#db, work);
     }
     #set(key, value) {
         this.#db.prepare(`

package/dist/tasks/agent.js

@@ -1,3 +1,8 @@
+// A run that *is* a Pi session: which session it opens (reuse, fresh, fork),
+// what the child is told before the prompt, and how many may run at once. The
+// concurrency caps are here rather than in execution.ts because they bound
+// agents specifically — a bash run costs a process, an agent run costs a
+// model's context and someone's rate limit.
 import { quietLabel, splitReply } from "../core/reply.js";
 import { Router } from "../core/router.js";
 import { runSource } from "./callbacks.js";

package/dist/tasks/command.js

@@ -1,4 +1,9 @@
+// A bash task's script, run in its cwd with its input on stdin. The output is
+// capped as it arrives rather than after: a run that printed a gigabyte is a
+// run whose result still has to fit in a row, a transcript and a callback.
 import { spawn } from "node:child_process";
+import { logger } from "../log.js";
+const log = logger("tasks");
 const OUTPUT_LIMIT = 1024 * 1024;
 class CappedOutput {
     chunks = [];
@@ -69,6 +74,16 @@ export function runBash(script, cwd, input, signal) {
                 stderrTruncated: stderr.truncated,
             });
         });
+        // A script that never reads stdin is ordinary (`exit 0`, a one-line curl),
+        // and writing the input to a pipe nobody is holding raises EPIPE *here*.
+        // Unhandled, that is an `error` event on a stream, which is an uncaught
+        // exception, which is main.ts exiting the process: one task script could
+        // take every session and every other run down with it. The input not being
+        // wanted is not a failure of the run — anything else still gets said.
+        child.stdin.on("error", (err) => {
+            if (err.code !== "EPIPE")
+                log.warn(`run input could not be written: ${err.message}`);
+        });
         child.stdin.end(encodedInput);
     });
 }

package/dist/tasks/definitions.js

@@ -1,3 +1,7 @@
+// 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 —
+// arrives here, so a field is checked in one place or nowhere.
 import { randomBytes } from "node:crypto";
 import { stat } from "node:fs/promises";
 import { Cron } from "croner";

package/dist/tasks/execution.js

@@ -1,3 +1,7 @@
+// One queued run carried to a result: dispatched by action kind (a bash
+// script, an agent session, another task), abortable while it goes, settled
+// exactly once. What the two action kinds actually do lives in command.ts and
+// agent.ts; this file owns only the lifecycle they share.
 import { logger } from "../log.js";
 import { AgentTaskRunner } from "./agent.js";
 import { TaskCallbacks } from "./callbacks.js";

package/dist/tasks/groups.js

@@ -1,3 +1,7 @@
+// The fan-out join: members start detached, and the group is what turns their
+// separate endings into one answer — when the join condition is met, which
+// members are cancelled, and the single aggregated callback that goes back.
+// Delivering it is the outbox's job; deciding it is this file's.
 import { Router } from "../core/router.js";
 import { logger } from "../log.js";
 import { runRef, runResultText } from "./callbacks.js";

package/dist/tasks/messages.js

@@ -1,3 +1,9 @@
+// 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";

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,3 +1,8 @@
+// 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";

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";

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/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.js

@@ -16,7 +16,7 @@ import { execFile } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { delimiter, join } from "node:path";
-import { pierDb } from "./db.js";
+import { pierDb, transact } from "./db.js";
 import { logger } from "./log.js";
 import { pierPath, resolveAgentDir } from "./paths.js";
 const log = logger("tools");
@@ -253,21 +253,15 @@ export class SyncLock {
      *  in one immediate transaction, so two waiters cannot both win. */
     #acquire(token) {
         const now = Date.now();
-        this.#db.exec("BEGIN IMMEDIATE");
-        try {
-            const stale = this.#db.prepare("DELETE FROM tools_sync_lock WHERE heartbeat_at <= ?")
-                .run(now - this.#timing.staleMs);
-            const taken = this.#db.prepare("INSERT OR IGNORE INTO tools_sync_lock (id, token, heartbeat_at) VALUES (1, ?, ?)")
-                .run(token, now);
-            this.#db.exec("COMMIT");
-            if (stale.changes && taken.changes)
-                log.warn("took over a tools sync lock whose holder stopped beating");
-            return taken.changes === 1;
-        }
-        catch (err) {
-            this.#db.exec("ROLLBACK");
-            throw err;
-        }
+        const { stale, taken } = transact(this.#db, () => ({
+            stale: this.#db.prepare("DELETE FROM tools_sync_lock WHERE heartbeat_at <= ?")
+                .run(now - this.#timing.staleMs),
+            taken: this.#db.prepare("INSERT OR IGNORE INTO tools_sync_lock (id, token, heartbeat_at) VALUES (1, ?, ?)")
+                .run(token, now),
+        }));
+        if (stale.changes && taken.changes)
+            log.warn("took over a tools sync lock whose holder stopped beating");
+        return taken.changes === 1;
     }
     /** Still ours? The authority is the row, asked now — not the heartbeat's own
      *  bookkeeping, which a stopped process does not get to run either. */