@mearl/agent-runtime 0.0.0-stage → 2.22.0

package/dist/generated/plugin-models.d.ts

@@ -0,0 +1,64 @@
+export type PluginModelMode = 'generate' | 'agent';
+export interface PluginModelRequest {
+    provider: string;
+    mode: PluginModelMode;
+    prompt: string;
+    instructions?: string;
+    model?: string;
+    reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    outputSchema?: Record<string, unknown>;
+    /** Opt-in conversation scoped to the bound document or calling command execution. */
+    conversation?: string;
+    /** Required for an agent task; never inferred from a pure-generation request. */
+    permissions?: 'read-only';
+}
+export interface PluginModelCapability {
+    provider: string;
+    modes: PluginModelMode[];
+    permissions: Array<'read-only'>;
+    structuredOutput: boolean;
+    streaming: boolean;
+    cancellation: boolean;
+}
+export interface PluginModelOption {
+    id: string;
+    displayName: string;
+    description?: string;
+    isDefault?: boolean;
+    reasoningEfforts?: NonNullable<PluginModelRequest['reasoningEffort']>[];
+    defaultReasoningEffort?: PluginModelRequest['reasoningEffort'];
+}
+export interface PluginModelList {
+    provider: string;
+    models: PluginModelOption[];
+}
+export interface PluginModelResult {
+    text: string;
+    output?: unknown;
+    provider: string;
+    mode: PluginModelMode;
+    model?: string;
+}
+/** Execution observations contain no prompts, account identities or credential values. */
+export interface PluginModelDiagnostic {
+    requestedModel?: string;
+    selectedModel?: string;
+    activeModel?: string;
+    runtime?: {
+        executable?: string;
+        version?: string;
+        selection: 'explicit' | 'automatic';
+        started?: boolean;
+    };
+    configuration?: {
+        source: 'default' | 'environment';
+        home?: string;
+        filePresent: boolean;
+        baseProvider?: string;
+        credentialStore?: 'file' | 'keyring' | 'auto' | 'ephemeral' | 'unknown';
+    };
+    authentication?: 'apikey' | 'chatgpt' | 'chatgptAuthTokens' | 'unknown';
+    threadRestrictionsAccepted?: boolean;
+    turnRestrictionsAccepted?: boolean;
+    retryCount?: number;
+}

package/dist/generated/plugin-models.js

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

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './provider.js';
+export * from './codex-provider.js';
+export * from './qoder-provider.js';
+export * from './model.js';
+export type * from './generated/plugin-models.js';
+export type * from './generated/agent-chat.js';
+export type * from './generated/agent-skills.js';
+export * from './model-catalog.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './provider.js';
+export * from './codex-provider.js';
+export * from './qoder-provider.js';
+export * from './model.js';
+export * from './model-catalog.js';

package/dist/model-catalog.d.ts

@@ -0,0 +1,4 @@
+import { CodexAgentProvider } from './codex-provider.js';
+import type { PluginModelOption } from './generated/plugin-models.js';
+/** Discovery starts no thread and always releases its short-lived app-server. */
+export declare function listCodexModels(signal: AbortSignal, provider?: CodexAgentProvider): Promise<PluginModelOption[]>;

package/dist/model-catalog.js

@@ -0,0 +1,21 @@
+import { CodexAgentProvider } from './codex-provider.js';
+import { readFileSync } from 'node:fs';
+/** Discovery starts no thread and always releases its short-lived app-server. */
+export async function listCodexModels(signal, provider = new CodexAgentProvider(() => { }, JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version)) {
+    signal.throwIfAborted();
+    let abort;
+    const cancelled = new Promise((_resolve, reject) => {
+        abort = () => {
+            provider.dispose();
+            reject(signal.reason ?? new Error('Model discovery cancelled'));
+        };
+        signal.addEventListener('abort', abort, { once: true });
+    });
+    try {
+        return await Promise.race([provider.listModels(), cancelled]);
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+        provider.dispose();
+    }
+}

