@hyperdrive.bot/paseo-server 0.3.10 → 0.3.12

package/dist/server/server/agent/session-digest-generator.d.ts

@@ -26,7 +26,33 @@ export interface SessionDigestRefreshOptions {
     };
     logger: Logger;
     deps?: SessionDigestGeneratorDeps;
+    /**
+     * Called once the derivation has finished, whether it produced a digest,
+     * skipped, or failed (JARVIS-V1-SPEC §4).
+     *
+     * This exists because the Jarvis judge and this refresh both listen to the
+     * SAME `finished` attention event. Run in parallel, the judge always wins the
+     * race and reads a digest that has not been written yet, so every briefing
+     * arrives with no summary, no blockers and no deadline, and the judge
+     * correctly answers "quiet" forever. That failure is silent: no error, no log,
+     * a feature that looks alive and delivers nothing. Chaining the judge off this
+     * callback is what makes the substrate actually reach it.
+     */
+    onSettled?: () => void;
+    /** Test seam. Defaults to DIGEST_GENERATION_TIMEOUT_MS. */
+    timeoutMs?: number;
 }
+/** Observability for a path whose failures are permanent (§3.1, hazard 2). */
+declare const digestCounters: {
+    attempted: number;
+    succeeded: number;
+    failed: number;
+    timedOut: number;
+    skippedUnchanged: number;
+};
+export declare function getSessionDigestCounters(): Readonly<typeof digestCounters>;
+/** Test seam: the maps are module-level, so tests need a way back to a clean slate. */
+export declare function resetSessionDigestStateForTests(): void;
 export declare function generateAndApplySessionDigest(options: SessionDigestRefreshOptions): Promise<void>;
 /**
  * Fire-and-forget, debounced digest refresh. Safe to call on every running→idle
@@ -34,4 +60,5 @@ export declare function generateAndApplySessionDigest(options: SessionDigestRefr
  * debounce window.
  */
 export declare function scheduleSessionDigestRefresh(options: SessionDigestRefreshOptions): void;
+export {};
 //# sourceMappingURL=session-digest-generator.d.ts.map

package/dist/server/server/agent/session-digest-generator.js

@@ -4,35 +4,200 @@ import { resolveStructuredGenerationProviders, } from "./structured-generation-p
 import { buildDigestSourceText, deriveKeyFilesFromTimeline, mergeDigest, } from "./session-digest.js";
 const SUMMARY_MAX_CHARS = 600;
 const ACCOMPLISHMENT_MAX = 10;
+const NEXT_STEP_MAX_CHARS = 240;
+const BLOCKER_MAX = 5;
 const DIGEST_SUMMARY_SCHEMA = z.object({
     summary: z.string().max(SUMMARY_MAX_CHARS),
     accomplishments: z.array(z.string()).max(ACCOMPLISHMENT_MAX),
+    // Jarvis substrate (JARVIS-V1-SPEC §3.1). These land in `derived*` digest keys,
+    // never in the self-reported `nextStep`/`blockers`.
+    // Nullish rather than required: partial substrate beats a whole generation
+    // failing schema validation and costing the summary too. Cheap insurance, and
+    // unlike a second generation call it costs no extra tokens.
+    nextStep: z.string().max(NEXT_STEP_MAX_CHARS).nullish(),
+    blockers: z.array(z.string()).max(BLOCKER_MAX).nullish(),
+    urgency: z.enum(["low", "normal", "high"]).nullish(),
+    deadline: z.string().nullish(),
 });
