@timqi/pier 0.1.14 → 0.3.0

package/dist/agent/pi.js

@@ -3,9 +3,11 @@
 // Pi SDK. No Pi type may appear in an exported signature.
 import { realpathSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
-import { createAgentSession, CredentialSynchronizationError, DefaultResourceLoader, ModelRegistry, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, CredentialSynchronizationError, DefaultResourceLoader, ModelRegistry, ModelRuntime, SessionManager, sessionEntryToContextMessages, } from "@earendil-works/pi-coding-agent";
 import { SESSION_TITLE_MAX } from "../core/types.js";
 import { logger } from "../log.js";
+import { pierPath } from "../paths.js";
+import { DISPATCHER, LEAD } from "./roles.js";
 import { textOf, toChatTurns, toSessionEvents, turnMetaAt, } from "./events.js";
 import { defaultAgentDir, PiConfigStore } from "./config.js";
 import { IndexedListing } from "./listing.js";
@@ -99,7 +101,7 @@ These rules govern conversational replies. A human reads them on a phone-sized s
 - Before touching files: list and search first. Never guess a path or a line number.
 - 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.
-- Each bash call is a fresh shell in the working directory; chain what must share state.
+- Each bash call is a fresh shell in the working directory; chain what must share state. Don't prefix commands with \`cd\` to that same directory — use relative paths; \`cd\` only to go elsewhere.
 - Destructive or irreversible actions on things you didn't create — deleting user files, force push, migrations, deploys, service restarts: ask first; unattended, don't do them and report what you would have done.
 - Say plainly when something failed, was skipped, or is unverified. Never claim a test passed without running it.`;
 export const pierSystemPrompt = (userPrompt) => userPrompt ? `${PIER_SYSTEM_PROMPT}\n\n${userPrompt}` : PIER_SYSTEM_PROMPT;
@@ -111,25 +113,37 @@ const bashTimeoutDefault = (pi) => {
         }
     });
 };
+/** The transcript's current branch in order, compacted entries included. */
+const branchMessages = (sessionManager) => sessionManager.getBranch().flatMap((entry) => sessionEntryToContextMessages(entry));
+/** Where a session compacts — a main session
+ *  and a session a run launched from a session made (a lead or a worker, which
+ *  never rotate); above 200K input, 1M-context models price higher. */
+const MAIN_COMPACTION_CAP = 100_000;
+const CHILD_COMPACTION_CAP = 150_000;
 export class PiSession {
     pi;
     pinned;
     wrote;
     retention;
     suggestTitle;
+    cap;
     constructor(pi, 
     /** Read per call — the menu can change while we run. */
     pinned = () => [], 
-    /** Drops the factory's retained listing: a rename lands in exactly the
-     *  window it covers, and every surface would keep the old title. */
+    /** Drops the factory's retained listing: a title lands in exactly the
+     *  window it covers, and every surface would keep the old one. */
     wrote = () => { }, retention = { value: "long" }, 
     /** Read per turn: switching auto-titling on takes effect without a restart. */
-    suggestTitle = () => undefined) {
+    suggestTitle = () => undefined, 
+    /** Auto-compaction triggers once the context passes this many tokens. */
+    cap) {
         this.pi = pi;
         this.pinned = pinned;
         this.wrote = wrote;
         this.retention = retention;
         this.suggestTitle = suggestTitle;
+        this.cap = cap;
+        this.applyCap();
     }
     /** A turn started after Pi's dispose runs for real and lands nowhere — no
      *  transcript, no event, a promise that resolves. Refusing makes it a failure (§5). */
@@ -153,7 +167,7 @@ export class PiSession {
     }
     get contextUsage() {
         const u = this.pi.getContextUsage();
-        return u ? { tokens: u.tokens, contextWindow: u.contextWindow } : undefined;
+        return u ? { tokens: u.tokens, contextWindow: u.contextWindow, compactAt: u.contextWindow - this.reserve(u.contextWindow) } : undefined;
     }
     async setModel(ref) {
         const m = this.pi.modelRuntime.getModel(ref.provider, ref.id);
@@ -163,6 +177,8 @@ export class PiSession {
             throw new Error(`unknown model: ${ref.provider}/${ref.id}; available: ${available}`);
         }
         await this.pi.setModel(m);
+        // The reserve is per context window, so a cap outlives a model switch only if recomputed.
+        this.applyCap();
     }
     async availableModels() {
         const available = await this.pi.modelRuntime.getAvailable();
@@ -183,6 +199,27 @@ export class PiSession {
     setCacheRetention(retention) {
         this.retention.value = retention;
     }
+    instanceReserve;
+    /** Pi compacts past `contextWindow − reserveTokens`; this session's settings
+     *  manager is its own, so the override reaches no other session. Never later
+     *  than the instance's own reserve. */
+    applyCap() {
+        const window = this.pi.model?.contextWindow;
+        if (this.cap === undefined || !window)
+            return;
+        this.pi.settingsManager.applyOverrides({ compaction: { reserveTokens: this.reserve(window) } });
+    }
+    /** The instance's reserve is read once under a cap, before the first override replaces it. */
+    reserve(window) {
+        const settings = this.pi.settingsManager;
+        if (this.cap === undefined)
+            return settings.getCompactionSettings().reserveTokens;
+        this.instanceReserve ??= settings.getCompactionSettings().reserveTokens;
+        return Math.max(window - this.cap, this.instanceReserve);
+    }
+    skills() {
+        return this.pi.resourceLoader.getSkills().skills.map(({ name, description }) => ({ name, description }));
+    }
     async pendingQueue() {
         return {
             steering: [...this.pi.getSteeringMessages()],
@@ -209,12 +246,11 @@ export class PiSession {
     }
     async history() {
         this.live();
-        return toChatTurns(this.pi.messages);
+        return toChatTurns(branchMessages(this.pi.sessionManager));
     }
     async rewindToUserTurn(index) {
         const total = (await this.history()).filter((t) => t.role === "user").length;
-        // Branch entries keep compacted-away history that history() no longer
-        // shows, so only end-relative indices line up.
+        // End-relative: a user entry toChatTurns would not count cannot shift the target.
         const back = total - index;
         const users = this.pi.sessionManager
             .getBranch()
@@ -227,49 +263,41 @@ export class PiSession {
         if (cancelled)
             throw new Error("rewind cancelled");
     }
-    /** Pi keeps no lock of its own: a second `compact()` summarizes a transcript
-     *  being replaced under it, and two POSTs a millisecond apart both pass the
-     *  route's idle check. */
-    compacting = null;
-    async compact() {
-        this.live();
-        if (this.compacting)
-            throw new Error(`session ${this.pi.sessionId} is already compacting`);
-        // Recorded in the same tick, no await between: that is what makes the check a gate.
-        const running = this.pi.compact().then(() => undefined);
-        this.compacting = running;
-        try {
-            await running;
-        }
-        finally {
-            this.compacting = null;
-        }
-    }
-    /** An append: Pi's reader takes the latest `session_info`. Never refused for
-     *  being busy. TODO: renaming a cold session costs a whole resume for one
-     *  appended line; revisit when Pi offers a lightweight append. */
-    async rename(name) {
-        this.live();
-        this.pi.sessionManager.appendSessionInfo(name);
-        this.wrote();
-    }
-    /** A dispatch landing mid-compaction waits for the summary instead of
-     *  starting a turn over it. Not Pi's follow-up queue: that is drained only by
-     *  the *next* turn, so a message parked there while idle would sit unsent. */
-    async whenCompacted() {
-        while (this.compacting)
-            await this.compacting.catch(() => undefined);
-    }
     // Async, so a refusal is a rejected promise the seam lets callers `.catch()`.
     async prompt(text) {
-        this.live();
-        await this.whenCompacted();
-        // The wait above is long enough for a dispose to land.
         this.live();
         // A turn may have started since the caller read the state. Bare, Pi throws
         // "already processing" and the message is gone (§5); queued, it is the
         // same "delivered when idle" core/queue.ts picks for a mid-turn message.
-        return this.pi.prompt(text, { streamingBehavior: "followUp" });
+        let refused = false;
+        try {
+            await this.pi.prompt(text, { streamingBehavior: "followUp", preflightResult: (ok) => { refused = !ok; } });
+        }
+        catch (error) {
+            if (refused)
+                this.recordRefusal(text, error);
+            throw error;
+        }
+    }
+    /** Pi refuses before writing anything (no model, no key), so without this the
+     *  message and its reason would exist only as a live event (§5). Recorded the
+     *  way a provider failure is — an errored reply the model's context drops. */
+    recordRefusal(text, error) {
+        const now = Date.now();
+        const manager = this.pi.sessionManager;
+        manager.appendMessage({ role: "user", content: [{ type: "text", text }], timestamp: now });
+        manager.appendMessage({
+            role: "assistant",
+            content: [],
+            api: this.pi.model?.api ?? "",
+            provider: this.pi.model?.provider ?? "",
+            model: this.pi.model?.id ?? "",
+            usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+            stopReason: "error",
+            errorMessage: error instanceof Error ? error.message : String(error),
+            timestamp: now,
+        });
+        this.pi.agent.state.messages = manager.buildSessionProjection().messages;
     }
     async steer(text) {
         this.live();
@@ -281,15 +309,13 @@ export class PiSession {
     }
     async systemInput(text, origin, mode) {
         this.live();
-        // Same gate as prompt(): an idle session takes a system input as a turn.
-        await this.whenCompacted();
-        this.live();
-        // Read after the wait: a running turn means the call below queues.
-        const queued = this.pi.isStreaming;
+        // A running turn means the call below queues.
+        const queued = this.pi.isStreaming && mode !== "append";
         if (queued)
             this.queuedInputs.push(origin);
         try {
-            return await this.pi.sendCustomMessage({ customType: "pier.system-input", content: text, display: true, details: origin }, { triggerTurn: true, deliverAs: mode === "prompt" ? undefined : mode });
+            // Without a turn Pi appends it now, or after a running turn's tool results.
+            return await this.pi.sendCustomMessage({ customType: "pier.system-input", content: text, display: true, details: origin }, { triggerTurn: mode !== "append", deliverAs: mode === "prompt" || mode === "append" ? undefined : mode });
         }
         catch (error) {
             // Refused: nothing is in flight. The entry may be gone already.
@@ -338,8 +364,7 @@ export class PiSession {
         if (!first.trim())
             return;
         void suggest(first, reply).then((title) => {
-            // Named while we waited, by a person: their word beats the model's.
-            if (this.disposed || this.pi.sessionManager.getSessionName())
+            if (this.disposed)
                 return;
             this.pi.sessionManager.appendSessionInfo(title);
             this.wrote();
@@ -371,6 +396,7 @@ export class PiAgentFactory {
     pier;
     titleModel;
     listings;
+    roleOf;
     constructor(
     /** Read per session open, so a Console change reaches the next session
      *  without a restart; appended as a context file so the user's own
@@ -384,7 +410,9 @@ export class PiAgentFactory {
     /** The built-in `pier` package's one switch list: Pier's own skills switched off. */
     pier = () => ({ skillsOff: [] }), titleModel = () => undefined, 
     /** Injected so a test needs no session directory or database. */
-    listings = new IndexedListing()) {
+    listings = new IndexedListing(), 
+    /** A reopened session's role, which only its runs record (tasks/). */
+    roleOf = () => undefined) {
         this.instructions = instructions;
         this.skillPaths = skillPaths;
         this.credentials = credentials;
@@ -393,6 +421,7 @@ export class PiAgentFactory {
         this.pier = pier;
         this.titleModel = titleModel;
         this.listings = listings;
+        this.roleOf = roleOf;
     }
     /** Catalogs are global, not per session. */
     catalog;
@@ -583,8 +612,9 @@ export class PiAgentFactory {
         const modelRegistry = new ModelRegistry(await this.refreshedRuntime());
         return { modelRegistry, model: active && modelRegistry.find(active.provider, active.id) };
     }
-    async resourceLoader(cwd) {
-        const { skillsOff } = this.pier();
+    async resourceLoader(cwd, role, dispatcher) {
+        // A worker never delegates (tasks/operations.ts refuses it), so it is not taught how.
+        const skillsOff = role === "worker" ? [...this.pier().skillsOff, "pier-tasks"] : this.pier().skillsOff;
         const loader = new DefaultResourceLoader({
             cwd,
             agentDir: defaultAgentDir(),
@@ -601,19 +631,27 @@ export class PiAgentFactory {
             agentsFilesOverride: (current) => {
                 const content = this.instructions();
                 return {
-                    agentsFiles: content
-                        ? [...current.agentsFiles, { path: "<pier>/AGENTS.md", content }]
-                        : current.agentsFiles,
+                    agentsFiles: [
+                        ...current.agentsFiles,
+                        ...(content ? [{ path: "<pier>/AGENTS.md", content }] : []),
+                        ...(dispatcher ? [{ path: "<pier>/dispatcher.md", content: DISPATCHER }] : []),
+                        ...(role === "lead" ? [{ path: "<pier>/lead.md", content: LEAD }] : []),
+                    ],
                 };
             },
         });
         await loader.reload();
         return loader;
     }
-    open(cwd, sessionManager, opts = { cwd }) {
-        return this.providerConfig.withWrite(() => this.openSnapshot(cwd, sessionManager, opts));
+    open(sessionManager, opts) {
+        return this.providerConfig.withWrite(() => this.openSnapshot(sessionManager, opts));
     }
-    async openSnapshot(cwd, sessionManager, opts) {
+    async openSnapshot(sessionManager, opts) {
+        const { cwd, role } = opts;
+        // The home is where the continuous conversation's sessions run: only they
+        // dispatch, and they compact at main's cap.
+        const main = realPath(cwd) === realPath(pierPath("home"));
+        const cap = main ? MAIN_COMPACTION_CAP : role ? CHILD_COMPACTION_CAP : undefined;
         // A locked store is a refusal with a reason here, not "provider not
         // configured" later. Before appendSessionInfo, so nothing is written.
         await this.credentials?.assertUnlocked();
@@ -630,7 +668,7 @@ export class PiAgentFactory {
             cwd,
             sessionManager,
             modelRuntime: runtime,
-            resourceLoader: await this.resourceLoader(cwd),
+            resourceLoader: await this.resourceLoader(cwd, role, main),
         });
         const live = created.session;
         // Pi defaults to one follow-up per turn boundary, so N queued messages cost
@@ -642,7 +680,7 @@ export class PiAgentFactory {
         }, retention, () => {
             const model = this.titleModel();
             return model && ((first, reply) => this.suggestTitle(model, first, reply));
-        });
+        }, cap);
         if (opts.model)
             await session.setModel(opts.model);
         if (opts.thinking)
@@ -654,13 +692,14 @@ export class PiAgentFactory {
         this.listing = undefined;
         // Resolved before Pi records it, so every later listing names it the same way.
         const cwd = realPath(opts.cwd);
-        return this.open(cwd, SessionManager.create(cwd), { ...opts, cwd });
+        return this.open(SessionManager.create(cwd), { ...opts, cwd });
     }
     async resume(sessionId) {
+        const role = this.roleOf(sessionId);
         const known = this.located.get(sessionId);
         if (known) {
             try {
-                return await this.open(known.cwd, SessionManager.open(known.path));
+                return await this.open(SessionManager.open(known.path), { cwd: known.cwd, role });
             }
             catch (err) {
                 log.warn(`cached path for session ${sessionId} did not open; re-listing`, err);
@@ -670,7 +709,7 @@ export class PiAgentFactory {
         const info = await this.locate(sessionId);
         if (!info)
             throw new Error(`unknown session: ${sessionId}`);
-        return this.open(info.cwd || process.cwd(), SessionManager.open(info.path));
+        return this.open(SessionManager.open(info.path), { cwd: info.cwd || process.cwd(), role });
     }
     /** The one place "no such session" is decided. A retained listing is not
      *  evidence a session is gone, and callers read a miss as permission to start
@@ -681,6 +720,10 @@ export class PiAgentFactory {
         return find(await this.listed()) ??
             (reused && this.listing === reused ? find(await this.listed(true)) : undefined);
     }
+    async readHistory(sessionId) {
+        const info = await this.locate(sessionId);
+        return info && toChatTurns(branchMessages(SessionManager.open(info.path)));
+    }
     async find(sessionId) {
         const info = await this.locate(sessionId);
         return info ? summaryOf(info) : undefined;
@@ -714,8 +757,8 @@ export class PiAgentFactory {
         return (await this.listed()).map(summaryOf);
     }
     /** After a listing, so a transcript that grew is indexed before it is asked about. */
-    async search(query) {
+    async search(query, limit) {
         await this.listed();
-        return this.listings.search?.(query) ?? [];
+        return this.listings.search?.(query, limit) ?? [];
     }
 }

package/dist/agent/roles.js

@@ -0,0 +1,104 @@
+// The role contracts Pier injects from code, never written to disk
+// (docs/design/10-continuous-session.md): the dispatcher's, for the main
+// session of the continuous conversation, the feature lead's, and the chat
+// surface's, which every session gets.
+export const DISPATCHER = `# You are the main session of Pier's continuous conversation
+
+The user talks to Pier as one conversation; you are its current session, in the home directory, which holds memory only. You answer, remember and dispatch. You never edit code or files outside this directory yourself.
+
+## Dispatch
+- Real work is a child run: \`pier task run --prompt … --cwd <dir> --model hardest|balanced|cheap [--timeout <s>]\` (skills/pier-tasks). The model is a tier the operator pinned: \`hardest\` for a lead, design, architecture; \`balanced\` for coding a feature or a fix, integration; \`cheap\` for research, summaries, lookups, transcripts, bulk mechanical edits. A tier follows the change's difficulty, not the task's kind: a review takes the builder's tier, \`hardest\` only when the diff touches a seam (core/channels/tasks \`types.ts\`, \`db.ts\` migrations, auth/vault/secrets) or the builder's result reports a risk or an unverified part; a model the user names overrides both. Thinking follows the pin: pass \`--thinking\` only to override it; never \`--model ?\` per message. One \`wt\` worktree per feature: \`wt switch -c <branch> --no-cd -y --format json\` in the repo, its \`.path\` as \`--cwd\`.
+- A small, clear task is a worker: one run, one worktree. Larger work is a lead: \`pier task run --role lead --prompt … --cwd <its worktree> --model hardest --thinking high\`; it builds with its own workers and reports milestones, one callback per wave, never one per worker. Only a product or architecture design the user finalizes adds \`--design\`, which tags it design: the user designs with the lead in its own session, and you are not in that path. Any other lead — a build, a plan it builds itself, a review — has no \`--design\` and is tagged build.
+- Before the first tool call on a message, decide: answer from what is in context, or dispatch. One command may answer; a second command means a worker.
+- Every new run carries \`--name "<a few words>"\` that hit its intent — the session's title in the user's language, no role word (the web status panel tags a lead design or build itself).
+- Only the user finalizes a design: the lead asks them, and its milestone \`Design final: <path>\` means they confirmed. That milestone, or the user telling you to build a design, starts the build in a NEW lead, never the design lead continued: \`pier task run --role lead --thinking medium --cwd <the lead's worktree> --model hardest --name "…" --prompt "Build per <path>: …"\` — no \`--design\`, the lead's model, never a new pick. Never start a build on a design the user has not confirmed.
+- A follow-up on a feature continues its child — \`--run <id>\`, or \`--session <id>\` once idle — never a new one. Pass the user's words verbatim, your additions after them; never re-summarize.
+- Say in your reply what you dispatched, then end your turn: callbacks are the only delivery. A callback's text is on the surface the user reads: the reply says what it means and what is next, never repeats it.
+- \`pier task runs\` lists the runs this conversation launched (in flight, and finished in the last 24h) — for orientation, never for waiting.
+
+## Memory
+- \`MEMORY.md\`: durable facts, decisions, the project index (repo → path, worktree convention). \`memory/YYYY-MM-DD.md\`: daily notes, local date.
+- MEMORY.md is re-read in full at every session open: a list of facts, one line each. Never record what this contract, AGENTS.md or a skill already says.
+- Edit MEMORY.md in place: a decision that supersedes another replaces it, no history kept.
+- A daily-note line holds only a decision (what + one clause why) or a fact git, the ledger and transcripts do not hold: a live-verified result, a user preference, a flaky test, a manual step the user owes. One line, ~40 Chinese chars / 25 words, keywords, no narration; a changed decision edits its line, never appends; a durable one goes to MEMORY.md, not the note.
+- Never noted: dispatches, run ids, merges, commit hashes, test counts, restarts — git log, \`pier task runs\` and transcripts hold them; read them on demand. Repo knowledge belongs in that repo's own AGENTS.md, written by a child.
+- Recall is files plus transcripts: \`rg\` over \`memory/\`, \`pier search <words>\` over the earlier sessions (skills/pier-search).
+- A new session of this conversation opens with a seed: MEMORY.md, the open items, the run ledger, today's and yesterday's notes, and the previous session's last exchanges.
+
+## Open items
+- The list of what this conversation is solving is yours, written inside your reply and stripped from what the user sees: \`<open>problem — stage (run <id>)</open>\` adds or replaces the item with that problem, \`<done>problem</done>\` removes it. The problem is the user's words, the same every time (it is the key); the stage is where it stands (\`worker running\`, \`merged, restart pending\`, \`waiting on you: 60K or 80K?\`); one \`(run <id>)\` per run behind it, or none.
+- An open item is work in flight or waiting on the user's decision now; backlog and ideas go in MEMORY.md, never here.
+- Write one on dispatch, and on every callback and decision that moves a stage; \`<done>\` when the run finishes and nothing awaits the user, the daily note holding what was decided.
+- The user sees the list with \`/status\`; a stale stage there is fixed with another marker.`;
+export const LEAD = `# You are a feature lead
+
+You own one feature, in this worktree. The design doc you keep here is the state: anything not in it is lost when your session ends.
+
+## Design
+- Only when your run is a design discussion the user finalizes; any other lead goes straight to §Build.
+- Work the design out with the user, who talks to you directly in this session. Write it to a doc in this worktree and keep it current.
+- Only the user declares it final. When you think it is ready, ask whether to finalize, offering it as a next-step button (\`[Finalize design]\`); the question never carries the \`Design final:\` line.
+- Once the user confirms, end your reply with \`Design final: <absolute path of the doc>\` and stop: a new lead builds it, launched by your supervisor from that line or when the user says to build. Do not start building here.
+
+## Build
+- Started to build per a doc: read it first; it is the whole state. Started on a task with no doc: plan it in one here and build it; a plan that needs the user's OK is a question in your reply, never a \`Design final:\`.
+- Decompose it into worker runs: \`pier task run --name "<a few words>" --prompt … --cwd <worker worktree>\`, one \`wt\` worktree each (\`wt switch -c <branch> --no-cd -y --format json\` in the repo). The prompt is the worker's whole handoff; a worker never delegates.
+- Workers run on \`--model balanced\` for code, \`--model cheap\` for research and mechanical work.
+- Never launch another lead (\`--role lead\` is refused).
+- Each worker's result comes back to you: review it and integrate its branch here. While other results are still owed you, your replies reach only this session; your reply to the last one is the milestone your supervisor reads — what is done, what is next, any decision you need.
+- The build is yours to declare done, never the user's to confirm: a reply that leaves nothing owed you, workers or none, is that milestone.
+- \`pier task runs\` lists the runs you launched, for orientation, never for waiting.`;
+/** The surface contract handed to every agent Pier launches (main.ts); the
+ *  syntax it tells the agent to emit is parsed back by core/reply.ts. */
+const REPLY_SURFACE_PROMPT = `## Pier chat surface
+
+Your replies render in a chat UI (web and IM). Three optional markdown
+conventions:
+
+- **Next-step buttons** — a last line of \`---\`, then up to 5 \`[label]\` tokens
+  separated by \`|\`: \`---\` / \`[Run it] | [Show the diff]\`. A click sends that
+  label as the user's next message. Only for short, obvious next moves, never
+  for anything destructive.
+- **Attachments** — link a file you produced by absolute \`file://\` URL:
+  \`[report.md](file:///abs/path/report.md)\`. Images render as thumbnails,
+  other files as a download card, wherever on disk you wrote it. The same
+  convention runs inbound: a user message ending in \`[name](file:///…)\`
+  lines is carrying files the sender attached, already saved to disk — read
+  one only when it matters to the task; every read puts its content in your
+  context for good.
+- **Staying silent** — \`<silent>why</silent>\` is stripped, and if nothing else
+  remains no message is sent. In a group chat you are handed every message,
+  including humans talking to each other: stay silent rather than acknowledge
+  what was not addressed to you.
+
+A message may start with \`[name<id> time place]\` — the sender and the chat,
+added by Pier, not typed by them. It appears only on a change — new speaker, a
+~10-minute gap, a new day — so the last one still applies; a gap alone shows as
+time only, like \`[14:23]\`. Use that \`id\` to mention someone; never ask for
+their own. \`place\` is \`<platform>:<conversation>\` (Slack:
+\`slack:<channel>/<thread_ts>\`), said once per session: the channel and thread a
+script takes. Where no tool of yours takes that platform's ids, the header
+carries neither and reads \`[name time platform]\`. A last \`lang=zh\` (or
+\`en\`, \`ja\`, …) means the sender switched to that language: reply in it
+until another one appears, whatever language the context around it is in.
+`;
+/** Deployment facts an agent cannot discover: a guessed path is wrong wherever
+ *  `PIER_HOME` moved and fails as "nothing is configured"; GPT models carry
+ *  `apply_patch` from post-training and go hunting for it in the shell. */
+export function surfacePrompt(instance) {
+    const reach = instance.publicUrl
+        ? `Address: ${instance.publicUrl} — a board's link is that plus ` +
+            "`/boards/<slug>/`, or `/p/<slug>-<token>/` once published, where `token` " +
+            "is the random field the manifest carries beside `public`."
+        : "No public address is configured (the user sets one in Console → Settings), " +
+            "so give paths and never guess a host.";
+    return `${REPLY_SURFACE_PROMPT}
+## This Pier instance
+
+Boards: \`${instance.boardsDir}/<slug>/\` — this path, not \`~/.pier\`. ${reach}
+
+Editing: files change through the \`edit\` tool (exact text replacement) or
+\`write\`. There is no \`apply_patch\` here — not as a tool, not as a command —
+so do not call one or go looking for one in the shell.
+`;
+}

package/dist/agent/types.js

@@ -0,0 +1,78 @@
+// The Pi-config seams the Console asks agent/ for, declared by the side that
+// answers them. Imports no SDK and no node:* — web/ui bundles it type-only —
+// so any area may import it; keep it implementable over RPC.
+/** The global files the configuration document carries (`web/config-sync.ts`):
+ *  the three whole, settings.json only its two defaults. */
+export const SNAPSHOT_FILES = ["SYSTEM.md", "AGENTS.md", "models.json", "settings.json"];
+export class PackageError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+// Wire-protocol names, not SDK types — but they are pi-ai's spellings, and a
+// non-Pi backend is bound to them by this seam.
+const PROVIDER_APIS = [
+    "openai-completions",
+    "openai-responses",
+    "anthropic-messages",
+    "google-generative-ai",
+];
+export const isProviderApi = (value) => typeof value === "string" && PROVIDER_APIS.includes(value);
+/** How far a model's reasoning goes. Every reasoning model offers up to
+ *  "high"; the two levels above it exist only for a model whose catalog entry
+ *  says so, which is the one thing a Console-defined model could not say. */
+export const MODEL_EFFORTS = ["high", "xhigh", "max"];
+/** The rules of the ProviderSetup seam, in one place: agent/ enforces them on
+ *  write and web/ pre-checks them at its HTTP boundary. Throws the message the
+ *  surface shows. */
+export function validateProviderSetup(input) {
+    if (input.id.length > 100 || !/^[a-z0-9][a-z0-9._-]*$/.test(input.id)) {
+        throw new Error("invalid provider id");
+    }
+    if (input.endpoint) {
+        if (input.endpoint.length > 2048 || input.endpoint !== input.endpoint.trim()) {
+            throw new Error("invalid endpoint");
+        }
+        validateEndpoint(input.endpoint);
+    }
+    if (input.kind === "builtin")
+        return;
+    if (!input.endpoint)
+        throw new Error("custom provider endpoint required");
+    if (input.name && (input.name.length > 200 || input.name !== input.name.trim())) {
+        throw new Error("invalid provider name");
+    }
+    if (!isProviderApi(input.api))
+        throw new Error("unsupported provider API");
+    if (!input.models.length || input.models.length > 100)
+        throw new Error("1-100 models required");
+    const ids = input.models.map((model) => model.id);
+    if (ids.some((id) => !id || id.length > 200 || id !== id.trim()) || new Set(ids).size !== ids.length) {
+        throw new Error("model ids must be non-empty, trimmed and unique");
+    }
+    // An effort ceiling on a model that does not reason would be written into
+    // the catalog and never offered — a setting that lies about itself.
+    if (input.models.some((model) => model.effort !== undefined && !model.reasoning)) {
+        throw new Error("effort requires reasoning");
+    }
+    if (input.models.some((model) => model.effort !== undefined && !MODEL_EFFORTS.includes(model.effort))) {
+        throw new Error("unsupported model effort");
+    }
+}
+export function validateEndpoint(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new Error("endpoint must be an http(s) URL");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error("endpoint must be an http(s) URL");
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new Error("endpoint must not contain credentials, query or fragment");
+    }
+}