@pentoshi/clai 4.19.0 → 5.1.0

package/dist/prompts/system.agent.md

@@ -53,7 +53,7 @@ These are defaults for a strong professional. Adapt when evidence demands it; sa
 - **Plan tasks** = roadmap inside a durable plan the user accepts — not "start coding now".
 - When an ACTIVE PLAN exists, follow its task states: `in_progress` → work → **read/analyze results** → `done` only when that outcome holds → open next. Never mark done because a command was fired. You are advised to work through every task, but the plan is not a hard gate: you may stop with tasks unfinished when genuinely blocked, when the user tells you to stop, or when the situation requires it — report the remaining tasks honestly instead of forcing completion. Use plan.clear to discard a plan that should no longer run.
 
-**Parallelism:** Parallelize independent reads. Choose synchronous chat execution, a normal background job, or a Responder job from the task's actual latency, interactivity, dependencies, and need for concurrent work. Commands are never automatically backgrounded: shell.exec stays foreground unless you explicitly choose background:"always" or responder:true; background:"never" takes precedence, and legacy background:"auto" behaves like omission. You choose foreground timeoutMs in milliseconds (1000–1800000; default 60000). timeoutMs is ignored for background and Responder jobs, which have no execution deadline. No command-name heuristic changes execution mode, timeout units, budgets, or ownership. Responder delegation is opt-in, never the default for costly work. Finite foreground work gets sufficient timeout and returns its result in one call. **Images:** vision/OCR/scratch path before asking re-save. Adapt defaults when evidence demands.
+**Parallelism:** Parallelize independent reads. Choose synchronous chat execution, a normal background job, or a Responder job from the task's actual latency, interactivity, dependencies, and need for concurrent work. Commands are never automatically backgrounded: shell.exec stays foreground unless you explicitly choose background:"always" or responder:true; background:"never" takes precedence, and legacy background:"auto" behaves like omission. You choose foreground timeoutMs in milliseconds (1000–1800000; default 60000). timeoutMs is ignored for background and Responder jobs, which have no execution deadline. No command-name heuristic changes execution mode, timeout units, budgets, or ownership. Always delegate finite work expected to exceed 4–5 minutes to Responder with shell.exec responder:true, including long test suites, builds, scans, and CI watches. Use foreground for shorter finite work, with sufficient timeout. Interactive sessions use terminal tools; persistent servers/watchers use named background:"always" jobs, never Responder. **Images:** vision/OCR/scratch path before asking re-save. Adapt defaults when evidence demands.
 
 **Minimize information load:** Decide the proof before each command; use quiet flags/pipes so output is that signal. Finite chatty work → shell.exec with selective output/artifacts; persistent work → background shell.exec + selective tail. Avoid duplicate noisy dumps; context is expensive, artifacts are cheap.
 
@@ -90,7 +90,7 @@ Default foreground `timeoutMs` is 60000ms (60s). You decide the budget in millis
 
 # TOOLS (use these EXACT argument names)
 
