@myagentroam/node 0.1.3 → 0.1.6

package/dist/opencode-runtime.js

@@ -0,0 +1,80 @@
+import { spawnSync } from 'node:child_process';
+import { minimalRunnerEnvironment, platformCliInvocation, runRunnerProbe } from './operational.js';
+const PROBE_TIMEOUT_MS = 3_000;
+export function probeOpenCode(command = 'opencode') {
+    const invocation = platformCliInvocation(command, ['--version']);
+    const result = spawnSync(invocation.command, invocation.args, {
+        windowsHide: true,
+        env: minimalRunnerEnvironment(),
+        timeout: PROBE_TIMEOUT_MS,
+        encoding: 'utf8'
+    });
+    if (result.status !== 0 || result.error !== undefined)
+        return { available: false, compatible: false };
+    return openCodeProbeResult(`${result.stdout}${result.stderr}`);
+}
+export async function probeOpenCodeAsync(command = 'opencode') {
+    const invocation = platformCliInvocation(command, ['--version']);
+    const result = await runRunnerProbe(invocation.command, invocation.args, {
+        env: minimalRunnerEnvironment(),
+        timeoutMs: PROBE_TIMEOUT_MS
+    });
+    return result.status === 0
+        ? openCodeProbeResult(`${result.stdout}${result.stderr}`)
+        : { available: false, compatible: false };
+}
+function openCodeProbeResult(output) {
+    const version = output.trim().replace(/^v/i, '').slice(0, 128);
+    return {
+        available: version.length > 0,
+        compatible: /^1\.18\./.test(version),
+        ...(version.length === 0 ? {} : { version })
+    };
+}
+export function openCodeProfileModels(catalog) {
+    const connected = new Set(catalog.connected ?? []);
+    return (catalog.all ?? [])
+        .filter((provider) => typeof provider.id === 'string' &&
+        connected.has(provider.id) &&
+        provider.source === 'config')
+        .flatMap((provider) => {
+        const providerId = provider.id;
+        return Object.entries(provider.models ?? {}).flatMap(([key, model]) => {
+            const modelId = boundedString(model.id) ?? boundedString(key);
+            if (modelId === undefined)
+                return [];
+            const variants = Object.entries(model.variants ?? {})
+                .filter(([, value]) => value.disabled !== true)
+                .map(([id]) => id)
+                .filter((id) => id.length > 0 && id.length <= 64)
+                .slice(0, 32);
+            return [
+                {
+                    id: `${providerId}/${modelId}`.slice(0, 128),
+                    label: (boundedString(model.name) ?? modelId).slice(0, 128),
+                    supportedEfforts: variants
+                }
+            ];
+        });
+    });
+}
+export function openCodeContextLimits(catalog) {
+    const connected = new Set(catalog.connected ?? []);
+    return new Map((catalog.all ?? [])
+        .filter((provider) => typeof provider.id === 'string' &&
+        connected.has(provider.id) &&
+        provider.source === 'config')
+        .flatMap((provider) => Object.entries(provider.models ?? {}).flatMap(([key, model]) => {
+        const modelId = boundedString(model.id) ?? boundedString(key);
+        const context = model.limit?.context;
+        return modelId !== undefined && Number.isSafeInteger(context) && (context ?? 0) > 0
+            ? [[`${provider.id}/${modelId}`, context]]
+            : [];
+    })));
+}
+function boundedString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 && trimmed.length <= 4096 ? trimmed : undefined;
+}

package/dist/opencode-server.d.ts

