@myagentroam/node 0.9.107 → 0.9.109

package/dist/capabilities.js

@@ -8,6 +8,7 @@ const nodeAppVersion = typeof nodePackage.version === 'string' ? nodePackage.ver
 const runtimeCredentialCapability = () => ({
     apiVersion: 1,
     websocket: true,
+    fastMode: true,
     httpVersions: ['1.1', '2']
 });
 const workspaceDirectTransferCapability = () => ({
@@ -19,6 +20,10 @@ const workspaceDirectTransferCapability = () => ({
     gitCommitBlob: true,
     maxChunkBytes: 256 * 1024
 });
+const terminalDirectCapability = () => ({
+    apiVersion: 1,
+    transport: true
+});
 export function reportedPlatform(platform = process.platform) {
     if (platform === 'win32')
         return 'windows';
@@ -47,7 +52,8 @@ export function unavailableCapabilities() {
         openCode: { available: false },
         marAgent: { available: true, version: nodeAppVersion },
         marAgentRuntimeCredentials: runtimeCredentialCapability(),
-        workspaceDirectTransfer: workspaceDirectTransferCapability()
+        workspaceDirectTransfer: workspaceDirectTransferCapability(),
+        terminalDirect: terminalDirectCapability()
     };
 }
 export function detectCapabilities(commands = {}) {
@@ -80,7 +86,8 @@ export function detectCapabilities(commands = {}) {
         },
         marAgent: { available: true, version: nodeAppVersion },
         marAgentRuntimeCredentials: runtimeCredentialCapability(),
-        workspaceDirectTransfer: workspaceDirectTransferCapability()
+        workspaceDirectTransfer: workspaceDirectTransferCapability(),
+        terminalDirect: terminalDirectCapability()
     };
 }
 export async function detectCapabilitiesAsync(commands = {}) {
@@ -117,6 +124,7 @@ export async function detectCapabilitiesAsync(commands = {}) {
         },
         marAgent: { available: true, version: nodeAppVersion },
         marAgentRuntimeCredentials: runtimeCredentialCapability(),
-        workspaceDirectTransfer: workspaceDirectTransferCapability()
+        workspaceDirectTransfer: workspaceDirectTransferCapability(),
+        terminalDirect: terminalDirectCapability()
     };
 }

package/dist/claude-agent-sdk.js

