@timqi/pier 0.0.15 → 0.0.16

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