-- shell.exec: {"command":"<cmd>","cwd":"<optional>","timeoutMs":<optional ms>,"background":"<auto|never|always>","name":"<optional job label>","responder":<optional bool>} — foreground by default for every command; no automatic backgrounding. You choose the foreground millisecond deadline (default 60000); timeoutMs is ignored for background and Responder execution. Choose enough time before launching finite work to receive its output in one call. Persistent servers/watchers/listeners: explicitly choose background:"always" plus a name; launch confirms only that the OS started it, so shell.tail and probe readiness, and check shell.jobs before starting another copy. For normal pollable finite jobs, use background:"always" and shell.wait; for independent finite fire-and-continue work, use responder:true and analyze terminal delivery with job.read instead of polling. background:"never" forces foreground even with responder:true; auto is a compatibility alias for omission. Prefer cwd over `cd`; Unix uses POSIX `/bin/sh`, so use portable syntax (explicit `bash -lc` only when required). Cost or command names never override your execution choice.
+- shell.exec: {"command":"<cmd>","cwd":"<optional>","timeoutMs":<optional ms>,"background":"<auto|never|always>","name":"<optional job label>","responder":<optional bool>} — foreground by default for every command; no automatic backgrounding. You choose the foreground millisecond deadline (default 60000); timeoutMs is ignored for background and Responder execution. Choose enough time before launching finite work to receive its output in one call. Persistent servers/watchers/listeners: explicitly choose background:"always" plus a name; launch confirms only that the OS started it, so shell.tail and probe readiness, and check shell.jobs before starting another copy. For normal pollable finite jobs, use background:"always" and shell.wait; for finite work expected to exceed 4–5 minutes, always use responder:true and analyze terminal delivery with job.read instead of polling. background:"never" forces foreground even with responder:true; auto is a compatibility alias for omission. Prefer cwd over `cd`; Unix uses POSIX `/bin/sh`, so use portable syntax (explicit `bash -lc` only when required). Cost or command names never override your execution choice.
 - shell.jobs: {} / shell.tail: {"id":"<job-id>","bytes":<optional>,"offset":<optional byte offset>,"stream":"<stdout|stderr|combined>"} / shell.stop: {"id":"<job-id>"} — tail defaults to stdout; for incremental polling reuse the prior nextOffset as offset on the SAME stream (stdout or stderr). combined is snapshot-only and rejects offset.
 - terminal.start: {"command":"<interactive command>","cwd":"<optional>","terminalMode":"<required|preferred|pipe>","columns":<optional>,"rows":<optional>,"idleTimeoutMs":<optional>,"lifetimeTimeoutMs":<optional>,"deadlineMs":<optional>} — persistent writable REPL/console for SSH, Python, debuggers, database shells, Metasploit, Meterpreter, and similar prompt-driven programs. preferred uses a PTY or explicitly reports pipe degradation; required refuses fallback (choose this for SSH passwords/readline consoles); pipe is only for stdin-driven programs that do not need a TTY. Dimensions are 2–1000 (defaults 80×24). Startup deadlineMs is 100–120000 (default 10000), NOT session lifetime. idleTimeoutMs is an optional 1000–86400000 inactivity cap; lifetimeTimeoutMs is an optional 1000–604800000 absolute cap; both are unset by default. Do not impose a short idle cap while the user enters a password. Start returns an initial page after waiting up to 1000ms for output; if no prompt is visible, read from nextCursor.
 - terminal.send: {"id":"<session id>","kind":"<text|secret|control|eof>","text":"<text only when kind=text>","secretPrompt":"<optional non-secret local prompt label>","secretSource":"<auto|user|prompt>","submit":"<enter|none>","control":"<interrupt|eof|suspend|escape|tab|backspace|up|down|left|right>","cursor":<optional>,"quietMs":<optional>,"deadlineMs":<optional>,"view":"<plain|encoded>"} — send exactly one ordered action. secretSource defaults to auto: reuse one clearly labeled user-provided password from the current request, earlier user messages or carried credentials; otherwise open masked input. user requires an unambiguous supplied password without prompting; prompt forces masked entry. NEVER put a password in text, command, secretPrompt, an environment variable or a fallback script. submit defaults to enter (adds Enter itself); none types without submitting. quietMs is 25–5000 (default 250); deadlineMs is 100–120000 (default 30000). Quiet means output paused, NOT command finished. After delivery=delivered/unknown or a delivered action's deadline, never resend; continue from page.nextCursor with terminal.read.
@@ -100,7 +100,7 @@ Default foreground `timeoutMs` is 60000ms (60s). You decide the budget in millis
 - Optional multi-file read: fs.read {"files":[{"path":"src/app.ts","offset":1,"limit":80},{"path":"src/config.ts","pattern":"export","context":2}]} for 1–10 necessary known files. Put each file’s filters directly inside its entry; omit top-level path/options. Single-file reads remain appropriate. Do not add irrelevant files to fill the limit. Results are ordered and labeled; inspect each file’s status and continuation independently. Use shell searches first when paths are unknown.
 - fs.write: {"path":"<file>","content":"<data>"} — new/full rewrite. Existing file → prefer fs.edit/replaceLines; for a full rewrite preserve all required lines and inspect the diff. Parent dirs auto-created; trust bytes/hash, don't re-read solely to verify.
 - fs.writeMany: {"files":[{"path":"<file>","content":"<data>"}, ...]} — up to 50 complete files; prefer for scaffolds.
-- fs.edit: {"path":"<file>","oldText":"<exact>","newText":"<replacement>","expectedReplacements":<optional>} — surgical edits on existing files.
+- fs.edit: {"path":"<file>","oldText":"<exact non-empty match>","newText":"<replacement>","expectedReplacements":<optional>} — surgical edits on existing files. Copy oldText from current file evidence; never pass "". newText is required; "" deletes the match. Create files with fs.write; insert at start/end with fs.append, or retain an existing anchor in oldText/newText for insertion within a file.
 - fs.replaceLines: {"path":"<file>","startLine":<1-indexed>,"endLine":<inclusive>,"content":"<replacement>"} — line-range replace; empty/delete:true deletes. Re-read first; prefer fs.edit when exact text anchors better.
 - fs.append: {"path":"<file>","content":"<data>","position":"<optional>","expectedPriorBytes":<optional>} — builds a long file in ordered chunks. Send the complete literal chunk, wait for its receipt, then use after_bytes as the next expectedPriorBytes or omit it.
 - FILE WRITE POLICY: New → complete fs.write; existing → fs.edit/replaceLines unless full rewrite is clearer. Too large for one call → fs.write the first substantial part, then fs.append substantial remaining chunks in order. Never copy omitted legacy payload metadata into a new call. Check diffs for duplicates/missing imports. Never invent written content.
@@ -136,10 +136,11 @@ User messages are sent exactly as written. If a message includes an explicit loc
 # OPERATING RULES
 
 - DO THE TASK. Pick the best tool and run it. Do not wait for the user to name a tool.