-// Debounce: `idle` fires on every pause for input, so cap LLM regeneration at
-// one pass per window per agent and never run two concurrently. keyFiles is
-// deterministic + cheap and refreshes on every call. See docs/session-digest.md §5.
-const DIGEST_DEBOUNCE_MS = 10 * 60 * 1000;
+/**
+ * Refresh gating (JARVIS-V1-SPEC §3.1, hazard 1).
+ *
+ * The ORIGINAL gate was a flat 10-minute wall-clock debounce, stamped BEFORE the
+ * work ran. Two consequences made it unsafe once the digest became a one-shot,
+ * unrecoverable derivation rather than a nice-to-have summary:
+ *
+ *   1. Back-to-back idles inside the window were silently dropped, and a dropped
+ *      derivation is not always recoverable (see the readability note below).
+ *   2. Stamping before the attempt meant a FAILED generation still burned the
+ *      window, so the next idle was skipped too. That is "record intent as fact":
+ *      the timestamp meant "we tried", not "we produced a digest".
+ *
+ * CORRECTION (measured 2026-07-31). An earlier version of this comment claimed
+ * the timeline is "destroyed shortly after a session goes cold". That is WRONG,
+ * and it was generalized from two probes at the extremes with nothing in between.
+ * What is actually true:
+ *
+ *   - paseo stores NO timeline of its own. Agent records on disk are ~4 KB of
+ *     pure metadata with no timeline key.
+ *   - `get_agent_activity` reads THROUGH to the provider's own transcript, for
+ *     Claude `~/.claude/projects/<slug>/<sid>.jsonl`. Readability is binary and
+ *     age-independent: a 19.6-day-old session returned 88 activities in full.
+ *   - Content is lost only when that provider file is pruned. For Claude that is
+ *     `cleanupPeriodDays`, default 30, which runs at CLI startup on file mtime.
+ *   - A second gate exists: the read fails outright when the agent's `cwd` no
+ *     longer exists ("Working directory does not exist"), which affects sessions
+ *     from removed worktrees or another machine regardless of file retention.
+ *
+ * So this derivation is NOT primarily insurance against a minutes-later loss.
+ * Its real value is (a) surviving the provider's prune window, (b) surviving the
+ * cwd gate, (c) normalizing across providers whose stores paseo cannot read, and
+ * (d) cost: a few hundred bytes of digest instead of re-reading a transcript that
+ * can exceed 40 MB. Still worth doing on every idle, for different reasons than
+ * originally written.
+ *
+ * The replacement gates on CONTENT and nothing else: skip only when the timeline
+ * has not grown since the last SUCCESSFUL digest. New content is new information
+ * and is always worth deriving.
+ *
+ * There is deliberately NO wall-clock floor. An earlier draft had one, and it
+ * reintroduced exactly the bug being fixed: two idles a minute apart, both with
+ * new content, and the second silently dropped. Any clock-based gate re-creates
+ * that, because "we ran recently" and "nothing new happened" are different
+ * questions and only the second is a safe reason to skip a one-shot derivation.
+ *
+ * Cost note: on a chatty session this derives roughly once per completed turn
+ * instead of once per 10 minutes. That is the intended trade. The spec classifies
+ * a lost derivation as a correctness bug and an extra derivation as a cost line.
+ * If cost needs tuning later, the knob must stay content-based (for example
+ * "only derive when the timeline grew by more than N rows"), never clock-based.
+ */
+/**
+ * Hard ceiling on one generation (found live 2026-07-31).
+ *
+ * `generateStructuredAgentResponseWithFallback` takes no signal and no timeout,
+ * and it CAN hang indefinitely: an internal generator agent spawned at 17:50:42
+ * and never settled, no success and no error, for the rest of the daemon's life.
+ *
+ * That is far worse than a slow digest. The hung promise never leaves `inFlight`,
+ * so the agent can never derive again, AND because the Jarvis judge is chained to
+ * `onSettled`, the judge goes permanently silent for that agent too. One stuck
+ * generation quietly removes a card from Jarvis forever, with nothing in the log.
+ *
+ * Racing a timeout turns that into an ordinary failure: counted, logged, mark not
+ * stamped so the next idle retries, and onSettled still fires so the judge runs
+ * with whatever substrate already exists. The abandoned work may keep running in
+ * the background; that is acceptable, recovering the caller is the point.
+ */
+const DIGEST_GENERATION_TIMEOUT_MS = 120000;
+class DigestGenerationTimeoutError extends Error {
+    constructor(ms) {
+        super(`Session digest generation exceeded ${ms}ms`);
+        this.name = "DigestGenerationTimeoutError";
+    }
+}
+function withTimeout(work, ms) {
+    let timer;
+    const bomb = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new DigestGenerationTimeoutError(ms)), ms);
+        // Never let this timer keep the daemon alive on shutdown.
+        timer.unref?.();
+    });
+    return Promise.race([work, bomb]).finally(() => {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    });
+}
 const lastDigestAt = new Map();
+/** agentId -> `${epoch}:${maxSeq}` of the last SUCCESSFUL digest. */
+const lastDigestMark = new Map();
 const inFlight = new Set();
