@myagentroam/node 0.1.3 → 0.1.6

package/README.md

@@ -3,7 +3,7 @@
 MyAgentRoam Node runtime CLI for Linux and Windows.
 
 For third-party deployment, registration, Runner prerequisites, and automatic startup, see the
-public **Node deployment and connection guide** at `/docs/help/node-deployment.html` in your MyAgentRoam
+public **Node deployment and connection guide** at `/docs/deployment/node-installation` in your MyAgentRoam
 Server Web Console. The same guide is also linked from **Settings → Node registration**.
 
 ## Requirements
@@ -31,4 +31,12 @@ npm install --global @myagentroam/node@latest
 mar-node run --config /path/to/mar-node.json
 ```
 
+Managed deployments should run the stable supervisor entrypoint instead:
+
+```bash
+mar-node supervise --config /path/to/mar-node.json
+```
+
+The supervisor only installs an exact version requested by an authenticated Server operation. It never follows the npm `latest` tag automatically.
+
 The package contains only the executable and its runtime dependencies. It never includes Node configuration, credentials, SQLite data, workspaces, or Runner credentials.

package/dist/capabilities.d.ts

@@ -3,8 +3,10 @@ export declare function unavailableCapabilities(): NodeCapabilities;
 export declare function detectCapabilities(commands?: {
     readonly codex?: string;
     readonly claudeCode?: string;
+    readonly openCode?: string;
 }): NodeCapabilities;
 export declare function detectCapabilitiesAsync(commands?: {
     readonly codex?: string;
     readonly claudeCode?: string;
+    readonly openCode?: string;
 }): Promise<NodeCapabilities>;

package/dist/capabilities.js

@@ -2,6 +2,7 @@ import { release, version } from 'node:os';
 import nodePackage from '../package.json' with { type: 'json' };
 import { probeClaudeCode, probeClaudeCodeAsync } from './claude-agent-sdk.js';
 import { probeCodex, probeCodexAsync } from './codex-app-server.js';
+import { probeOpenCode, probeOpenCodeAsync } from './opencode-runtime.js';
 const nodeAppVersion = typeof nodePackage.version === 'string' ? nodePackage.version : 'unknown';
 function reportedPlatform() {
     return process.platform === 'win32' ? 'windows' : 'linux';
@@ -20,7 +21,8 @@ export function unavailableCapabilities() {
             osVersion: version()
         },
         codex: { available: false },
-        claudeCode: { available: false }
+        claudeCode: { available: false },
+        openCode: { available: false }
     };
 }
 export function detectCapabilities(commands = {}) {
@@ -29,6 +31,7 @@ export function detectCapabilities(commands = {}) {
     }
     const codex = probeCodex(commands.codex);
     const claudeCode = probeClaudeCode(commands.claudeCode);
+    const openCode = probeOpenCode(commands.openCode);
     return {
         platform: reportedPlatform(),
         architecture: process.arch,
@@ -45,6 +48,10 @@ export function detectCapabilities(commands = {}) {
         claudeCode: {
             available: claudeCode.available && claudeCode.compatible,
             ...(claudeCode.version === undefined ? {} : { version: claudeCode.version })
+        },
+        openCode: {
+            available: openCode.available && openCode.compatible,
+            ...(openCode.version === undefined ? {} : { version: openCode.version })
         }
     };
 }
@@ -52,9 +59,10 @@ export async function detectCapabilitiesAsync(commands = {}) {
     if (process.platform !== 'win32' && process.platform !== 'linux') {
         throw new Error('NODE_PLATFORM_UNSUPPORTED');
     }
-    const [codex, claudeCode] = await Promise.all([
+    const [codex, claudeCode, openCode] = await Promise.all([
         probeCodexAsync(commands.codex),
-        probeClaudeCodeAsync(commands.claudeCode)
+        probeClaudeCodeAsync(commands.claudeCode),
+        probeOpenCodeAsync(commands.openCode)
     ]);
     return {
         platform: reportedPlatform(),
@@ -72,7 +80,10 @@ export async function detectCapabilitiesAsync(commands = {}) {
         claudeCode: {
             available: claudeCode.available && claudeCode.compatible,
             ...(claudeCode.version === undefined ? {} : { version: claudeCode.version })
+        },
+        openCode: {
+            available: openCode.available && openCode.compatible,
+            ...(openCode.version === undefined ? {} : { version: openCode.version })
         }
     };
 }
-//# sourceMappingURL=capabilities.js.map

package/dist/claude-agent-sdk.d.ts

@@ -1,4 +1,4 @@
-import { type CanUseTool, type Options, type PermissionResult, type Query, type SDKMessage, type SDKSessionInfo, type SDKUserMessage, type SessionMessage } from '@anthropic-ai/claude-agent-sdk';
+import { forkSession, type CanUseTool, type Options, type PermissionResult, type Query, type SDKMessage, type SDKSessionInfo, type SDKUserMessage, type SessionMessage } from '@anthropic-ai/claude-agent-sdk';
 export interface ClaudeCodeProbe {
     readonly available: boolean;
     readonly compatible: boolean;
@@ -21,6 +21,7 @@ export interface ClaudeQueryInput {
     readonly onPermission: CanUseTool;
     readonly onMessage: (message: SDKMessage) => void;
     readonly onChannelReply?: (content: string) => void;
+    readonly environment?: Readonly<Record<string, string>>;
 }
 /** Image blocks accepted by the Claude Agent SDK message input. */
 export interface ClaudeImageAttachment {
@@ -31,20 +32,11 @@ export interface ClaudeRunHandle {
     readonly completed: Promise<void>;
     interrupt(): Promise<void>;
     cancel(): void;
-    getContextUsage(): Promise<ClaudeContextUsage>;
 }
 /** A live, SDK-owned session accepts input only after the SDK consumes it. */
 export interface ClaudeChannelRunHandle extends ClaudeRunHandle {
     deliver(content: string): Promise<void>;
 }
-/** Normalized public portion of the official SDK context usage response. */
-export interface ClaudeContextUsage {
-    readonly model: string;
-    readonly usedTokens: number;
-    readonly maxTokens: number;
-    readonly rawMaxTokens: number;
-    readonly percentage: number;
-}
 /** The small injectable surface prevents tests from depending on authentication. */
 export interface ClaudeSdkBindings {
     readonly query: (input: {
@@ -61,6 +53,7 @@ export interface ClaudeSdkBindings {
     readonly getSessionMessages: (sessionId: string, options: {
         readonly dir?: string;
     }) => Promise<SessionMessage[]>;
+    readonly forkSession?: typeof forkSession;
 }
 /**
  * Adapter for the supported Agent SDK APIs only. It neither parses nor writes
@@ -78,13 +71,8 @@ export declare class ClaudeAgentSdkAdapter {
     private startWithPrompt;
     listSessions(cwd: string): Promise<SDKSessionInfo[]>;
     readSession(sessionId: string, cwd: string): Promise<SessionMessage[]>;
+    forkSession(sessionId: string, cwd: string, upToMessageId: string, title: string): Promise<string>;
     sessionInfo(sessionId: string, cwd: string): Promise<SDKSessionInfo | undefined>;
-    /**
-     * Reads context occupancy through the SDK's control channel. The input
-     * iterable deliberately never yields a user message, so this does not add
-     * `/context` or any synthetic text to the native conversation.
-     */
-    readContextUsage(sessionId: string, cwd: string): Promise<ClaudeContextUsage>;
     /**
      * The SDK publishes the authoritative, session-specific command list in its
      * first system/init record.  Keep the input stream empty and stop as soon as

package/dist/claude-agent-sdk.js

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import { createSdkMcpServer, getSessionInfo, getSessionMessages, listSessions, query } from '@anthropic-ai/claude-agent-sdk';
+import { createSdkMcpServer, forkSession, getSessionInfo, getSessionMessages, listSessions, query } from '@anthropic-ai/claude-agent-sdk';
 import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 import { minimalRunnerEnvironment, platformCliInvocation, runRunnerProbe } from './operational.js';
@@ -49,7 +49,14 @@ export class ClaudeAgentSdkAdapter {
             prompt,
             options: {
                 cwd: input.cwd,
-                env: minimalRunnerEnvironment(),
+                // Claude SDK defaults CLAUDE_CODE_ENTRYPOINT to sdk-ts. Keep the
+                // transcript discoverable by the same VS Code session filters used by
+                // the external Claude Code extension.
+                env: {
+                    ...minimalRunnerEnvironment(),
+                    ...input.environment,
+                    CLAUDE_CODE_ENTRYPOINT: 'claude-vscode'
+                },
                 ...(input.resumeSessionId === undefined ? {} : { resume: input.resumeSessionId }),
                 ...(input.model === undefined || input.model === null ? {} : { model: input.model }),
                 ...(isClaudeEffort(input.effort) ? { effort: input.effort } : {}),
@@ -68,9 +75,6 @@ export class ClaudeAgentSdkAdapter {
             async interrupt() {
                 await stream.interrupt();
             },
-            async getContextUsage() {
-                return normalizeContextUsage(await stream.getContextUsage());
-            },
             cancel() {
                 abortController.abort();
                 stream.close();
@@ -86,59 +90,17 @@ export class ClaudeAgentSdkAdapter {
     readSession(sessionId, cwd) {
         return this.sdk.getSessionMessages(sessionId, { dir: cwd });
     }
+    async forkSession(sessionId, cwd, upToMessageId, title) {
+        const result = await (this.sdk.forkSession ?? forkSession)(sessionId, {
+            dir: cwd,
+            upToMessageId,
+            title
+        });
+        return result.sessionId;
+    }
     sessionInfo(sessionId, cwd) {
         return this.sdk.getSessionInfo(sessionId, { dir: cwd });
     }
-    /**
-     * Reads context occupancy through the SDK's control channel. The input
-     * iterable deliberately never yields a user message, so this does not add
-     * `/context` or any synthetic text to the native conversation.
-     */
-    async readContextUsage(sessionId, cwd) {
-        const abortController = new AbortController();
-        // 冷启动 Claude CLI 可能需要数秒加载本地 skills；3 秒会在控制响应
-        // 到达前主动中止，导致历史会话看似没有上下文。
-        const timeout = setTimeout(() => abortController.abort(), 15_000);
-        const emptyInput = {
-            async *[Symbol.asyncIterator]() {
-                await new Promise(() => undefined);
-                yield* [];
-            }
-        };
-        const stream = this.sdk.query({
-            prompt: emptyInput,
-            options: {
-                cwd,
-                env: minimalRunnerEnvironment(),
-                resume: sessionId,
-                abortController
-            }
-        });
-        // Claude 的控制请求由 Query 的事件循环驱动。即使不发送用户输入，
-        // 也必须消费该流，initialize/get_context_usage 才能收到 CLI 响应。
-        // 这个 drain 只读取 SDK 事件，emptyInput 永远不会产生一个 Turn。
-        const drain = (async () => {
-            try {
-                for await (const message of stream) {
-                    void message;
-                    // Context probe has no presentation events to project.
-                }
-            }
-            catch {
-                // Closing this short-lived control query aborts its read loop normally.
-            }
-        })();
-        try {
-            await stream.initializationResult();
-            return normalizeContextUsage(await stream.getContextUsage());
-        }
-        finally {
-            clearTimeout(timeout);
-            abortController.abort();
-            stream.close();
-            await drain;
-        }
-    }
     /**
      * The SDK publishes the authoritative, session-specific command list in its
      * first system/init record.  Keep the input stream empty and stop as soon as
@@ -175,28 +137,6 @@ export class ClaudeAgentSdkAdapter {
         }
     }
 }
-function normalizeContextUsage(value) {
-    if (!Number.isFinite(value.totalTokens) ||
-        !Number.isInteger(value.totalTokens) ||
-        !Number.isFinite(value.maxTokens) ||
-        !Number.isInteger(value.maxTokens) ||
-        !Number.isFinite(value.rawMaxTokens) ||
-        !Number.isInteger(value.rawMaxTokens) ||
-        !Number.isFinite(value.percentage) ||
-        value.totalTokens < 0 ||
-        value.maxTokens <= 0 ||
-        value.rawMaxTokens <= 0 ||
-        typeof value.model !== 'string' ||
-        value.model.length === 0)
-        throw new Error('CLAUDE_CONTEXT_USAGE_INVALID');
-    return {
-        model: value.model,
-        usedTokens: value.totalTokens,
-        maxTokens: value.maxTokens,
-        rawMaxTokens: value.rawMaxTokens,
-        percentage: value.percentage
-    };
-}
 function isClaudeEffort(value) {
     return (value === 'low' ||
         value === 'medium' ||
@@ -216,7 +156,7 @@ function claudePermissionMode(access) {
 function channelMcpServer(input) {
     return createSdkMcpServer({
         name: 'myagentroam',
-        version: '0.1.3',
+        version: '0.1.4',
         instructions: 'Use the myagentroam_channel_reply tool only to send a concise reply to the Admin Channel.',
         alwaysLoad: true,
         tools: [
@@ -372,4 +312,3 @@ export async function probeClaudeCodeAsync(command = 'claude') {
 export function denyPermission(message = 'USER_DECISION_REJECTED') {
     return { behavior: 'deny', message };
 }
-//# sourceMappingURL=claude-agent-sdk.js.map

package/dist/claude-channel.js

@@ -42,4 +42,3 @@ export class ClaudeChannelGate {
         return this.deliveries.get(messageId);
     }
 }
-//# sourceMappingURL=claude-channel.js.map

package/dist/codex-app-server.d.ts

@@ -40,6 +40,7 @@ export interface CodexAppServerOptions {
     readonly socketPath?: string;
     readonly spawnProcess?: (command: string, args: readonly string[], options: {
         readonly cwd?: string;
+        readonly env?: NodeJS.ProcessEnv;
     }) => ChildProcessWithoutNullStreams;
 }
 export interface CodexRunConfiguration {
@@ -70,7 +71,10 @@ export declare class CodexAppServerClient {
     private nextId;
     private readonly pending;
     private readonly notifications;
+    private environment;
     constructor(options?: CodexAppServerOptions);
+    configureEnvironment(environment: Readonly<Record<string, string>>): void;
+    clearEnvironment(): void;
     start(): Promise<void>;
     stop(): void;
     onNotification(listener: (notification: JsonRpcNotification) => void): () => void;
@@ -81,6 +85,7 @@ export declare class CodexAppServerClient {
     listThreads(): Promise<unknown>;
     listCollaborationModes(): Promise<unknown>;
     readThread(threadId: string, includeTurns?: boolean): Promise<unknown>;
+    forkThread(threadId: string, cwd: string, lastTurnId: string, configuration?: CodexRunConfiguration): Promise<unknown>;
     setThreadName(threadId: string, name: string): Promise<unknown>;
     resumeThread(threadId: string, cwd: string, configuration?: CodexRunConfiguration): Promise<unknown>;
     startTurn(threadId: string, text: string, cwd: string, configuration?: CodexRunConfiguration, attachments?: readonly Extract<CodexComposerInput, {

package/dist/codex-app-server.js

@@ -49,9 +49,20 @@ export class CodexAppServerClient {
     nextId = 1;
     pending = new Map();
     notifications = new Set();
+    environment = {};
     constructor(options = {}) {
         this.options = options;
     }
+    configureEnvironment(environment) {
+        if (this.child !== undefined)
+            throw new Error('CODEX_APP_SERVER_ALREADY_STARTED');
+        this.environment = { ...environment };
+    }
+    clearEnvironment() {
+        if (this.child !== undefined)
+            throw new Error('CODEX_APP_SERVER_ALREADY_STARTED');
+        this.environment = {};
+    }
     async start() {
         if (this.child !== undefined)
             return;
@@ -66,7 +77,8 @@ export class CodexAppServerClient {
         ];
         const spawnProcess = this.options.spawnProcess ?? defaultSpawn;
         let child = spawnProcess(command, args, {
-            ...(this.options.cwd === undefined ? {} : { cwd: this.options.cwd })
+            ...(this.options.cwd === undefined ? {} : { cwd: this.options.cwd }),
+            env: { ...minimalRunnerEnvironment(), ...this.environment }
         });
         this.child = child;
         let socket;
@@ -84,7 +96,8 @@ export class CodexAppServerClient {
                     await unlink(this.socketPath);
                 this.socketPath = undefined;
                 child = spawnProcess(command, baseArgs, {
-                    ...(this.options.cwd === undefined ? {} : { cwd: this.options.cwd })
+                    ...(this.options.cwd === undefined ? {} : { cwd: this.options.cwd }),
+                    env: { ...minimalRunnerEnvironment(), ...this.environment }
                 });
                 this.child = child;
             }
@@ -98,7 +111,7 @@ export class CodexAppServerClient {
             this.failAll(new Error('CODEX_APP_SERVER_EXITED'));
         });
         await this.request('initialize', {
-            clientInfo: { name: 'myagentroam', title: 'MyAgentRoam', version: '0.1.3' },
+            clientInfo: { name: 'codex_vscode', title: 'MyAgentRoam', version: '0.1.4' },
             capabilities: { experimentalApi: true }
         });
         this.notify('initialized', {});
@@ -160,6 +173,14 @@ export class CodexAppServerClient {
     readThread(threadId, includeTurns = true) {
         return this.request('thread/read', { threadId, includeTurns });
     }
+    forkThread(threadId, cwd, lastTurnId, configuration = {}) {
+        return this.request('thread/fork', {
+            threadId,
+            lastTurnId,
+            cwd,
+            ...codexThreadConfiguration(cwd, configuration)
+        });
+    }
     setThreadName(threadId, name) {
         return this.request('thread/name/set', { threadId, name });
     }
@@ -340,7 +361,8 @@ function defaultSpawn(command, args, options) {
         stdio: ['pipe', 'pipe', 'pipe'],
         shell: false,
         windowsHide: true,
-        ...(options.cwd === undefined ? {} : { cwd: options.cwd })
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        ...(options.env === undefined ? {} : { env: options.env })
     });
 }
 function stdioTransport(child) {
@@ -376,4 +398,3 @@ function connectUnix(socketPath, timeoutMs) {
         attempt();
     });
 }
-//# sourceMappingURL=codex-app-server.js.map

package/dist/config.d.ts

@@ -7,6 +7,9 @@ export interface NodeConfig {
     readonly nodeId?: string;
     readonly credential?: string;
     readonly registrationToken?: string;
+    readonly upgrade?: {
+        readonly registryUrl?: string;
+    };
 }
 export declare function nodeConfigPath(): string;
 export declare function loadNodeConfig(path?: string): Promise<NodeConfig>;

package/dist/config.js

@@ -21,6 +21,14 @@ export async function loadNodeConfig(path = nodeConfigPath()) {
     const credential = optionalString('credential');
     const registrationToken = optionalString('registrationToken');
     const databasePath = optionalString('databasePath');
+    const upgradeInput = input['upgrade'];
+    if (upgradeInput !== undefined &&
+        (upgradeInput === null ||
+            typeof upgradeInput !== 'object' ||
+            Array.isArray(upgradeInput) ||
+            ('registryUrl' in upgradeInput &&
+                typeof upgradeInput['registryUrl'] !== 'string')))
+        throw new Error('NODE_CONFIG_INVALID');
     const allowedRoots = Array.isArray(input['allowedRoots'])
         ? input['allowedRoots']
         : defaultAllowedRoots();
@@ -30,7 +38,16 @@ export async function loadNodeConfig(path = nodeConfigPath()) {
         ...(nodeId === undefined ? {} : { nodeId }),
         ...(credential === undefined ? {} : { credential }),
         ...(registrationToken === undefined ? {} : { registrationToken }),
-        ...(databasePath === undefined ? {} : { databasePath })
+        ...(databasePath === undefined ? {} : { databasePath }),
+        ...(upgradeInput === undefined
+            ? {}
+            : {
+                upgrade: {
+                    ...(upgradeInput['registryUrl'] === undefined
+                        ? {}
+                        : { registryUrl: upgradeInput['registryUrl'] })
+                }
+            })
     };
 }
 /** Uses the Node service account's scope when no Workspace roots are configured. */
@@ -48,4 +65,3 @@ export async function saveNodeConfig(config, path = nodeConfigPath()) {
         await chmod(path, 0o600);
     }
 }
-//# sourceMappingURL=config.js.map

package/dist/connector/node-connector-options.d.ts

@@ -0,0 +1,26 @@
+import type { NodeCapabilities } from '@myagentroam/protocol';
+import type { ClaudeAgentSdkAdapter } from '../claude-agent-sdk.js';
+import type { CodexAppServerClient } from '../codex-app-server.js';
+import type { NodeConfig } from '../config.js';
+import type { NodeDatabase } from '../database.js';
+import type { FakeRunner, FakeRunnerStep } from '../fake-runner.js';
+import type { RunnerUsageReader } from '../runner-usage.js';
+import type { TerminalManager } from '../terminal.js';
+import type { OpenCodeServerClient } from '../opencode-server.js';
+export interface NodeConnectorOptions {
+    readonly configPath?: string;
+    readonly config?: NodeConfig;
+    readonly capabilities?: NodeCapabilities;
+    readonly capabilityDetector?: () => NodeCapabilities | Promise<NodeCapabilities>;
+    readonly reconnect?: boolean;
+    readonly fakeRunner?: FakeRunner;
+    readonly fakeScript?: (input: unknown, runId: string) => readonly FakeRunnerStep[];
+    readonly codexClient?: CodexAppServerClient;
+    readonly claudeClient?: ClaudeAgentSdkAdapter;
+    readonly openCodeClient?: OpenCodeServerClient;
+    readonly database?: NodeDatabase;
+    readonly claudeApprovalTimeoutMs?: number;
+    readonly terminalManager?: TerminalManager;
+    readonly runnerUsageReader?: RunnerUsageReader;
+    readonly upgradeReady?: () => void;
+}

package/dist/connector/node-connector-options.js

@@ -0,0 +1 @@
+export {};

package/dist/connector/node-operation-router.d.ts

@@ -0,0 +1,9 @@
+export type NodeOperationHandler = (data: unknown) => Promise<unknown> | unknown;
+/** Exact allow-list dispatcher for protocol-defined Node operations. */
+export declare class NodeOperationRouter {
+    private readonly handlers;
+    register(operation: string, handler: NodeOperationHandler): void;
+    registerAll(handlers: Readonly<Record<string, NodeOperationHandler>>): void;
+    has(operation: string): boolean;
+    execute(operation: string, data: unknown): Promise<unknown>;
+}

package/dist/connector/node-operation-router.js

@@ -0,0 +1,22 @@
+/** Exact allow-list dispatcher for protocol-defined Node operations. */
+export class NodeOperationRouter {
+    handlers = new Map();
+    register(operation, handler) {
+        if (this.handlers.has(operation))
+            throw new Error(`NODE_OPERATION_ALREADY_REGISTERED:${operation}`);
+        this.handlers.set(operation, handler);
+    }
+    registerAll(handlers) {
+        for (const [operation, handler] of Object.entries(handlers))
+            this.register(operation, handler);
+    }
+    has(operation) {
+        return this.handlers.has(operation);
+    }
+    execute(operation, data) {
+        const handler = this.handlers.get(operation);
+        if (handler === undefined)
+            return Promise.reject(new Error('OPERATION_UNSUPPORTED'));
+        return Promise.resolve(handler(data));
+    }
+}