-- MATCH THE DELIVERABLE. Research/explain/compare → answer in chat (tables for comparisons). Do NOT scaffold a project or plan.create for pure Q&A. Do NOT write into the user project to "save" an answer unless asked. Scratch only under {{scratch}} (this session's unique folder under system temp {{tempRoot}} — macOS /var/folders, Linux /tmp, Windows %TEMP%). Keep ALL temporary/engagement files there (findings, notes, captures). Tool run outputs land in {{scratch}}/temp automatically — never scatter in the temp root, never write into the current/project directory for scratch.
+- MATCH THE DELIVERABLE. Research/explain/compare → answer in chat (tables for comparisons). Do NOT scaffold a project or plan.create for pure Q&A. Do NOT write into the user project to "save" an answer unless asked.
+- FILE PLACEMENT. Deliverables (projects, source, scripts, reports, docs) go to the user's location, else cwd if it is the task folder (empty, or the project the task concerns), else a new named folder under it; state the path. New work never adopts an existing same/similarly-named folder or file: pick a free name (e.g. watch-website-2) unless the user points at it or cwd is inside it. Scratch only under {{scratch}} (tool outputs in {{scratch}}/temp), only for disposable probes, captures and notes — never deliverables, never the temp root or a project.
 - NEW APPS / BUILDS: prefer latest stable packages and current framework setups (e.g. current React/Vite/Next/Tailwind majors). If you are unsure about today's scaffold/config, web.search or web.fetch official docs before inventing outdated steps.
 - STAY ON TARGET. Narrow tools for narrow questions. One focused recon command beats a bundled sweep; broaden only when the engagement needs it.
-- EXISTING PROJECTS: preserve installed dependency versions and conventions. Consult authoritative documentation for the installed version when behavior is uncertain; do not upgrade unrelated dependencies as part of a fix.
+- EXISTING PROJECTS: preserve installed dependency versions and conventions; consult docs for the installed version when unsure; do not upgrade unrelated dependencies.
 - HIGH-SIGNAL COMMANDS: apply minimize-information-load above on **every** domain (builds, tests, git, docker, scans, installs — not only fuzzers). Prefer quiet flags, status filters, structured output + jq, failure-only test output. Scanners (ffuf/gobuster/feroxbuster/…): filter at the command (`-mc`/`-fc`/`-fs`) and ALWAYS emit machine output (`-o out.json -of json`) so hits carry status + size. Never use blanket `ffuf -mc all`; retain its useful default matcher or specify purposeful statuses, then calibrate `-fc`/`-fs` from a nonexistent-path baseline. Do NOT pass `ffuf -s` (silent mode hides the Status/Size columns, leaving bare paths you cannot triage — you will not know what actually exists). To inspect a finished job, read the JSON artifact (or tail stdout, whose hit lines keep `[Status: N, Size: N]`) — keep every real status (2xx/3xx/4xx/5xx) with its size, drop only `:: Progress:`/spinner/`[2K` noise — never fs.read the whole scanner log. Use evidence → check missing executables if needed → purposeful run. When a card/artifact already has content, use it — never claim empty tools or re-fire solely because context is head+tail capped. Filter noise, not truth: large files → shell searches / fs.read pattern or offset windows; if a footer says hasMore/auto-head, page next — do not invent unread lines.
 - VERIFY BEFORE CLAIMING. Coding: (1) stack checks that apply — typecheck, build, unit/integration tests — fix failures first; (2) then live/runtime proof when a server or UI applies (background shell.exec + tail + localhost probe). Report only what those checks showed. Remote pentest: evidence from tools against the remote target — NEVER start a local dev server to "finish" a website assessment; NEVER treat the clai workspace as the target.
 - Don't run two equivalent scanners just to pad steps; do escalate when coverage is incomplete.
@@ -189,16 +190,16 @@ Give every child a lean, task-specific brief: target goal and deliverable, relev
 - Start slow work early when its expected value and independence justify parallel execution; otherwise use the smallest direct action that can answer the current question.
 - **TWO KINDS OF JOB.** (1) *Normal/pollable* — explicitly choose `background:"always"` without `responder:true`; YOU own them. For finite jobs, call shell.wait with a sufficient wait budget instead of polling in a loop. For persistent servers/watchers, use shell.tail plus a readiness probe, then shell.stop when cleanup is required. (2) *Responder/fire-and-continue* — finite work explicitly launched with `responder:true`. Never delegate a server/watcher because it does not self-complete. Select either mode only when it fits the task; all work otherwise stays synchronous. Trust the returned receipt's responder ownership and its single follow-up policy.
 - **RESPONDER = FIRE-AND-CONTINUE.** After launching one, move on instead of sleeping, polling, tailing, or reading its log to watch progress. A launch is not a completion guarantee: the user can cancel it, so say the result will be delivered only if the job reaches a terminal receipt and never promise automatic completion. Each terminal receipt is injected at the next safe model boundary. Analyze it once, gather only bounded evidence still needed, then call job.read by job or notification id before giving a final response. job.read requires no plan and atomically records delivered + read; never create or update a plan merely to consume a receipt. If an active plan exists, add only evidence-driven follow-ups and let its Responder child settle automatically from the same receipt. If only report creation remains while Responder work is running or unread, leave it open and stop; completion resumes the session. Never sleep/poll/tail-loop.
-- Never launch a duplicate while a matching job is active. On a Responder completion, inspect only filtered result lines or a bounded shell.tail window, then job.read when satisfied. Add follow-up tasks only when an active plan exists and the result requires more work. Finite installs/scaffolds/builds/tests stay foreground in shell.exec with sufficient timeoutMs unless independent work justifies explicit backgrounding; if a finite job receipt says `responder:false`/omits responder, use shell.wait to terminal status instead of re-running or repeatedly polling.
+- Never launch a duplicate while a matching job is active. On a Responder completion, inspect only filtered result lines or a bounded shell.tail window, then job.read when satisfied. Add follow-up tasks only when an active plan exists and the result requires more work. Always delegate finite work expected to exceed 4–5 minutes with shell.exec responder:true, even without independent work remaining; shorter installs/scaffolds/builds/tests may stay foreground with sufficient timeoutMs; if a finite job receipt says `responder:false`/omits responder, use shell.wait to terminal status instead of re-running or repeatedly polling.
 - Localhost: curl via shell.exec or http.fetch to localhost/127.0.0.1 (GET/HEAD auto-owned) — never web.fetch for loopback/private.
 - Long installs/scaffolds may be quiet for minutes: keep the foreground call and wait; do not abandon, duplicate, or re-scaffold.
 - Double Esc cancels the live turn, queued prompts, and all session-owned Responder jobs; single Esc only dismisses/arms cancellation.
 
 # BUILDING SOFTWARE
 
-- Work in {{cwd}} unless the user named another destination. Resolve absolute destinations with a leading `/` — never turn `/Users/…/Desktop` into relative `Users/…` under cwd. Never write user app source into the agent package tree.
-- Establish the relevant project root and stack from existing context or targeted inspection. If either is uncertain, inspect only what resolves that uncertainty; do not list directories or repeat discovery when the location and manifests are already known. Match the lockfile's package manager (package-lock → npm, pnpm-lock → pnpm, yarn.lock → yarn, bun.lockb → bun). Empty path → pick a sensible modern default and say which.
-- Prefer official non-interactive scaffolders into a NEW EMPTY subfolder. The scaffold **destination** is that subfolder (e.g. Desktop/blogging-app), not the parent Desktop. Scaffolders refuse non-empty dirs ("Operation cancelled") — that is FAILURE, not success. Existing project → CONTINUE (implement feature); never re-scaffold. Do not scaffold into a hidden temp tree and merge/delete it with shell loops; preserve existing config and use fs tools or hand-write the known tree. If scaffolding fails, hand-write a minimal correct tree and install deps.
+- Place work per FILE PLACEMENT. Resolve absolute destinations with a leading `/` — never turn `/Users/…/Desktop` into relative `Users/…` under cwd. Never write user app source into the agent package tree.
+- Establish project root and stack from existing context; if uncertain, inspect only what resolves it — no repeated discovery once location and manifests are known. Match the lockfile's package manager (package-lock → npm, pnpm-lock → pnpm, yarn.lock → yarn, bun.lockb → bun). Empty path → pick a sensible modern default and say which.
+- Prefer official non-interactive scaffolders into a NEW EMPTY subfolder. The scaffold **destination** is that subfolder (e.g. Desktop/blogging-app), not the parent Desktop. Scaffolders refuse non-empty dirs ("Operation cancelled") — that is FAILURE, not success. Existing target project → CONTINUE (implement feature); never re-scaffold. Do not scaffold into a hidden temp tree and merge/delete it with shell loops; preserve existing config and use fs tools or hand-write the known tree. If scaffolding fails, hand-write a minimal correct tree and install deps.
 - **THE DELIVERABLE IS THE WORKING FEATURE, not the scaffold.** Replace starter boilerplate (default Vite/Next/CRA pages, "Welcome to…") with what the user asked for. Leaving the default starter is a failure even if it builds.
 - Synthesize explicit and implicit acceptance criteria and invariants from the ask (e.g. todo → add/list/toggle/delete ± persist; plus empty/duplicate/error states and data surviving reload). Implement until those hold, not until a checkbox feels done.
 - Before editing existing code, inspect the contracts it touches — types, function signatures, callers, schemas, config, API/response shapes — and trace the data flow through them, so a change satisfies every caller and preserves invariants instead of breaking a hidden one.

package/dist/rea/availability.d.ts

@@ -0,0 +1,22 @@
+export interface ReaEngine {
+    readonly id: string;
+    readonly name: string;
+    readonly ready: boolean;
+    readonly code: string | undefined;
+    readonly reason: string | undefined;
+    readonly failed: readonly string[];
+    readonly java: string | undefined;
+}
+export interface ReaBlockedGroup {
+    readonly tools: readonly string[];
+    readonly remediation: string;
+}
+export interface ReaAvailability {
+    readonly engines: readonly ReaEngine[];
+    readonly open: ReadonlySet<string>;
+    readonly deep: ReadonlySet<string>;
+    readonly blocked: ReadonlySet<string>;
+    readonly blockedGroups: readonly ReaBlockedGroup[];
+}
+export declare function parseReaAvailability(text: string): ReaAvailability | undefined;
+export declare function readyEngines(availability: ReaAvailability | undefined): readonly ReaEngine[];

package/dist/rea/availability.js

@@ -0,0 +1,82 @@
+const DEEP_SURFACES = new Set(["official-proxy", "enhanced"]);
+const BLOCKED_REASONS = new Set(["provider_missing", "provider_unavailable"]);
+const MAX_REASON_CHARS = 160;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function strings(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+function compact(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const text = value.replace(/\s+/g, " ").trim();
+    if (!text)
+        return undefined;
+    return text.length > MAX_REASON_CHARS ? `${text.slice(0, MAX_REASON_CHARS - 1)}…` : text;
+}
+function engine(candidate) {
+    if (!isRecord(candidate) || !isRecord(candidate.provider))
+        return undefined;
+    const { id, name } = candidate.provider;
+    if (typeof id !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(id))
+        return undefined;
+    const availability = isRecord(candidate.availability) ? candidate.availability : {};
+    const diagnostics = isRecord(availability.diagnostics) ? availability.diagnostics : {};
+    const checks = Array.isArray(diagnostics.checks) ? diagnostics.checks.filter(isRecord) : [];
+    const java = diagnostics.java_version;
+    return {
+        id,
+        name: typeof name === "string" && name.length <= 64 ? name : id,
+        ready: availability.status === "available",
+        code: typeof availability.code === "string" ? availability.code : undefined,
+        reason: compact(availability.reason),
+        failed: checks.filter((check) => check.ok === false && typeof check.name === "string").map((check) => String(check.name)).slice(0, 12),
+        java: typeof java === "string" && /^[0-9A-Za-z._+-]{1,24}$/.test(java) ? java : undefined,
+    };
+}
+export function parseReaAvailability(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const session = isRecord(parsed) && isRecord(parsed.result) ? parsed.result : parsed;
+    if (!isRecord(session) || !Array.isArray(session.analysis_provider_candidates))
+        return undefined;
+    const engines = session.analysis_provider_candidates.flatMap((candidate) => engine(candidate) ?? []);
+    const groups = isRecord(session.tool_availability) && Array.isArray(session.tool_availability.groups)
+        ? session.tool_availability.groups.filter(isRecord)
+        : [];
+    const open = new Set();
+    const deep = new Set();
+    const blocked = new Set();
+    const blockedGroups = [];
+    for (const group of groups) {
+        const names = strings(group.names);
+        if (typeof group.surface === "string" && DEEP_SURFACES.has(group.surface)) {
+            for (const name of names)
+                deep.add(name);
+        }
+        if (group.available === true)
+            continue;
+        if (group.reason === "target_required") {
+            for (const name of names)
+                open.add(name);
+        }
+        else if (typeof group.reason === "string" && BLOCKED_REASONS.has(group.reason)) {
+            for (const name of names)
+                blocked.add(name);
+            blockedGroups.push({ tools: names, remediation: compact(group.remediation) ?? "a prerequisite is missing" });
+        }
+    }
+    if (engines.length === 0 && open.size === 0 && deep.size === 0 && blocked.size === 0)
+        return undefined;
+    return { engines, open, deep, blocked, blockedGroups };
+}
+export function readyEngines(availability) {
+    return availability?.engines.filter((entry) => entry.ready) ?? [];
+}
+//# sourceMappingURL=availability.js.map

package/dist/rea/availability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"availability.js","sourceRoot":"","sources":["../../src/rea/availability.ts"],"names":[],"mappings":"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"}

package/dist/rea/connection.d.ts

@@ -0,0 +1,8 @@
+import type { McpRuntime } from "../mcp/runtime.js";
+import type { McpServerStatus, McpToolMetadata } from "../mcp/types.js";
+export interface ReaConnection {
+    readonly server: McpServerStatus | undefined;
+    readonly selected: boolean;
+}
+export declare function reaTools(runtime: Pick<McpRuntime, "getState">): McpToolMetadata[];
+export declare function reaConnection(runtime: Pick<McpRuntime, "getState">): ReaConnection;

package/dist/rea/connection.js

@@ -0,0 +1,12 @@
+import { REA_SERVER } from "./workflow.js";
+export function reaTools(runtime) {
+    return runtime.getState().snapshot.tools.filter((tool) => tool.serverName === REA_SERVER);
+}
+export function reaConnection(runtime) {
+    const { snapshot, selection } = runtime.getState();
+    const server = snapshot.statuses.find((entry) => entry.name === REA_SERVER);
+    const selected = server?.status === "ready" &&
+        (selection.mode === "all" || (selection.mode === "servers" && selection.serverNames.includes(REA_SERVER)));
+    return { server, selected };
+}
+//# sourceMappingURL=connection.js.map

package/dist/rea/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/rea/connection.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAO3C,MAAM,UAAU,QAAQ,CAAC,OAAqC;IAC5D,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,KAAK,UAAU,CAAC,CAAC;AAC5F,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAqC;IACjE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IACnD,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;IAC5E,MAAM,QAAQ,GAAG,MAAM,EAAE,MAAM,KAAK,OAAO;QACzC,CAAC,SAAS,CAAC,IAAI,KAAK,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,KAAK,SAAS,IAAI,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC7G,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC9B,CAAC"}

package/dist/rea/distribution.d.ts

@@ -0,0 +1,13 @@
+export interface NpmRelease {
+    readonly name: string;
+    readonly version: string;
+    readonly tarball: string;
+    readonly integrity: string;
+}
+export declare function officialUrl(value: string): URL;
+export declare function fetchBytes(url: string, limit: number, signal?: AbortSignal, onProgress?: (received: number, total?: number) => void): Promise<Buffer>;
+export declare function fetchJson(url: string, signal?: AbortSignal): Promise<unknown>;
+export declare function jsonObject(value: unknown): Record<string, unknown>;
+export declare function npmRelease(name: "rea-agents" | "npm", tag?: string, signal?: AbortSignal): Promise<NpmRelease>;
+export declare function verifyIntegrity(bytes: Buffer, integrity: string): void;
+export declare function extractPackage(bytes: Buffer, destination: string, archiveRoot: string): Promise<void>;

package/dist/rea/distribution.js

@@ -0,0 +1,140 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+const ORIGINS = new Set(["https://nodejs.org", "https://registry.npmjs.org"]);
+const VERSION = /^\d+\.\d+\.\d+$/;
+const STALL_TIMEOUT_MS = 60_000;
+const PROGRESS_STEP_BYTES = 256 * 1024;
+export function officialUrl(value) {
+    const url = new URL(value);
+    if (!ORIGINS.has(url.origin) || url.username || url.password) {
+        throw new Error(`Refusing unofficial download origin: ${url.origin}`);
+    }
+    return url;
+}
+export async function fetchBytes(url, limit, signal, onProgress) {
+    const stall = new AbortController();
+    let timer;
+    const watch = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => stall.abort(new Error(`Download stalled: no data for ${STALL_TIMEOUT_MS / 1000}s (${url})`)), STALL_TIMEOUT_MS);
+    };
+    watch();
+    try {
+        const response = await fetch(officialUrl(url), {
+            redirect: "error",
+            signal: signal ? AbortSignal.any([signal, stall.signal]) : stall.signal,
+            headers: { "User-Agent": "clai-rea-installer" },
+        });
+        if (!response.ok)
+            throw new Error(`Download failed: HTTP ${response.status} (${url})`);
+        const encoding = response.headers.get("content-encoding")?.toLowerCase();
+        const declared = Number(response.headers.get("content-length"));
+        const length = encoding && encoding !== "identity" ? 0 : declared;
+        if (declared > limit) {
+            await response.body?.cancel();
+            throw new Error(`Download exceeds ${limit} bytes`);
+        }
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw new Error(`Empty download: ${url}`);
+        const exact = length > 0 ? Buffer.allocUnsafe(length) : undefined;
+        const chunks = [];
+        let received = 0;
+        let reported = 0;
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                watch();
+                if (received + value.byteLength > limit)
+                    throw new Error(`Download exceeds ${limit} bytes`);
+                if (exact) {
+                    if (received + value.byteLength > exact.byteLength)
+                        throw new Error("Download exceeds its declared length");
+                    exact.set(value, received);
+                }
+                else
+                    chunks.push(value);
+                received += value.byteLength;
+                if (received - reported >= PROGRESS_STEP_BYTES) {
+                    reported = received;
+                    onProgress?.(received, length > 0 ? length : undefined);
+                }
+            }
+            if (received === 0 || (exact && received !== exact.byteLength))
+                throw new Error("Incomplete download");
+            onProgress?.(received, length > 0 ? length : undefined);
+            return exact ?? Buffer.concat(chunks, received);
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+            reader.releaseLock();
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function fetchJson(url, signal) {
+    return JSON.parse((await fetchBytes(url, 4 * 1024 * 1024, signal)).toString("utf8"));
+}
+export function jsonObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid release metadata");
+    return value;
+}
+export async function npmRelease(name, tag = "latest", signal) {
+    if (tag !== "latest" && !VERSION.test(tag))
+        throw new Error("Invalid package version");
+    const metadata = jsonObject(await fetchJson(`https://registry.npmjs.org/${name}/${tag}`, signal));
+    const dist = jsonObject(metadata.dist);
+    if (metadata.name !== name || typeof metadata.version !== "string" || !VERSION.test(metadata.version) ||
+        typeof dist.tarball !== "string" || typeof dist.integrity !== "string") {
+        throw new Error(`Invalid official ${name} release metadata`);
+    }
+    const url = officialUrl(dist.tarball);
+    if (url.origin !== "https://registry.npmjs.org" || !url.pathname.startsWith(`/${name}/-/`)) {
+        throw new Error(`Invalid official ${name} package URL`);
+    }
+    return { name, version: metadata.version, tarball: url.href, integrity: dist.integrity };
+}
+export function verifyIntegrity(bytes, integrity) {
+    const match = /^sha(256|512)-([A-Za-z0-9+/]+={0,2})$/.exec(integrity);
+    if (!match)
+        throw new Error("A SHA-256 or SHA-512 package checksum is required");
+    const actual = createHash(`sha${match[1]}`).update(bytes).digest();
+    const expected = Buffer.from(match[2], "base64");
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+        throw new Error("Downloaded package checksum mismatch");
+}
+export async function extractPackage(bytes, destination, archiveRoot) {
+    await mkdir(destination, { recursive: true, mode: 0o700 });
+    const { Unpack } = await import("tar");
+    let total = 0;
+    let entries = 0;
+    const unpack = new Unpack({
+        cwd: destination, strip: 1, strict: true,
+        preserveOwner: false, noMtime: true, maxDecompressionRatio: 200,
+        filter: (path, entry) => {
+            const parts = path.replace(/\\/g, "/").replace(/\/$/, "").split("/");
+            if (parts[0] !== archiveRoot || parts.some((part) => !part || part === ".." || part === "." || /[:\0]/.test(part))) {
+                unpack.abort(new Error("Unsafe path in downloaded archive"));
+                return false;
+            }
+            if (!("type" in entry) || (entry.type !== "File" && entry.type !== "Directory"))
+                return false;
+            total += entry.size;
+            entries += 1;
+            if (total > 512 * 1024 * 1024 || entries > 30_000) {
+                unpack.abort(new Error("Downloaded archive exceeds extraction limits"));
+                return false;
+            }
+            return true;
+        },
+    });
+    await pipeline(Readable.from([bytes]), unpack);
+}
+//# sourceMappingURL=distribution.js.map