-function buildDigestPrompt(sourceText) {
+/** Observability for a path whose failures are permanent (§3.1, hazard 2). */
+const digestCounters = { attempted: 0, succeeded: 0, failed: 0, timedOut: 0, skippedUnchanged: 0 };
+export function getSessionDigestCounters() {
+    return { ...digestCounters };
+}
+/** Test seam: the maps are module-level, so tests need a way back to a clean slate. */
+export function resetSessionDigestStateForTests() {
+    lastDigestAt.clear();
+    lastDigestMark.clear();
+    inFlight.clear();
+    digestCounters.attempted = 0;
+    digestCounters.succeeded = 0;
+    digestCounters.failed = 0;
+    digestCounters.timedOut = 0;
+    digestCounters.skippedUnchanged = 0;
+}
+function buildDigestPrompt(sourceText, todayIso) {
     return [
         "You are summarizing a coding agent session so an orchestrator can understand it",
-        "without reading the full transcript. Return JSON with exactly two fields:",
+        "without reading the full transcript. Return JSON with exactly these fields:",
         `- summary: one paragraph (<= ${SUMMARY_MAX_CHARS} chars) describing what this session`,
         "  is doing and its current state.",
         `- accomplishments: up to ${ACCOMPLISHMENT_MAX} short strings, each a concrete thing done`,
         "  (file changed, feature added, bug fixed). Be specific and factual; do not invent.",
+        `- nextStep: <= ${NEXT_STEP_MAX_CHARS} chars, the single concrete thing this session was`,
+        "  about to do next, phrased as an action. Null if the work is finished or you cannot tell.",
+        `- blockers: up to ${BLOCKER_MAX} short strings, each something STOPPING progress. If the`,
+        "  session is waiting on a specific person or an external party, name them explicitly",
+        '  (for example "waiting on Marco to sign the contract"). Empty array if nothing blocks it.',
+        "- urgency: one of low, normal, high. Judge from the work itself, not from how recent it is.",
+        "  high = production is broken, a client is affected, or a dated commitment is at risk.",
+        "  normal = ordinary in-flight work. low = exploration, cleanup, or already finished.",
+        `- deadline: a real-world calendar date named in the session as a commitment, in YYYY-MM-DD`,
+        `  form. Today is ${todayIso}, so resolve relative phrases like "Friday" against it. Null if`,
+        "  no date is committed to. Do NOT invent one and do not infer a date from mere urgency.",
         "",
         "Session transcript:",
         sourceText,
     ].join("\n");
 }
+/**
+ * `${epoch}:${maxSeq}` for the agent's current timeline.
+ *
+ * Row `seq` restarts at 1 whenever the timeline store is re-initialized without
+ * seeded rows, so a seq is ONLY comparable within an epoch. Comparing a bare seq
+ * across epochs makes a fresh timeline look older than the last digest and skips
+ * forever, silently. Found live: turn 2 of a session never re-derived because
+ * its post-resume seq was below the pre-resume high-water mark.
+ */
+function resolveDigestMark(agentManager, agentId, rows) {
+    const maxSeq = rows.length > 0 ? rows[rows.length - 1].seq : 0;
+    try {
+        return `${agentManager.getTimelineEpoch(agentId)}:${maxSeq}`;
+    }
+    catch {
+        // Agent not resident: use a marker that can never match a stored one, so we
+        // derive rather than skip. Skipping is the dangerous direction.
+        return `unknown-${Date.now()}:${maxSeq}`;
+    }
+}
+function isUnchangedSinceLastDigest(agentId, mark) {
+    const seen = lastDigestMark.get(agentId);
+    if (seen === undefined) {
+        return false;
+    }
+    const sep = seen.lastIndexOf(":");
+    const markSep = mark.lastIndexOf(":");
+    const sameEpoch = seen.slice(0, sep) === mark.slice(0, markSep);
+    return sameEpoch && Number(mark.slice(markSep + 1)) <= Number(seen.slice(sep + 1));
+}
 export async function generateAndApplySessionDigest(options) {
     const { agentManager, agentId, cwd, logger } = options;
     const rows = await agentManager.getTimelineRows(agentId);
     if (rows.length === 0) {
         return;
     }
+    // Content-based gate (see the lastDigestMark block comment above). Extracted
+    // to a helper to stay under the oxlint complexity ceiling of 20.
+    const mark = resolveDigestMark(agentManager, agentId, rows);
+    if (isUnchangedSinceLastDigest(agentId, mark)) {
+        digestCounters.skippedUnchanged += 1;
+        // INFO, not debug. Every bug in this file has been a silent skip; a skip
+        // nobody can see is how a dead feature looks healthy.
+        logger.info({ agentId, mark }, "Session digest skipped: timeline unchanged");
+        return;
+    }
     // Deterministic, no LLM — always safe to refresh.
     const keyFiles = deriveKeyFilesFromTimeline(rows);
     const existing = agentManager.getAgent(agentId)?.digest;
@@ -50,10 +215,11 @@ export async function generateAndApplySessionDigest(options) {
                     currentSelection: options.currentSelection,
                 })
                 : [];
-            const result = await generator({
+            digestCounters.attempted += 1;
+            const result = await withTimeout(generator({
                 manager: agentManager,
                 cwd,
-                prompt: buildDigestPrompt(sourceText),
+                prompt: buildDigestPrompt(sourceText, new Date().toISOString().slice(0, 10)),
                 schema: DIGEST_SUMMARY_SCHEMA,
                 schemaName: "SessionDigestSummary",
                 maxRetries: 2,
@@ -64,18 +230,36 @@ export async function generateAndApplySessionDigest(options) {
                     title: "Session digest generator",
                     internal: true,
                 },
-            });
+            }), options.timeoutMs ?? DIGEST_GENERATION_TIMEOUT_MS);
             summaryPatch = {
                 summary: result.summary,
                 accomplishments: result.accomplishments,
+                // Derived fields go in their own keys. Writing `nextStep`/`blockers`
+                // directly would clobber whatever the session self-reported, because
+                // mergeDigest overwrites any key present in the patch.
+                ...(result.nextStep ? { derivedNextStep: result.nextStep } : {}),
+                ...(result.blockers ? { derivedBlockers: result.blockers } : {}),
+                ...(result.urgency ? { urgency: result.urgency } : {}),
+                ...(result.deadline ? { derivedDeadline: result.deadline } : {}),
             };
+            // Stamp ONLY on success. A failure must leave the window open so the next
+            // idle retries: there is no catch-up job, and the source transcript is
+            // subject to the provider's own prune window and the cwd gate, so a
+            // derivation missed today may not be reproducible later.
+            lastDigestAt.set(agentId, Date.now());
+            lastDigestMark.set(agentId, mark);
+            digestCounters.succeeded += 1;
         }
         catch (error) {
+            digestCounters.failed += 1;
+            if (error instanceof DigestGenerationTimeoutError) {
+                digestCounters.timedOut += 1;
+            }
             const attempts = error instanceof StructuredAgentFallbackError ? error.attempts : undefined;
-            logger.error({ err: error, agentId, attempts }, error instanceof StructuredAgentResponseError ||
+            logger.error({ err: error, agentId, attempts, failedTotal: digestCounters.failed }, error instanceof StructuredAgentResponseError ||
                 error instanceof StructuredAgentFallbackError
-                ? "Session digest summary generation failed"
-                : "Session digest generation failed");
+                ? "Session digest summary generation failed (derivation lost for this idle; will retry on next idle)"
+                : "Session digest generation failed (derivation lost for this idle; will retry on next idle)");
             // Fall through — still persist the deterministic keyFiles + timestamp.
         }
     }