@@ -0,0 +1,47 @@
+import { spawn } from 'node:child_process';
+import type { OpenCodeProviderCatalog } from './opencode-runtime.js';
+export interface OpenCodeServerOptions {
+    readonly command?: string;
+    readonly startTimeoutMs?: number;
+    readonly spawnProcess?: typeof spawn;
+}
+export declare class OpenCodeServerClient {
+    private readonly options;
+    private child;
+    private client;
+    private starting;
+    private environment;
+    constructor(options?: OpenCodeServerOptions);
+    configureEnvironment(environment: Readonly<Record<string, string>>): void;
+    start(): Promise<void>;
+    private startServer;
+    providers(directory: string): Promise<OpenCodeProviderCatalog>;
+    sessions(directory: string, limit?: number): Promise<readonly unknown[]>;
+    sessionStatus(directory: string): Promise<Readonly<Record<string, unknown>>>;
+    createSession(directory: string, title?: string): Promise<unknown>;
+    forkSession(directory: string, sessionID: string, messageID: string): Promise<unknown>;
+    messages(directory: string, sessionID: string, limit?: number): Promise<readonly unknown[]>;
+    updateSession(directory: string, sessionID: string, title: string): Promise<unknown>;
+    deleteSession(directory: string, sessionID: string): Promise<unknown>;
+    abort(directory: string, sessionID: string): Promise<unknown>;
+    summarize(directory: string, sessionID: string, model: string): Promise<unknown>;
+    replyPermission(directory: string, requestID: string, decision: 'APPROVED' | 'REJECTED'): Promise<unknown>;
+    replyQuestion(directory: string, requestID: string, answers: readonly (readonly string[])[]): Promise<unknown>;
+    rejectQuestion(directory: string, requestID: string): Promise<unknown>;
+    prompt(input: {
+        readonly directory: string;
+        readonly sessionID: string;
+        readonly text: string;
+        readonly model: string;
+        readonly variant?: string;
+        readonly agent?: 'plan' | 'build';
+        readonly attachments?: readonly {
+            readonly name: string;
+            readonly mime: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+            readonly dataBase64: string;
+        }[];
+    }): Promise<unknown>;
+    subscribe(directory: string, signal: AbortSignal, onEvent: (event: unknown) => void, onReady?: () => void): Promise<void>;
+    stop(): Promise<void>;
+    private requireClient;
+}

package/dist/opencode-server.js