package/dist/rea/distribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"distribution.js","sourceRoot":"","sources":["../../src/rea/distribution.ts"],"names":[],"mappings":"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"}

package/dist/rea/download.d.ts

@@ -0,0 +1,22 @@
+export type FetchFunction = (input: string, init?: RequestInit) => Promise<Response>;
+export interface RequestOptions {
+    readonly hosts: readonly string[];
+    readonly maxBytes: number;
+    readonly signal?: AbortSignal | undefined;
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+    readonly fetch?: FetchFunction | undefined;
+    readonly stallMs?: number | undefined;
+}
+export interface DownloadOptions extends RequestOptions {
+    readonly sha256?: string | undefined;
+    readonly bytes?: number | undefined;
+    readonly onProgress?: ((received: number, total?: number) => void) | undefined;
+}
+export interface DownloadResult {
+    readonly bytes: number;
+    readonly sha256: string;
+}
+export declare function allowedHost(url: URL, hosts: readonly string[]): boolean;
+export declare function fetchText(url: string, options: RequestOptions): Promise<string>;
+export declare function fetchJsonValue(url: string, options: RequestOptions): Promise<unknown>;
+export declare function downloadFile(url: string, destination: string, options: DownloadOptions): Promise<DownloadResult>;

package/dist/rea/download.js

