@myagentroam/agent 0.11.33 → 0.11.34

package/dist/cli/catalog-file.d.ts

@@ -0,0 +1,78 @@
+import { type AgentModelConfiguration, type ModelCatalog } from '../index.js';
+export type CliModelCredentialSource = 'CODEX_AUTH_FILE';
+export interface CliModelConfiguration extends AgentModelConfiguration {
+    credentialSource?: CliModelCredentialSource;
+}
+export interface CliModelCatalog extends Omit<ModelCatalog, 'models'> {
+    models: readonly CliModelConfiguration[];
+}
+export declare const modelCatalogPath: (home: string) => string;
+export declare function readModelCatalog(home: string): Promise<CliModelCatalog>;
+export declare function writeModelCatalog(home: string, catalog: CliModelCatalog): Promise<void>;
+export declare function serializeModel(model: CliModelConfiguration): {
+    apiKey: string;
+    conversationModel?: boolean;
+    useResourceUrl?: boolean;
+    responsesConfigurationUpdates?: boolean;
+    responsesTransport?: import("../index.js").ResponsesTransport;
+    responsesPreviousResponseId?: boolean;
+    id: string;
+    name: string;
+    protocol: "OPENAI_RESPONSES" | "ANTHROPIC_MESSAGES";
+    baseUrl: string;
+    modelId: string;
+    contextWindowTokens: number;
+    maxOutputTokens: number;
+    inputCapabilities: ("TEXT" | "IMAGE")[];
+    outputCapabilities: ["TEXT"];
+    reasoningEfforts: ("low" | "medium" | "high" | "xhigh" | "max" | "ultra")[];
+    defaultReasoningEffort?: "low" | "medium" | "high" | "xhigh" | "max" | "ultra" | undefined;
+    titleGeneration: boolean;
+    codeMode: boolean;
+    fastMode?: boolean | undefined;
+    serviceTier?: "default" | "auto" | "flex" | "priority" | "fast" | "ultrafast" | undefined;
+    hostedWebSearch: boolean;
+    responsesToolNamespace?: string | undefined;
+    responsesOptionalParameters?: {
+        reasoningEffort: boolean;
+        reasoningSummary: boolean;
+        textVerbosity: boolean;
+        promptCacheKey: boolean;
+        nativeTools?: boolean | undefined;
+    } | undefined;
+    enabled: boolean;
+} | {
+    credential: {
+        type: "CODEX_AUTH_FILE";
+    };
+    conversationModel?: boolean;
+    useResourceUrl?: boolean;
+    responsesConfigurationUpdates?: boolean;
+    responsesTransport?: import("../index.js").ResponsesTransport;
+    responsesPreviousResponseId?: boolean;
+    id: string;
+    name: string;
+    protocol: "OPENAI_RESPONSES" | "ANTHROPIC_MESSAGES";
+    baseUrl: string;
+    modelId: string;
+    contextWindowTokens: number;
+    maxOutputTokens: number;
+    inputCapabilities: ("TEXT" | "IMAGE")[];
+    outputCapabilities: ["TEXT"];
+    reasoningEfforts: ("low" | "medium" | "high" | "xhigh" | "max" | "ultra")[];
+    defaultReasoningEffort?: "low" | "medium" | "high" | "xhigh" | "max" | "ultra" | undefined;
+    titleGeneration: boolean;
+    codeMode: boolean;
+    fastMode?: boolean | undefined;
+    serviceTier?: "default" | "auto" | "flex" | "priority" | "fast" | "ultrafast" | undefined;
+    hostedWebSearch: boolean;
+    responsesToolNamespace?: string | undefined;
+    responsesOptionalParameters?: {
+        reasoningEffort: boolean;
+        reasoningSummary: boolean;
+        textVerbosity: boolean;
+        promptCacheKey: boolean;
+        nativeTools?: boolean | undefined;
+    } | undefined;
+    enabled: boolean;
+};

package/dist/cli/catalog-file.js

