@myagentroam/agent 0.9.115 → 0.9.117

package/dist/index.d.ts

@@ -1,17 +1,13 @@
 export { MarAgentError } from './error.js';
 export { SecretValue, marAgentReasoningEffortSchema, parseModelCatalog, resolveModelDefaultReasoningEffort, type MarAgentModelConfiguration, type MarAgentReasoningEffort, type ModelCatalog, type ModelCredential, type ModelCredentialAcquireReason, type ModelCredentialProvider, type ResponsesTransport } from './model/configuration.js';
 export { MAR_AGENT_HOST_API_VERSION, negotiateHost, type HostDescription, type MarAgentHostCapability } from './host/contracts.js';
-export { OpenAiResponsesAdapter } from './model/openai-responses.js';
-export { AnthropicMessagesAdapter } from './model/anthropic-messages.js';
-export type { ClientToolDefinition, ModelAdapter, ModelEvent, ModelMessage, ModelRequest, ModelStopReason, ModelTurnSession, ModelUsage } from './model/contracts.js';
-export { LocalWorkspaceTools, type ExecInput, type ExecResult } from './tools/local-workspace-tools.js';
+export { testMarAgentModelTransport } from './model/transport-test.js';
+export type { ClientToolDefinition } from './model/contracts.js';
 export type { ApplyPatchFileResult, ApplyPatchResult } from './tools/apply-patch.js';
 export { openMarAgentSessionCatalog, type MarAgentContextUsage, type MarAgentSessionDeleteResult, type MarAgentHistoryEntry, type MarAgentHistoryPage, type MarAgentSessionCatalog, type MarAgentSessionImage, type MarAgentSessionPage, type MarAgentSessionSummary } from './session/catalog.js';
 export { LocalAgentHost, selectExecutionShell, type LocalAgentExecutionMcpBinding, type LocalAgentMcpBinding, type LocalAgentExecutionExtensions } from './host/local-agent-host.js';
 export type { LocalProcessExecutor, LocalProcessSpawnRequest } from './host/local-process-executor.js';
 export type { WorkspacePathMount } from './tools/shared/path-resolver.js';
+export type { SessionListInput, SessionSource } from './session/types.js';
 export { createMarAgent } from './sdk/agent.js';
-export { MAR_AGENT_PROMPT_VERSION, buildSystemPrompt } from './prompts/index.js';
-export { TodoStore, type TodoItem } from './tools/todo.js';
-export { SubagentScheduler, type SubagentOutputOptions, type SubagentMessageOptions, type SubagentRunOptions, type SubagentTaskInput, type SubagentTaskResult, type SubagentTaskSnapshot } from './subagent/scheduler.js';
 export type { AccessMode, CreateMarAgentOptions, CreateSessionInput, ExecutionHandle, ExecutionMode, ExecutionResult, HostSessionResourceSnapshot, HostSkill, HostExecutionExtensions, McpToolCatalogContext, MarAgent, MarAgentEvent, MarAgentHost, MarAgentImageMetadata, MarAgentSession, MarAgentToolArtifact, MarAgentToolImageArtifact, RolloutBudgetOptions, RunInput, RunInputImage, ToolCall, ToolExecutionContext, ToolExecutionResult } from './sdk/types.js';

package/dist/index.js

@@ -1,12 +1,7 @@
 export { MarAgentError } from './error.js';
 export { SecretValue, marAgentReasoningEffortSchema, parseModelCatalog, resolveModelDefaultReasoningEffort } from './model/configuration.js';
 export { MAR_AGENT_HOST_API_VERSION, negotiateHost } from './host/contracts.js';
-export { OpenAiResponsesAdapter } from './model/openai-responses.js';
-export { AnthropicMessagesAdapter } from './model/anthropic-messages.js';
-export { LocalWorkspaceTools } from './tools/local-workspace-tools.js';
+export { testMarAgentModelTransport } from './model/transport-test.js';
 export { openMarAgentSessionCatalog } from './session/catalog.js';
 export { LocalAgentHost, selectExecutionShell } from './host/local-agent-host.js';
 export { createMarAgent } from './sdk/agent.js';