@@ -0,0 +1,250 @@
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:net';
+import { createOpencodeClient } from '@opencode-ai/sdk/v2/client';
+import { minimalRunnerEnvironment, platformCliInvocation } from './operational.js';
+import { terminateProcessTree } from './process-tree.js';
+const START_TIMEOUT_MS = 10_000;
+export class OpenCodeServerClient {
+    options;
+    child;
+    client;
+    starting;
+    environment = {};
+    constructor(options = {}) {
+        this.options = options;
+    }
+    configureEnvironment(environment) {
+        if (this.child !== undefined)
+            throw new Error('OPENCODE_SERVER_ALREADY_STARTED');
+        this.environment = { ...environment };
+    }
+    async start() {
+        if (this.client !== undefined)
+            return;
+        if (this.starting !== undefined)
+            return this.starting;
+        const starting = this.startServer();
+        this.starting = starting;
+        try {
+            await starting;
+        }
+        finally {
+            if (this.starting === starting)
+                this.starting = undefined;
+        }
+    }
+    async startServer() {
+        const port = await availablePort();
+        const password = randomBytes(24).toString('base64url');
+        const invocation = platformCliInvocation(this.options.command ?? 'opencode', [
+            'serve',
+            '--hostname',
+            '127.0.0.1',
+            '--port',
+            String(port)
+        ]);
+        const spawnProcess = this.options.spawnProcess ?? spawn;
+        const child = spawnProcess(invocation.command, invocation.args, {
+            windowsHide: true,
+            detached: process.platform !== 'win32',
+            env: {
+                ...minimalRunnerEnvironment(),
+                ...this.environment,
+                OPENCODE_SERVER_USERNAME: 'opencode',
+                OPENCODE_SERVER_PASSWORD: password,
+                OPENCODE_DISABLE_AUTOUPDATE: 'true'
+            },
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        this.child = child;
+        const authorization = `Basic ${Buffer.from(`opencode:${password}`).toString('base64')}`;
+        const client = createOpencodeClient({
+            baseUrl: `http://127.0.0.1:${port}`,
+            headers: { authorization },
+            throwOnError: true
+        });
+        try {
+            await waitUntilHealthy(`http://127.0.0.1:${port}/global/health`, authorization, child, this.options.startTimeoutMs ?? START_TIMEOUT_MS);
+            this.client = client;
+        }
+        catch (error) {
+            await this.stop();
+            throw error;
+        }
+    }
+    async providers(directory) {
+        const client = await this.requireClient();
+        return unwrap(await client.provider.list({ directory }));
+    }
+    async sessions(directory, limit = 100) {
+        const client = await this.requireClient();
+        return unwrap(await client.session.list({ directory, limit }));
+    }
+    async sessionStatus(directory) {
+        const client = await this.requireClient();
+        return unwrap(await client.session.status({ directory }));
+    }
+    async createSession(directory, title) {
+        const client = await this.requireClient();
+        return unwrap(await client.session.create({ directory, ...(title === undefined ? {} : { title }) }));
+    }
+    async forkSession(directory, sessionID, messageID) {
+        const client = await this.requireClient();
+        return unwrap(await client.session.fork({ directory, sessionID, messageID }));
+    }
+    async messages(directory, sessionID, limit = 100) {
+        const client = await this.requireClient();
+        return unwrap(await client.session.messages({ directory, sessionID, limit }));
+    }
+    async updateSession(directory, sessionID, title) {
+        const client = await this.requireClient();
+        return unwrap(await client.session.update({ directory, sessionID, title }));
+    }
+    async deleteSession(directory, sessionID) {
+        const client = await this.requireClient();
+        return unwrap(await client.session.delete({ directory, sessionID }));
+    }
+    async abort(directory, sessionID) {
+        const client = await this.requireClient();
+        return unwrap(await client.session.abort({ directory, sessionID }));
+    }
+    async summarize(directory, sessionID, model) {
+        const client = await this.requireClient();
+        const separator = model.indexOf('/');
+        if (separator <= 0 || separator === model.length - 1)
+            throw new Error('OPENCODE_MODEL_INVALID');
+        return unwrap(await client.session.summarize({
+            directory,
+            sessionID,
+            providerID: model.slice(0, separator),
+            modelID: model.slice(separator + 1)
+        }));
+    }
+    async replyPermission(directory, requestID, decision) {
+        const client = await this.requireClient();
+        return unwrap(await client.permission.reply({
+            directory,
+            requestID,
+            reply: decision === 'APPROVED' ? 'once' : 'reject'
+        }));
+    }
+    async replyQuestion(directory, requestID, answers) {
+        const client = await this.requireClient();
+        return unwrap(await client.question.reply({
+            directory,
+            requestID,
+            answers: answers.map((answer) => [...answer])
+        }));
+    }
+    async rejectQuestion(directory, requestID) {
+        const client = await this.requireClient();
+        return unwrap(await client.question.reject({ directory, requestID }));
+    }
+    async prompt(input) {
+        const client = await this.requireClient();
+        const separator = input.model.indexOf('/');
+        if (separator <= 0 || separator === input.model.length - 1)
+            throw new Error('OPENCODE_MODEL_INVALID');
+        return unwrap(await client.session.promptAsync({
+            directory: input.directory,
+            sessionID: input.sessionID,
+            model: {
+                providerID: input.model.slice(0, separator),
+                modelID: input.model.slice(separator + 1)
+            },
+            ...(input.variant === undefined || input.variant.length === 0
+                ? {}
+                : { variant: input.variant }),
+            ...(input.agent === undefined ? {} : { agent: input.agent }),
+            parts: [
+                { type: 'text', text: input.text },
+                ...(input.attachments ?? []).map((attachment) => ({
+                    type: 'file',
+                    mime: attachment.mime,
+                    filename: attachment.name,
+                    url: `data:${attachment.mime};base64,${attachment.dataBase64}`
+                }))
+            ]
+        }));
+    }
+    async subscribe(directory, signal, onEvent, onReady) {
+        const client = await this.requireClient();
+        const stream = await client.event.subscribe({ directory }, { signal });
+        onReady?.();
+        for await (const event of stream.stream)
+            onEvent(event);
+    }
+    async stop() {
+        this.client = undefined;
+        const child = this.child;
+        this.child = undefined;
+        if (child === undefined)
+            return;
+        if (child.pid === undefined) {
+            child.kill('SIGTERM');
+            return;
+        }
+        try {
+            await terminateProcessTree({
+                pid: child.pid,
+                kill: (signal) => child.kill(signal)
+            });
+        }
+        catch {
+            child.kill('SIGTERM');
+        }
+    }
+    async requireClient() {
+        await this.start();
+        return this.client;
+    }
+}
+async function availablePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address !== null ? address.port : undefined;
+            server.close((error) => {
+                if (error !== undefined)
+                    reject(error);
+                else if (port === undefined)
+                    reject(new Error('OPENCODE_PORT_UNAVAILABLE'));
+                else
+                    resolve(port);
+            });
+        });
+    });
+}
+async function waitUntilHealthy(url, authorization, child, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (child.exitCode !== null)
+            throw new Error('OPENCODE_SERVER_EXITED');
+        try {
+            const response = await fetch(url, {
+                headers: { authorization },
+                signal: AbortSignal.timeout(Math.min(1_000, Math.max(1, deadline - Date.now())))
+            });
+            if (response.ok)
+                return;
+        }
+        catch {
+            // The child may still be binding its loopback socket.
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    throw new Error('OPENCODE_SERVER_START_TIMEOUT');
+}
+function unwrap(result) {
+    if (typeof result !== 'object' || result === null || !('data' in result))
+        return result;
+    const wrapped = result;
+    if (wrapped.error !== undefined)
+        throw new Error('OPENCODE_REQUEST_FAILED');
+    if (wrapped.data === undefined)
+        throw new Error('OPENCODE_RESPONSE_INVALID');
+    return wrapped.data;
+}

package/dist/operational.js

@@ -101,12 +101,19 @@ export function platformCliInvocation(command, args, platform = process.platform
     const cliCommand = platformCliCommand(command, platform);
     if (platform !== 'win32' || !/\.(?:cmd|bat)$/i.test(cliCommand))
         return { command: cliCommand, args };
-    if (![cliCommand, ...args].every((value) => /^[A-Za-z0-9_./:\\-]+$/.test(value)))
+    if (![cliCommand, ...args].every((value) => /^[A-Za-z0-9_@./:\\ -]+$/.test(value)))
         throw new Error('NODE_CLI_COMMAND_INVALID');
-    return { command: comspec, args: ['/d', '/s', '/c', [cliCommand, ...args].join(' ')] };
+    return {
+        command: comspec,
+        args: [
+            '/d',
+            '/s',
+            '/c',
+            [cliCommand, ...args].map((value) => (value.includes(' ') ? `"${value}"` : value)).join(' ')
+        ]
+    };
 }
 export function nodeLog(event, fields = {}) {
     const safeFields = redactLogValue(fields);
     process.stdout.write(`${JSON.stringify({ timestamp: new Date().toISOString(), level: 'info', component: 'mar-node', event, ...safeFields })}\n`);
 }
-//# sourceMappingURL=operational.js.map

package/dist/process-tree.js

@@ -16,4 +16,3 @@ export async function terminateProcessTree(child, platform = process.platform, r
         child.kill('SIGTERM');
     }
 }