@@ -0,0 +1,102 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AgentError, parseModelCatalog } from '../index.js';
+export const modelCatalogPath = (home) => join(home, '.mar', 'agent', 'models.json');
+export async function readModelCatalog(home) {
+    try {
+        return parseCliModelCatalog(JSON.parse(await readFile(modelCatalogPath(home), 'utf8')), {
+            allowLoopbackHttp: true
+        });
+    }
+    catch (cause) {
+        if (cause instanceof AgentError)
+            throw cause;
+        if (cause.code === 'ENOENT')
+            return { version: 1, models: [] };
+        throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Model catalog cannot be read.', {
+            cause
+        });
+    }
+}
+export async function writeModelCatalog(home, catalog) {
+    const path = modelCatalogPath(home);
+    await mkdir(join(home, '.mar', 'agent'), { recursive: true });
+    const raw = {
+        version: 1,
+        ...(catalog.defaultModelId ? { defaultModelId: catalog.defaultModelId } : {}),
+        models: catalog.models.map(serializeModel)
+    };
+    parseCliModelCatalog(raw, { allowLoopbackHttp: true });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(raw, null, 2)}\n`, { mode: 0o600 });
+    await rename(temporary, path);
+}
+export function serializeModel(model) {
+    const { apiKey, credentialProvider, credentialSource, ...configuration } = model;
+    if (apiKey !== undefined) {
+        if (credentialProvider !== undefined || credentialSource !== undefined)
+            throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Model credential sources are ambiguous.');
+        return { ...configuration, apiKey: apiKey.reveal() };
+    }
+    if (credentialSource !== undefined)
+        return {
+            ...configuration,
+            credential: { type: credentialSource }
+        };
+    throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Dynamic model credentials cannot be persisted without an external credential marker.');
+}
+function parseCliModelCatalog(input, options = {}) {
+    if (!isRecord(input) || !Array.isArray(input.models))
+        return parseModelCatalog(input, options);
+    const externalCredentialModels = new Set();
+    const normalizedModels = input.models.map((model, index) => {
+        if (isRecord(model) && Object.hasOwn(model, 'highDensityCompaction')) {
+            if (typeof model.highDensityCompaction !== 'boolean')
+                throw invalidCatalog();
+            const { highDensityCompaction: _compaction, ...configuration } = model;
+            void _compaction;
+            model = configuration;
+        }
+        if (isRecord(model) && Object.hasOwn(model, 'responsesEncoding')) {
+            if (model.protocol !== 'OPENAI_RESPONSES' ||
+                (model.responsesEncoding !== 'STANDARD' && model.responsesEncoding !== 'LITE'))
+                throw invalidCatalog();
+            const { responsesEncoding: _encoding, ...configuration } = model;
+            void _encoding;
+            model = configuration;
+        }
+        if (!isRecord(model) || !Object.hasOwn(model, 'credential'))
+            return model;
+        const credential = model.credential;
+        if (!isRecord(credential) ||
+            credential.type !== 'CODEX_AUTH_FILE' ||
+            Object.keys(credential).length !== 1)
+            throw invalidCatalog();
+        if (Object.hasOwn(model, 'apiKey'))
+            throw invalidCatalog();
+        externalCredentialModels.add(index);
+        const { credential: _credential, ...configuration } = model;
+        void _credential;
+        return { ...configuration, apiKey: '__MAR_AGENT_EXTERNAL_CREDENTIAL__' };
+    });
+    const parsed = parseModelCatalog({ ...input, models: normalizedModels }, options);
+    return {
+        ...parsed,
+        models: parsed.models.map((model, index) => {
+            if (!externalCredentialModels.has(index))
+                return model;
+            if (model.protocol !== 'OPENAI_RESPONSES')
+                throw invalidCatalog();
+            const { apiKey: _apiKey, ...configuration } = model;
+            void _apiKey;
+            return { ...configuration, credentialSource: 'CODEX_AUTH_FILE' };
+        })
+    };
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function invalidCatalog() {
+    return new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Model catalog is invalid.');
+}

package/dist/cli/codex-auth-file.d.ts

@@ -1,4 +1,4 @@
-import { type ModelCredential, type ModelCredentialAcquireReason, type ModelCredentialProvider } from '../agent-core/model/configuration.js';
+import { type ModelCredential, type ModelCredentialAcquireReason, type ModelCredentialProvider } from '../index.js';
 export declare class CodexAuthFileCredentialProvider implements ModelCredentialProvider {
     #private;
     constructor(path: string);

package/dist/cli/codex-auth-file.js

@@ -3,9 +3,8 @@ import { constants } from 'node:fs';
 import { lstat, open } from 'node:fs/promises';
 import { promisify } from 'node:util';
 import { z } from 'zod';
-import { MarAgentError } from '../agent-core/error.js';
-import { SecretValue } from '../agent-core/model/configuration.js';
-import { productUserAgent } from '../agent-core/model/product-user-agent.js';
+import { AgentError, SecretValue } from '../index.js';
+import { productUserAgent } from '../network/product-user-agent.js';
 const MAX_AUTH_FILE_BYTES = 1024 * 1024;
 const TOKEN_MAX_BYTES = 131_072;
 const AUTH_FALLBACK_LIFETIME_MS = 8 * 24 * 60 * 60 * 1000;
@@ -32,12 +31,12 @@ export class CodexAuthFileCredentialProvider {
     #closed = false;
     constructor(path) {
         if (!path)
-            throw new MarAgentError('MAR_AGENT_CREDENTIAL_FILE_INVALID', 'Codex auth file path is required.');
+            throw new AgentError('MAR_AGENT_CREDENTIAL_FILE_INVALID', 'Codex auth file path is required.');
         this.#path = path;
     }
     async acquire(reason) {
         if (this.#closed)
-            throw new MarAgentError('MAR_AGENT_CREDENTIAL_FILE_INVALID', 'Codex auth file provider is closed.');
+            throw new AgentError('MAR_AGENT_CREDENTIAL_FILE_INVALID', 'Codex auth file provider is closed.');
         const file = await readSecureAuthFile(this.#path);
         const force = reason === 'UNAUTHORIZED' ||
             (this.#cached !== undefined &&
@@ -184,7 +183,7 @@ foreach ($rule in $acl.Access) {
             throw unsafeFile();
     }
     catch (cause) {
-        if (cause instanceof MarAgentError)
+        if (cause instanceof AgentError)
             throw cause;
         throw unsafeFile(cause);
     }
@@ -217,7 +216,7 @@ function parseAuthFile(content) {
     if (expiresAt === undefined)
         throw invalidFile();
     if (expiresAt <= Date.now())
-        throw new MarAgentError('MAR_AGENT_MODEL_AUTH_FAILED', 'Codex auth file access credential is expired.');
+        throw new AgentError('MAR_AGENT_MODEL_AUTH_FAILED', 'Codex auth file access credential is expired.');
     void result.data.tokens.refresh_token;
     return {
         accessToken: result.data.tokens.access_token,
@@ -237,7 +236,7 @@ function jwtClaims(token) {
         return record(value);
     }
     catch (cause) {
-        if (cause instanceof MarAgentError)
+        if (cause instanceof AgentError)
             throw cause;
         throw invalidFile(cause);
     }
@@ -265,8 +264,8 @@ function record(value) {
         : {};
 }
 function unsafeFile(cause) {
-    return new MarAgentError('MAR_AGENT_CREDENTIAL_FILE_UNSAFE', 'Codex auth file permissions or file type are unsafe.', cause === undefined ? {} : { cause });
+    return new AgentError('MAR_AGENT_CREDENTIAL_FILE_UNSAFE', 'Codex auth file permissions or file type are unsafe.', cause === undefined ? {} : { cause });
 }
 function invalidFile(cause) {
-    return new MarAgentError('MAR_AGENT_CREDENTIAL_FILE_INVALID', 'Codex auth file is invalid.', cause === undefined ? {} : { cause });
+    return new AgentError('MAR_AGENT_CREDENTIAL_FILE_INVALID', 'Codex auth file is invalid.', cause === undefined ? {} : { cause });
 }

package/dist/cli/main.js

@@ -3,14 +3,10 @@ import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { stdin, stdout } from 'node:process';
 import { createInterface } from 'node:readline/promises';
-import { describeMarAgentError, MarAgentError } from '../agent-core/error.js';
-import { LocalAgentHost } from '../agent-core/host/local-agent-host.js';
-import { AnthropicMessagesAdapter } from '../agent-core/model/anthropic-messages.js';
-import { readModelCatalog, writeModelCatalog } from '../agent-core/model/catalog-file.js';
-import { marAgentReasoningEffortSchema, resolveModelDefaultReasoningEffort, SecretValue } from '../agent-core/model/configuration.js';
-import { OpenAiResponsesAdapter } from '../agent-core/model/openai-responses.js';
-import { DEFAULT_COMPACTION_FOCUS } from '../agent-core/runtime/compaction/history.js';
-import { createMarAgent } from '../agent-core/sdk/agent.js';
+import { describeAgentError } from '../error.js';
+import { LocalAgentHost } from '../host.js';
+import { readModelCatalog, writeModelCatalog } from './catalog-file.js';
+import { AgentError, createAgent, agentReasoningEffortSchema, resolveModelDefaultReasoningEffort, SecretValue, testAgentModelTransport } from '../index.js';
 import { CodexAuthFileCredentialProvider } from './codex-auth-file.js';
 import { generateSessionTitle } from '../shared/auto-title.js';
 const HELP = `maragent - MAR coding agent