@@ -96,11 +280,9 @@ export function scheduleSessionDigestRefresh(options) {
     if (inFlight.has(agentId)) {
         return;
     }
-    const now = Date.now();
-    if (now - (lastDigestAt.get(agentId) ?? 0) < DIGEST_DEBOUNCE_MS) {
-        return;
-    }
-    lastDigestAt.set(agentId, now);
+    // The gate itself moved into generateAndApplySessionDigest: it needs the
+    // timeline to tell "nothing new happened" apart from "we ran recently", and
+    // only the former is a safe reason to skip a one-shot derivation.
     inFlight.add(agentId);
     queueMicrotask(() => {
         void generateAndApplySessionDigest(options)
@@ -109,6 +291,15 @@ export function scheduleSessionDigestRefresh(options) {
         })
             .finally(() => {
             inFlight.delete(agentId);
+            // Fires even on skip or failure: a judge that only ran on the happy path
+            // would go silent exactly when something went wrong, which is when the
+            // user most needs to hear about it.
+            try {
+                options.onSettled?.();
+            }
+            catch (error) {
+                options.logger.error({ err: error, agentId }, "Session digest onSettled hook threw");
+            }
         });
     });
 }

package/dist/server/server/agent/tools/paseo-tools.d.ts

@@ -6,6 +6,7 @@ import type { VoiceCallerContext, VoiceSpeakHandler } from "../../voice-types.js
 import type { FirstAgentContext } from "../../messages.js";
 import type { TerminalManager } from "../../../terminal/terminal-manager.js";
 import type { CreatePaseoWorktreeWorkflowFn } from "../../worktree-session.js";