package/dist/model.d.ts

@@ -0,0 +1,18 @@
+import type { PluginModelDiagnostic, PluginModelRequest, PluginModelResult } from './generated/plugin-models.js';
+import { CodexAgentProvider } from './codex-provider.js';
+export { CODEX_MODEL_CAPABILITY } from './capabilities.js';
+export interface ModelExecutionContext {
+    signal: AbortSignal;
+    cwd: string;
+    /** The supervised conversation worker owns this in-memory thread and provider. */
+    conversation?: {
+        threadId?: string;
+    };
+    onDiagnostic?(metadata: PluginModelDiagnostic): void;
+    onDelta(delta: string, index: number, metadata?: {
+        itemId?: string;
+        phase?: string;
+    }): void;
+}
+/** A supervised worker owns the provider; explicit conversations retain its in-memory thread. */
+export declare function runCodexModel(request: PluginModelRequest, context: ModelExecutionContext, provider?: CodexAgentProvider): Promise<PluginModelResult>;

package/dist/model.js

@@ -0,0 +1,194 @@
+import { readFileSync } from 'node:fs';
+import { CodexAgentProvider } from './codex-provider.js';
+export { CODEX_MODEL_CAPABILITY } from './capabilities.js';
+/** A supervised worker owns the provider; explicit conversations retain its in-memory thread. */
+export async function runCodexModel(request, context, provider = new CodexAgentProvider(() => { }, JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version)) {
+    if (request.provider !== 'codex' ||
+        request.mode !== 'agent' ||
+        request.permissions !== 'read-only')
+        throw Object.assign(new Error('Codex supports explicit read-only agent execution; strict tool-free generation is unavailable'), { code: 'PLUGIN_MODEL_CAPABILITY_UNSUPPORTED' });
+    context.signal.throwIfAborted();
+    let session, turn, text;
+    let bytes = 0, index = 0, retries = 0;
+    let buffered = '';
+    let streamItem, streamPhase;
+    const phases = new Map();
+    let flushTimer;
+    const flush = () => {
+        clearTimeout(flushTimer);
+        flushTimer = undefined;
+        try {
+            for (let offset = 0; offset < buffered.length; offset += 4000)
+                if (streamItem || streamPhase)
+                    context.onDelta(buffered.slice(offset, offset + 4000), ++index, {
+                        ...(streamItem ? { itemId: streamItem } : {}),
+                        ...(streamPhase ? { phase: streamPhase } : {}),
+                    });
+                else
+                    context.onDelta(buffered.slice(offset, offset + 4000), ++index);
+        }
+        catch (error) {
+            fail(error);
+        }
+        buffered = '';
+    };
+    let finish, fail;
+    const completed = new Promise((resolve, reject) => {
+        finish = resolve;
+        fail = reject;
+    });
+    void completed.catch(() => { });
+    const listener = (event) => {
+        const params = event.params;
+        if (event.method === 'provider/model/diagnostic')
+            context.onDiagnostic?.(params);
+        if (event.method === 'account/updated')
+            context.onDiagnostic?.({
+                authentication: ['apikey', 'chatgpt', 'chatgptAuthTokens'].includes(params?.authMode)
+                    ? params.authMode
+                    : 'unknown',
+            });
+        if (event.method === 'session/model/updated' && typeof params?.model?.id === 'string')
+            context.onDiagnostic?.({ selectedModel: params.model.id });
+        if (event.method === 'session/activeModel/updated' && typeof params?.model?.id === 'string')
+            context.onDiagnostic?.({ activeModel: params.model.id });
+        const relevant = event.providerSessionId === undefined || event.providerSessionId === session;
+        if (event.kind === 'request' && relevant) {
+            try {
+                provider.respondToRequest(event.requestId, {
+                    error: 'Interactive requests are disabled for background model tasks',
+                });
+            }
+            catch {
+                /* Disposal also closes unanswered provider requests. */
+            }
+            fail(Object.assign(new Error('Model requested interactive input'), {
+                code: 'PLUGIN_MODEL_INTERACTION_REQUIRED',
+            }));
+            provider.dispose();
+            return;
+        }
+        if ((event.kind === 'error' || event.method === 'provider/exited') && relevant) {
+            if (event.method !== 'provider/exited' && params?.willRetry === true) {
+                context.onDiagnostic?.({ retryCount: ++retries });
+                return;
+            }
+            fail(Object.assign(new Error(String(params?.error?.message ?? params?.message ?? 'Model provider failed')), { code: 'PLUGIN_MODEL_PROVIDER_ERROR' }));
+            provider.dispose();
+            return;
+        }
+        if (!session || event.providerSessionId !== session)
+            return;
+        if (event.method === 'item/started' && params?.item?.type === 'agentMessage') {
+            flush();
+            streamItem = params.item.id;
+            streamPhase = params.item.phase;
+            if (streamItem && streamPhase)
+                phases.set(streamItem, streamPhase);
+        }
+        else if (event.method === 'item/agentMessage/delta' && typeof params?.delta === 'string') {
+            const itemId = params.itemId ?? streamItem;
+            const phase = params.phase ?? (itemId ? phases.get(itemId) : streamPhase);
+            if (itemId !== streamItem || phase !== streamPhase)
+                flush();
+            streamItem = itemId;
+            streamPhase = phase;
+            bytes += Buffer.byteLength(params.delta);
+            if (bytes > 32 * 1024 * 1024) {
+                fail(new Error('Model output exceeds 32 MiB'));
+                return;
+            }
+            buffered += params.delta;
+            if (buffered.length >= 16000)
+                flush();
+            else
+                flushTimer ??= setTimeout(flush, 50);
+        }
+        else if (event.method === 'item/completed' &&
+            params?.item?.type === 'agentMessage' &&
+            typeof params.item.text === 'string') {
+            flush();
+            if (Buffer.byteLength(params.item.text) > 32 * 1024 * 1024) {
+                fail(new Error('Model output exceeds 32 MiB'));
+                return;
+            }
+            // Only final messages supply the business result; progress deltas may contain commentary.
+            if (!params.item.phase || params.item.phase === 'final_answer')
+                text = params.item.text;
+        }
+        else if (event.method === 'turn/completed') {
+            if (params?.turn?.status !== 'completed')
+                fail(Object.assign(new Error(`Model turn ended with ${String(params?.turn?.status)}${params?.turn?.error?.message ? `: ${params.turn.error.message}` : ''}`), { code: 'PLUGIN_MODEL_TURN_FAILED' }));
+            else if (text === undefined)
+                fail(new Error('Model returned no final text'));
+            else {
+                flush();
+                finish(text);
+            }
+        }
+    };
+    const unsubscribe = provider.onEvent(listener);
+    const abort = () => {
+        fail(Object.assign(new Error('Model execution cancelled'), { code: 'PLUGIN_EXECUTION_CANCELLED' }));
+        if (session && turn)
+            void provider.interrupt(session, turn).catch(() => { });
+        provider.dispose();
+    };
+    context.signal.addEventListener('abort', abort, { once: true });
+    try {
+        session =
+            context.conversation?.threadId ??
+                (await provider.startSession({
+                    cwd: context.cwd,
+                    ephemeral: true,
+                    readOnly: true,
+                    modelExecution: true,
+                    ...(request.model ? { modelId: request.model } : {}),
+                    ...(request.instructions ? { developerInstructions: request.instructions } : {}),
+                }));
+        if (context.conversation)
+            context.conversation.threadId = session;
+        context.onDiagnostic?.({
+            ...(provider.getSessionModel(session)?.id
+                ? { selectedModel: provider.getSessionModel(session).id }
+                : {}),
+        });
+        context.signal.throwIfAborted();
+        const [, result] = await Promise.all([
+            provider
+                .sendMessage(session, request.prompt, [], {
+                reasoningSummary: 'none',
+                reasoningEffort: request.reasoningEffort,
+                outputSchema: request.outputSchema,
+                modelExecution: true,
+            })
+                .then(value => {
+                turn = value.turnId;
+            }),
+            completed,
+        ]);
+        context.signal.throwIfAborted();
+        return {
+            text: result,
+            provider: request.provider,
+            mode: request.mode,
+            ...(provider.getSessionModel(session)?.id
+                ? { model: provider.getSessionModel(session).id }
+                : {}),
+        };
+    }
+    catch (error) {
+        if (context.conversation) {
+            delete context.conversation.threadId;
+            provider.dispose();
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(flushTimer);
+        context.signal.removeEventListener('abort', abort);
+        unsubscribe();
+        if (!context.conversation)
+            provider.dispose();
+    }
+}

package/dist/process-env.d.ts

@@ -0,0 +1,2 @@
+export { prependNodePath as createAgentChildEnv, resolveSpawnCommand as agentSpawnCommand, versionManagerExecutableCandidates, } from '@mearl/daemon-core';
+export type { SpawnCommand as AgentSpawnCommand } from '@mearl/daemon-core';

package/dist/process-env.js

@@ -0,0 +1 @@
+export { prependNodePath as createAgentChildEnv, resolveSpawnCommand as agentSpawnCommand, versionManagerExecutableCandidates, } from '@mearl/daemon-core';

package/dist/provider.d.ts

@@ -0,0 +1,58 @@
+import type { AgentInstalledSkill } from './generated/agent-skills.js';
+import type { AgentChatEventKind, AgentChatImageInput, AgentChatListSessionsOptions, AgentChatModelInfo, AgentChatProviderDescriptor, AgentChatRunOptions, AgentChatSessionSummary } from './generated/agent-chat.js';
+export interface AgentProviderEvent {
+    providerSessionId?: string;
+    kind: AgentChatEventKind;
+    method: string;
+    params: unknown;
+    timestamp?: number;
+    requestId?: string | number;
+}
+export interface AgentProviderSessionOptions {
+    cwd?: string;
+    developerInstructions?: string;
+    ephemeral?: boolean;
+    readOnly?: boolean;
+    modelExecution?: boolean;
+    modelId?: string;
+}
+export interface AgentProviderTurnOptions {
+    reasoningEffort?: AgentChatRunOptions['reasoningEffort'];
+    reasoningSummary?: 'none' | 'detailed';
+    outputSchema?: Record<string, unknown>;
+    modelExecution?: boolean;
+}
+export type AgentProviderSessionSummary = Omit<AgentChatSessionSummary, 'providerId'>;
+export interface AgentProviderListSessionsOptions extends Omit<AgentChatListSessionsOptions, 'providerId' | 'limit'> {
+    limit: number;
+}
+export interface AgentProviderListSessionsResult {
+    sessions: AgentProviderSessionSummary[];
+    nextCursor?: string;
+}
+export interface AgentProviderResumeResult {
+    providerSessionId: string;
+    history?: AgentProviderEvent[];
+    historyComplete?: boolean;
+}
+export interface AgentProvider {
+    readonly id: string;
+    getDescriptor(): Promise<AgentChatProviderDescriptor>;
+    prepare(): Promise<void>;
+    onEvent(listener: (event: AgentProviderEvent) => void): () => void;
+    listSessions?(options: AgentProviderListSessionsOptions): Promise<AgentProviderListSessionsResult>;
+    listSkills?(cwd?: string): Promise<AgentInstalledSkill[]>;
+    startSession(options: AgentProviderSessionOptions): Promise<string>;
+    resumeSession(providerSessionId: string, options: AgentProviderSessionOptions): Promise<AgentProviderResumeResult>;
+    getSessionModel?(providerSessionId: string): AgentChatModelInfo | undefined;
+    validateMessageInput?(images: AgentChatImageInput[]): Promise<void>;
+    sendMessage(providerSessionId: string, message: string, images?: AgentChatImageInput[], options?: AgentProviderTurnOptions): Promise<{
+        turnId: string;
+    }>;
+    interrupt(providerSessionId: string, turnId: string): Promise<void>;
+    closeSession(providerSessionId: string): Promise<void>;
+    openSession?(providerSessionId: string): Promise<void>;
+    openWorkspace?(cwd: string): Promise<void>;
+    respondToRequest(requestId: string | number, result: unknown): void;
+    dispose(): void;
+}

package/dist/provider.js

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

package/dist/qoder-provider.d.ts

@@ -0,0 +1,68 @@
+import type { AgentInstalledSkill } from './generated/agent-skills.js';
+import fs from 'node:fs';
+import type * as acp from '@agentclientprotocol/sdk';
+import type { AgentChatImageInput, AgentChatModelInfo, AgentChatProviderDescriptor } from './generated/agent-chat.js';
+import type { AgentProvider, AgentProviderEvent, AgentProviderListSessionsOptions, AgentProviderListSessionsResult, AgentProviderResumeResult, AgentProviderSessionOptions } from './provider.js';
+export declare function qoderModelInfo(configOptions: acp.SessionConfigOption[] | null | undefined): AgentChatModelInfo | undefined;
+export declare function parseQoderSkillsList(output: string, cwd: string, home?: string): AgentInstalledSkill[];
+export declare function qoderInstallCommand(platform?: NodeJS.Platform): string;
+interface QoderExecutableCandidateOptions {
+    env?: NodeJS.ProcessEnv;
+    homedir?: () => string;
+    platform?: NodeJS.Platform;
+    processExecPath?: string;
+    readdirSync?: typeof fs.readdirSync;
+}
+export declare function qoderExecutableCandidatePaths(options?: QoderExecutableCandidateOptions): string[];
+export declare class QoderAgentProvider implements AgentProvider {
+    private readonly log;
+    private readonly clientVersion;
+    readonly id = "qoder";
+    private process;
+    private sdk;
+    private connection;
+    private context;
+    private initializeResponse;
+    private startPromise;
+    private lifecycle;
+    private listeners;
+    private sessions;
+    private pendingPermissions;
+    private historyCaptures;
+    private nextTurnId;
+    private readonly executableResolver;
+    constructor(log: (...args: any[]) => void, clientVersion: string);
+    getDescriptor(): Promise<AgentChatProviderDescriptor>;
+    prepare(): Promise<void>;
+    onEvent(listener: (event: AgentProviderEvent) => void): () => void;
+    listSessions(options: AgentProviderListSessionsOptions): Promise<AgentProviderListSessionsResult>;
+    listSkills(cwd?: string): Promise<AgentInstalledSkill[]>;
+    startSession(options: AgentProviderSessionOptions): Promise<string>;
+    resumeSession(providerSessionId: string, options: AgentProviderSessionOptions): Promise<AgentProviderResumeResult>;
+    getSessionModel(providerSessionId: string): AgentChatModelInfo | undefined;
+    validateMessageInput(images: AgentChatImageInput[]): Promise<void>;
+    sendMessage(providerSessionId: string, message: string, images?: AgentChatImageInput[]): Promise<{
+        turnId: string;
+    }>;
+    interrupt(providerSessionId: string, _turnId: string): Promise<void>;
+    closeSession(providerSessionId: string): Promise<void>;
+    respondToRequest(requestId: string | number, result: unknown): void;
+    dispose(): void;
+    private ensureStarted;
+    private start;
+    private runPrompt;
+    private handleSessionUpdate;
+    private emitToolUpdate;
+    private handlePermissionRequest;
+    private cancelPermissions;
+    private handleExit;
+    private getContext;
+    private assertImageInputSupported;
+    private withTimeout;
+    private probeExecutable;
+    private runSkillsList;
+    private resolveExecutable;
+    private resolveExecutableCandidates;
+    private emit;
+}
+export {};