@@ -27,10 +23,10 @@ function takeOption(arguments_, name) {
     if (index < 0)
         return undefined;
     if (arguments_.indexOf(name, index + 1) >= 0)
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `${name} cannot be repeated.`);
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `${name} cannot be repeated.`);
     const value = arguments_[index + 1];
     if (!value)
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `${name} requires a value.`);
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `${name} requires a value.`);
     arguments_.splice(index, 2);
     return value;
 }
@@ -48,26 +44,26 @@ function booleanFlag(arguments_, enabled, disabled, fallback) {
     const on = takeFlag(arguments_, enabled);
     const off = takeFlag(arguments_, disabled);
     if (on && off)
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `${enabled} and ${disabled} cannot be combined.`);
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `${enabled} and ${disabled} cannot be combined.`);
     return on ? true : off ? false : fallback;
 }
 async function readApiKey() {
     if (stdin.isTTY)
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--api-key-stdin requires piped stdin.');
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--api-key-stdin requires piped stdin.');
     stdin.setEncoding('utf8');
     let value = '';
     for await (const chunk of stdin)
         value += chunk;
     if (!value.trim())
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'API key stdin was empty.');
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'API key stdin was empty.');
     return value.trim();
 }
 async function modelsCommand(home, arguments_, codexAuthFile) {
     if (arguments_.includes('--high-density-compaction') ||
         arguments_.includes('--no-high-density-compaction'))
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'High-density compaction is no longer a model option.');
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'High-density compaction is no longer a model option.');
     if (arguments_.includes('--responses-encoding'))
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Responses encoding is no longer configurable.');
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Responses encoding is no longer configurable.');
     const action = arguments_[1];
     const catalog = await loadCatalog(home);
     if (action === 'list') {
@@ -77,13 +73,13 @@ async function modelsCommand(home, arguments_, codexAuthFile) {
     }
     const id = arguments_[2];
     if (!id)
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Model id is required.');
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Model id is required.');
     const existing = catalog.models.find((model) => model.id === id);
     if (action === 'remove') {
         if (!existing)
-            throw new MarAgentError('MAR_AGENT_MODEL_NOT_FOUND', 'Model was not found.');
+            throw new AgentError('MAR_AGENT_MODEL_NOT_FOUND', 'Model was not found.');
         if (!takeFlag(arguments_, '--yes') && !stdin.isTTY)
-            throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Non-interactive removal requires --yes.');
+            throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Non-interactive removal requires --yes.');
         await writeModelCatalog(home, {
             version: 1,
             models: catalog.models.filter((model) => model.id !== id),
@@ -95,17 +91,11 @@ async function modelsCommand(home, arguments_, codexAuthFile) {
     }
     if (action === 'test') {
         if (!existing)
-            throw new MarAgentError('MAR_AGENT_MODEL_NOT_FOUND', 'Model was not found.');
+            throw new AgentError('MAR_AGENT_MODEL_NOT_FOUND', 'Model was not found.');
         assertExternalCredentialAvailable(existing, codexAuthFile);
         const runtime = runtimeModels([existing], codexAuthFile);
-        const adapter = existing.protocol === 'OPENAI_RESPONSES'
-            ? new OpenAiResponsesAdapter(runtime.models[0])
-            : new AnthropicMessagesAdapter(runtime.models[0]);
         try {
-            let response = '';
-            for await (const event of adapter.start({ system: 'Reply OK.', messages: [{ role: 'user', content: 'Reply OK.' }], tools: [] }, AbortSignal.timeout(30_000)))
-                if (event.type === 'text.completed')
-                    response = event.text;
+            const { response } = await testAgentModelTransport(runtime.models[0], AbortSignal.timeout(30_000), { system: 'Reply OK.', prompt: 'Reply OK.' });
             stdout.write(`${JSON.stringify({ success: true, modelId: id, response: response.slice(0, 80) })}\n`);
             return;
         }
@@ -114,37 +104,37 @@ async function modelsCommand(home, arguments_, codexAuthFile) {
         }
     }
     if (action !== 'add' && action !== 'edit')
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Unknown model command.');
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Unknown model command.');
     if (action === 'add' && existing)
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Model id already exists.');
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Model id already exists.');
     if (action === 'edit' && !existing)
-        throw new MarAgentError('MAR_AGENT_MODEL_NOT_FOUND', 'Model was not found.');
+        throw new AgentError('MAR_AGENT_MODEL_NOT_FOUND', 'Model was not found.');
     const option = (name, fallback) => takeOption(arguments_, name) ?? fallback;
     const integer = (name, fallback) => {
         const raw = takeOption(arguments_, name);
         const value = raw === undefined ? fallback : Number(raw);
         if (!Number.isSafeInteger(value) || value <= 0)
-            throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `${name} is invalid.`);
+            throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `${name} is invalid.`);
         return value;
     };
     const protocol = option('--protocol', existing?.protocol ?? 'ANTHROPIC_MESSAGES');
     if (protocol !== 'OPENAI_RESPONSES' && protocol !== 'ANTHROPIC_MESSAGES')
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--protocol is invalid.');
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--protocol is invalid.');
     const required = (value, name) => {
         if (!value)
-            throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `${name} is required.`);
+            throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `${name} is required.`);
         return value;
     };
     const credential = option('--credential', existing?.credentialSource === 'CODEX_AUTH_FILE' ? 'codex-auth-file' : 'api-key') ?? 'api-key';
     if (credential !== 'api-key' && credential !== 'codex-auth-file')
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--credential is invalid.');
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--credential is invalid.');
     const hasFastModeOption = arguments_.includes('--fast-mode') || arguments_.includes('--no-fast-mode');
     const fastMode = booleanFlag(arguments_, '--fast-mode', '--no-fast-mode', credential === 'codex-auth-file' ? (existing?.fastMode ?? false) : false);
     if (hasFastModeOption && (protocol !== 'OPENAI_RESPONSES' || credential !== 'codex-auth-file'))
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--fast-mode requires Codex.');
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--fast-mode requires Codex.');
     const readsApiKey = takeFlag(arguments_, '--api-key-stdin');
     if (credential === 'codex-auth-file' && readsApiKey)
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--api-key-stdin cannot be combined with an external credential.');
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--api-key-stdin cannot be combined with an external credential.');
     const responsesTransport = parseResponsesTransport(option('--responses-transport'), protocol, existing?.responsesTransport);
     const reasoningEffortsOption = option('--reasoning-efforts');
     const reasoningEfforts = reasoningEffortsOption === undefined