+import type { JudgeRelayGate } from "../judge-relay-gate.js";
 import type { ScheduleService } from "../../schedule/service.js";
 import type { ProviderSnapshotManager } from "../provider-snapshot-manager.js";
 import type { GitHubService } from "../../../services/github-service.js";
@@ -48,6 +49,17 @@ export interface PaseoToolHostDependencies {
     resolveCallerContext?: (callerAgentId: string) => VoiceCallerContext | null;
     enableVoiceTools?: boolean;
     voiceOnly?: boolean;
+    /**
+     * Restrict the surface to READ_ONLY_PASEO_TOOLS (JARVIS-V1-SPEC §6).
+     * Enforced by not registering the tool at all, never by prompt wording.
+     */
+    readOnly?: boolean;
+    /**
+     * Present only for the Jarvis judge. Enables `relay_to_agent`, the single
+     * mutating capability it may hold, gated at execution time on a human turn
+     * and on the target having been briefed. See judge-relay-gate.ts.
+     */
+    judgeRelayGate?: JudgeRelayGate;
     logger: Logger;
 }
 export declare function createPaseoToolCatalog(options: PaseoToolHostDependencies): PaseoToolCatalog;

package/dist/server/server/agent/tools/paseo-tools.js

@@ -10,6 +10,7 @@ import { killTerminalsForWorkspace, } from "../../workspace-archive-service.js";
 import { WaitForAgentTracker } from "../wait-for-agent-tracker.js";
 import { createAgentCommand } from "../create-agent/create.js";
 import { expandUserPath, isSameOrDescendantPath, resolvePathFromBase } from "../../path-utils.js";
+import { isReadOnlyPaseoTool } from "./read-only-surface.js";
 import { ScheduleRunSchema, ScheduleSummarySchema, StoredScheduleSchema, } from "@hyperdrive.bot/paseo-protocol/schedule/types";
 import { AgentModelSchema, AgentProviderEnum, AgentStatusEnum, ProviderModeSchema, ProviderSummarySchema, parseDurationString, resolveRequiredProviderModel, sanitizePermissionRequest, serializeSnapshotWithMetadata, toScheduleSummary, waitForAgentWithTimeout, } from "../mcp-shared.js";
 import { sendPromptToAgent, setupFinishNotification } from "../agent-prompt.js";