-//# sourceMappingURL=process-tree.js.map

package/dist/runner/abstract-runner.d.ts

@@ -0,0 +1,153 @@
+import type { NodeCapabilities, RunnerDefaultConfiguration, RunnerCommandDescriptor, NodeEnvelope, RunnerName, RunnerProfile, RunnerCommandState, SessionActivityState } from '@myagentroam/protocol';
+import type { NodeAgentSession, NodeConversationTurn, NodeDatabase, NodeWorkspace } from '../database.js';
+import type { ChannelDelivery } from '../claude-channel.js';
+import type { CodexSessionControl } from '../codex-app-server.js';
+export type RegisteredRunnerName = RunnerName | 'fake';
+/**
+ * Stable lifecycle boundary for every Node Runner implementation.
+ *
+ * Vendor clients and payload decoders stay behind subclasses. Domain services
+ * depend on this boundary (or a capability interface implemented by it), never
+ * on an SDK/App Server client directly.
+ */
+export declare abstract class AbstractRunner<TName extends RegisteredRunnerName = RegisteredRunnerName> {
+    private control;
+    private commandControl;
+    abstract readonly name: TName;
+    /** Test-only runners are registered explicitly but never advertised. */
+    readonly advertised: boolean;
+    readonly interceptsRuns: boolean;
+    abstract readonly discoveryScope: 'ALL_WORKSPACES' | 'WORKSPACE_REQUIRED';
+    abstract profile(capabilities: NodeCapabilities): RunnerProfile | undefined;
+    refreshProfile(capabilities: NodeCapabilities, workspace?: NodeWorkspace, environment?: Readonly<Record<string, string>>): Promise<RunnerProfile | undefined>;
+    abstract available(capabilities: NodeCapabilities): boolean;
+    abstract defaultConfiguration(workspace?: NodeWorkspace): RunnerDefaultConfiguration;
+    supportsConfiguration(configuration: RunnerDefaultConfiguration, workspace?: NodeWorkspace): boolean;
+    protected abstract profileForValidation(): RunnerProfile;
+    abstract resumeExternal(session: NodeAgentSession, context: ExternalResumeContext, force?: boolean): Promise<ExternalResumeResult>;
+    abstract discoverSessions(context: RunnerDiscoveryContext, workspace?: NodeWorkspace): Promise<readonly NodeAgentSession[]>;
+    abstract readContextUsage(session: NodeAgentSession): Promise<RunnerContextUsage | undefined>;
+    presentSession(session: NodeAgentSession, capabilities: NodeCapabilities, context: RunnerSessionPresentationContext): RunnerSessionPresentation;
+    prepareMessageInput(input: string, collaborationMode: 'default' | 'plan'): string;
+    channelToken(sessionId: string): string | undefined;
+    deliverChannel(sessionId: string, messageId: string, senderId: string, token: string, content: string, notify: (runId: string, messageId: string, delivery: ChannelDelivery) => void): ChannelDelivery;
+    executeGlobalCommand(commandId: string, input: string): unknown;
+    serviceTier(): 'fast' | undefined;
+    usesRunnerTitleForRename(): boolean;
+    renameNative(session: NodeAgentSession, input: {
+        readonly title?: string | null;
+        readonly pinned?: boolean;
+    }, database: NodeDatabase): Promise<void>;
+    removeNative(session: NodeAgentSession, nativeSessionId: string): Promise<boolean>;
+    forkNative(session: NodeAgentSession, boundary: string | null, title: string): Promise<string | null>;
+    projectedRunnerTitle(metadata: ReturnType<NodeDatabase['getNativeSessionMetadata']>, input: RunnerProjectionTitleInput, database: NodeDatabase | undefined): string | null;
+    managedAliasId(nativeSessionId: string): string | undefined;
+    nativeAliasesFor(managedSessionId: string): readonly string[];
+    forgetNativeAlias(nativeSessionId: string): void;
+    rememberManagedNative(session: NodeAgentSession, nativeSessionId: string): void;
+    readManagedRunnerTitle(session: NodeAgentSession, nativeSessionId: string): Promise<string | undefined>;
+    readOfficialConversation(session: NodeAgentSession, input: {
+        readonly cursor?: string;
+        readonly limit?: number;
+    }, managedTurn: (nativeTurnId: string) => NodeConversationTurn | undefined): Promise<RunnerOfficialConversationPage | undefined>;
+    readExternalActivity(session: NodeAgentSession): Promise<SessionActivityState | undefined>;
+    acceptsTruncatedNativeHistory(): boolean;
+    nativeImageRoot(session: NodeAgentSession): string | undefined;
+    managedRunForNativeTurn(nativeTurnId: string): string | undefined;
+    abstract stop(): void | Promise<void>;
+    bindControl(control: RunnerControl): void;
+    acceptsRun(runner: unknown): boolean;
+    startManagedRun(envelope: NodeEnvelope): void;
+    cancelManagedRun(runId: string, intent: RunnerCancellationIntent): boolean;
+    decideApproval(input: RunnerApprovalDecision): boolean;
+    respondUserInput(runId: string, requestId: string, answers: Record<string, unknown>): boolean;
+    bindCommandControl(control: RunnerCommandControl): void;
+    executeCommand(session: NodeAgentSession, command: RunnerCommandDescriptor, input: string, context: {
+        readonly secretEnvironment: Readonly<Record<string, string>>;
+    }): Promise<unknown>;
+}
+export type RunnerCancellationIntent = 'CANCEL' | 'INTERRUPT';
+export interface RunnerControl {
+    start(envelope: NodeEnvelope): void;
+    cancel(runId: string, intent: RunnerCancellationIntent): boolean;
+    decideApproval?(input: RunnerApprovalDecision): boolean;
+    respondUserInput?(runId: string, requestId: string, answers: Record<string, unknown>): boolean;
+}
+export interface RunnerCommandControl {
+    execute(session: NodeAgentSession, command: RunnerCommandDescriptor, input: string, context: {
+        readonly secretEnvironment: Readonly<Record<string, string>>;
+    }): Promise<unknown>;
+}
+export interface RunnerApprovalDecision {
+    readonly runId: string;
+    readonly approvalId: string;
+    readonly decision: 'APPROVED' | 'REJECTED';
+}
+export interface RunnerDiscoveryContext {
+    readonly workspaces: readonly NodeWorkspace[];
+    createProjection(input: {
+        readonly workspace: NodeWorkspace;
+        readonly runner: RunnerName;
+        readonly externalSessionId: string;
+        readonly cwd: string;
+        readonly title?: string;
+        readonly titleOrigin?: 'OFFICIAL' | 'NATIVE';
+        readonly lastActivityAt?: number;
+    }): NodeAgentSession;
+}
+export interface ExternalResumeContext {
+    readonly available: boolean;
+    projectionFor(session: NodeAgentSession): NodeAgentSession | undefined;
+    managedAliasFor(session: NodeAgentSession): NodeAgentSession | undefined;
+    currentResumed(sessionId: string): NodeAgentSession | undefined;
+    promote(sessionId: string): NodeAgentSession | undefined;
+    ensureConfiguration(session: NodeAgentSession): NodeAgentSession;
+    create(session: NodeAgentSession): NodeAgentSession;
+    workspacePath(workspaceId: string): string | undefined;
+    rememberManagedNative(nativeSessionId: string, sessionId: string): void;
+}
+export interface ExternalResumeResult {
+    readonly session?: NodeAgentSession;
+    readonly activity?: 'IDLE' | 'EXTERNAL_ACTIVE' | 'UNAVAILABLE';
+    readonly failureCode?: string;
+    readonly failureDetail?: string;
+    readonly messageFailureCode?: string;
+}
+export interface RunnerContextUsage {
+    readonly model?: string | null;
+    readonly usedTokens: number;
+    readonly maxTokens: number;
+}
+export interface RunnerProjectionTitleInput {
+    readonly externalSessionId: string;
+    readonly workspaceId: string;
+    readonly title?: string;
+    readonly titleOrigin?: 'OFFICIAL' | 'NATIVE';
+}
+export interface RunnerOfficialConversationPage {
+    readonly turns: readonly NodeConversationTurn[];
+    readonly nextCursor: string | null;
+}
+export interface RunnerSessionPresentationContext {
+    readonly managedActive: boolean;
+    readonly externalActivity: SessionActivityState | undefined;
+    readonly commandStates: readonly RunnerCommandState[];
+}
+export interface RunnerSessionPresentation {
+    readonly activity: SessionActivityState;
+    readonly control: {
+        readonly level: CodexSessionControl['level'];
+        readonly capabilities: CodexSessionControl['capabilities'];
+    };
+    readonly runtime: {
+        readonly level: CodexSessionControl['level'];
+        readonly capabilities: readonly string[];
+        readonly reasonCode: string | null;
+    };
+    readonly commandStates: readonly RunnerCommandState[];
+}
+export declare class RunnerCapabilityError extends Error {
+    readonly runner: RegisteredRunnerName;
+    readonly capability: string;
+    constructor(runner: RegisteredRunnerName, capability: string);
+}