@@ -208,15 +198,15 @@ async function modelsCommand(home, arguments_, codexAuthFile) {
     });
 }
 function parseReasoningEffort(value, optionName) {
-    const parsed = marAgentReasoningEffortSchema.safeParse(value.trim());
+    const parsed = agentReasoningEffortSchema.safeParse(value.trim());
     if (!parsed.success)
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `${optionName} is invalid.`);
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `${optionName} is invalid.`);
     return parsed.data;
 }
 function parseResponsesTransport(value, protocol, existing) {
     if (protocol !== 'OPENAI_RESPONSES') {
         if (value !== undefined)
-            throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--responses-transport requires OPENAI_RESPONSES.');
+            throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--responses-transport requires OPENAI_RESPONSES.');
         return undefined;
     }
     const selected = value?.toLowerCase();
@@ -228,7 +218,7 @@ function parseResponsesTransport(value, protocol, existing) {
         return { transport: 'HTTP', httpVersion: '2' };
     if (selected === 'http1' || selected === 'http1.1')
         return { transport: 'HTTP', httpVersion: '1.1' };
-    throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--responses-transport is invalid.');
+    throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--responses-transport is invalid.');
 }
 async function main() {
     const arguments_ = process.argv.slice(2);
@@ -254,17 +244,17 @@ async function main() {
     if (permissionModeOption !== undefined &&
         permissionModeOption !== 'auto' &&
         permissionModeOption !== 'full-access')
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--permission-mode must be auto or full-access.');
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', '--permission-mode must be auto or full-access.');
     const permissionMode = permissionModeOption;
     if (legacyAccess !== undefined && legacyAccess !== 'full-access')
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'The deprecated --access option only accepts full-access.');
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'The deprecated --access option only accepts full-access.');
     const format = takeOption(arguments_, '--format') ?? 'text';
     const command = arguments_[0];
     const selectedModel = catalog.models.find((model) => model.id === modelId && model.enabled && model.conversationModel !== false);
     if (selectedModel !== undefined)
         assertExternalCredentialAvailable(selectedModel, codexAuthFile);
     if (reasoningEffort && selectedModel && !selectedModel.reasoningEfforts.includes(reasoningEffort))
-        throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `Reasoning effort "${reasoningEffort}" is not supported by model "${selectedModel.id}".`);
+        throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', `Reasoning effort "${reasoningEffort}" is not supported by model "${selectedModel.id}".`);
     const interactive = command !== 'run';
     let prompt = command === 'run' ? arguments_.slice(1).join(' ') : '';
     // `run` does not need stdin until a question occurs. Create