@@ -249,6 +250,11 @@ export function createPaseoToolCatalog(options) {
     const registerTool = (name, config, 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Tool handlers are schema-validated at registration boundaries.
     handler) => {
+        // Read-only gate (JARVIS-V1-SPEC §6). Allowlist, so a mutating tool added
+        // later fails closed instead of silently joining a read-only surface.
+        if (options.readOnly && !isReadOnlyPaseoTool(name)) {
+            return;
+        }
         tools.set(name, {
             name,
             title: config.title,
@@ -743,6 +749,48 @@ export function createPaseoToolCatalog(options) {
             };
         });
     }
+    // The judge's one mutating capability. Registered through `tools.set` rather
+    // than `registerTool` on purpose: `registerTool` applies the read-only
+    // allowlist, and this tool must be available to a read-only agent precisely
+    // BECAUSE its own gate is stricter than the allowlist. Keeping it out of
+    // READ_ONLY_PASEO_TOOLS also keeps that list honestly "reads only".
+    if (options.judgeRelayGate) {
+        const gate = options.judgeRelayGate;
+        tools.set("relay_to_agent", {
+            name: "relay_to_agent",
+            title: "Relay the user's decision to an agent",
+            description: "Pass the user's instruction to an agent you were briefed about. Only usable when the user has just told you something in this conversation; it is refused while you are processing an event. You do not act yourself, the target agent acts with its own context and permissions.",
+            inputSchema: {
+                agentId: z.string().describe("The agent to relay to. Must be one you were briefed about."),
+                message: z
+                    .string()
+                    .trim()
+                    .min(1)
+                    .max(4000)
+                    .describe("The user's instruction, in your words. Do not invent instructions."),
+            },
+            outputSchema: { ok: z.boolean(), agentId: z.string() },
+            handler: (async (args) => {
+                const decision = gate.evaluate(args.agentId);
+                if (!decision.allowed) {
+                    throw new Error(decision.detail ?? "Relay refused");
+                }
+                const target = await ensureAgentLoaded(args.agentId, {
+                    agentManager,
+                    agentStorage,
+                    logger: options.logger,
+                });
+                if (agentManager.hasInFlightRun(target.id)) {
+                    throw new Error(`Agent ${args.agentId} is mid-run; try again once it settles.`);
+                }
+                await agentManager.runAgent(target.id, args.message);
+                return {
+                    content: [],
+                    structuredContent: ensureValidJson({ ok: true, agentId: args.agentId }),
+                };
+            }),
+        });
+    }
     if (options.voiceOnly) {
         return toCatalog();
     }

package/dist/server/server/agent/tools/read-only-surface.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Read-only paseo tool surface (JARVIS-V1-SPEC §6, HARD REQUIREMENT).
+ *
+ * The Jarvis judge reads other sessions' contents in order to decide whether to
+ * interrupt the user. Those transcripts are arbitrary untrusted text by design:
+ * fetched web pages, repository files, tool output, error messages. Handing a
+ * reader of untrusted text a permission-granting tool creates a direct path from
+ * "text somebody else wrote" to "an approved action on the user's machine". No
+ * malice is required, only a transcript containing a sentence shaped like an
+ * instruction.
+ *
+ * A prompt saying "do not do this" is a suggestion to a model that is actively
+ * reading adversarial input. Absence of the tool is a wall. This module is the
+ * wall.
+ *
+ * ## Why an ALLOWLIST and not a denylist
+ *
+ * A denylist fails OPEN: the day somebody adds a new mutating tool, the judge
+ * silently gains it and nobody notices until it is used. An allowlist fails
+ * CLOSED: the new tool is simply unavailable until a human deliberately adds it
+ * here. The benign failure (a new read tool the judge cannot see yet) is worth
+ * far more than the dangerous one.
+ *
+ * ## Two registration paths, both gated
+ *
+ * Tools reach an agent through TWO places, and gating only one leaves a hole:
+ *   1. `paseo-tools.ts` `registerTool` (35 tools) -> filtered by this allowlist.
+ *   2. `mcp-server.ts`, which re-exposes the catalog and then registers 10 MORE
+ *      of its own, including `set_session_digest`, `set_session_tags`,
+ *      `open_url`, `workflow_start` and `workflow_cancel`. That path takes an
+ *      early return in read-only mode, so none of its extras are exposed.
+ */
+/**
+ * Every paseo tool a read-only agent may hold. Anything absent is denied.
+ *
+ * Deliberately excluded and why:
+ * - `respond_to_permission`  grants permissions. The core injection target.
+ * - `send_agent_prompt`      drives another agent. Action by proxy.
+ * - `update_agent`, `archive_agent`, `kill_agent`, `cancel_agent`  mutate sessions.
+ * - `set_agent_mode`         could lift the agent OUT of read-only. Privilege escalation.
+ * - `create_agent`, `create_worktree`, `archive_worktree`          create or destroy.
+ * - `create_terminal`, `kill_terminal`, `send_terminal_keys`       arbitrary command execution.
+ * - `create_schedule`, `update_schedule`, `delete_schedule`,
+ *   `pause_schedule`, `resume_schedule`, `create_heartbeat`        persistent side effects.
+ * - `rename_workspace`       mutates.
+ * - `speak`                  an outward side effect, and voice is out of v1 scope.
+ * - `wait_for_agent`         not mutating, but it BLOCKS. An event-woken judge
+ *                            that blocks holds its run open indefinitely.
+ */
+export declare const READ_ONLY_PASEO_TOOLS: ReadonlySet<string>;
+export declare function isReadOnlyPaseoTool(name: string): boolean;
+//# sourceMappingURL=read-only-surface.d.ts.map

package/dist/server/server/agent/tools/read-only-surface.js

@@ -0,0 +1,68 @@
+/**
+ * Read-only paseo tool surface (JARVIS-V1-SPEC §6, HARD REQUIREMENT).
+ *
+ * The Jarvis judge reads other sessions' contents in order to decide whether to
+ * interrupt the user. Those transcripts are arbitrary untrusted text by design:
+ * fetched web pages, repository files, tool output, error messages. Handing a
+ * reader of untrusted text a permission-granting tool creates a direct path from
+ * "text somebody else wrote" to "an approved action on the user's machine". No
+ * malice is required, only a transcript containing a sentence shaped like an
+ * instruction.
+ *
+ * A prompt saying "do not do this" is a suggestion to a model that is actively
+ * reading adversarial input. Absence of the tool is a wall. This module is the
+ * wall.
+ *
+ * ## Why an ALLOWLIST and not a denylist
+ *
+ * A denylist fails OPEN: the day somebody adds a new mutating tool, the judge
+ * silently gains it and nobody notices until it is used. An allowlist fails
+ * CLOSED: the new tool is simply unavailable until a human deliberately adds it
+ * here. The benign failure (a new read tool the judge cannot see yet) is worth
+ * far more than the dangerous one.
+ *
+ * ## Two registration paths, both gated
+ *
+ * Tools reach an agent through TWO places, and gating only one leaves a hole:
+ *   1. `paseo-tools.ts` `registerTool` (35 tools) -> filtered by this allowlist.
+ *   2. `mcp-server.ts`, which re-exposes the catalog and then registers 10 MORE
+ *      of its own, including `set_session_digest`, `set_session_tags`,
+ *      `open_url`, `workflow_start` and `workflow_cancel`. That path takes an
+ *      early return in read-only mode, so none of its extras are exposed.
+ */
+/**
+ * Every paseo tool a read-only agent may hold. Anything absent is denied.
+ *
+ * Deliberately excluded and why:
+ * - `respond_to_permission`  grants permissions. The core injection target.
+ * - `send_agent_prompt`      drives another agent. Action by proxy.
+ * - `update_agent`, `archive_agent`, `kill_agent`, `cancel_agent`  mutate sessions.
+ * - `set_agent_mode`         could lift the agent OUT of read-only. Privilege escalation.
+ * - `create_agent`, `create_worktree`, `archive_worktree`          create or destroy.
+ * - `create_terminal`, `kill_terminal`, `send_terminal_keys`       arbitrary command execution.
+ * - `create_schedule`, `update_schedule`, `delete_schedule`,
+ *   `pause_schedule`, `resume_schedule`, `create_heartbeat`        persistent side effects.
+ * - `rename_workspace`       mutates.
+ * - `speak`                  an outward side effect, and voice is out of v1 scope.
+ * - `wait_for_agent`         not mutating, but it BLOCKS. An event-woken judge
+ *                            that blocks holds its run open indefinitely.
+ */
+export const READ_ONLY_PASEO_TOOLS = new Set([
+    "capture_terminal",
+    "get_agent_activity",
+    "get_agent_status",
+    "inspect_provider",
+    "inspect_schedule",
+    "list_agents",
+    "list_models",
+    "list_pending_permissions",
+    "list_providers",
+    "list_schedules",
+    "list_terminals",
+    "list_worktrees",
+    "schedule_logs",
+]);
+export function isReadOnlyPaseoTool(name) {
+    return READ_ONLY_PASEO_TOOLS.has(name);
+}
+//# sourceMappingURL=read-only-surface.js.map

package/dist/server/server/agent/tools/types.d.ts

@@ -31,6 +31,11 @@ export interface PaseoToolRuntimeContext {
     callerAgentId?: string;
     enableVoiceTools?: boolean;
     voiceOnly?: boolean;
+    /**
+     * Restrict this session's surface to READ_ONLY_PASEO_TOOLS
+     * (JARVIS-V1-SPEC §6). Set by bootstrap for the Jarvis judge's agent id.
+     */
+    readOnly?: boolean;
 }
 export type PaseoToolCatalogFactory = (context: PaseoToolRuntimeContext) => PaseoToolCatalog | Promise<PaseoToolCatalog>;
 //# sourceMappingURL=types.d.ts.map