-export { MAR_AGENT_PROMPT_VERSION, buildSystemPrompt } from './prompts/index.js';
-export { TodoStore } from './tools/todo.js';
-export { SubagentScheduler } from './subagent/scheduler.js';

package/dist/model/transport-test.d.ts

@@ -0,0 +1,3 @@
+import type { MarAgentModelConfiguration } from './configuration.js';
+/** Probe a configured protocol without exposing its adapter or wire events. */
+export declare function testMarAgentModelTransport(configuration: MarAgentModelConfiguration, signal: AbortSignal): Promise<boolean>;

package/dist/model/transport-test.js

@@ -0,0 +1,23 @@
+import { AnthropicMessagesAdapter } from './anthropic-messages.js';
+import { OpenAiResponsesAdapter } from './openai-responses.js';
+/** Probe a configured protocol without exposing its adapter or wire events. */
+export async function testMarAgentModelTransport(configuration, signal) {
+    const adapter = configuration.protocol === 'OPENAI_RESPONSES'
+        ? new OpenAiResponsesAdapter(configuration)
+        : new AnthropicMessagesAdapter(configuration);
+    try {
+        let completed = false;
+        for await (const event of adapter.start({
+            system: 'You are performing a model transport connectivity test.',
+            messages: [{ role: 'user', content: 'Reply with OK.' }],
+            tools: [],
+            allowTools: false
+        }, signal))
+            if (event.type === 'completed')
+                completed = true;
+        return completed;
+    }
+    finally {
+        await adapter.close?.();
+    }
+}

package/dist/sdk/agent.d.ts

@@ -1,2 +1,11 @@
+import { type MarAgentModelConfiguration } from '../model/configuration.js';
+import type { ModelAdapter } from '../model/contracts.js';
 import type { CreateMarAgentOptions, MarAgent } from './types.js';
+interface InternalCreateMarAgentOptions extends CreateMarAgentOptions {
+    readonly adapterFactory?: (configuration: MarAgentModelConfiguration) => ModelAdapter;
+}
+/** Validate models before Host negotiation and expose only built-in protocol adapters. */
 export declare function createMarAgent(options: CreateMarAgentOptions): Promise<MarAgent>;
+/** Package-internal seam for deterministic adapter tests; not a package export. */
+export declare function createMarAgentWithAdapter(options: InternalCreateMarAgentOptions): Promise<MarAgent>;
+export {};

package/dist/sdk/agent.js

@@ -33,6 +33,7 @@ import { executeRegisteredTool } from '../tools/runtime.js';
 import { scheduleToolCallBatch } from '../tools/scheduler.js';
 import { withCodeModeResultTypes } from '../tools/code-mode.js';
 import { SubagentSessionController } from '../subagent/session-controller.js';