@@ -277,7 +267,7 @@ async function main() {
         workspace,
         question: async (request) => {
             if (!stdin.isTTY)
-                throw new MarAgentError('MAR_AGENT_USER_INPUT_UNAVAILABLE', 'Interactive input is unavailable.');
+                throw new AgentError('MAR_AGENT_USER_INPUT_UNAVAILABLE', 'Interactive input is unavailable.');
             const answers = {};
             for (const question of request.questions) {
                 const value = question;
@@ -288,7 +278,7 @@ async function main() {
         }
     });
     const runtime = runtimeModels(catalog.models, codexAuthFile);
-    const agent = await createMarAgent({
+    const agent = await createAgent({
         mode: 'normal',
         host,
         models: runtime.models,
@@ -301,22 +291,22 @@ async function main() {
         }
         if (command === 'sessions' && arguments_[1] === 'delete' && arguments_[2]) {
             if (!takeFlag(arguments_, '--yes') && !stdin.isTTY)
-                throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Non-interactive deletion requires --yes.');
+                throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Non-interactive deletion requires --yes.');
             await agent.deleteSession(arguments_[2]);
             return;
         }
         if (command === 'sessions')
-            throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Unknown sessions command.');
+            throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Unknown sessions command.');
         let resumeId = command === 'resume' ? arguments_[1] : undefined;
         if (command === 'resume' && !resumeId) {
             if (!stdin.isTTY)
-                throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'resume requires a session id.');
+                throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'resume requires a session id.');
             const listed = (await agent.listSessions());
             for (const item of listed.sessions ?? [])
                 stdout.write(`${item.id}\t${item.title}\t${item.lastActivityAt}\n`);
             resumeId = (await requireTerminal().question('Session ID: ')).trim();
             if (!resumeId)
-                throw new MarAgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Session id is required.');
+                throw new AgentError('MAR_AGENT_CLI_ARGUMENT_INVALID', 'Session id is required.');
         }
         const session = resumeId
             ? await agent.openSession(resumeId)
@@ -346,12 +336,12 @@ async function main() {
                 if (!prompt.trim())
                     break;
                 const invocation = parseExecutionInvocation(prompt);
-                const runInput = {
+                const executionOptions = {
                     ...(permissionMode === undefined ? {} : { permissionMode }),
-                    prompt: invocation.prompt,
                     ...(modelId === undefined ? {} : { modelId }),
                     ...(reasoningEffort === undefined ? {} : { reasoningEffort })
                 };
+                const runInput = { ...executionOptions, prompt: invocation.prompt };
                 const metadata = !resumeId && invocation.mode !== 'compact'
                     ? await agent.getSession(session.id).catch(() => undefined)
                     : undefined;
@@ -360,7 +350,7 @@ async function main() {
                 const handle = invocation.mode === 'plan'
                     ? session.plan(runInput)
                     : invocation.mode === 'compact'
-                        ? session.compact(runInput)
+                        ? session.compact(invocation.prompt ? runInput : executionOptions)
                         : session.run(runInput);
                 activeHandle = handle;
                 for await (const event of handle) {
@@ -441,7 +431,7 @@ function runtimeModels(models, codexAuthFile) {
 }
 function assertExternalCredentialAvailable(model, codexAuthFile) {
     if (model.credentialSource === 'CODEX_AUTH_FILE' && codexAuthFile === undefined)
-        throw new MarAgentError('MAR_AGENT_MODEL_AUTH_FAILED', 'Codex auth file is required for the selected model.');
+        throw new AgentError('MAR_AGENT_MODEL_AUTH_FAILED', 'Codex auth file is required for the selected model.');
 }
 function cliExitCode(code) {
     if (code === undefined)
@@ -468,11 +458,11 @@ function parseExecutionInvocation(input) {
         prompt: argument ||
             (mode === 'plan'
                 ? 'Investigate the current objective, resolve discoverable uncertainty, and produce an executable implementation and verification plan without claiming the work is complete.'
-                : DEFAULT_COMPACTION_FOCUS)
+                : '')
     };
 }
 main().catch((error) => {
-    const diagnostic = describeMarAgentError(error, 'MAR_AGENT_CLI_FAILED', 'CLI command failed.');
+    const diagnostic = describeAgentError(error, 'MAR_AGENT_CLI_FAILED', 'CLI command failed.');
     process.stderr.write(`${diagnostic.code}: ${diagnostic.message}\n`);
     process.exitCode = cliExitCode(diagnostic.code);
 });

package/dist/error.d.ts

@@ -0,0 +1,15 @@
+export declare class AgentError extends Error {
+    readonly code: string;
+    readonly publicMessage: string;
+    readonly details: Readonly<Record<string, unknown>> | undefined;
+    readonly retryable: boolean;
+    constructor(code: string, message: string, options?: {
+        details?: Readonly<Record<string, unknown>>;
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+export declare function describeAgentError(error: unknown, fallbackCode: string, fallbackMessage?: string, includeCauses?: boolean): {
+    code: string;
+    message: string;
+};

package/dist/error.js

@@ -0,0 +1,74 @@
+export class AgentError extends Error {
+    code;
+    publicMessage;
+    details;
+    retryable;
+    constructor(code, message, options = {}) {
+        super(`${code}: ${message}`, { cause: options.cause });
+        this.name = 'MarAgentError';
+        this.code = code;
+        this.publicMessage = message;
+        this.details = options.details;
+        this.retryable = options.retryable ?? false;
+    }
+}
+const MAX_ERROR_MESSAGE_CHARACTERS = 1_000;
+export function describeAgentError(error, fallbackCode, fallbackMessage = 'MAR Agent operation failed.', includeCauses = true) {
+    const code = diagnosticCode(error) ?? fallbackCode;
+    const messages = [];
+    const seen = new Set();
+    let current = error;
+    while (current !== undefined && current !== null && !seen.has(current) && messages.length < 4) {
+        seen.add(current);
+        const currentCode = diagnosticCode(current);
+        const message = diagnosticMessage(current, currentCode);
+        const summary = message && currentCode !== undefined && currentCode !== code
+            ? `${currentCode}: ${message}`
+            : message;
+        if (summary && !messages.includes(summary))
+            messages.push(summary);
+        if (!includeCauses)
+            break;
+        current = diagnosticCause(current);
+    }
+    return {
+        code,
+        message: truncateErrorMessage(messages.join(' Caused by: ') || fallbackMessage)
+    };
+}
+function diagnosticCode(value) {
+    if (value instanceof AgentError)
+        return value.code;
+    if (value === null || typeof value !== 'object' || !('code' in value))
+        return undefined;
+    const code = value.code;
+    return typeof code === 'string' && code.trim().length > 0 ? code.trim().slice(0, 80) : undefined;
+}
+function diagnosticMessage(value, code) {
+    const message = value instanceof AgentError
+        ? value.publicMessage
+        : value instanceof Error
+            ? value.message
+            : value !== null &&
+                typeof value === 'object' &&
+                'message' in value &&
+                typeof value.message === 'string'
+                ? value.message
+                : typeof value === 'string'
+                    ? value
+                    : undefined;
+    const normalized = message?.trim();
+    if (!normalized)
+        return undefined;
+    return code !== undefined && normalized.startsWith(`${code}: `)
+        ? normalized.slice(code.length + 2)
+        : normalized;
+}
+function diagnosticCause(value) {
+    if (value === null || typeof value !== 'object' || !('cause' in value))
+        return undefined;
+    return value.cause;
+}
+function truncateErrorMessage(value) {
+    return [...value].slice(0, MAX_ERROR_MESSAGE_CHARACTERS).join('');
+}