letagents 0.12.17 → 0.12.19

package/README.md

@@ -115,6 +115,41 @@ restore them explicitly; MCP never guesses another chat's identity. Existing
 integrations using `agent_session_id` and supervisor-managed workers keep their
 existing registration flow. The MCP server still runs locally through `npx`.
 
+## Workspace summaries from MCP
+
+Independent coding agents can share their actual file changes in the room and
+open saved reviews in the agent's Workspace tab. The local MCP process reads Git;
+the agent supplies only a short explanation of the changes.
+
+```text
+begin_workspace_capture(worker_id="worker_...", room_id="room_example", cwd="/path/to/project")
+→ capture_id="..."
+
+...make changes...
+
+publish_workspace_capture(worker_id="worker_...", room_id="room_example", capture_id="...", summary="Added task editing and keyboard shortcuts.")
+```
+
+Keep the capture ID until publication finishes. Repeat publish with the same ID
+if it returns `uploading` or the connection drops; it reuses the saved files and
+summary without creating another message. Publication posts the room summary
+itself. A new piece of work starts with a new capture.
+
+This first version depends on the agent calling both tools. Instructions are
+provided at MCP initialization and worker registration; there are no automatic
+IDE hooks. Begin before editing: without a valid starting snapshot, exact changes
+for that piece of work are unavailable. Existing dirty files are excluded from
+the before/after contribution, but remain visible in the overall workspace view.
+Edits made by someone else in the same checkout during the capture cannot be
+separated. Different computers have separate checkouts.
+
+Captures require a hosted room and a local Git repository with an initial commit.
+They include tracked and non-ignored untracked files, shared with room participants.
+Large reviews upload in bounded pages; files beyond capture limits are marked
+unavailable or incomplete. Prepared uploads are stored privately beside the MCP
+state file and removed after publication. Desktop-supervised agents retain their
+existing automatic capture.
+
 ## MCP Tools
 
 | Tool | Description |
@@ -125,6 +160,8 @@ existing registration flow. The MCP server still runs locally through `npx`.
 | `get_current_room` | Show current room and how it was joined |
 | `register_agent_session` | Create a chat's durable worker handle or explicitly reconnect it |
 | `disconnect_agent_session` | End a worker connection while retaining its handle for reconnects |
+| `begin_workspace_capture` | Record a worker's starting files before editing |
+| `publish_workspace_capture` | Share the worker's summary and saved file review; retry the same capture ID until published |
 | `send_message` | Send a top-level message, or pass `thread_parent_id` to keep a reply in a thread |
 | `send_thread_message` | Reply inside an existing message thread without polluting the main room |
 | `read_messages` | Read all messages from the current room or a specific `room_id` |

package/dist/mcp/server/register-tools.js

@@ -8,6 +8,7 @@ import { registerSupervisedRoomTurnTools } from "./tools/supervised-room-turn.js
 import { toolSurfaceForExecutionProfile } from "./runtime/tool-surface-policy.js";
 import { profileAwareToolServer } from "./supervised-tool-facade.js";
 import { workerAwareToolServer } from "./worker-tool-facade.js";