@@ -0,0 +1,198 @@
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { rm } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { publish } from "./install.js";
+const MAX_REDIRECTS = 5;
+const STALL_TIMEOUT_MS = 60_000;
+const PROGRESS_STEP_BYTES = 1024 * 1024;
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+export function allowedHost(url, hosts) {
+    if (url.protocol !== "https:" || url.username || url.password || url.port)
+        return false;
+    return hosts.some((host) => host.startsWith("*.") ? url.hostname.endsWith(host.slice(1)) : url.hostname === host);
+}
+function checkedUrl(value, hosts) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`Refusing malformed download URL: ${value.slice(0, 80)}`);
+    }
+    if (!allowedHost(url, hosts))
+        throw new Error(`Refusing unofficial download origin: ${url.origin}`);
+    return url;
+}
+async function open(url, options, signal) {
+    const request = options.fetch ?? fetch;
+    let current = checkedUrl(url, options.hosts);
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
+        const response = await request(current.href, {
+            redirect: "manual",
+            signal,
+            headers: { "User-Agent": "clai-rea-installer", ...options.headers },
+        });
+        if (!REDIRECTS.has(response.status))
+            return response;
+        const location = response.headers.get("location");
+        await response.body?.cancel().catch(() => undefined);
+        if (!location)
+            throw new Error(`Download redirect without a location (${current.origin})`);
+        current = checkedUrl(new URL(location, current).href, options.hosts);
+    }
+    throw new Error(`Download redirected more than ${MAX_REDIRECTS} times`);
+}
+function stallGuard(options) {
+    const stall = new AbortController();
+    const limit = options.stallMs ?? STALL_TIMEOUT_MS;
+    let timer;
+    const touch = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => stall.abort(new Error(`Download stalled: no data for ${Math.round(limit / 1000)}s`)), limit);
+    };
+    touch();
+    return {
+        signal: options.signal ? AbortSignal.any([options.signal, stall.signal]) : stall.signal,
+        touch,
+        stop: () => clearTimeout(timer),
+    };
+}
+function cancelled(signal) {
+    return signal.reason instanceof Error ? signal.reason : new Error("Download cancelled");
+}
+async function* chunksOf(body, signal) {
+    const reader = body.getReader();
+    const onAbort = () => {
+        reader.cancel(cancelled(signal)).catch(() => undefined);
+    };
+    if (signal.aborted)
+        onAbort();
+    else
+        signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (signal.aborted)
+                throw cancelled(signal);
+            if (done)
+                return;
+            yield value;
+        }
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+        reader.cancel().catch(() => undefined);
+    }
+}
+function requestFailure(response, host) {
+    const base = `Request failed: HTTP ${response.status} (${host})`;
+    const remaining = response.headers.get("x-ratelimit-remaining");
+    const reset = Number(response.headers.get("x-ratelimit-reset"));
+    const retryAfter = Number(response.headers.get("retry-after"));
+    const limited = response.status === 429 || ((response.status === 403 || response.status === 503) && (remaining === "0" || retryAfter > 0));
+    if (!limited)
+        return base;
+    const seconds = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : Number.isFinite(reset) && reset > 0 ? Math.max(0, reset - Math.floor(Date.now() / 1000)) : undefined;
+    const minutes = seconds === undefined ? undefined : Math.max(1, Math.ceil(seconds / 60));
+    return `${base}: ${host} is rate limiting this network${minutes === undefined ? "" : `; try again in about ${minutes} minute${minutes === 1 ? "" : "s"}`}`;
+}
+export async function fetchText(url, options) {
+    const guard = stallGuard(options);
+    try {
+        const response = await open(url, options, guard.signal);
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new Error(requestFailure(response, new URL(url).hostname));
+        }
+        if (!response.body)
+            throw new Error("Empty response");
+        const chunks = [];
+        let received = 0;
+        for await (const chunk of chunksOf(response.body, guard.signal)) {
+            guard.touch();
+            received += chunk.byteLength;
+            if (received > options.maxBytes)
+                throw new Error(`Response exceeds ${options.maxBytes} bytes`);
+            chunks.push(chunk);
+        }
+        return Buffer.concat(chunks, received).toString("utf8");
+    }
+    finally {
+        guard.stop();
+    }
+}
+export async function fetchJsonValue(url, options) {
+    const text = await fetchText(url, options);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error("Release metadata is not valid JSON");
+    }
+}
+export async function downloadFile(url, destination, options) {
+    const expected = options.sha256?.toLowerCase();
+    if (expected !== undefined && !/^[0-9a-f]{64}$/.test(expected))
+        throw new Error("A SHA-256 checksum is required for downloads");
+    const guard = stallGuard(options);
+    const partial = `${destination}.part`;
+    try {
+        await rm(partial, { force: true });
+        const response = await open(url, options, guard.signal);
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new Error(`Download failed: HTTP ${response.status} (${new URL(url).hostname})`);
+        }
+        const encoding = response.headers.get("content-encoding")?.toLowerCase();
+        const declared = encoding && encoding !== "identity" ? 0 : Number(response.headers.get("content-length"));
+        const total = options.bytes ?? (Number.isFinite(declared) && declared > 0 ? declared : undefined);
+        const refuse = async (message) => {
+            await response.body?.cancel().catch(() => undefined);
+            throw new Error(message);
+        };
+        if ((total ?? 0) > options.maxBytes)
+            await refuse(`Download exceeds ${options.maxBytes} bytes`);
+        if (options.bytes !== undefined && declared > 0 && declared !== options.bytes) {
+            await refuse(`Download size ${declared} does not match the published size ${options.bytes}`);
+        }
+        if (!response.body)
+            throw new Error("Empty download");
+        const hash = createHash("sha256");
+        let received = 0;
+        let reported = 0;
+        async function* counted(body) {
+            for await (const chunk of chunksOf(body, guard.signal)) {
+                guard.touch();
+                received += chunk.byteLength;
+                if (received > options.maxBytes || (total !== undefined && received > total)) {
+                    throw new Error(`Download exceeds ${total ?? options.maxBytes} bytes`);
+                }
+                hash.update(chunk);
+                if (received - reported >= PROGRESS_STEP_BYTES) {
+                    reported = received;
+                    options.onProgress?.(received, total);
+                }
+                yield chunk;
+            }
+        }
+        await pipeline(Readable.from(counted(response.body)), createWriteStream(partial, { flags: "wx", mode: 0o600 }), { signal: guard.signal });
+        if (received === 0 || (total !== undefined && received !== total))
+            throw new Error("Incomplete download");
+        const digest = hash.digest("hex");
+        if (expected !== undefined && digest !== expected)
+            throw new Error("Downloaded file checksum mismatch");
+        options.onProgress?.(received, total);
+        await publish(partial, destination);
+        return { bytes: received, sha256: digest };
+    }
+    catch (error) {
+        await rm(partial, { force: true }).catch(() => undefined);
+        throw guard.signal.aborted && guard.signal.reason instanceof Error ? guard.signal.reason : error;
+    }
+    finally {
+        guard.stop();
+    }
+}
+//# sourceMappingURL=download.js.map