+/** Retry only classified recoverable failures within the attempt budget; never retry cancellation. */
 async function recoverModelStream(error, retryState, signal) {
     if (signal.aborted ||
         !(isRetryableModelRequestError(error) ||
@@ -45,7 +46,14 @@ async function recoverModelStream(error, retryState, signal) {
     await waitForModelRetry(typeof error.details?.retryAfter === 'string' ? error.details.retryAfter : null, retryState.attempts - 1, signal, delayMs);
     return true;
 }
+/** Validate models before Host negotiation and expose only built-in protocol adapters. */
 export async function createMarAgent(options) {
+    if (Object.hasOwn(options, 'adapterFactory'))
+        throw new MarAgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Custom model adapters are not supported.');
+    return createMarAgentWithAdapter(options);
+}
+/** Package-internal seam for deterministic adapter tests; not a package export. */
+export async function createMarAgentWithAdapter(options) {
     const rolloutBudgetOptions = resolveRolloutBudgetOptions(options.rolloutBudget);
     const resolvedModels = resolveAgentModels(options.models);
     let { models, defaultModelId } = resolvedModels;
@@ -155,6 +163,7 @@ export async function createMarAgent(options) {
             let manualCompactionStarted = false;
             let emitTail = Promise.resolve();
             let exhaustedModelAttempt;
+            // Serialize durable events before either the local stream or Host observes them.
             const emit = (event) => {
                 const full = {
                     ...event,
@@ -344,26 +353,21 @@ export async function createMarAgent(options) {
                         const inputImageMetadata = input.images?.length
                             ? await store.persistInputImages(sessionId, input.images)
                             : [];
-                        try {
-                            await store.append(sessionId, {
-                                type: 'turn.user',
-                                payload: {
-                                    prompt: input.prompt,
-                                    ...(internal.delivery ? { messageId: internal.delivery.messageId } : {}),
-                                    ...(internal.inputSource === undefined
-                                        ? {}
-                                        : { inputSource: internal.inputSource }),
-                                    ...(input.clientMessageId ? { clientMessageId: input.clientMessageId } : {}),
-                                    ...(inputImageMetadata.length ? { images: inputImageMetadata } : {})
-                                },
-                                executionId,
-                                turnId
-                            });
-                        }
-                        catch (error) {
-                            await store.removeInputImages(sessionId, inputImageMetadata).catch(() => undefined);
-                            throw error;
-                        }
+                        // A failed sync can still leave a complete record; lease recovery decides image ownership.
+                        await store.append(sessionId, {
+                            type: 'turn.user',
+                            payload: {
+                                prompt: input.prompt,
+                                ...(internal.delivery ? { messageId: internal.delivery.messageId } : {}),
+                                ...(internal.inputSource === undefined
+                                    ? {}
+                                    : { inputSource: internal.inputSource }),
+                                ...(input.clientMessageId ? { clientMessageId: input.clientMessageId } : {}),
+                                ...(inputImageMetadata.length ? { images: inputImageMetadata } : {})
+                            },
+                            executionId,
+                            turnId
+                        });
                         messages.push({ role: 'user', content: input.prompt });
                         currentExecutionUserIndex = messages.length - 1;
                         internal.delivery?.applied();
@@ -1157,6 +1161,7 @@ export async function createMarAgent(options) {
                         if (mode !== 'compact' &&
                             sessionSource.type !== 'subagent' &&
                             latestUsage !== undefined) {
+                            // Only a committed GC checkpoint may replace active context and invalidate continuation.
                             const committed = await contextGc.run({
                                 store,
                                 sessionId,
@@ -2079,6 +2084,7 @@ function stableJson(value) {
             .join(',')}}`;
     return JSON.stringify(value) ?? 'undefined';
 }
+/** Project only known, validated tool result shapes into public structured events. */
 function structuredToolEventData(toolName, value) {
     if (!isRecord(value))
         return undefined;
@@ -2172,6 +2178,7 @@ function structuredToolArtifacts(value) {
         throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_INVALID', 'Tool image artifact is invalid.');
     return value.map((artifact) => ({ ...artifact }));
 }
+/** Keep streaming deltas live-only; exec output has one durable copy in model context records. */
 function eventForPersistence(event) {
     if (event.type === 'message.delta' || event.type === 'context.compacting')
         return undefined;

package/dist/sdk/types.d.ts

@@ -1,8 +1,7 @@
 import type { HostDescription } from '../host/contracts.js';
 import type { MarAgentModelConfiguration, MarAgentReasoningEffort } from '../model/configuration.js';
-import type { ModelAdapter } from '../model/contracts.js';
 import type { MarAgentSessionPage, MarAgentSessionSummary } from '../session/catalog.js';
-import type { SessionListInput, SessionSource } from '../session/jsonl-store.js';
+import type { SessionListInput, SessionSource } from '../session/types.js';
 /** @deprecated MAR Agent always executes tools directly through the Host. */
 export type AccessMode = 'full-access';
 export type ExecutionMode = 'run' | 'plan' | 'compact';
@@ -68,6 +67,7 @@ export interface HostSessionResourceSnapshot {
         cwd: string;
     }[];
 }
+/** The Host owns workspace/tool effects; the SDK owns JSONL storage beneath its supplied HOME. */
 export interface MarAgentHost {
     describe(): Promise<HostDescription>;
     executeTool(call: ToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
@@ -229,11 +229,14 @@ export interface ExecutionResult {
     errorCode?: string;
     errorMessage?: string;
 }
+/** A live execution exposes streamed events separately from its terminal result. */
 export interface ExecutionHandle extends AsyncIterable<MarAgentEvent> {
     readonly executionId: string;
     result(): Promise<ExecutionResult>;
+    /** Signals abort; await result() to observe the terminal status and cleanup. */
     cancel(): void;
 }
+/** A persisted Session permits one active main execution at a time. */
 export interface MarAgentSession {
     readonly id: string;
     run(input: RunInput): ExecutionHandle;
@@ -246,11 +249,13 @@ export interface MarAgent {
     openSession(sessionId: string): Promise<MarAgentSession>;
     listSessions(input?: SessionListInput): Promise<MarAgentSessionPage>;
     clearSession(sessionId: string): Promise<void>;
+    /** Rebinds future main executions only; running subagents keep their captured model providers. */
     reconfigureModels(input: {
         readonly models: readonly MarAgentModelConfiguration[];
         readonly defaultModelId?: string;
     }): Promise<void>;
     deleteSession(sessionId: string): Promise<void>;
+    /** Cancels active executions, then closes SDK-owned providers, the Host and the Session store. */
     dispose(): Promise<void>;
 }
 export interface RolloutBudgetOptions {
@@ -271,6 +276,5 @@ export interface CreateMarAgentOptions {
         readonly physicalPath: string;
     };
     rolloutBudget?: false | RolloutBudgetOptions;
-    adapterFactory?: (configuration: MarAgentModelConfiguration) => ModelAdapter;
 }
 export type { MarAgentSessionSummary, SessionListInput, SessionSource };

package/dist/session/catalog.d.ts

@@ -1,4 +1,4 @@
-import { type SessionListInput, type SessionSource } from './jsonl-store.js';
+import type { SessionListInput, SessionSource } from './types.js';
 import type { MarAgentEvent, MarAgentImageMetadata } from '../sdk/types.js';
 export interface MarAgentSessionSummary {
     id: string;

package/dist/session/catalog.js

@@ -1,3 +1,4 @@
+import { MarAgentError } from '../error.js';
 import { JsonlSessionStore } from './jsonl-store.js';
 const MAX_INPUT_IMAGE_BYTES = 5 * 1024 * 1024;
 const INPUT_IMAGE_MIME_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
@@ -90,8 +91,8 @@ function parseCursor(cursor) {
     if (cursor === undefined)
         return undefined;
     const value = Number(cursor);
-    if (!Number.isSafeInteger(value) || value < 1)
-        return undefined;
+    if (!/^[1-9]\d*$/u.test(cursor) || !Number.isSafeInteger(value))
+        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Session history cursor is invalid.');
     return value;
 }
 function isRecord(value) {

package/dist/session/jsonl-store.d.ts

@@ -2,6 +2,8 @@ import type { ModelUsage } from '../model/contracts.js';
 import type { EnvironmentContextState } from '../prompts/core.js';
 import { type TodoSnapshot } from '../tools/todo.js';
 import { type ContextGcCheckpointDraft } from './context-gc-checkpoint.js';
+import type { SessionListInput, SessionSource } from './types.js';
+export type { SessionListInput, SessionSource } from './types.js';
 export interface SessionRecord {
     schemaVersion: 1;
     recordId: string;
@@ -18,23 +20,6 @@ export interface SessionExecutionState {
     todo: TodoSnapshot;
     contextRecords: SessionRecord[];
 }
-export type SessionSource = {
-    readonly type: 'user';
-} | {
-    readonly type: 'subagent';
-    readonly parentSessionId: string;
-    readonly rootSessionId: string;
-    readonly parentExecutionId: string;
-    readonly role: 'general-purpose' | 'explore';
-    readonly description: string;
-};
-export interface SessionListInput {
-    readonly limit?: number;
-    readonly cursor?: string;
-    readonly source?: SessionSource['type'];
-    readonly parentSessionId?: string;
-    readonly rootSessionId?: string;
-}
 export interface CompactHistoryMessage {
     role: 'user';
     content: string;
@@ -68,6 +53,7 @@ interface SessionMeta {
     source?: SessionSource;
     nextSequence: number;
     automaticTitlePending?: boolean;
+    storageTransactionId?: string;
     resume?: {
         version: 1;
         compactSequence?: number;
@@ -84,10 +70,12 @@ interface SessionMeta {
         bytes: number;
     }>;
 }
+/** SDK-owned JSONL history with per-HOME in-process sharing and cross-process file locks. */
 export declare class JsonlSessionStore {
     #private;
     private constructor();
     static open(home: string): Promise<JsonlSessionStore>;
+    /** Append the durable creation record before making this Session visible in the index. */
     createSession(input: {
         title?: string;
         workspace: string;
@@ -96,13 +84,13 @@ export declare class JsonlSessionStore {
     sessionDirectory(sessionId: string): string;
     readContextualWorldState(sessionId: string): Promise<unknown | undefined>;
     writeContextualWorldState(sessionId: string, state: unknown): Promise<void>;
+    /** Mark each image pending before publication; turn.user or lease recovery resolves ownership. */
     persistInputImages(sessionId: string, images: readonly SessionInputImage[]): Promise<SessionInputImageMetadata[]>;
     readInputImages(sessionId: string, value: unknown): Promise<RestoredSessionInputImage[]>;
     readInputImage(sessionId: string, input: {
         readonly sequence: number;
         readonly imageIndex: number;
     }): Promise<SessionInputImageData | undefined>;
-    removeInputImages(sessionId: string, images: readonly Pick<SessionInputImageMetadata, 'fileName'>[]): Promise<void>;
     forkSession(sourceSessionId: string, input: {
         readonly boundaryTurnId: string | null;
         readonly title: string;
@@ -114,6 +102,7 @@ export declare class JsonlSessionStore {
         lastActivityAt: string;
         source: SessionSource | undefined;
     }>;
+    /** Replace history under a journal; the indexed transaction ID decides the commit side. */
     rollbackSession(sessionId: string, input: {
         readonly boundaryTurnId: string | null;
     }): Promise<{
@@ -128,6 +117,7 @@ export declare class JsonlSessionStore {
         executionId?: string;
         turnId?: string;
     }): Promise<void>;
+    /** Reset history with the same recovery journal while preserving the Session identity. */
     clearSession(sessionId: string): Promise<{
         id: string;
         title: string;
@@ -155,6 +145,7 @@ export declare class JsonlSessionStore {
     readExecutionState(sessionId: string): Promise<SessionExecutionState>;
     readContext(sessionId: string): Promise<SessionRecord[]>;
     contextGcProjectionHash(sessionId: string, boundarySequence: number): Promise<string>;
+    /** Recheck a planned GC checkpoint against authoritative records before appending it. */
     commitContextGc(sessionId: string, draft: ContextGcCheckpointDraft): Promise<SessionRecord>;
     readPage(sessionId: string, input?: {
         limit?: number;
@@ -174,6 +165,7 @@ export declare class JsonlSessionStore {
         executionId?: string;
         turnId?: string;
     }): Promise<SessionRecord>;
+    /** Recover files under the sole writer lock; flush dirty index state before releasing it. */
     acquireSessionLease(sessionId: string): Promise<() => Promise<void>>;
     list(input?: SessionListInput): Promise<{
         nextCursor?: string;
@@ -209,4 +201,3 @@ export declare class JsonlSessionStore {
 }
 export declare function compactSummaryFromCheckpoint(record: SessionRecord | undefined): string | undefined;
 export declare function replacementHistoryFromCheckpoint(record: SessionRecord): CompactHistoryMessage[] | undefined;
-export {};