+import { registerWorkspaceTools } from "./tools/workspace.js";
 export function registerTools(server, profile = "autonomous_mcp_worker", supervisedProvider = process.env.LETAGENTS_SUPERVISOR_PROVIDER?.trim() || null, options = {}) {
     const profileTools = options.executionOwner === "daemon"
         ? server
@@ -20,6 +21,8 @@ export function registerTools(server, profile = "autonomous_mcp_worker", supervi
         registerAgentSessionTools(tools);
     registerRoomInspectionTools(tools);
     registerStatusTools(tools);
+    if (profile === "autonomous_mcp_worker" || profile === "interactive_desktop")
+        registerWorkspaceTools(tools);
     registerTaskTools(tools);
     registerRepoInitializationTool(tools);
     registerMessageTools(tools, { includeDeliveryLoop: surface.deliveryLoop });

package/dist/mcp/server/runtime/workspace-capture.js

@@ -0,0 +1,267 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { open, readFile, realpath, rm } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { promisify } from 'node:util';
+import { Worker } from 'node:worker_threads';
+import { parseRoomAgentWorkSummary } from '../../../../shared/room-agent-work.mjs';
+import { REVIEW_LIMIT, REVIEW_PAGE_SIZE } from '../../../../shared/workspace-review.mjs';
+import { releaseWorkspaceTree } from '../../../../shared/workspace-turn-capture.mjs';
+import { getLocalStatePath, readLocalStateSnapshot, updateLocalState } from '../../local-state/storage.js';
+import { assertWorkerConnection } from '../../worker-call-context.js';
+import { encodeRoomIdPath } from '../../room-id.js';
+import { agentSessionCredentials, resolveWorkerToolIdentity } from './agent-sessions.js';
+import { ApiError, apiCall, getApiUrl } from './api.js';
+import { getRuntimeWorkingDirectory } from './daemon-tool-context.js';
+import { isLocalRoomStorageEnabled } from '../../local-state.js';
+import { requireValidWorkerBearerRuntime } from './worker-bearer.js';
+const execute = promisify(execFile);
+const activeCalls = new Set();
+let captureWorkerActive = false;
+const validId = (id) => /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(id);
+const directory = (id) => join(`${getLocalStatePath()}.workspaces`, id);
+const preparationDirectory = (capture) => {
+    if (!capture.preparation_id || !validId(capture.preparation_id))
+        throw new Error('Saved preparation is unavailable.');
+    return join(directory(capture.capture_id), capture.preparation_id);
+};
+const sameWorker = (capture, session) => capture.api_url === getApiUrl()
+    && capture.room_id === session.room_id && capture.agent_key === session.agent_key && capture.agent_instance_id === session.agent_instance_id;
+async function identity(roomId, agentSessionId) {
+    if (requireValidWorkerBearerRuntime().mode !== 'owner')
+        throw new Error('Desktop-supervised agents already have automatic capture. These tools require an independent MCP worker.');
+    const { agentSession } = await resolveWorkerToolIdentity({ roomId, agentSessionId });
+    if (!agentSession.agent_instance_id || !agentSession.session_token || agentSession.ended_at)
+        throw new Error('Reconnect this worker with register_agent_session first.');
+    if (await isLocalRoomStorageEnabled(agentSession.room_id))
+        throw new Error('Workspace sharing requires a hosted LetAgents room. Join the shared room before capturing.');
+    assertWorkerConnection(agentSession);
+    return agentSession;
+}
+function captures() {
+    const snapshot = readLocalStateSnapshot();
+    if (!snapshot.complete)
+        throw new Error('Local capture state is unavailable. Restore it before continuing.');
+    return snapshot.state.workspace_captures ?? {};
+}
+function readCapture(id, session) {
+    const capture = validId(id) ? captures()[id] : null;
+    if (!capture || !sameWorker(capture, session))
+        throw new Error('This worker has no such capture. Call begin_workspace_capture before editing and retain its capture_id.');
+    return capture;
+}
+function save(session, update) {
+    updateLocalState(state => {
+        const stored = state.agent_sessions?.[session.session_id];
+        if (!stored || stored.ended_at || stored.session_token !== session.session_token)
+            throw new Error('Worker connection changed. Reconnect explicitly before retrying.');
+        state.workspace_captures ??= {};
+        update(state.workspace_captures);
+    });
+}
+async function exclusive(key, operation) {
+    if (activeCalls.has(key))
+        throw new Error('This worker already has a capture operation in progress. Retry when it finishes.');
+    activeCalls.add(key);
+    try {
+        return await operation();
+    }
+    finally {
+        activeCalls.delete(key);
+    }
+}
+async function runCapture(operation, capture, text) {
+    if (captureWorkerActive)
+        throw new Error('Another workspace is being captured. Retry shortly; the original baseline is preserved.');
+    captureWorkerActive = true;
+    let worker;
+    try {
+        return await new Promise((resolve, reject) => {
+            worker = new Worker(new URL('../../../../shared/mcp-workspace-capture-worker.mjs', import.meta.url), {
+                execArgv: [], workerData: { operation, capture, text, directory: operation === 'finish' ? preparationDirectory(capture) : null },
+            });
+            const timeout = setTimeout(() => { reject(new Error('Capture exceeded its time limit. Retry using the same capture_id.')); void worker?.terminate(); }, 120_000);
+            worker.once('message', result => { clearTimeout(timeout); result.error ? reject(new Error(result.error)) : resolve(result); });
+            worker.once('error', error => { clearTimeout(timeout); reject(error); });
+            worker.once('exit', () => { clearTimeout(timeout); reject(new Error('Capture stopped before completion.')); });
+        });
+    }
+    finally {
+        await worker?.terminate();
+        captureWorkerActive = false;
+    }
+}
+export async function beginWorkspaceCapture(input) {
+    const session = await identity(input.room_id, input.agent_session_id);
+    return exclusive(`${getLocalStatePath()}:${session.agent_instance_id}:${session.room_id}`, async () => {
+        const prior = Object.values(captures()).find(record => sameWorker(record, session) && !['published', 'blocked'].includes(record.phase));
+        // Reject contention before recording a start that could never be captured.
+        if (captureWorkerActive)
+            throw new Error('Another workspace is being captured. Retry shortly before editing.');
+        const cwd = await realpath(resolve(input.cwd || prior?.workspace || getRuntimeWorkingDirectory()));
+        const git = async (args) => (await execute('git', ['--no-optional-locks', ...args], {
+            cwd, timeout: 5_000, maxBuffer: 16 * 1024,
+            env: Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+        })).stdout.trim();
+        const workspace = await realpath(await git(['rev-parse', '--show-toplevel']));
+        if (prior) {
+            if (prior.workspace !== workspace)
+                throw new Error('This worker has an unfinished capture in another repository. Publish it before beginning a different workspace.');
+            return { capture_id: prior.capture_id, workspace: prior.workspace, baseline_available: Boolean(prior.baseline),
+                instruction: 'Continue this capture. Keep its capture_id and call publish_workspace_capture when finished.',
+                ...(prior.baseline ? {} : { warning: 'The starting snapshot is unavailable. Exact changes for this piece of work cannot be attributed.' }) };
+        }
+        const baseRevision = await git(['rev-parse', '--verify', 'HEAD']);
+        const capture = { capture_id: randomUUID(), api_url: getApiUrl(), room_id: session.room_id,
+            agent_key: session.agent_key, agent_instance_id: session.agent_instance_id, workspace, base_revision: baseRevision,
+            baseline: null, phase: 'starting', next_page: 0 };
+        const obsolete = Object.values(captures()).filter(record => sameWorker(record, session));
+        save(session, records => {
+            if (Object.values(records).some(record => sameWorker(record, session) && !['published', 'blocked'].includes(record.phase))) {
+                throw new Error('This worker already began a capture. Retry begin to retrieve it.');
+            }
+            for (const [id, record] of Object.entries(records))
+                if (sameWorker(record, session))
+                    delete records[id];
+            records[capture.capture_id] = capture;
+        });
+        for (const record of obsolete)
+            await rm(directory(record.capture_id), { recursive: true, force: true });
+        try {
+            const result = await runCapture('begin', capture);
+            capture.baseline = result.baseline ?? null;
+        }
+        finally {
+            // A failed/interrupted start is never silently recaptured after editing.
+            capture.phase = 'ready';
+            try {
+                save(session, records => { records[capture.capture_id] = capture; });
+            }
+            catch (error) {
+                await releaseWorkspaceTree(capture.workspace, `mcp-workspace:${capture.capture_id}`);
+                throw error;
+            }
+        }
+        return { capture_id: capture.capture_id, workspace, baseline_available: Boolean(capture.baseline),
+            ...(capture.baseline ? {} : { warning: 'A complete starting snapshot could not be captured. Exact changes for this piece of work will be unavailable.' }),
+            instruction: 'Make your changes, then call publish_workspace_capture with this capture_id and a short summary. It posts the summary to the room; do not send a duplicate summary message.' };
+    });
+}
+async function preparedCapture(capture) {
+    if (!capture.preparation_id)
+        return null;
+    let raw;
+    raw = await readFile(join(preparationDirectory(capture), 'prepared.json'), 'utf8');
+    const value = JSON.parse(raw);
+    const summary = parseRoomAgentWorkSummary(value.summary);
+    if (!summary || summary.version !== 3 || typeof value.text !== 'string' || value.text.length > 400
+        || (value.archive && (!/^[a-f0-9]{64}$/.test(value.archive.digest) || !Number.isSafeInteger(value.archive.length)
+            || value.archive.length < 1 || value.archive.length > REVIEW_LIMIT || value.archive.total !== Math.ceil(value.archive.length / REVIEW_PAGE_SIZE)))) {
+        throw new Error('Saved capture is invalid. It cannot be published.');
+    }
+    return { ...value, summary };
+}
+export async function publishWorkspaceCapture(input) {
+    const session = await identity(input.room_id, input.agent_session_id);
+    return exclusive(`${getLocalStatePath()}:${session.agent_instance_id}:${session.room_id}`, async () => {
+        let capture = readCapture(input.capture_id, session);
+        if (capture.phase === 'blocked')
+            throw new Error('This capture was deleted or cleared. It will not be republished. Begin a new capture for new work.');
+        if (capture.phase === 'published')
+            return { status: 'published', capture_id: capture.capture_id, source_message_id: capture.source_message_id, attempt_id: capture.attempt_id };
+        let prepared = await preparedCapture(capture);
+        if (!prepared) {
+            const text = input.summary.trim();
+            if (!text || text.length > 400)
+                throw new Error('Supply a short summary of at most 400 characters.');
+            const candidate = { ...capture, preparation_id: randomUUID() };
+            try {
+                await runCapture('finish', candidate, text);
+                await preparedCapture(candidate);
+                // Commit one immutable preparation under the same lock that fences
+                // reconnects. Stale processes only write their own disposable directory.
+                save(session, records => {
+                    const current = records[capture.capture_id];
+                    if (!current || !sameWorker(current, session) || ['published', 'blocked'].includes(current.phase))
+                        throw new Error('Capture is no longer pending.');
+                    capture = current.preparation_id ? current : { ...current, preparation_id: candidate.preparation_id };
+                    records[capture.capture_id] = capture;
+                });
+            }
+            finally {
+                if (capture.preparation_id !== candidate.preparation_id)
+                    await rm(preparationDirectory(candidate), { recursive: true, force: true });
+            }
+            prepared = await preparedCapture(capture);
+            if (!prepared)
+                throw new Error('Capture did not finish. Retry with the same capture_id.');
+        }
+        await releaseWorkspaceTree(capture.workspace, `mcp-workspace:${capture.capture_id}`);
+        const payload = prepared;
+        const credentials = agentSessionCredentials(session);
+        const request = (path, body) => {
+            assertWorkerConnection(session);
+            return apiCall(`/rooms/${encodeRoomIdPath(session.room_id)}/${path}`, {
+                method: 'POST', signal: AbortSignal.timeout(30_000), body: JSON.stringify({ ...body, ...credentials }),
+            });
+        };
+        const persist = () => save(session, records => { records[capture.capture_id] = capture; });
+        try {
+            if (!capture.source_message_id) {
+                const message = await request('messages', { sender: session.actor_label, text: payload.text,
+                    client_message_id: `mcp-workspace:${capture.capture_id}` });
+                if (!/^msg_[1-9]\d{0,9}$/.test(message?.id))
+                    throw new Error('The server did not confirm the summary message. Retry this capture.');
+                capture = { ...capture, source_message_id: message.id, phase: 'publishing' };
+                persist();
+            }
+            const total = payload.archive?.total ?? 1;
+            const review = payload.archive ? await open(join(preparationDirectory(capture), 'review'), 'r') : null;
+            try {
+                // At most 1 MiB per tool call; large uploads resume from the saved page.
+                // Each request carries the same immutable summary and 64 KiB archive page.
+                const end = Math.min(total, capture.next_page + 16);
+                for (let index = capture.next_page; index < end; index++) {
+                    let page;
+                    if (review && payload.archive) {
+                        const length = Math.min(REVIEW_PAGE_SIZE, payload.archive.length - index * REVIEW_PAGE_SIZE);
+                        const buffer = Buffer.alloc(length);
+                        const { bytesRead } = await review.read(buffer, 0, length, index * REVIEW_PAGE_SIZE);
+                        if (bytesRead !== length)
+                            throw new Error('Saved review is incomplete. It cannot be published.');
+                        page = { digest: payload.archive.digest, index, total, data: buffer.toString('ascii') };
+                    }
+                    const result = await request('agent-work', {
+                        source_message_id: capture.source_message_id, summary: payload.summary, ...(page ? { review_page: page } : {}),
+                    });
+                    if (!validId(result.work?.attempt_id) || result.work.agent_key !== session.agent_key || result.work.room_id !== session.room_id
+                        || result.work.source_message_id !== capture.source_message_id)
+                        throw new Error('The server returned a different capture.');
+                    capture = { ...capture, attempt_id: result.work.attempt_id, next_page: index + 1 };
+                    persist();
+                }
+            }
+            finally {
+                await review?.close();
+            }
+            if (capture.next_page === total) {
+                capture = { ...capture, phase: 'published' };
+                persist();
+                await rm(directory(capture.capture_id), { recursive: true, force: true });
+            }
+            return { status: capture.phase === 'published' ? 'published' : 'uploading', capture_id: capture.capture_id,
+                source_message_id: capture.source_message_id, attempt_id: capture.attempt_id,
+                baseline_available: Boolean(capture.baseline), ...(payload.warning ? { warning: payload.warning } : {}),
+                ...(capture.phase === 'published' ? { instruction: 'The summary and captured review are shared in the room. Do not send a duplicate summary.' }
+                    : { instruction: 'Call publish_workspace_capture again with the same capture_id to finish sharing the captured review. Saved bytes and summary will be reused.' }) };
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 410) {
+                capture = { ...capture, phase: 'blocked' };
+                persist();
+                await rm(directory(capture.capture_id), { recursive: true, force: true });
+            }
+            throw error;
+        }
+    });
+}

package/dist/mcp/server/tools/agent-sessions.js

@@ -6,6 +6,7 @@ import { AGENT_INSTANCE_UUID, RepoRoomAuthRequiredError, apiCall, agentSessionCr
 import { requireValidWorkerBearerRuntime, workerModeDisabledToolResult, } from "../runtime/worker-bearer.js";
 import { bindSupervisedWorkerSessionWithContext } from "../runtime/supervisor-bridge.js";
 import { registerMcpWorker } from "../runtime/worker-handles.js";
+import { WORKSPACE_CAPTURE_INSTRUCTIONS } from './workspace.js';
 export function registerAgentSessionTools(server) {
     // -- register_agent_session -------------------------------------------------
     server.tool("register_agent_session", "Connect a worker to a room. For an independent chat, supply a unique registration_key once, keep the returned worker_id, and use worker_id on room tools. After an MCP restart, reconnect with that worker_id. Separate chats must use separate registration keys. Unregistered traffic remains controller traffic. Legacy agent_session_id registration is retained for existing integrations.", {
@@ -44,6 +45,7 @@ export function registerAgentSessionTools(server) {
                             success: true, worker_id: result.worker.worker_id,
                             agent_session: toPublicAgentSession(result.session),
                             instruction: "Keep worker_id for this chat and pass it to room tools. After an MCP restart, reconnect with register_agent_session(worker_id, room_id). A separate chat needs its own registration_key. Credentials stay private to MCP.",
+                            workspace_instructions: WORKSPACE_CAPTURE_INSTRUCTIONS,
                         }) }] };
         }
         const workerRuntime = requireValidWorkerBearerRuntime();