@@ -301,7 +301,8 @@ export async function probeClaudeCodeAsync(command = 'claude') {
     const authInvocation = platformCliInvocation(command, ['auth', 'status', '--json']);
     const authResult = await runRunnerProbe(authInvocation.command, authInvocation.args, {
         env: minimalRunnerEnvironment(),
-        timeoutMs: 3_000
+        timeoutMs: 3_000,
+        logStderr: false
     });
     let authenticated = false;
     if (authResult.status === 0) {

package/dist/connector.js

@@ -1133,6 +1133,7 @@ export class NodeConnector {
             handleNodeRequest: (envelope) => this.nodeRequests.handle(envelope),
             handleRuntimeCredentialResponse: (envelope) => this.runtimeCredentials.handle(envelope),
             handleDirectTransfer: (envelope) => this.handleDirectTransfer(envelope),
+            handleTerminalDirect: (envelope) => this.handleTerminalDirect(envelope),
             reconcileRuns: (envelope) => this.runEventBridge.reconcile(envelope),
             runners: this.runners,
             deliverSessionChannelMessage: (envelope) => this.runnerChannelMessages.handle(envelope),
@@ -1456,6 +1457,9 @@ export class NodeConnector {
             return new DirectTransferService({
                 nodeGeneration: () => this.nodeGeneration,
                 send: (type, payload) => this.send(type, payload),
+                terminalManager: this.terminalManager,
+                sendTerminalReady: (directSessionId) => this.send('terminal.direct.ready', { directSessionId }),
+                sendTerminalTakeover: (directSessionId) => this.send('terminal.direct.takeover', { directSessionId }),
                 udpPortRange: () => directTransferUdpPortRange(this.config),
                 openUpload: async (descriptor) => {
                     if (descriptor.direction !== 'UPLOAD' || descriptor.resource.kind !== 'WORKSPACE_FILE')
@@ -1512,6 +1516,13 @@ export class NodeConnector {
         });
         return true;
     }
+    handleTerminalDirect(envelope) {
+        const command = {
+            type: envelope.type,
+            ...(typeof envelope.payload === 'object' && envelope.payload !== null ? envelope.payload : {})
+        };
+        return this.directTransferService?.handleTerminal(command) ?? false;
+    }
     clearMissionRetry(sessionId) {
         const retry = this.missionRetryTimers.get(sessionId);
         if (retry !== undefined)

package/dist/operational.js

@@ -1,8 +1,10 @@
 import { spawn } from 'node:child_process';
+import { basename } from 'node:path';
 import { writeNodeLog } from './rotating-log.js';
 const secretKey = /(?:password|credential|token|cookie|authorization|secret|api[_-]?key)/i;
 export function runRunnerProbe(command, args, options) {
     return new Promise((resolve) => {
+        const startedAt = performance.now();
         const child = spawn(command, args, {
             windowsHide: true,
             env: options.env,
@@ -11,22 +13,29 @@ export function runRunnerProbe(command, args, options) {
         let stdout = '';
         let stderr = '';
         let settled = false;
-        const finish = (status) => {
+        const finish = (status, reason) => {
             if (settled)
                 return;
             settled = true;
             clearTimeout(timer);
+            if (status !== 0)
+                logNodeCommandFailure(basename(command), {
+                    ...(status === null ? {} : { exitCode: status }),
+                    ...(options.logStderr === false ? {} : { stderr }),
+                    ...(reason === undefined ? {} : { reason }),
+                    durationMs: Math.round(performance.now() - startedAt)
+                });
             resolve({ status, stdout, stderr });
         };
         const timer = setTimeout(() => {
-            finish(null);
+            finish(null, 'TIMEOUT');
             child.kill();
         }, options.timeoutMs);
         child.stdout.setEncoding('utf8');
         child.stderr.setEncoding('utf8');
         child.stdout.on('data', (value) => (stdout += value));
         child.stderr.on('data', (value) => (stderr += value));
-        child.once('error', () => finish(null));
+        child.once('error', (error) => finish(null, error.code ?? 'START_FAILED'));
         child.once('close', (status) => finish(status));
     });
 }
@@ -120,3 +129,14 @@ export function nodeLog(event, fields = {}) {
     process.stdout.write(line);
     writeNodeLog(line);
 }
+/** Logs Node-owned subprocess failures without copying argv, stdout or environment values. */
+export function logNodeCommandFailure(command, result) {
+    const details = result.stderr?.trim().slice(0, 1_000);
+    nodeLog('node.command.failed', {
+        command,
+        ...(result.exitCode === undefined ? {} : { exitCode: result.exitCode }),
+        ...(result.reason === undefined ? {} : { reason: result.reason }),
+        ...(result.durationMs === undefined ? {} : { durationMs: result.durationMs }),
+        ...(details ? { errorDetails: details } : {})
+    });
+}

package/dist/runner/mar-agent/conversation-normalizer.js

@@ -134,8 +134,10 @@ export class MarAgentConversationNormalizer {
             if (action === 'start' && typeof input.command === 'string') {
                 const command = {
                     itemId: ownItemId,
+                    turnKey: event.turnId ?? event.executionId,
                     command: compactRunnerText(input.command, 10_000),
                     cwd: typeof input.cwd === 'string' ? compactRunnerText(input.cwd, 4_096) : null,
+                    status: 'IN_PROGRESS',
                     outputPreview: '',
                     exitCode: null,
                     truncated: false
@@ -154,6 +156,29 @@ export class MarAgentConversationNormalizer {
                 typeof input.processId === 'string') {
                 const origin = this.#processOrigins.get(input.processId);
                 if (origin !== undefined) {
+                    const previous = this.#commands.get(origin);
+                    const sameTurn = previous?.turnKey === (event.turnId ?? event.executionId);
+                    if (previous !== undefined && !sameTurn) {
+                        const command = {
+                            itemId: ownItemId,
+                            turnKey: event.turnId ?? event.executionId,
+                            command: previous.command,
+                            cwd: previous.cwd,
+                            status: 'IN_PROGRESS',
+                            outputPreview: '',
+                            exitCode: null,
+                            truncated: false
+                        };
+                        this.#commands.set(event.callId, command);
+                        this.#tools.set(event.callId, {
+                            toolName: event.toolName,
+                            input: event.input,
+                            itemId: ownItemId,
+                            structured: true,
+                            commandOrigin: event.callId
+                        });
+                        return [];
+                    }
                     this.#tools.set(event.callId, {
                         toolName: event.toolName,
                         input: event.input,
@@ -201,6 +226,7 @@ export class MarAgentConversationNormalizer {
                     : result.status === 'completed' && result.exitCode === 0
                         ? 'COMPLETED'
                         : 'FAILED';
+                command.status = status;
                 return [commandItem(command, status)];
             }
         }
@@ -256,8 +282,15 @@ export class MarAgentConversationNormalizer {
         const state = this.#tools.get(event.callId);
         if (event.toolName === 'exec' && state?.commandOrigin !== undefined) {
             const command = this.#commands.get(state.commandOrigin);
-            if (command !== undefined)
+            const input = record(state.input);
+            if (command !== undefined &&
+                command.status === 'IN_PROGRESS' &&
+                (state.itemId !== command.itemId ||
+                    input?.action === 'start' ||
+                    (input?.action == null && typeof input?.command === 'string'))) {
+                command.status = 'FAILED';
                 return [commandItem(command, 'FAILED')];
+            }
         }
         if (event.toolName === 'apply_patch' && state?.structured === true)
             return [fileChangeItem(state?.itemId ?? itemId('tool', event.callId), 'FAILED', [])];
@@ -361,7 +394,9 @@ function commandItem(command, status) {
 function applyCommandResult(command, result) {
     const output = [result.stdout, result.stderr].filter(Boolean).join('\n');
     if (output.length > 0) {
-        const combined = [command.outputPreview, output].filter(Boolean).join('\n');
+        const combined = result.cached
+            ? output
+            : [command.outputPreview, output].filter(Boolean).join('\n');
         command.truncated ||= combined.length > 10_000;
         command.outputPreview = compactRunnerText(combined, 10_000);
     }
@@ -443,6 +478,7 @@ function execResult(value, summary, eventTruncated = false) {
         stdout,
         stderr,
         ...(exitCode === undefined ? {} : { exitCode }),
+        ...(data?.cached === true || summaryData?.cached === true ? { cached: true } : {}),
         truncated: eventTruncated ||
             data?.truncated === true ||
             summaryData?.truncated === true ||

package/dist/runner/mar-agent/managed-run-controller.js

@@ -511,6 +511,7 @@ export class MarAgentManagedRunController {
                 agent,
                 session,
                 host: localHost,
+                normalizer: new MarAgentConversationNormalizer(),
                 mcpLease,
                 dynamicCredentials,
                 models,
@@ -639,7 +640,7 @@ export class MarAgentManagedRunController {
                 itemId: boundedConversationItemId('mar-agent-message', event.itemId)
             });
         else {
-            let normalizer = this.#normalizers.get(runId);
+            let normalizer = this.#normalizers.get(runId) ?? this.#sessionRuntimes.get(event.sessionId)?.normalizer;
             if (normalizer === undefined) {
                 normalizer = new MarAgentConversationNormalizer();
                 this.#normalizers.set(runId, normalizer);

package/dist/runner/mar-agent/runtime-model-factory.js

@@ -64,6 +64,7 @@ export class MarAgentRuntimeModelFactory {
                     titleGeneration: configuration.titleGeneration,
                     codeMode: configuration.codeMode,
                     highDensityCompaction: configuration.highDensityCompaction,
+                    ...(configuration.fastMode === true ? { fastMode: true } : {}),
                     hostedWebSearch: configuration.hostedWebSearch,
                     ...(imageGeneration === undefined ? {} : { imageGeneration }),
                     ...(configuration.responsesTransport === undefined

package/dist/service/code-navigation/ctags-index-storage.js

@@ -4,6 +4,7 @@ import { createReadStream, createWriteStream } from 'node:fs';
 import { lstat, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
 import { relative, resolve, sep } from 'node:path';
 import { createInterface } from 'node:readline';
+import { logNodeCommandFailure } from '../../operational.js';
 import { compareTagNames } from './ctags-query.js';
 import { sourceFileFingerprint } from './navigation-target-validator.js';
 const BUILD_TIMEOUT_MS = 120_000;
@@ -175,6 +176,15 @@ export async function runCtags(executable, cwd, fileList, destination) {
             windowsHide: true,
             stdio: ['ignore', 'ignore', 'pipe']
         });
+        const errors = [];
+        let errorBytes = 0;
+        const stderr = () => Buffer.concat(errors).toString('utf8');
+        const reportFailure = (reason, exitCode) => logNodeCommandFailure('ctags', {
+            reason,
+            ...(exitCode === undefined ? {} : { exitCode }),
+            stderr: stderr(),
+            durationMs: Date.now() - startedAt
+        });
         let settled = false;
         const settle = (callback) => {
             if (settled)
@@ -197,12 +207,32 @@ export async function runCtags(executable, cwd, fileList, destination) {
         };
         const timer = setTimeout(() => {
             terminate();
-            settle(() => reject(new Error('SYMBOL_INDEX_BUILD_FAILED')));
+            settle(() => {
+                reportFailure('TIMEOUT');
+                reject(new Error('SYMBOL_INDEX_BUILD_FAILED'));
+            });
         }, BUILD_TIMEOUT_MS);
         timer.unref();
-        child.stderr.on('data', () => undefined);
-        child.once('error', () => settle(() => reject(new Error('SYMBOL_INDEX_BUILD_FAILED'))));
-        child.once('exit', (code) => settle(() => (code === 0 ? resolvePromise() : reject(new Error('SYMBOL_INDEX_BUILD_FAILED')))));
+        child.stderr.on('data', (chunk) => {
+            const remaining = Math.max(0, 1_000 - errorBytes);
+            if (remaining === 0)
+                return;
+            const retained = chunk.subarray(0, remaining);
+            errors.push(retained);
+            errorBytes += retained.length;
+        });
+        child.once('error', (error) => settle(() => {
+            reportFailure(error.code ?? 'START_FAILED');
+            reject(new Error('SYMBOL_INDEX_BUILD_FAILED'));
+        }));
+        child.once('close', (code) => settle(() => {
+            if (code === 0)
+                resolvePromise();
+            else {
+                reportFailure('EXIT', code ?? undefined);
+                reject(new Error('SYMBOL_INDEX_BUILD_FAILED'));
+            }
+        }));
     });
     return Date.now() - startedAt;
 }

package/dist/service/direct-transfer-service.js

@@ -1,4 +1,5 @@
 import { directDataControlFrameSchema, directNodeCommandSchema } from '@myagentroam/protocol';
+import { TerminalDirectService } from './terminal-direct-service.js';
 import { IceUdpMuxListener as NativeIceUdpMuxListener } from 'node-datachannel';
 import { RTCPeerConnection } from 'node-datachannel/polyfill';
 const MAX_HOST_CANDIDATES = 32;
@@ -18,6 +19,7 @@ export class DirectTransferService {
     peerConfiguration;
     leaseGraceMs;
     leaseCheckMs;
+    terminalDirect;
     disposed = false;
     constructor(options) {
         this.options = options;
@@ -37,6 +39,17 @@ export class DirectTransferService {
                 ((configuration) => new RTCPeerConnection(configuration));
         this.leaseGraceMs = options.leaseGraceMs ?? LEASE_GRACE_MS;
         this.leaseCheckMs = options.leaseCheckMs ?? LEASE_CHECK_MS;
+        if (options.terminalManager !== undefined)
+            this.terminalDirect = new TerminalDirectService(options.terminalManager, (id) => options.sendTerminalReady?.(id), (id) => options.sendTerminalTakeover?.(id), (command, peer) => {
+                const transport = this.transports.get(command.transportSessionId);
+                return (transport?.peer === peer &&
+                    transport.command.workbenchConnectionId === command.workbenchConnectionId &&
+                    transport.command.nodeGeneration === command.nodeGeneration &&
+                    command.nodeGeneration === options.nodeGeneration() &&
+                    peer.connectionState === 'connected' &&
+                    command.browserFingerprint === fingerprint(peer.remoteDescription?.sdp) &&
+                    command.nodeFingerprint === fingerprint(peer.localDescription?.sdp));
+            }, this.now);
     }
     handle(value) {
         const parsed = directNodeCommandSchema.safeParse(value);
@@ -54,7 +67,11 @@ export class DirectTransferService {
         });
         return true;
     }
+    handleTerminal(value) {
+        return this.terminalDirect?.handle(value, (id) => this.transports.get(id)?.peer) ?? false;
+    }
     close() {
+        this.terminalDirect?.close();
         for (const transfer of [...this.transfers.values()])
             void this.removeTransfer(transfer, 'DIRECT_NODE_STOPPED');
         for (const transport of [...this.transports.values()])
@@ -65,6 +82,7 @@ export class DirectTransferService {
             return;
         this.disposed = true;
         this.close();
+        this.terminalDirect?.dispose();
         this.iceUdpMuxListener.stop();
     }
     async dispatch(command) {
@@ -236,6 +254,12 @@ export class DirectTransferService {
             if (attached)
                 return;
             attached = true;
+            if (channel.label.startsWith('mar-terminal-')) {
+                this.terminalDirect?.open(transport.command.directSessionId, channel, event.data);
+                if (this.terminalDirect === undefined)
+                    channel.close();
+                return;
+            }
             void this.openChannel(transport, channel, event.data).catch((error) => {
                 channel.close();
                 const id = openFrameSessionId(event.data);
@@ -396,6 +420,7 @@ export class DirectTransferService {
         if (!this.transports.delete(transport.command.directSessionId))
             return;
         clearInterval(transport.leaseTimer);
+        this.terminalDirect?.removeTransport(transport.command.directSessionId);
         for (const transfer of [...this.transfers.values()])
             if (transfer.command.transportSessionId === transport.command.directSessionId)
                 void this.removeTransfer(transfer, code ?? 'DIRECT_CONNECTION_FAILED');

package/dist/service/hosted-conversation-node-service.js

@@ -2004,6 +2004,7 @@ function modelSummary(model, index) {
         titleGeneration: model.titleGeneration,
         codeMode: model.codeMode,
         highDensityCompaction: model.highDensityCompaction,
+        ...(model.fastMode === true ? { fastMode: true } : {}),
         hostedWebSearch: model.hostedWebSearch,
         ...(model.responsesTransport === undefined
             ? {}

package/dist/service/node-control-message-service.js

@@ -38,6 +38,9 @@ export class NodeControlMessageService {
         if (envelope.type.startsWith('direct.') &&
             this.options.handleDirectTransfer?.(envelope) === true)
             return;
+        if (envelope.type.startsWith('terminal.direct.') &&
+            this.options.handleTerminalDirect?.(envelope) === true)
+            return;
         if (envelope.type === 'ack')
             return;
         if (envelope.type === 'runs.reconcile') {

package/dist/service/terminal-direct-service.js

@@ -0,0 +1,202 @@
+import { terminalDataFrameSchema, terminalDirectNodeCommandSchema, terminalDirectOpenFrameSchema } from '@myagentroam/protocol';
+const MAX_SESSIONS = 128;
+const MAX_BUFFERED_BYTES = 1024 * 1024;
+const MAX_FRAME_BYTES = 128 * 1024;
+const HEARTBEAT_GRACE_MS = 30_000;
+export class TerminalDirectService {
+    manager;
+    sendReady;
+    sendTakeover;
+    verifyTransport;
+    sessions = new Map();
+    timer;
+    stopListening;
+    now;
+    constructor(manager, sendReady, sendTakeover, verifyTransport, now = Date.now) {
+        this.manager = manager;
+        this.sendReady = sendReady;
+        this.sendTakeover = sendTakeover;
+        this.verifyTransport = verifyTransport;
+        this.now = now;
+        this.stopListening = manager.onFrame((frame) => {
+            for (const session of this.sessions.values())
+                if (session.opened && session.command.terminalId === frame.terminalId)
+                    this.sendFrame(session, frame);
+        });
+        this.timer = setInterval(() => {
+            for (const session of [...this.sessions.values()])
+                if (session.expiresAt <= this.now() ||
+                    this.now() - session.lastHeartbeat > HEARTBEAT_GRACE_MS)
+                    this.remove(session);
+        }, 5_000);
+        this.timer.unref?.();
+    }
+    handle(value, getPeer) {
+        const parsed = terminalDirectNodeCommandSchema.safeParse(value);
+        if (!parsed.success)
+            return false;
+        const command = parsed.data;
+        if (command.type === 'terminal.direct.prepare') {
+            const peer = getPeer(command.transportSessionId);
+            if (peer === undefined ||
+                !this.verifyTransport(command, peer) ||
+                this.sessions.size >= MAX_SESSIONS ||
+                this.sessions.has(command.directSessionId) ||
+                command.openExpiresAt <= this.now() ||
+                command.expiresAt <= this.now())
+                return true;
+            this.sessions.set(command.directSessionId, {
+                command,
+                peer,
+                opened: false,
+                expiresAt: command.expiresAt,
+                lastHeartbeat: this.now()
+            });
+            this.sendReady(command.directSessionId);
+            return true;
+        }
+        const session = this.sessions.get(command.directSessionId);
+        if (session === undefined)
+            return true;
+        if (command.type === 'terminal.direct.cancel')
+            this.remove(session);
+        else if (session.expiresAt > this.now() && command.expiresAt > this.now()) {
+            session.expiresAt = command.expiresAt;
+            session.lastHeartbeat = this.now();
+        }
+        else
+            this.remove(session);
+        return true;
+    }
+    open(transportId, channel, raw) {
+        if (typeof raw !== 'string' || Buffer.byteLength(raw) > 4_096) {
+            channel.close();
+            return;
+        }
+        let parsed;
+        try {
+            parsed = terminalDirectOpenFrameSchema.safeParse(JSON.parse(raw));
+        }
+        catch {
+            channel.close();
+            return;
+        }
+        const session = parsed.success ? this.sessions.get(parsed.data.directSessionId) : undefined;
+        if (session === undefined ||
+            session.channel !== undefined ||
+            session.opened ||
+            session.command.transportSessionId !== transportId ||
+            session.command.grant !== (parsed.success ? parsed.data.grant : undefined) ||
+            session.command.openExpiresAt <= this.now() ||
+            session.expiresAt <= this.now() ||
+            !this.verifyTransport(session.command, session.peer)) {
+            channel.close();
+            return;
+        }
+        session.channel = channel;
+        channel.onclose = () => this.remove(session);
+        try {
+            const terminal = this.manager.get(session.command.terminalId);
+            if (terminal.state !== 'RUNNING' ||
+                terminal.workspaceId !== (session.command.workspaceId ?? null))
+                throw new Error('TERMINAL_NOT_FOUND');
+            const attachment = this.manager.authorizeAttach({
+                terminalId: session.command.terminalId,
+                afterSequence: session.command.afterSequence,
+                readonly: session.command.readonly,
+                takeover: session.command.takeover
+            });
+            session.attachmentId = attachment.attachmentId;
+            session.opened = true;
+            channel.send(JSON.stringify({
+                type: 'ATTACHED',
+                terminalId: session.command.terminalId,
+                afterSequence: session.command.afterSequence
+            }));
+            for (const frame of attachment.frames)
+                this.sendFrame(session, frame);
+            if (!session.command.readonly && session.command.takeover) {
+                for (const other of [...this.sessions.values()])
+                    if (other !== session &&
+                        other.opened &&
+                        !other.command.readonly &&
+                        other.command.terminalId === session.command.terminalId)
+                        this.remove(other, 'TERMINAL_RELAY_REPLACED');
+                this.sendTakeover(session.command.directSessionId);
+            }
+            channel.onmessage = (event) => this.accept(session, event.data);
+        }
+        catch {
+            this.remove(session, 'TERMINAL_ATTACH_FAILED');
+        }
+    }
+    removeTransport(transportId) {
+        for (const session of [...this.sessions.values()])
+            if (session.command.transportSessionId === transportId)
+                this.remove(session);
+    }
+    close() {
+        for (const session of [...this.sessions.values()])
+            this.remove(session);
+    }
+    dispose() {
+        this.close();
+        clearInterval(this.timer);
+        this.stopListening();
+    }
+    accept(session, raw) {
+        if (!session.opened ||
+            typeof raw !== 'string' ||
+            Buffer.byteLength(raw) > MAX_FRAME_BYTES ||
+            session.expiresAt <= this.now()) {
+            this.remove(session, 'TERMINAL_FRAME_REJECTED');
+            return;
+        }
+        try {
+            const frame = terminalDataFrameSchema.parse(JSON.parse(raw));
+            if (frame.terminalId !== session.command.terminalId ||
+                !['input', 'resize', 'close'].includes(frame.type) ||
+                session.attachmentId === undefined)
+                throw new Error('TERMINAL_FRAME_INVALID');
+            void this.manager
+                .acceptFrame(session.attachmentId, frame)
+                .catch(() => this.remove(session, 'TERMINAL_FRAME_REJECTED'));
+        }
+        catch {
+            this.remove(session, 'TERMINAL_FRAME_REJECTED');
+        }
+    }
+    sendFrame(session, frame) {
+        const channel = session.channel;
+        if (channel?.readyState !== 'open') {
+            this.remove(session);
+            return;
+        }
+        const value = JSON.stringify(frame);
+        if (channel.bufferedAmount + Buffer.byteLength(value) > MAX_BUFFERED_BYTES) {
+            this.remove(session, 'TERMINAL_BACKPRESSURE');
+            return;
+        }
+        try {
+            channel.send(value);
+        }
+        catch {
+            this.remove(session);
+        }
+    }
+    remove(session, code) {
+        if (!this.sessions.delete(session.command.directSessionId))
+            return;
+        if (session.attachmentId !== undefined)
+            this.manager.detach(session.attachmentId);
+        if (code !== undefined && session.channel?.readyState === 'open') {
+            try {
+                session.channel.send(JSON.stringify({ type: 'error', terminalId: session.command.terminalId, code }));
+            }
+            catch {
+                // A closing channel must not prevent attachment cleanup.
+            }
+        }
+        session.channel?.close();
+    }
+}

package/dist/service/terminal-service.js

@@ -26,7 +26,8 @@ export class TerminalService {
                         data?.__requestUserId)
             }),
             'terminal.close': (data) => this.close(data),
-            'terminal.attach.authorize': (data) => this.authorizeAttach(data)
+            'terminal.attach.authorize': (data) => this.authorizeAttach(data),
+            'terminal.direct.preflight': (data) => this.preflightDirect(data)
         };
     }
     open(data) {
@@ -82,6 +83,18 @@ export class TerminalService {
         const attachment = this.terminalManager.authorizeAttach(data);
         return { attachment, terminal: this.terminalManager.get(attachment.terminalId) };
     }
+    preflightDirect(data) {
+        if (data === null || typeof data !== 'object')
+            throw new Error('TERMINAL_ATTACH_INVALID');
+        const input = data;
+        this.assertOwner(input);
+        const terminal = this.terminalManager.get(String(input.terminalId));
+        if (terminal.state !== 'RUNNING')
+            throw new Error('TERMINAL_CLOSED');
+        if (terminal.workspaceId !== (input.workspaceId ?? null))
+            throw new Error('TERMINAL_WORKSPACE_MISMATCH');
+        return { terminalId: terminal.id, workspaceId: terminal.workspaceId };
+    }
     assertOwner(input) {
         const owner = this.gitOwners.get(String(input.terminalId));
         if (owner !== undefined && owner.userId !== input.__requestUserId)

package/dist/service/workbench-manifest-service.js

@@ -47,6 +47,7 @@ export class WorkbenchManifestService {
                 maxSearchResults: 200
             },
             directTransfer: capabilities.workspaceDirectTransfer,
+            terminalDirect: capabilities.terminalDirect,
             git: {
                 available: true,
                 reasonCode: null,

package/dist/service/workspace-change-service.js

@@ -42,7 +42,7 @@ export class WorkspaceChangeService {
                 ...(error instanceof GitCommandError
                     ? {
                         parameters: { gitExitCode: error.code },
-                        details: `Git command exited with status ${error.code}.`
+                        details: error.publicDetails
                     }
                     : {})
             });
@@ -53,6 +53,7 @@ export class WorkspaceChangeService {
                     groupPath: path,
                     errorCode: error.code,
                     ...error.parameters,
+                    ...(error.details === undefined ? {} : { errorDetails: error.details }),
                     durationMs: Math.round(performance.now() - startedAt)
                 });
             };

package/dist/service/workspace-content-search-service.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { createReadStream } from 'node:fs';
 import { lstat, realpath } from 'node:fs/promises';
 import { isAbsolute, join, relative, sep } from 'node:path';
+import { logNodeCommandFailure } from '../operational.js';
 import { bundledRipgrepPath } from '../ripgrep-binary.js';
 const RESULT_LIMIT = 200;
 const PER_FILE_LIMIT = 20;
@@ -113,10 +114,14 @@ export class WorkspaceContentSearchService {
     async validateNativeRegex(root, search, deadline) {
         const command = commandFor('RIPGREP', [], search, this.ripgrep ?? undefined);
         const result = await runCommand(command.file, [...command.args, '-'], root, deadline);
-        if (result.code === 2)
+        if (result.code === 2) {
+            logNodeCommandFailure('rg', { exitCode: result.code, reason: 'INVALID_QUERY' });
             throw new Error('FILE_CONTENT_SEARCH_INVALID');
-        if (!command.validCodes.includes(result.code))
+        }
+        if (!command.validCodes.includes(result.code)) {
+            logNodeCommandFailure('rg', { exitCode: result.code, stderr: result.stderr });
             throw new Error('CONTENT_SEARCH_COMMAND_FAILED');
+        }
     }
     async candidates(workspace, deadline) {
         const root = await realpath(workspace.path);
@@ -167,8 +172,11 @@ export class WorkspaceContentSearchService {
             const command = commandFor(engine, batch, search, this.ripgrep ?? undefined);
             const result = await runCommand(command.file, command.args, root, deadline, engine === 'RIPGREP');
             if (!command.validCodes.includes(result.code)) {
-                if (search.regex && result.code === 2)
+                if (search.regex && result.code === 2) {
+                    logNodeCommandFailure('rg', { exitCode: result.code, reason: 'INVALID_QUERY' });
                     throw new Error('FILE_CONTENT_SEARCH_INVALID');
+                }
+                logNodeCommandFailure('rg', { exitCode: result.code, stderr: result.stderr });
                 throw new Error('CONTENT_SEARCH_COMMAND_FAILED');
             }
             const paths = new Map(batch.flatMap((file) => [
@@ -268,21 +276,42 @@ function resolveRipgrep() {
 }
 async function runCommand(file, args, cwd, deadline, stopAfterResultLimit = false) {
     return new Promise((resolve, reject) => {
+        const startedAt = performance.now();
         const child = spawn(file, args, {
             cwd,
             windowsHide: true,
-            stdio: ['ignore', 'pipe', 'ignore']
+            stdio: ['ignore', 'pipe', 'pipe']
         });
         const chunks = [];
+        const errors = [];
         let pending = Buffer.alloc(0);
         let bytes = 0;
+        let errorBytes = 0;
         let matches = 0;
         let stopped = false;
-        const timer = setTimeout(() => child.kill(), Math.max(1, deadline - Date.now()));
+        let failed = false;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, Math.max(1, deadline - Date.now()));
         child.once('error', (error) => {
             clearTimeout(timer);
+            failed = true;
+            logNodeCommandFailure('rg', {
+                reason: error.code ?? 'START_FAILED',
+                durationMs: Math.round(performance.now() - startedAt)
+            });
             reject(error);
         });
+        child.stderr.on('data', (chunk) => {
+            const remaining = Math.max(0, 1_000 - errorBytes);
+            if (remaining === 0)
+                return;
+            const retained = chunk.subarray(0, remaining);
+            errors.push(retained);
+            errorBytes += retained.length;
+        });
         child.stdout.on('data', (chunk) => {
             bytes += chunk.length;
             if (bytes > OUTPUT_BYTE_LIMIT) {
@@ -311,14 +340,23 @@ async function runCommand(file, args, cwd, deadline, stopAfterResultLimit = fals
         });
         child.once('close', (code, signal) => {
             clearTimeout(timer);
+            if (failed)
+                return;
+            const stderr = Buffer.concat(errors).toString('utf8');
             if (stopped)
-                resolve({ code: 0, stdout: Buffer.concat(chunks) });
-            else if (signal !== null || bytes > OUTPUT_BYTE_LIMIT)
+                resolve({ code: 0, stdout: Buffer.concat(chunks), stderr });
+            else if (timedOut || signal !== null || bytes > OUTPUT_BYTE_LIMIT) {
+                logNodeCommandFailure('rg', {
+                    reason: timedOut ? 'TIMEOUT' : bytes > OUTPUT_BYTE_LIMIT ? 'OUTPUT_LIMIT' : 'SIGNAL',
+                    stderr,
+                    durationMs: Math.round(performance.now() - startedAt)
+                });
                 reject(new Error('CONTENT_SEARCH_COMMAND_LIMIT'));
+            }
             else {
                 if (stopAfterResultLimit && pending.length > 0)
                     chunks.push(pending);
-                resolve({ code: code ?? -1, stdout: Buffer.concat(chunks) });
+                resolve({ code: code ?? -1, stdout: Buffer.concat(chunks), stderr });
             }
         });
     });

package/dist/workspace.js

@@ -4,6 +4,7 @@ import { homedir, platform as hostPlatform } from 'node:os';
 import { basename, dirname, isAbsolute, posix, relative, resolve, sep, win32 } from 'node:path';
 import { spawn } from 'node:child_process';
 import { minimatch } from 'minimatch';
+import { logNodeCommandFailure } from './operational.js';
 import { terminateProcessTree } from './process-tree.js';
 import { gitOperationEnvironment } from './service/git-operation-service.js';
 const GIT_TIMEOUT_MS = 5_000;
@@ -1116,7 +1117,7 @@ export async function listGitWorktrees(workspacePath) {
     if (nulDelimited.code === 0)
         return parseGitWorktreeList(workspacePath, nulDelimited, true);
     if (!canRetryGitWorktreeListWithoutNullOutput(nulDelimited))
-        throw new GitCommandError(nulDelimited.code, nulDelimited.stderr);
+        throw gitCommandFailure(nulDelimited.code, nulDelimited.stderr, 'worktree');
     const lineDelimited = await runReadOnlyGit(workspacePath, ['worktree', 'list', '--porcelain'], options);
     return parseGitWorktreeList(workspacePath, lineDelimited, false);
 }
@@ -1570,7 +1571,7 @@ export async function readGitHistoryFileContentRange(repository, commit, request
         timeoutMs: GIT_HISTORY_TIMEOUT_MS
     });
     if (result.code !== 0)
-        throw new GitCommandError(result.code, result.stderr);
+        throw gitCommandFailure(result.code, result.stderr, 'cat-file');
     const content = result.output.subarray(offset, Math.min(size, offset + limit));
     const nextOffset = offset + content.length;
     return {
@@ -1633,7 +1634,7 @@ export async function openGitHistoryFileContent(repository, commit, requestedPat
                     yield new Uint8Array(chunk);
                 const result = await exit;
                 if (result.code !== 0)
-                    throw new GitCommandError(result.code, result.stderr);
+                    throw gitCommandFailure(result.code, result.stderr, 'cat-file');
             }
             finally {
                 if (!closed)
@@ -1686,7 +1687,7 @@ async function readCurrentChangeGitDiff(workspacePath, path) {
             path
         ]);
         if (result.code !== 0 && result.code !== 1)
-            throw new GitCommandError(result.code, result.stderr);
+            throw gitCommandFailure(result.code, result.stderr, 'diff');
         return result;
     }
     return runReadOnlyGit(workspacePath, [
@@ -1816,12 +1817,25 @@ function gitChange(status) {
 export class GitCommandError extends Error {
     code;
     stderr;
+    publicDetails;
+    publicParameters;
     constructor(code, stderr) {
         super('GIT_COMMAND_FAILED');
         this.code = code;
         this.stderr = stderr;
+        this.publicParameters = { gitExitCode: code };
+        this.publicDetails = stderr.trim().slice(0, 1_000) || `Git exited with status ${code}.`;
     }
 }
+function gitCommandFailure(code, stderr, subcommand, durationMs, reason) {
+    logNodeCommandFailure(`git ${subcommand}`, {
+        exitCode: code,
+        stderr,
+        ...(durationMs === undefined ? {} : { durationMs }),
+        ...(reason === undefined ? {} : { reason })
+    });
+    return new GitCommandError(code, stderr);
+}
 async function runReadOnlyGit(workspacePath, args, options = {}) {
     return runGit(workspacePath, args, { ...options, readOnly: true });
 }
@@ -1829,14 +1843,16 @@ async function runReadOnlyGitAllowFailure(workspacePath, args, options = {}) {
     return runGitAllowFailure(workspacePath, args, { ...options, readOnly: true });
 }
 async function runGit(workspacePath, args, options = {}) {
+    const startedAt = performance.now();
     const result = await runGitAllowFailure(workspacePath, args, options);
     if (result.code !== 0) {
-        throw new GitCommandError(result.code, result.stderr);
+        throw gitCommandFailure(result.code, result.stderr, args[0] ?? 'unknown', Math.round(performance.now() - startedAt));
     }
     return result;
 }
 async function runGitAllowFailure(workspacePath, args, options = {}) {
     return new Promise((resolve, reject) => {
+        const startedAt = performance.now();
         const outputLimit = options.outputLimit ?? GIT_OUTPUT_LIMIT;
         const child = spawn('git', [...args], {
             cwd: workspacePath,
@@ -1854,7 +1870,9 @@ async function runGitAllowFailure(workspacePath, args, options = {}) {
         let size = 0;
         let errorSize = 0;
         let truncated = false;
+        let timedOut = false;
         const timer = setTimeout(() => {
+            timedOut = true;
             if (process.platform === 'win32') {
                 const pid = child.pid;
                 if (pid === undefined) {
@@ -1895,16 +1913,24 @@ async function runGitAllowFailure(workspacePath, args, options = {}) {
         });
         child.once('error', (error) => {
             clearTimeout(timer);
+            logNodeCommandFailure(`git ${args[0] ?? 'unknown'}`, {
+                reason: error.code ?? 'START_FAILED'
+            });
             reject(error);
         });
         child.once('close', (code) => {
             clearTimeout(timer);
+            const stderr = Buffer.concat(errors).toString('utf8');
+            if (timedOut) {
+                reject(gitCommandFailure(code === null || code === 0 ? 1 : code, `Git command timed out after ${options.timeoutMs ?? GIT_TIMEOUT_MS} ms.${stderr ? `\n${stderr}` : ''}`, args[0] ?? 'unknown', Math.round(performance.now() - startedAt), 'TIMEOUT'));
+                return;
+            }
             const output = Buffer.concat(chunks);
             resolve({
                 code: code ?? 1,
                 output,
                 text: output.toString('utf8'),
-                stderr: Buffer.concat(errors).toString('utf8'),
+                stderr,
                 truncated
             });
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/node",
-  "version": "0.9.107",
+  "version": "0.9.109",
   "description": "MyAgentRoam Node runtime CLI.",
   "license": "Apache-2.0 AND GPL-2.0-or-later",
   "type": "module",
@@ -30,9 +30,9 @@
     "npm": "11.12.1",
     "ws": "^8.21.3",
     "zod": "4.4.3",
-    "@myagentroam/agent": "0.9.107",
-    "@myagentroam/code-navigation": "0.9.107",
-    "@myagentroam/protocol": "0.9.107"
+    "@myagentroam/agent": "0.9.109",
+    "@myagentroam/code-navigation": "0.9.109",
+    "@myagentroam/protocol": "0.9.109"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"