package/dist/mcp/server/tools/tasks/board-intent-tools.js

@@ -277,7 +277,7 @@ export function registerBoardIntentTools(server) {
             return taskToolError(String(error));
         }
     });
-    server.tool("approve_board_intent", "Approve a pending board intent. For task_create intents this creates the task immediately and returns result.kind=\"task_created\"; do not call add_task afterward. Other intent types return a scoped approval token for the follow-up board action.", {
+    server.tool("approve_board_intent", "Approve a pending board intent. For task_create intents this creates the task immediately and returns result.kind=\"task_created\"; do not call add_task afterward. Other intent types notify the proposer to perform the exact follow-up with board_intent_id and their own worker session. The scoped approval token remains available for legacy callers; do not post it in room messages.", {
         intent_id: z.string().describe("Board intent id to approve."),
         reason: z.string().optional().describe("Short approval reason."),
         ...workerTaskIdentitySchema,

package/dist/mcp/server/tools/tasks/mutation-tools.js

@@ -6,8 +6,9 @@ import { resolveTaskToolIdentity, resolveTaskToolTarget, taskActorPayload, } fro
 import { jsonToolResponse, taskToolError } from "./response.js";
 import { deprecatedAssigneeSchema, boardIntentApprovalSchema, TASK_STATUSES, workerTaskIdentitySchema, workflowArtifactSchema, } from "./schemas.js";
 export function registerTaskMutationTools(server) {
-    server.tool("claim_task", "Claim an accepted task. The task must be in 'accepted' " +
-        "status. This sets the assignee to you and moves the status to 'assigned'. " +
+    server.tool("claim_task", "Claim an accepted task, or retry your own assigned task to recover a missing work lease. " +
+        "This sets the assignee to you and moves the status to 'assigned'. A retry with your active lease is idempotent. " +
+        "If approval is required, register a task claim intent; after the manager approves it, pass board_intent_id. Managed workers do not need to copy approval tokens. " +
         "Do NOT claim proposed tasks — they need to be accepted first.", {
         task_id: z.string().describe("The task ID to claim, e.g. 'task_1'"),
         assignee: deprecatedAssigneeSchema,

package/dist/mcp/server/tools/workspace.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { beginWorkspaceCapture, publishWorkspaceCapture } from '../runtime/workspace-capture.js';
+import { jsonToolResponse } from './messages/response.js';
+export const WORKSPACE_CAPTURE_INSTRUCTIONS = 'For independent coding work you are sharing in a LetAgents room: register this chat as a worker, call begin_workspace_capture before editing, retain capture_id, and call publish_workspace_capture when finished with a short summary. Pass this chat\'s worker_id to both tools. The publish tool posts the summary itself; do not send a duplicate message. If it returns uploading, repeat publish with the same capture_id until published. A missing baseline means exact changes cannot be attributed. Captures include tracked and non-ignored untracked files in the selected repository, and are shared with room participants. These are explicit agent tool calls, not automatic IDE hooks.';
+export function registerWorkspaceTools(server) {
+    const identity = { room_id: z.string().min(1).max(512).describe('Canonical hosted room ID.'),
+        agent_session_id: z.string().optional().describe('Registered worker session. Prefer the worker_id returned for this chat.') };
+    server.tool('begin_workspace_capture', 'Before editing a repository for work shared in this room, record the starting files. Keep capture_id for publish_workspace_capture. Repeating begin preserves this worker\'s outstanding baseline. Files are inspected locally; nothing is posted until publish.', { ...identity, cwd: z.string().optional().describe('Actual project/worktree folder. Defaults to the MCP working directory.') }, async (input) => jsonToolResponse(await beginWorkspaceCapture(input)));
+    server.tool('publish_workspace_capture', 'After editing, publish this capture\'s short summary, changed files and saved review to the room as this worker. Posts its own summary message. Retry with the same capture_id after errors or uploading; retries reuse saved bytes. Requires begin_workspace_capture before the work.', { ...identity, capture_id: z.string().uuid().describe('ID returned by begin_workspace_capture for this piece of work.'),
+        summary: z.string().trim().min(1).max(400).describe('Plain-English description of what changed. Keep it concise; use Markdown if helpful.') }, async (input) => jsonToolResponse(await publishWorkspaceCapture(input)));
+}

package/dist/mcp/server.js

@@ -6,19 +6,20 @@ import { registerTools } from "./server/register-tools.js";
 import { attachMcpServer, autoJoinFromContext, shutdownRuntime } from "./server/runtime.js";
 import { requireValidWorkerBearerRuntime } from "./server/runtime/worker-bearer.js";
 import { executionProfile } from "./server/runtime/execution-profile.js";
+import { WORKSPACE_CAPTURE_INSTRUCTIONS } from "./server/tools/workspace.js";
 import { LETAGENTS_RUNTIME_CONTRACT_ARG, letAgentsRuntimeContract, } from "./server/runtime-contract.js";
 async function main() {
     if (process.argv.slice(2).includes(LETAGENTS_RUNTIME_CONTRACT_ARG)) {
         process.stdout.write(`${JSON.stringify(letAgentsRuntimeContract())}\n`);
         return;
     }
+    const profile = executionProfile();
     const server = new McpServer({
         name: "letagents",
         version: "0.2.0",
-    });
+    }, { instructions: profile === "autonomous_mcp_worker" || profile === "interactive_desktop" ? WORKSPACE_CAPTURE_INSTRUCTIONS : undefined });
     attachMcpServer(server);
     registerRoomResources(server);
-    const profile = executionProfile();
     registerTools(server, profile);
     requireValidWorkerBearerRuntime();
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letagents",
-  "version": "0.12.17",
+  "version": "0.12.19",
   "description": "Let Agents Chat — MCP server for AI agent communication",
   "type": "module",
   "main": "dist/mcp/server.js",

package/shared/contribution-text.d.mts

@@ -0,0 +1 @@
+export function readableContributionText(value: string | null | undefined, limit?: number): string | null;

package/shared/contribution-text.mjs

@@ -0,0 +1,34 @@
+/** Compact public prose without leaking machine paths or cutting a sentence in half. */
+export function readableContributionText(value, limit = 400) {
+  if (!value?.trim()) return null;
+  // A legacy 400-character value may already be cut. Never present its trailing fragment.
+  const possiblyCut = value.length >= limit;
+  const links = [];
+  const protect = text => {
+    const markdown = /^\[([^\]]+)\]\(([^)]+)\)$/.exec(text);
+    const target = markdown?.[2] ?? text;
+    const file = /^https?:\/\/(?:github\.com\/[^/]+\/[^/]+\/(?:blob|raw)|raw\.githubusercontent\.com\/[^/]+\/[^/]+)\/[^/]+\/(.+?)(?:[?#].*)?$/.exec(target);
+    const name = file?.[1].split('/').at(-1);
+    const punctuation = !markdown ? name?.match(/[.,;:!?]+$/)?.[0] ?? '' : '';
+    const label = name ? '`' + name.slice(0, name.length - punctuation.length) + '`' + punctuation : markdown?.[1] ?? text;
+    return '\u0000LINK' + (links.push(label) - 1) + '\u0000';
+  };
+  const source = value.replace(/\u0000/g, '').replace(/\[[^\]\n]+\]\(https?:\/\/[^)]+\)|https?:\/\/[^\s<>]+/g, protect);
+  let text = source.replace(/\[([^\]\n]+)\]\((<[^>]+>|[^)]+)\)/g, (match, label, target) => /^https?:\/\//.test(target) ? match : '`' + label.split(/[\\/]/).at(-1) + '`')
+    .replace(/(?:file:\/\/)?(?:\/[A-Za-z0-9_.~ -]+)+\/([^\s`<>\[\]()]+)|[A-Za-z]:\\(?:[^\s\\]+\\)+([^\s`<>]+)|(?:\.\.?\/)(?:[^\s/]+\/)*([^\s`<>]+)/g,
+      (_match, unix, windows, relative) => '`' + (unix || windows || relative) + '`')
+    .replace(/(?<!`)``([^`\n]+)``(?!`)/g, '`$1`')
+    .replace(/^\s*(?:Done\.?|Path:\s*`[^`]+`)\s*$/gmi, '')
+    .trim();
+  text = text.replace(/\u0000LINK(\d+)\u0000/g, (_match, index) => links[Number(index)] ?? '');
+  if (!text) return null;
+  if (text.length > limit || possiblyCut) {
+    const prefix = text.slice(0, limit);
+    // Keep complete paragraphs or sentences only; a file list below remains the grounded fallback.
+    const end = [...prefix.matchAll(/(?<![.!?])[.!?](?=\s|$)/g)].at(-1);
+    if (!end) return null;
+    text = prefix.slice(0, end.index + 1).trim();
+    if ((text.match(/```/g)?.length ?? 0) % 2) text = text.slice(0, text.lastIndexOf('```')).trim();
+  }
+  return /^Done[.!]?$/i.test(text) ? null : text || null;
+}

package/shared/mcp-workspace-capture-worker.mjs

@@ -0,0 +1,41 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { mkdir, writeFile, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { captureWorkspaceTree, captureWorkspacePair } from './workspace-turn-capture.mjs';
+import { encodeWorkspaceReview, REVIEW_PAGE_SIZE } from './workspace-review.mjs';
+
+// Git inspection and archive encoding never occupy the MCP transport's thread.
+// A process runs at most one capture worker; only small metadata crosses IPC.
+try {
+  const { capture, directory, text } = workerData;
+  const identity = `mcp-workspace:${capture.capture_id}`;
+  if (workerData.operation === 'begin') {
+    parentPort.postMessage({ baseline: await captureWorkspaceTree(capture.workspace, identity) });
+  } else {
+    const pair = await captureWorkspacePair(capture.workspace, capture.base_revision, capture.baseline, `${identity}:${capture.preparation_id}`);
+    pair.contribution.summary = text;
+    const { review, ...preview } = pair;
+    const summary = { version: 3, recorded_state: 'completed', evidence_incomplete: true, elapsed_ms: null,
+      operation_counts: { unresolved: 0, succeeded: 0, failed: 0, denied_before_start: 0,
+        cancelled_before_start: 0, interrupted_after_start: 0, lost_after_start: 0 }, ...preview };
+    let encoded = null;
+    let warning = capture.baseline ? null : 'The starting snapshot is unavailable; no exact change attribution is available.';
+    try { encoded = encodeWorkspaceReview(review); }
+    catch (error) {
+      if (!(error instanceof RangeError)) throw error;
+      warning = 'This capture exceeds the full-review size limit. Only its bounded preview is available.';
+    }
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    if (encoded) {
+      await writeFile(join(directory, 'review.tmp'), encoded.data, { mode: 0o600 });
+      await rename(join(directory, 'review.tmp'), join(directory, 'review'));
+    }
+    const prepared = { summary, text, warning,
+      archive: encoded ? { digest: encoded.digest, length: encoded.data.length, total: Math.ceil(encoded.data.length / REVIEW_PAGE_SIZE) } : null };
+    await writeFile(join(directory, 'prepared.tmp'), JSON.stringify(prepared), { mode: 0o600 });
+    await rename(join(directory, 'prepared.tmp'), join(directory, 'prepared.json'));
+    parentPort.postMessage({ prepared: true });
+  }
+} catch {
+  parentPort.postMessage({ error: 'Workspace capture could not finish. Retry with the same capture_id.' });
+}

package/shared/room-agent-work.d.mts

@@ -1,7 +1,10 @@
+import type { WorkspaceChangeSummary } from "./workspace-change-summary.mjs";
 export const ROOM_WORK_STATES: readonly ["active", "completed", "completed_no_reply", "failed", "interrupted", "lost", "unknown"];
 export const ROOM_WORK_OPERATION_OUTCOMES: readonly ["unresolved", "succeeded", "failed", "denied_before_start", "cancelled_before_start", "interrupted_after_start", "lost_after_start"];
 export type RoomAgentWorkSummary = {
-  version: 1;
+  version: 1 | 2 | 3;
+  contribution?: { changes: WorkspaceChangeSummary; summary: string | null };
+  workspace?: WorkspaceChangeSummary;
   recorded_state: typeof ROOM_WORK_STATES[number];
   evidence_incomplete: boolean;
   elapsed_ms: number | null;

package/shared/room-agent-work.mjs

@@ -1,6 +1,7 @@
-// Room-public, host-reported evidence; never execution or approval authority.
-// No free-form strings, native handles, paths, command text, or output belong
-// in this version. Both the publisher and server use this strict boundary.
+import { parseWorkspaceChangeSummary } from './workspace-change-summary.mjs';
+// v1 is numeric execution evidence. v2 additionally carries a bounded,
+// deliberately room-visible workspace review snapshot. v3 separates changes
+// during one turn from the cumulative workspace, with an optional public summary.
 export const ROOM_WORK_STATES = [
   "active", "completed", "completed_no_reply", "failed", "interrupted", "lost", "unknown",
 ];
@@ -21,8 +22,22 @@ export function isClearedRoomAgentWorkSummary(value) {
 
 /** Return a canonical allowlisted copy, or reject without echoing private input. */
 export function parseRoomAgentWorkSummary(value) {
-  if (!exactKeys(value, ["version", "recorded_state", "evidence_incomplete", "elapsed_ms", "operation_counts"])
-    || value.version !== 1 || !ROOM_WORK_STATES.includes(value.recorded_state)
+  const workspace = [2, 3].includes(value?.version) ? parseWorkspaceChangeSummary(value.workspace) : null;
+  const keys = ["version", "recorded_state", "evidence_incomplete", "elapsed_ms", "operation_counts"];
+  if ([2, 3].includes(value?.version)) keys.push("workspace");
+  let contribution = null;
+  if (value?.version === 3) {
+    keys.push("contribution");
+    const candidate = value.contribution;
+    if (!exactKeys(candidate, ["changes", "summary"]) || !(candidate.summary === null
+      || typeof candidate.summary === "string" && candidate.summary.length <= 400)) return null;
+    const changes = parseWorkspaceChangeSummary(candidate.changes);
+    if (!changes) return null;
+    contribution = { changes, summary: candidate.summary };
+    if (new TextEncoder().encode(JSON.stringify(value)).length > 500 * 1024) return null;
+  }
+  if (!exactKeys(value, keys)
+    || ![1, 2, 3].includes(value.version) || (value.version >= 2 && !workspace) || !ROOM_WORK_STATES.includes(value.recorded_state)
     || typeof value.evidence_incomplete !== "boolean"
     || (value.elapsed_ms !== null && (!Number.isSafeInteger(value.elapsed_ms) || Number(value.elapsed_ms) < 0))
     || !exactKeys(value.operation_counts, ROOM_WORK_OPERATION_OUTCOMES)) return null;
@@ -37,7 +52,9 @@ export function parseRoomAgentWorkSummary(value) {
   // A bounded evidence snapshot, not an unbounded lifetime counter.
   if (total > 10_000) return null;
   return {
-    version: 1, recorded_state: value.recorded_state,
+    version: value.version, recorded_state: value.recorded_state,
+    ...(workspace ? { workspace } : {}),
+    ...(contribution ? { contribution } : {}),
     evidence_incomplete: value.evidence_incomplete, elapsed_ms: value.elapsed_ms,
     operation_counts: counts,
   };

package/shared/workspace-change-capture.d.mts

@@ -0,0 +1,2 @@
+import type { WorkspaceChangeSummary } from './workspace-change-summary.mjs';
+export function captureWorkspaceChanges(workspace: string, startingRevision: string | null, settledTree?: string, fullReview?: boolean): Promise<WorkspaceChangeSummary>;

package/shared/workspace-change-capture.mjs

@@ -0,0 +1,147 @@
+import { execFile } from 'node:child_process';
+import { constants } from 'node:fs';
+import { open, readlink, lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { WORKSPACE_FILE_LIMIT, WORKSPACE_PATCH_LIMIT, parseWorkspaceChangeSummary } from './workspace-change-summary.mjs';
+const execute = promisify(execFile);
+async function git(cwd, args, limit = 4 * 1024 * 1024) {
+    const result = await execute('git', ['--no-optional-locks', ...args], {
+        cwd, encoding: 'utf8', timeout: 5_000, maxBuffer: limit,
+        env: { ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))), GIT_TERMINAL_PROMPT: '0' },
+    });
+    return result.stdout;
+}
+/** Reads the actual provider workspace; never stages, commits, or changes its index. */
+export async function captureWorkspaceChanges(workspace, startingRevision, settledTree, fullReview = false) {
+    const patchLimit = fullReview ? 128 * 1024 * 1024 : WORKSPACE_PATCH_LIMIT;
+    const fileLimit = fullReview ? 10_000 : WORKSPACE_FILE_LIMIT;
+    const empty = (state) => ({
+        captured_at: new Date().toISOString(), branch: null, base_revision: null, state,
+        files: [], additions: 0, deletions: 0, hidden_files: 0, patch: '', patch_truncated: false,
+    });
+    try {
+        if ((await git(workspace, ['rev-parse', '--is-inside-work-tree'])).trim() !== 'true')
+            return empty('not_git');
+    }
+    catch (error) {
+        return empty(/not a git repository/i.test(String(error.stderr ?? '')) ? 'not_git' : 'unavailable');
+    }
+    try {
+        if (startingRevision !== null && !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(startingRevision))
+            return empty('unavailable');
+        const branch = await git(workspace, ['symbolic-ref', '--quiet', '--short', 'HEAD']).then(value => value.trim(), () => null);
+        if (settledTree && !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(settledTree))
+            return empty('unavailable');
+        const base = await git(workspace, ['rev-parse', '--verify', `${startingRevision ?? 'HEAD'}^{tree}`])
+            .then(value => value.trim(), error => { if (startingRevision)
+            throw error; return null; });
+        const diffArgs = ['--no-ext-diff', '--no-textconv', '--no-color', '-M'];
+        const [names, stats, untracked] = await Promise.all([
+            base ? git(workspace, ['diff', ...diffArgs, '--name-status', '-z', base, ...(settledTree ? [settledTree] : []), '--']) : Promise.resolve(''),
+            base ? git(workspace, ['diff', ...diffArgs, '--numstat', '-z', base, ...(settledTree ? [settledTree] : []), '--']) : Promise.resolve(''),
+            settledTree ? Promise.resolve('') : git(workspace, ['ls-files', '--others', '--exclude-standard', ...(base ? [] : ['--cached']), '-z']),
+        ]);
+        const files = new Map();
+        const nameParts = names.split('\0');
+        for (let i = 0; i < nameParts.length - 1;) {
+            const code = nameParts[i++];
+            const first = nameParts[i++];
+            const renamed = code.startsWith('R') || code.startsWith('C');
+            const path = renamed ? nameParts[i++] : first;
+            const status = { A: 'added', M: 'modified', D: 'deleted', R: 'renamed', C: 'copied', T: 'typechange' }[code[0]] ?? 'unknown';
+            files.set(path, { path, previous_path: renamed ? first : null, status, additions: 0, deletions: 0, binary: false });
+        }
+        const statParts = stats.split('\0');
+        for (let i = 0; i < statParts.length; i++) {
+            const match = /^([^\t]+)\t([^\t]+)\t([\s\S]*)$/.exec(statParts[i]);
+            if (!match)
+                continue;
+            let path = match[3];
+            if (!path) {
+                path = statParts[i + 2];
+                i += 2;
+            }
+            const file = files.get(path);
+            if (!file)
+                continue;
+            file.binary = match[1] === '-' || match[2] === '-';
+            file.additions = file.binary ? 0 : Number(match[1]);
+            file.deletions = file.binary ? 0 : Number(match[2]);
+        }
+        let patch = '';
+        let truncated = false;
+        if (base) {
+            try {
+                patch = await git(workspace, ['diff', ...diffArgs, '--unified=3', base, ...(settledTree ? [settledTree] : []), '--'], patchLimit);
+            }
+            catch (error) {
+                const failure = error;
+                if (failure.code !== 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER')
+                    throw error;
+                patch = String(failure.stdout ?? '').slice(0, patchLimit);
+                truncated = true;
+            }
+        }
+        const newPaths = [...new Set(untracked.split('\0').filter(Boolean))];
+        let inspectedFiles = 0;
+        for (const path of newPaths) {
+            if (files.has(path))
+                continue;
+            const file = { path, previous_path: null, status: base ? 'untracked' : 'added', additions: 0, deletions: 0, binary: false };
+            files.set(path, file);
+            if (++inspectedFiles > fileLimit) {
+                truncated = true;
+                continue;
+            }
+            // Do not follow symlinks into files outside the workspace.
+            const absolute = join(workspace, path);
+            const metadata = await lstat(absolute);
+            let bytes;
+            if (metadata.isSymbolicLink())
+                bytes = Buffer.from(await readlink(absolute));
+            else if (metadata.isFile() && metadata.size <= 1024 * 1024) {
+                const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    const buffer = Buffer.alloc(1024 * 1024 + 1);
+                    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                    bytes = buffer.subarray(0, bytesRead);
+                    if (bytesRead > 1024 * 1024) {
+                        truncated = true;
+                        continue;
+                    }
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            else {
+                truncated = true;
+                continue;
+            }
+            file.binary = bytes.includes(0);
+            if (file.binary)
+                continue;
+            const text = bytes.toString('utf8');
+            const lines = text ? text.replace(/\n$/, '').split('\n') : [];
+            file.additions = lines.length;
+            if (patch.length < patchLimit) {
+                const label = JSON.stringify(`b/${path}`);
+                const addition = `diff --git ${JSON.stringify(`a/${path}`)} ${label}\nnew file mode ${metadata.isSymbolicLink() ? '120000' : '100644'}\n--- /dev/null\n+++ ${label}\n@@ -0,0 +1,${lines.length} @@\n${lines.map(line => `+${line}\n`).join('')}`;
+                patch += addition;
+            }
+            else
+                truncated = true;
+        }
+        const all = [...files.values()];
+        const result = parseWorkspaceChangeSummary({ ...empty('ready'), branch, base_revision: startingRevision ?? base,
+            files: all.slice(0, fileLimit), additions: all.reduce((n, file) => n + file.additions, 0),
+            deletions: all.reduce((n, file) => n + file.deletions, 0), hidden_files: Math.max(0, all.length - fileLimit),
+            patch: patch.slice(0, patchLimit), patch_truncated: truncated || patch.length > patchLimit,
+        }, fullReview);
+        return result ?? empty('unavailable');
+    }
+    catch {
+        return empty('unavailable');
+    }
+}

package/shared/workspace-change-summary.d.mts

@@ -0,0 +1,24 @@
+export const WORKSPACE_PATCH_LIMIT: number;
+export const WORKSPACE_FILE_LIMIT: number;
+export type WorkspaceChangedFile = {
+  path: string;
+  previous_path: string | null;
+  status: 'added' | 'modified' | 'deleted' | 'renamed' | 'copied' | 'typechange' | 'untracked' | 'unknown';
+  additions: number;
+  deletions: number;
+  binary: boolean;
+};
+export type WorkspaceChangeSummary = {
+  captured_at: string;
+  branch: string | null;
+  /** Immutable workspace starting revision; includes committed work since creation. */
+  base_revision: string | null;
+  state: 'ready' | 'unavailable' | 'not_git';
+  files: WorkspaceChangedFile[];
+  additions: number;
+  deletions: number;
+  hidden_files: number;
+  patch: string;
+  patch_truncated: boolean;
+};
+export function parseWorkspaceChangeSummary(value: unknown, fullReview?: boolean): WorkspaceChangeSummary | null;

package/shared/workspace-change-summary.mjs

@@ -0,0 +1,44 @@
+// Bounded room-visible source changes. Absolute host paths and arbitrary metadata
+// are excluded; patch text is intentional review content, never execution input.
+export const WORKSPACE_PATCH_LIMIT = 128 * 1024;
+export const WORKSPACE_FILE_LIMIT = 200;
+const states = ['added', 'modified', 'deleted', 'renamed', 'copied', 'typechange', 'untracked', 'unknown'];
+const exact = (value, keys) => value && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const count = value => Number.isSafeInteger(value) && value >= 0;
+const path = value => typeof value === 'string' && value.length > 0 && value.length <= 2048
+  && !value.startsWith('/') && !/^[A-Za-z]:/.test(value) && !value.split(/[\\/]/).includes('..')
+  && !/[\x00-\x1f\x7f]/.test(value);
+
+export function parseWorkspaceChangeSummary(value, fullReview = false) {
+  if (!exact(value, ['captured_at', 'branch', 'base_revision', 'state', 'files', 'additions', 'deletions', 'hidden_files', 'patch', 'patch_truncated'])
+    || typeof value.captured_at !== 'string' || !Number.isFinite(Date.parse(value.captured_at))
+    || !(value.branch === null || typeof value.branch === 'string' && value.branch.length <= 256 && !/[\x00-\x1f\x7f]/.test(value.branch))
+    || !(value.base_revision === null || typeof value.base_revision === 'string' && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value.base_revision))
+    || !['ready', 'unavailable', 'not_git'].includes(value.state)
+    || !Array.isArray(value.files) || value.files.length > (fullReview ? 10_000 : WORKSPACE_FILE_LIMIT)
+    || !count(value.additions) || !count(value.deletions) || !count(value.hidden_files)
+    || typeof value.patch !== 'string' || value.patch.length > (fullReview ? 128 * 1024 * 1024 : WORKSPACE_PATCH_LIMIT)
+    || typeof value.patch_truncated !== 'boolean') return null;
+  // Full reviews are byte-bounded by their encoded envelope. Re-serializing each
+  // patch here creates several full-size copies while decoding a large review.
+  if (!fullReview && new TextEncoder().encode(JSON.stringify(value)).length > 480 * 1024) return null;
+  const files = [];
+  const paths = new Set();
+  for (const file of value.files) {
+    if (!exact(file, ['path', 'previous_path', 'status', 'additions', 'deletions', 'binary'])
+      || !path(file.path) || paths.has(file.path)
+      || !(file.previous_path === null || path(file.previous_path)) || !states.includes(file.status)
+      || !count(file.additions) || !count(file.deletions) || typeof file.binary !== 'boolean') return null;
+    paths.add(file.path);
+    files.push({ path: file.path, previous_path: file.previous_path, status: file.status,
+      additions: file.additions, deletions: file.deletions, binary: file.binary });
+  }
+  if (value.state !== 'ready' && (files.length || value.additions || value.deletions || value.hidden_files || value.patch || value.patch_truncated)) return null;
+  if (files.reduce((n, file) => n + file.additions, 0) > value.additions
+    || files.reduce((n, file) => n + file.deletions, 0) > value.deletions) return null;
+  return { captured_at: new Date(value.captured_at).toISOString(), branch: value.branch,
+    base_revision: value.base_revision, state: value.state, files, additions: value.additions,
+    deletions: value.deletions, hidden_files: value.hidden_files, patch: value.patch,
+    patch_truncated: value.patch_truncated };
+}

package/shared/workspace-diff.d.mts

@@ -0,0 +1,9 @@
+import type { WorkspaceChangedFile } from './workspace-change-summary.mjs';
+export type WorkspaceDiffLine = { text: string; kind: 'context' | 'added' | 'deleted' | 'hunk' | 'metadata'; before: number | null; after: number | null };
+export type WorkspaceDiffPageLine = WorkspaceDiffLine & { textLength: number; textOffset: number; nextTextOffset: number | null };
+export type WorkspaceDiffPage = { lines: WorkspaceDiffPageLine[]; nextOffset: number | null; included: boolean };
+export type WorkspaceDiffPageOptions = { offset?: number; textOffset?: number; singleLine?: boolean };
+export type WorkspaceDiffIndex = { patch: string; files: Map<string, { end: number; checkpoints: { position: number; before: number; after: number }[] }> };
+export function createWorkspaceDiffIndex(patch: string, files: WorkspaceChangedFile[]): WorkspaceDiffIndex;
+export function readWorkspaceDiffPage(index: WorkspaceDiffIndex, path: string, options?: WorkspaceDiffPageOptions): WorkspaceDiffPage;
+export function workspaceFilePatches(patch: string, files: WorkspaceChangedFile[], window?: { offset: number; limit: number }): Map<string, WorkspaceDiffLine[]>;

package/shared/workspace-diff.mjs

@@ -0,0 +1,105 @@
+function unquotePath(path) {
+  if (!path.startsWith('"') || !path.endsWith('"')) return path;
+  const bytes = [];
+  const source = path.slice(1, -1);
+  const encoder = new TextEncoder();
+  for (let i = 0; i < source.length;) {
+    const octal = source[i] === '\\' ? /^\\([0-7]{1,3})/.exec(source.slice(i)) : null;
+    if (octal) { bytes.push(parseInt(octal[1], 8)); i += octal[0].length; continue; }
+    if (source[i] === '\\' && i + 1 < source.length) {
+      const char = source[++i];
+      bytes.push(...encoder.encode(({ t: '\t', n: '\n', r: '\r', b: '\b', f: '\f', v: '\v' })[char] ?? char));
+      i++; continue;
+    }
+    const char = String.fromCodePoint(source.codePointAt(i));
+    bytes.push(...encoder.encode(char)); i += char.length;
+  }
+  return new TextDecoder().decode(new Uint8Array(bytes));
+}
+
+// File boundaries and sparse line checkpoints are retained only by an open review.
+export function createWorkspaceDiffIndex(patch, files) {
+  const byPath = new Map(files.map(file => [file.path, file]));
+  const byHeader = new Map(files.flatMap(file => [
+    [`diff --git a/${file.previous_path ?? file.path} b/${file.path}`, file],
+    [`diff --git ${JSON.stringify(`a/${file.previous_path ?? file.path}`)} ${JSON.stringify(`b/${file.path}`)}`, file],
+  ]));
+  const result = { patch, files: new Map() };
+  const boundary = /^diff --git /gm;
+  let current = boundary.exec(patch);
+  while (current) {
+    const next = boundary.exec(patch), end = next?.index ?? patch.length;
+    const headers = [];
+    let position = current.index;
+    while (position < end) {
+      const newline = patch.indexOf('\n', position);
+      const stop = newline < 0 || newline >= end ? end : newline;
+      const line = patch.slice(position, stop);
+      if (line.startsWith('@@ ')) break;
+      headers.push(line); position = stop + 1;
+    }
+    const target = headers.find(line => line.startsWith('+++ '));
+    const source = headers.find(line => line.startsWith('--- '));
+    const path = target && target !== '+++ /dev/null' ? unquotePath(target.slice(4)).replace(/^b\//, '')
+      : source ? unquotePath(source.slice(4)).replace(/^a\//, '') : null;
+    const renamed = headers.find(line => line.startsWith('rename to '));
+    const file = byPath.get(path) ?? (renamed ? byPath.get(unquotePath(renamed.slice(10))) : undefined) ?? byHeader.get(headers[0]);
+    if (file) result.files.set(file.path, { end, checkpoints: [{ position, before: 0, after: 0 }] });
+    current = next;
+  }
+  return result;
+}
+
+function readLines(index, path, offset, limit, textOffset, characterLimit, budget) {
+  const file = index.files.get(path);
+  if (!file) return { lines: [], nextOffset: null, included: false };
+  const checkpointIndex = Math.min(Math.floor(offset / 500), file.checkpoints.length - 1);
+  let { position, before, after } = file.checkpoints[checkpointIndex];
+  let row = checkpointIndex * 500;
+  const lines = [];
+  while (position < file.end) {
+    const newline = index.patch.indexOf('\n', position);
+    const stop = newline < 0 || newline >= file.end ? file.end : newline;
+    const start = position;
+    position = stop + 1;
+    // Only hunk headers need a regular expression; never slice a giant code line.
+    const first = index.patch[start];
+    const hunk = first === '@' ? /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(index.patch.slice(start, Math.min(stop, start + 256))) : null;
+    let kind, oldLine = null, newLine = null, contentStart = start;
+    if (hunk) { before = Number(hunk[1]); after = Number(hunk[2]); kind = 'hunk'; }
+    else if (first === '+') { kind = 'added'; contentStart++; newLine = after++; }
+    else if (first === '-') { kind = 'deleted'; contentStart++; oldLine = before++; }
+    else if (first === ' ') { kind = 'context'; contentStart++; oldLine = before++; newLine = after++; }
+    else if (stop > start) kind = 'metadata';
+    else continue;
+    if (row >= offset) {
+      const textLength = stop - contentStart;
+      let from = Math.min(textOffset, textLength), to = Math.min(textLength, from + characterLimit, from + budget);
+      // Keep UTF-16 surrogate pairs intact at display-chunk boundaries.
+      if (from && /[\uDC00-\uDFFF]/.test(index.patch[contentStart + from]) && /[\uD800-\uDBFF]/.test(index.patch[contentStart + from - 1])) from--;
+      if (to < textLength && /[\uD800-\uDBFF]/.test(index.patch[contentStart + to - 1])) to--;
+      const text = index.patch.slice(contentStart + from, contentStart + to);
+      lines.push({ text, kind, before: oldLine, after: newLine, textLength, textOffset: from, nextTextOffset: to < textLength ? to : null });
+      budget -= text.length;
+    }
+    row++;
+    if (row % 500 === 0 && !file.checkpoints[row / 500]) file.checkpoints[row / 500] = { position, before, after };
+    if (lines.length >= limit || budget <= 0) break;
+  }
+  return { lines, nextOffset: position < file.end ? row : null, included: true };
+}
+
+export function readWorkspaceDiffPage(index, path, options = {}) {
+  const { offset = 0, textOffset = 0, singleLine = false } = options;
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > index.patch.length
+    || !Number.isSafeInteger(textOffset) || textOffset < 0 || textOffset > index.patch.length) throw new Error('Invalid diff page.');
+  return readLines(index, path, offset, singleLine ? 1 : 500, textOffset, 4096, 128 * 1024);
+}
+
+// Existing callers can still inspect a small preview without a review session.
+export function workspaceFilePatches(patch, files, window) {
+  const index = createWorkspaceDiffIndex(patch, files);
+  return new Map([...index.files.keys()].map(path => [path,
+    readLines(index, path, window?.offset ?? 0, window?.limit ?? Infinity, 0, Infinity, Infinity).lines
+      .map(({ text, kind, before, after }) => ({ text, kind, before, after }))]));
+}

package/shared/workspace-review-worker.mjs

@@ -0,0 +1,47 @@
+import { parentPort } from 'node:worker_threads';
+import { DatabaseSync } from 'node:sqlite';
+import { decodeWorkspaceReview, parseWorkspaceReviewPage } from './workspace-review.mjs';
+import { createWorkspaceDiffIndex, readWorkspaceDiffPage } from './workspace-diff.mjs';
+
+let review = null;
+let pages = [], digest = '', total = 0;
+const indexes = new Map();
+const describe = () => ({ version: 1, workspace: { ...review.workspace, patch: '' }, contribution: { ...review.contribution, patch: '' } });
+parentPort.on('message', ({ id, method, input }) => {
+  try {
+    let result;
+    if (method === 'local') {
+      let db;
+      try {
+        db = new DatabaseSync(input.databasePath, { readOnly: true });
+        const row = db.prepare(`SELECT r.data,r.digest FROM room_workspace_reviews r JOIN room_work_publications p
+          USING(agent_id,room_id,source_message_id) WHERE p.room_id=? AND p.agent_key=? AND p.source_message_id=? AND p.api_origin=? AND p.state='open'`)
+          .get(input.roomId, input.agentKey, input.sourceMessageId, input.apiOrigin);
+        if (row) review = decodeWorkspaceReview(String(row.data), String(row.digest));
+      } catch { review = null; } finally { db?.close(); }
+      result = review ? describe() : null;
+    } else if (method === 'append') {
+      if (!Array.isArray(input) || input.length > 4) throw new Error('Invalid review pages.');
+      if (!pages.length) { review = null; indexes.clear(); }
+      for (const raw of input) {
+        const page = parseWorkspaceReviewPage(raw);
+        if (!page || page.index !== pages.length || (pages.length && (page.digest !== digest || page.total !== total))) throw new Error('Incomplete workspace review.');
+        digest = page.digest; total = page.total; pages.push(page.data);
+      }
+      result = null;
+    } else if (method === 'finish') {
+      if (!total || pages.length !== total) throw new Error('Incomplete workspace review.');
+      const data = pages.join(''); pages = [];
+      review = decodeWorkspaceReview(data, digest);
+      result = describe();
+    } else if (method === 'page') {
+      if (!review || !['workspace', 'contribution'].includes(input.view) || typeof input.path !== 'string') throw new Error('Review is not open.');
+      if (!indexes.has(input.view)) {
+        const snapshot = review[input.view];
+        indexes.set(input.view, createWorkspaceDiffIndex(snapshot.patch, snapshot.files));
+      }
+      result = readWorkspaceDiffPage(indexes.get(input.view), input.path, input);
+    } else throw new Error('Invalid review operation.');
+    parentPort.postMessage({ id, result });
+  } catch (error) { parentPort.postMessage({ id, error: error.message }); }
+});

package/shared/workspace-review.d.mts

@@ -0,0 +1,10 @@
+import type { WorkspaceChangeSummary } from './workspace-change-summary.mjs';
+export const REVIEW_LIMIT: number;
+export const REVIEW_PAGE_SIZE: number;
+export const REVIEW_MAX_PAGES: number;
+export type WorkspaceReview = { version: 1; workspace: WorkspaceChangeSummary; contribution: WorkspaceChangeSummary };
+export type WorkspaceReviewPage = { digest: string; index: number; total: number; data: string };
+export function parseWorkspaceReview(value: unknown): WorkspaceReview | null;
+export function encodeWorkspaceReview(value: WorkspaceReview): { data: string; digest: string };
+export function decodeWorkspaceReview(data: string, digest: string): WorkspaceReview;
+export function parseWorkspaceReviewPage(value: unknown): WorkspaceReviewPage | null;

package/shared/workspace-review.mjs

@@ -0,0 +1,45 @@
+import { createHash } from 'node:crypto';
+import { gzipSync, gunzipSync } from 'node:zlib';
+import { parseWorkspaceChangeSummary } from './workspace-change-summary.mjs';
+
+// Full review bytes travel separately from the bounded room timeline.
+export const REVIEW_LIMIT = 128 * 1024 * 1024;
+export const REVIEW_PAGE_SIZE = 64 * 1024;
+export const REVIEW_MAX_PAGES = REVIEW_LIMIT / REVIEW_PAGE_SIZE;
+export function parseWorkspaceReview(value) {
+  if (!value || value.version !== 1 || Object.keys(value).sort().join(',') !== 'contribution,version,workspace') return null;
+  const workspace = parseWorkspaceChangeSummary(value.workspace, true);
+  const contribution = parseWorkspaceChangeSummary(value.contribution, true);
+  if (!workspace || !contribution) return null;
+  return { version: 1, workspace, contribution };
+}
+export function encodeWorkspaceReview(value) {
+  const parsed = parseWorkspaceReview(value);
+  if (!parsed) throw new Error('Invalid full workspace review.');
+  const json = JSON.stringify(parsed);
+  if (Buffer.byteLength(json) > REVIEW_LIMIT) throw new RangeError('Workspace review exceeds capture capacity.');
+  const data = gzipSync(json).toString('base64');
+  if (data.length > REVIEW_LIMIT) throw new RangeError('Workspace review exceeds transfer capacity.');
+  return { data, digest: createHash('sha256').update(data).digest('hex') };
+}
+export function decodeWorkspaceReview(data, digest) {
+  if (typeof data !== 'string' || data.length > REVIEW_LIMIT || createHash('sha256').update(data).digest('hex') !== digest) throw new Error('Incomplete workspace review.');
+  const compressed = Buffer.from(data, 'base64');
+  // Our single-member gzip records its output size in the trailer. Use it only
+  // as a bounded allocation hint: zlib still verifies CRC/size and enforces the
+  // output limit. One spare byte avoids allocating another full output buffer.
+  const chunkSize = compressed.length < 4 ? 16 * 1024
+    : Math.max(16 * 1024, Math.min(REVIEW_LIMIT + 1, compressed.readUInt32LE(compressed.length - 4) + 1));
+  const value = parseWorkspaceReview(JSON.parse(gunzipSync(compressed, { maxOutputLength: REVIEW_LIMIT, chunkSize }).toString('utf8')));
+  if (!value) throw new Error('Invalid workspace review.');
+  return value;
+}
+export function parseWorkspaceReviewPage(value) {
+  if (!value || Object.keys(value).sort().join(',') !== 'data,digest,index,total'
+    || typeof value.digest !== 'string' || !/^[a-f0-9]{64}$/.test(value.digest)
+    || !Number.isSafeInteger(value.total) || value.total < 1 || value.total > REVIEW_MAX_PAGES
+    || !Number.isSafeInteger(value.index) || value.index < 0 || value.index >= value.total
+    || typeof value.data !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value.data)
+    || value.data.length > REVIEW_PAGE_SIZE || (value.index < value.total - 1 && value.data.length !== REVIEW_PAGE_SIZE)) return null;
+  return { digest: value.digest, index: value.index, total: value.total, data: value.data };
+}

package/shared/workspace-turn-capture.d.mts

@@ -0,0 +1,10 @@
+import type { WorkspaceChangeSummary } from './workspace-change-summary.mjs';
+import type { WorkspaceReview } from './workspace-review.mjs';
+export function unavailableWorkspace(): WorkspaceChangeSummary;
+export function captureWorkspaceTree(workspace: string, identity: string): Promise<string | null>;
+export function releaseWorkspaceTree(workspace: string, identity: string): Promise<void>;
+export function captureWorkspacePair(workspace: string, startingRevision: string | null, baseline: string | null, identity: string): Promise<{
+  workspace: WorkspaceChangeSummary;
+  contribution: { changes: WorkspaceChangeSummary; summary: string | null };
+  review: WorkspaceReview;
+}>;

package/shared/workspace-turn-capture.mjs

@@ -0,0 +1,118 @@
+import { execFile } from 'node:child_process';
+import { constants } from 'node:fs';
+import { lstat, mkdtemp, open, readlink, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative } from 'node:path';
+import { createHash } from 'node:crypto';
+import { captureWorkspaceChanges } from './workspace-change-capture.mjs';
+const environment = () => Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+function git(cwd, args, signal, index, input) {
+    return new Promise((resolve, reject) => {
+        const child = execFile('git', ['-c', 'core.hooksPath=/dev/null', '--no-optional-locks', ...args], {
+            cwd, signal, timeout: 5_000, maxBuffer: 4 * 8 * 1024 * 1024, encoding: 'utf8',
+            env: { ...environment(), GIT_TERMINAL_PROMPT: '0', ...(index ? { GIT_INDEX_FILE: index } : {}) },
+        }, (error, stdout) => error ? reject(error) : resolve(stdout));
+        child.stdin?.on('error', () => { });
+        child.stdin?.end(input);
+    });
+}
+export const unavailableWorkspace = () => ({ captured_at: new Date().toISOString(), branch: null,
+    base_revision: null, state: 'unavailable', files: [], additions: 0, deletions: 0, hidden_files: 0, patch: '', patch_truncated: false });
+const reviewRef = (identity) => `refs/letagents/workspace-review/${createHash('sha256').update(identity).digest('hex')}`;
+/** Retained Git tree, with no changes to the user's index, branch, or working files.
+ * Unsupported/oversized observations fail closed; a partial baseline is never a turn diff. */
+export async function captureWorkspaceTree(workspace, identity) {
+    const signal = AbortSignal.timeout(20_000);
+    const scratch = await mkdtemp(join(tmpdir(), 'letagents-workspace-'));
+    const index = join(scratch, 'index');
+    try {
+        const root = await realpath(workspace);
+        const head = (await git(root, ['rev-parse', '--verify', 'HEAD^{tree}'], signal)).trim();
+        await git(root, ['read-tree', head], signal, index);
+        const original = new Map((await git(root, ['ls-tree', '-r', '-z', head], signal)).split('\0').filter(Boolean).map(entry => {
+            const split = entry.indexOf('\t');
+            return [entry.slice(split + 1), entry.slice(0, split).split(' ')];
+        }));
+        const paths = [...new Set([...original.keys(), ...(await git(root, ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], signal)).split('\0').filter(Boolean)])];
+        if (paths.length > 10_000)
+            return null;
+        const entries = [];
+        let bytesRead = 0;
+        for (const path of paths) {
+            // Parent symlinks must not redirect an observation outside the managed workspace.
+            const parent = await realpath(dirname(join(root, path))).catch(() => null);
+            if (parent && (relative(root, parent).startsWith('..') || relative(root, parent).startsWith('/')))
+                return null;
+            if (signal.aborted)
+                return null;
+            const absolute = join(root, path);
+            const stat = await lstat(absolute).catch(error => { if (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+                return null; throw error; });
+            if (original.get(path)?.[1] === 'commit')
+                return null; // Submodules need their own workspace.
+            if (!stat) {
+                entries.push(`0 ${'0'.repeat(head.length)}\t${path}\0`);
+                continue;
+            }
+            let bytes;
+            if (stat.isSymbolicLink())
+                bytes = Buffer.from(await readlink(absolute));
+            else if (stat.isFile() && stat.size <= 8 * 1024 * 1024) {
+                const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    const buffer = Buffer.alloc(8 * 1024 * 1024 + 1);
+                    const read = await handle.read(buffer, 0, buffer.length, 0);
+                    bytes = buffer.subarray(0, read.bytesRead);
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            else
+                return null; // Includes submodule changes: do not attribute a fabricated text diff.
+            bytesRead += bytes.length;
+            if (bytes.length > 8 * 1024 * 1024 || bytesRead > 64 * 1024 * 1024)
+                return null;
+            const mode = stat.isSymbolicLink() ? '120000' : stat.mode & 0o111 ? '100755' : '100644';
+            const rawOid = createHash(head.length === 64 ? 'sha256' : 'sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+            if (original.get(path)?.[0] === mode && original.get(path)?.[2] === rawOid)
+                continue;
+            if (entries.length >= 10_000)
+                return null;
+            const oid = (await git(root, ['hash-object', '-w', '--no-filters', '--stdin'], signal, undefined, bytes)).trim();
+            entries.push(`${mode} ${oid}\t${path}\0`);
+        }
+        if (entries.length)
+            await git(root, ['update-index', '-z', '--index-info'], signal, index, entries.join(''));
+        const tree = (await git(root, ['write-tree'], signal, index)).trim();
+        await git(root, ['update-ref', reviewRef(identity), tree], signal);
+        return tree;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+export async function releaseWorkspaceTree(workspace, identity) {
+    try {
+        await git(workspace, ['update-ref', '-d', reviewRef(identity)], AbortSignal.timeout(5_000));
+    }
+    catch { /* Retain on failure, never jeopardize provider work. */ }
+}
+export async function captureWorkspacePair(workspace, startingRevision, baseline, identity) {
+    const tree = await captureWorkspaceTree(workspace, `${identity}:settled`);
+    try {
+        const full = tree ? await captureWorkspaceChanges(workspace, startingRevision, tree, true) : unavailableWorkspace();
+        const changes = tree && baseline ? await captureWorkspaceChanges(workspace, baseline, tree, true) : unavailableWorkspace();
+        const preview = (snapshot) => ({ ...snapshot,
+            files: snapshot.files.slice(0, 200), hidden_files: snapshot.hidden_files + Math.max(0, snapshot.files.length - 200),
+            patch: snapshot.patch.slice(0, 48 * 1024), patch_truncated: snapshot.patch_truncated || snapshot.patch.length > 48 * 1024 });
+        return { workspace: preview(full), contribution: { changes: preview(changes), summary: null },
+            review: { version: 1, workspace: full, contribution: changes } };
+    }
+    finally {
+        await releaseWorkspaceTree(workspace, `${identity}:settled`);
+    }
+}