@myagentroam/node 0.11.20 → 0.11.22

package/dist/capabilities.js

@@ -14,6 +14,7 @@ const runtimeCredentialCapability = () => ({
     responsesOptionalParameters: true,
     responsesHttpContinuation: true,
     conversationModels: true,
+    resourceInput: true,
     httpVersions: ['1.1', '2']
 });
 const workspaceDirectTransferCapability = () => ({

package/dist/connector.js

@@ -83,6 +83,7 @@ import { SessionCommandService } from './service/session-command-service.js';
 import { SessionPresentationService, sessionGroup } from './service/session-presentation-service.js';
 import { isPlainRecord, isRunnerImageAttachment, parseRunnerImageAttachments } from './util/node-operation-parsers.js';
 import { WebToolService } from './service/web-tool-service.js';
+import { ModelResourcePublicationService } from './service/model-resource-publication-service.js';
 export { nodeConnectEndpoint, validatedCapabilities } from './util/node-operation-parsers.js';
 import { NodeControlChannel } from './service/node-control-channel.js';
 import { NodeControlMessageService } from './service/node-control-message-service.js';
@@ -241,6 +242,7 @@ export class NodeConnector {
     sessionCatalogService;
     sessionCommandService;
     runAttachmentService;
+    modelResourcePublicationService;
     terminalChannel;
     codexClient;
     codexRunController;
@@ -448,6 +450,11 @@ export class NodeConnector {
             capabilities: () => this.capabilities,
             probe: this.conversationHostingProbe,
             runtime: {
+                publishModelResource: (image, context) => this.modelResourcePublicationService.publish({
+                    conversationId: context.conversationId,
+                    sessionId: context.sessionId,
+                    homeDirectory: context.homeDirectory
+                }, image),
                 webSearch: (input, signal) => this.webToolService.webSearch(input, signal),
                 webFetch: (input, signal) => this.webToolService.webFetch(input, signal, false),
                 modelFactory: this.marAgentRuntimeModels,
@@ -502,6 +509,20 @@ export class NodeConnector {
         this.fakeScript = options.fakeScript;
         this.runAttachmentService = new RunAttachmentService((session) => this.runners.require(session.runner).nativeImageRoots(session), (sessionId) => this.runtime.activeSessionRun(sessionId) !== undefined ||
             this.runtime.sessionQueue(sessionId).itemIds.length > 0, () => this.attachmentTemporaryRoot());
+        this.modelResourcePublicationService = new ModelResourcePublicationService({
+            directory: () => resolve(nodeDataDirectory(this.config, this.configPath), 'model-resources'),
+            nodeId: () => this.config?.nodeId,
+            origin: () => {
+                if (!this.config)
+                    return undefined;
+                const url = new URL(this.config.serverUrl);
+                if (url.protocol === 'ws:')
+                    url.protocol = 'http:';
+                if (url.protocol === 'wss:')
+                    url.protocol = 'https:';
+                return url.protocol === 'http:' || url.protocol === 'https:' ? url.origin : undefined;
+            }
+        });
         this.codexClient = new CodexRunner(options.codexClient, options.codexProfileClientFactory, options.codexRunClientFactory);
         this.codexRunController = new CodexManagedRunController(this.codexClient, {
             available: () => this.capabilities.codex.available,
@@ -593,6 +614,16 @@ export class NodeConnector {
             }
         }, {
             modelFactory: this.marAgentRuntimeModels,
+            publishModelResource: (image, context) => {
+                const session = this.runtime.getAgentSession(context.ownerSessionId);
+                if (session === undefined)
+                    throw new Error('RUN_SESSION_NOT_FOUND');
+                return this.modelResourcePublicationService.publish({
+                    workspaceId: session.workspaceId,
+                    sessionId: context.sessionId,
+                    homeDirectory: context.homeDirectory
+                }, image);
+            },
             retainEnvironment: (environment) => this.gitExecution().retain(environment),
             computerUse: this.computerUseProvider
         });
@@ -723,6 +754,7 @@ export class NodeConnector {
             readImage: async (runId, selector) => typeof selector === 'number'
                 ? this.runAttachmentService.read(runId, selector)
                 : this.runAttachmentService.readNative(runId, selector),
+            readModelResource: (input) => this.modelResourcePublicationService.read(input),
             respondUserInput: (runId, requestId, answers) => this.runnerInteractionService.respondUserInput(runId, requestId, answers),
             pauseQueue: (sessionId) => this.workspaceQueueWorkbenchService.pauseSessionQueue(sessionId),
             runInterrupted: (sessionId) => {
@@ -1681,6 +1713,7 @@ export class NodeConnector {
         this.runEventService.clear();
         this.sessionContextService.dispose();
         this.runAttachmentService.dispose();
+        this.modelResourcePublicationService.dispose();
         const marAgentDrain = this.marAgentRunController.dispose();
         const conversationHostingDrain = this.conversationHosting.dispose();
         const uploadDrain = this.workspaceUploadService.shutdown();

package/dist/runner/mar-agent/compact-extensions.js

@@ -70,18 +70,21 @@ export async function generateMarAgentCompact(context, selected, signal) {
     const budget = Math.floor(window * 0.9) - overhead;
     let modelRequests = 0;
     let inputTokensEstimateAfter = overhead;
+    let failure = {};
     const report = async (state, reason, errorCode) => {
         try {
             await context.reportDiagnostic?.({
                 modelId: selected.model.id,
                 providerModelId: selected.model.modelId,
                 reasoningEffort: selected.reasoningEffort,
+                trigger: context.reason,
                 state,
                 inputTokensEstimateBefore: countModelTokens(full) + overhead,
                 inputTokensEstimateAfter,
                 modelRequests,
                 elapsedMs: Math.max(0, Date.now() - startedAt),
                 ...(reason === undefined ? {} : { reason }),
+                ...failure,
                 ...(errorCode === undefined ? {} : { errorCode })
             });
         }
@@ -114,9 +117,20 @@ export async function generateMarAgentCompact(context, selected, signal) {
             outputLimit: Math.min(selected.model.maxOutputTokens, context.summaryTokenBudget),
             onAttemptDiagnostic: async (diagnostic) => {
                 if (diagnostic.state === 'STARTED') {
+                    failure = {};
                     modelRequests++;
                     await report('STARTED');
                 }
+                else if (diagnostic.state === 'FAILED') {
+                    failure = {
+                        ...(diagnostic.errorCode === undefined ? {} : { errorCode: diagnostic.errorCode }),
+                        ...(diagnostic.causeCode === undefined ? {} : { causeCode: diagnostic.causeCode }),
+                        ...(diagnostic.reason === undefined ? {} : { errorReason: diagnostic.reason }),
+                        ...(diagnostic.retryable === undefined ? {} : { retryable: diagnostic.retryable }),
+                        transport: diagnostic.transport
+                    };
+                    await report('FAILED', 'MODEL_FAILED');
+                }
             },
             signal
         });
@@ -127,7 +141,18 @@ export async function generateMarAgentCompact(context, selected, signal) {
     }
     catch (error) {
         signal.throwIfAborted();
-        await report('FAILED', 'MODEL_FAILED', error instanceof MarAgentError ? error.code : 'MAR_AGENT_COMPACT_MODEL_FAILED');
+        if (error instanceof MarAgentError) {
+            const status = error.details?.status;
+            failure = {
+                ...failure,
+                retryable: error.retryable,
+                ...(typeof status === 'number' ? { httpStatus: status } : {}),
+                ...(typeof error.details?.reason === 'string' ? { errorReason: error.details.reason } : {})
+            };
+        }
+        await report('FAILED', 'MODEL_FAILED', error instanceof MarAgentError
+            ? error.code
+            : (failure.errorCode ?? 'MAR_AGENT_COMPACT_MODEL_FAILED'));
         return undefined;
     }
 }

package/dist/runner/mar-agent/hosted-conversation-runtime.js

@@ -17,6 +17,7 @@ export class MarAgentHostedConversationRuntime {
     #createAgent;
     #generateTitle;
     #createHost;
+    #publishModelResource;
     #openCatalog;
     #now;
     #onEvent;
@@ -26,6 +27,7 @@ export class MarAgentHostedConversationRuntime {
     #modelFactory;
     #registerNativeImages;
     constructor(options = {}) {
+        this.#publishModelResource = options.publishModelResource;
         this.#createAgent = options.createAgent ?? createMarAgent;
         this.#generateTitle = options.generateTitle ?? generateSessionTitle;
         this.#createHost = options.createHost ?? ((input) => new LocalAgentHost(input));
@@ -341,6 +343,14 @@ export class MarAgentHostedConversationRuntime {
                 ...(this.#webFetch === undefined ? {} : { webFetch: this.#webFetch })
             }));
             host = this.#createHost({
+                ...(this.#publishModelResource === undefined
+                    ? {}
+                    : {
+                        publishModelResource: (image, context) => this.#publishModelResource(image, {
+                            ...context,
+                            conversationId: input.conversationId
+                        })
+                    }),
                 ...('onModelUsage' in input && input.onModelUsage !== undefined
                     ? { modelUsage: input.onModelUsage }
                     : {}),

package/dist/runner/mar-agent/image-generation-extensions.js

@@ -46,7 +46,7 @@ export function createImageGenerationExtensions(input) {
                         .host()
                         .executeTool({ name: 'view_image', arguments: { path } }, context);
                     const image = output.images?.length === 1 ? output.images[0] : undefined;
-                    if (image === undefined)
+                    if (image === undefined || image.dataBase64 === undefined)
                         throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_INVALID', 'Referenced image result is invalid.');
                     const data = Buffer.from(image.dataBase64, 'base64');
                     if (data.byteLength === 0)

package/dist/runner/mar-agent/managed-run-controller.js

@@ -52,6 +52,7 @@ export class MarAgentManagedRunController {
                 }),
             customTitle: (sessionId) => this.host.customTitle?.(sessionId) ?? undefined,
             modelUsage: (runId, usage) => this.host.emit(runId, 'run.usage', normalizeMarAgentUsage(usage)),
+            publishModelResource: options.publishModelResource,
             question: (runId, request, signal) => this.requestQuestion(runId, request, signal),
             ...(this.host.createApproval && this.host.publishApproval
                 ? {

package/dist/runner/mar-agent/runtime-model-factory.js

@@ -1,4 +1,4 @@
-import { SecretValue } from '@myagentroam/agent';
+import { MarAgentError, SecretValue } from '@myagentroam/agent';
 import { marAgentRuntimeModelConfigurationSchema, resolveMarAgentDefaultReasoningEffort } from '@myagentroam/protocol';
 export function sdkModelConfigurations(models) {
     return models.map(({ imageGeneration: _imageGeneration, ...model }) => model);
@@ -72,6 +72,7 @@ export class MarAgentRuntimeModelFactory {
                         ? { fastMode: true }
                         : {}),
                     hostedWebSearch: configuration.hostedWebSearch,
+                    useResourceUrl: configuration.useResourceUrl,
                     ...(imageGeneration === undefined ? {} : { imageGeneration }),
                     ...(configuration.responsesTransport === undefined
                         ? {}
@@ -94,11 +95,11 @@ export class MarAgentRuntimeModelFactory {
                         apiKey: new SecretValue(credential.value)
                     };
                 if (credential?.type !== 'RUNTIME_TICKET')
-                    throw new Error('MAR_AGENT_RUNTIME_MODEL_CREDENTIAL_INVALID');
+                    throw new MarAgentError('MAR_AGENT_RUNTIME_MODEL_CREDENTIAL_INVALID', 'The runtime model credential is invalid.');
                 if (context.runtimeScopeId === undefined ||
                     context.runtimeScopeId !== credential.ticket.runtimeScopeId ||
                     !credential.ticket.allowedModelIds.includes(configuration.id))
-                    throw new Error('MAR_AGENT_RUNTIME_CREDENTIAL_SCOPE_INVALID');
+                    throw new MarAgentError('MAR_AGENT_RUNTIME_CREDENTIAL_SCOPE_INVALID', 'The runtime credential does not authorize this execution or model.');
                 const provider = runtimeProvider(credential, configuration.id, context, tickets, providers, this.control, this.now);
                 return {
                     ...model,
@@ -140,7 +141,7 @@ function runtimeProvider(credential, consumerId, context, tickets, providers, co
     if (context.runtimeScopeId === undefined ||
         context.runtimeScopeId !== credential.ticket.runtimeScopeId ||
         !credential.ticket.allowedModelIds.includes(consumerId))
-        throw new Error('MAR_AGENT_RUNTIME_CREDENTIAL_SCOPE_INVALID');
+        throw new MarAgentError('MAR_AGENT_RUNTIME_CREDENTIAL_SCOPE_INVALID', 'The runtime credential does not authorize this execution or model.');
     const key = `${credential.credentialId}\0${credential.ticket.runtimeScopeId}\0${credential.ticket.purpose ?? 'MODEL'}`;
     let state = tickets.get(key);
     if (state === undefined) {
@@ -152,7 +153,7 @@ function runtimeProvider(credential, consumerId, context, tickets, providers, co
         tickets.set(key, state);
     }
     else if (!sameRuntimeCredentialTicket(state.ticket, credential.ticket))
-        throw new Error('MAR_AGENT_RUNTIME_CREDENTIAL_SCOPE_INVALID');
+        throw new MarAgentError('MAR_AGENT_RUNTIME_CREDENTIAL_SCOPE_INVALID', 'The runtime credential does not authorize this execution or model.');
     const provider = new ServerRuntimeCredentialProvider(control, state, consumerId, context.runtimeScopeId, context.executionId, now);
     providers.push(provider);
     return provider;
@@ -178,7 +179,7 @@ class ServerRuntimeCredentialProvider {
     }
     async acquire(reason) {
         if (this.#closed || this.state.released)
-            throw new Error('MAR_AGENT_RUNTIME_CREDENTIAL_PROVIDER_CLOSED');
+            throw new MarAgentError('MAR_AGENT_RUNTIME_CREDENTIAL_PROVIDER_CLOSED', 'The runtime credential provider is closed.');
         if (isReusableCredential(this.state.credential, this.now())) {
             if (isWithinRefreshWindow(this.state.ticket.expiresAt, this.now()))
                 this.refreshAutomatically();
@@ -263,9 +264,9 @@ class ServerRuntimeCredentialProvider {
             reason
         }, signal);
         if (this.state.released)
-            throw new Error('MAR_AGENT_RUNTIME_CREDENTIAL_PROVIDER_CLOSED');
+            throw new MarAgentError('MAR_AGENT_RUNTIME_CREDENTIAL_PROVIDER_CLOSED', 'The runtime credential provider is closed.');
         if ('error' in response)
-            throw new Error(response.error.code);
+            throw new MarAgentError(response.error.code, response.error.message);
         this.state.ticket = response.nextTicket;
         const credential = {
             revision: response.credential.revision,
@@ -332,11 +333,11 @@ function clearRefreshTimer(state) {
 }
 function waitForCredential(pending, signal) {
     if (signal.aborted)
-        return Promise.reject(new Error('MAR_AGENT_RUNTIME_CREDENTIAL_PROVIDER_CLOSED'));
+        return Promise.reject(new MarAgentError('MAR_AGENT_RUNTIME_CREDENTIAL_PROVIDER_CLOSED', 'The runtime credential provider is closed.'));
     return new Promise((resolve, reject) => {
         const abort = () => {
             cleanup();
-            reject(new Error('MAR_AGENT_RUNTIME_CREDENTIAL_PROVIDER_CLOSED'));
+            reject(new MarAgentError('MAR_AGENT_RUNTIME_CREDENTIAL_PROVIDER_CLOSED', 'The runtime credential provider is closed.'));
         };
         const cleanup = () => signal.removeEventListener('abort', abort);
         signal.addEventListener('abort', abort, { once: true });

package/dist/runner/mar-agent/session-runtime.js

@@ -30,6 +30,12 @@ export async function createSessionRuntime(input, sessionKey, fingerprint, hostC
         releaseEnvironment = dependencies.retainEnvironment?.(input.secretEnvironment ?? {});
         const mcp = mcpLease.pool;
         const localHost = new LocalAgentHost({
+            publishModelResource: dependencies.publishModelResource === undefined
+                ? undefined
+                : (image, context) => dependencies.publishModelResource(image, {
+                    ...context,
+                    ownerSessionId: input.sessionId
+                }),
             modelUsage: (usage) => {
                 const runId = currentRunId();
                 if (runId !== undefined)

package/dist/runner/mar-agent-runner.js

@@ -1,4 +1,4 @@
-import { marAgentNodeModelSummarySchema, resolveMarAgentDefaultReasoningEffort } from '@myagentroam/protocol';
+import { marAgentNodeModelSummarySchema, parseComposerTags, resolveMarAgentDefaultReasoningEffort, serializeComposerTag } from '@myagentroam/protocol';
 import { nodeLog } from '../operational.js';
 import { runnerErrorProjection } from '../util/runner-error.js';
 import { MarAgentError, openMarAgentSessionCatalog } from '@myagentroam/agent';
@@ -11,6 +11,22 @@ import { captureMarAgentExecutionInput } from './mar-agent/execution-input.js';
 export class MarAgentRunner extends AbstractRunner {
     homeDirectory;
     name = 'mar-agent';
+    prepareMessageInput(input, collaborationMode) {
+        const prepared = super.prepareMessageInput(input, collaborationMode);
+        return parseComposerTags(prepared)
+            .map((part) => {
+            if (part.kind === 'text')
+                return part.text;
+            if (part.kind === 'mar_attachments' &&
+                part.payload.files.some((file) => file.mime.startsWith('image/')))
+                return serializeComposerTag('mar_attachments', {
+                    ...part.payload,
+                    instruction: 'Images are included. Use view_image only to revisit them.'
+                });
+            return part.raw;
+        })
+            .join('');
+    }
     prepareExecutionContext(input) {
         return { runner: this.name, runnerInput: captureMarAgentExecutionInput(input) };
     }

package/dist/service/model-resource-publication-service.js

@@ -0,0 +1,148 @@
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { MarAgentError, openMarAgentSessionCatalog } from '@myagentroam/agent';
+import { modelResourceReadInputSchema } from '@myagentroam/protocol';
+const TTL_MS = 24 * 60 * 60_000;
+/** Only capability metadata lives here. The SDK owns the sole immutable image file. */
+export class ModelResourcePublicationService {
+    options;
+    #pending = new Map();
+    #key;
+    constructor(options) {
+        this.options = options;
+    }
+    async publish(source, resource) {
+        const origin = this.options.origin();
+        const nodeId = this.options.nodeId();
+        if (origin === undefined || nodeId === undefined)
+            return undefined;
+        const id = this.identity(source, resource.resourceId);
+        const current = this.#pending.get(id);
+        if (current !== undefined)
+            return current;
+        const creation = this.create(id, source, resource.resourceId, origin, nodeId);
+        this.#pending.set(id, creation);
+        try {
+            return await creation;
+        }
+        finally {
+            if (this.#pending.get(id) === creation)
+                this.#pending.delete(id);
+        }
+    }
+    async create(id, source, resourceId, origin, nodeId) {
+        const key = await this.signingKey();
+        try {
+            const record = JSON.parse(await readFile(this.path(id), 'utf8'));
+            if (record.version !== 2 || this.identity(record.source, record.resourceId) !== id)
+                throw new Error('MODEL_RESOURCE_INVALID');
+            return { url: record.url, urlExpiresAt: record.expiresAt };
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const expiresAt = this.now() + TTL_MS;
+        const signature = this.signature(key, nodeId, source, resourceId, expiresAt);
+        const scope = 'workspaceId' in source
+            ? `workspaces/${encodeURIComponent(source.workspaceId)}`
+            : `conversations/${encodeURIComponent(source.conversationId)}`;
+        const url = `${origin}/api/nodes/${encodeURIComponent(nodeId)}/${scope}/sessions/${encodeURIComponent(source.sessionId)}/resources/${resourceId}?expiresAt=${expiresAt}&signature=${signature}`;
+        const record = { version: 2, source, resourceId, expiresAt, url };
+        const temporary = join(this.options.directory(), `.${id}.${randomUUID()}.tmp`);
+        try {
+            await writeFile(temporary, JSON.stringify(record), { mode: 0o600, flag: 'wx', flush: true });
+            await rename(temporary, this.path(id));
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+        return { url, urlExpiresAt: expiresAt };
+    }
+    async read(input) {
+        if (!modelResourceReadInputSchema.safeParse(input).success)
+            return undefined;
+        if (input.expiresAt <= this.now())
+            return undefined;
+        const nodeId = this.options.nodeId();
+        if (nodeId === undefined)
+            return undefined;
+        const scope = 'workspaceId' in input
+            ? { workspaceId: input.workspaceId }
+            : { conversationId: input.conversationId };
+        const source = { ...scope, sessionId: input.sessionId };
+        const expected = this.signature(await this.signingKey(), nodeId, source, input.resourceId, input.expiresAt);
+        if (!timingSafeEqual(Buffer.from(expected), Buffer.from(input.signature)))
+            return undefined;
+        let record;
+        try {
+            record = JSON.parse(await readFile(this.path(this.identity(source, input.resourceId)), 'utf8'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+        if (record.version !== 2 ||
+            record.expiresAt !== input.expiresAt ||
+            this.identity(record.source, record.resourceId) !== this.identity(source, input.resourceId))
+            return undefined;
+        const catalog = await openMarAgentSessionCatalog({
+            homeDirectory: record.source.homeDirectory
+        });
+        try {
+            return await catalog.readResource(record.source.sessionId, record.resourceId);
+        }
+        catch (error) {
+            if (error instanceof MarAgentError && error.code === 'MAR_AGENT_SESSION_NOT_FOUND')
+                return undefined;
+            throw error;
+        }
+        finally {
+            await catalog.close();
+        }
+    }
+    dispose() {
+        this.#pending.clear();
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+    path(id) {
+        return join(this.options.directory(), `${id}.json`);
+    }
+    identity(source, resourceId) {
+        return createHash('sha256')
+            .update(JSON.stringify([
+            'workspaceId' in source ? 'workspace' : 'conversation',
+            'workspaceId' in source ? source.workspaceId : source.conversationId,
+            source.sessionId,
+            resourceId
+        ]))
+            .digest('hex');
+    }
+    signature(key, nodeId, source, resourceId, expiresAt) {
+        return createHmac('sha256', key)
+            .update(JSON.stringify([nodeId, this.identity(source, resourceId), expiresAt]))
+            .digest('base64url');
+    }
+    signingKey() {
+        return (this.#key ??= (async () => {
+            const directory = this.options.directory();
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+            const path = join(directory, 'signing-key');
+            try {
+                await writeFile(path, randomBytes(32), { mode: 0o600, flag: 'wx', flush: true });
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+            const key = await readFile(path);
+            if (key.length !== 32)
+                throw new Error('MODEL_RESOURCE_SIGNING_KEY_INVALID');
+            return key;
+        })());
+    }
+}

package/dist/service/run-workbench-service.js

@@ -1,4 +1,4 @@
-import { runImageReadInputSchema } from '@myagentroam/protocol';
+import { modelResourceReadInputSchema, runImageReadInputSchema } from '@myagentroam/protocol';
 import { nodeOperationData } from '../util/node-operation-data.js';
 import { isTerminalRunStatus } from '../util/node-operation-parsers.js';
 import { isPlainRecord } from '../util/node-operation-parsers.js';
@@ -13,6 +13,7 @@ export class RunWorkbenchService {
         return {
             'run.get': (data) => this.get(record(data)),
             'run.image.read': (data) => this.image(record(data)),
+            'model.resource.read': (data) => this.modelResource(record(data)),
             'run.user-input.respond': (data) => this.respond(record(data)),
             'session.interrupt': (data) => this.interruptSession(record(data)),
             'run.cancel': (data) => this.cancelOrInterrupt('run.cancel', record(data)),
@@ -20,6 +21,15 @@ export class RunWorkbenchService {
             'run.approval.decide': (data) => this.decideApproval(record(data))
         };
     }
+    async modelResource(input) {
+        const parsed = modelResourceReadInputSchema.safeParse(nodeOperationData(input));
+        if (!parsed.success)
+            throw new Error('RUN_IMAGE_INVALID');
+        const image = await this.options.readModelResource?.(parsed.data);
+        if (image === undefined)
+            throw new Error('RUN_IMAGE_NOT_FOUND');
+        return { image };
+    }
     get(input) {
         return { run: this.requireRun(input.runId) };
     }

package/dist/service/runtime-credential-control-service.js

@@ -1,3 +1,4 @@
+import { MarAgentError } from '@myagentroam/agent';
 import { createEnvelope, runtimeCredentialResolveRequestSchema, runtimeCredentialResolveResponseSchema } from '@myagentroam/protocol';
 const DEFAULT_TIMEOUT_MS = 15_000;
 /** Correlates the closed runtime-credential exchange on the authenticated control connection. */
@@ -32,7 +33,7 @@ export class RuntimeCredentialControlService {
             return true;
         const parsed = runtimeCredentialResolveResponseSchema.safeParse(envelope.payload);
         if (!parsed.success) {
-            pending.reject(new Error('MAR_AGENT_RUNTIME_CREDENTIAL_RESPONSE_INVALID'));
+            pending.reject(new MarAgentError('MAR_AGENT_RUNTIME_CREDENTIAL_RESPONSE_INVALID', 'The runtime credential response is invalid.'));
             return true;
         }
         pending.resolve(parsed.data);
@@ -40,9 +41,9 @@ export class RuntimeCredentialControlService {
     }
     resolve(request, signal) {
         if (this.#closed)
-            return Promise.reject(new Error('MAR_AGENT_RUNTIME_CREDENTIAL_CONTROL_CLOSED'));
+            return Promise.reject(new MarAgentError('MAR_AGENT_RUNTIME_CREDENTIAL_CONTROL_CLOSED', 'The runtime credential control service is closed.'));
         if (!this.#connected)
-            return Promise.reject(new Error('MAR_AGENT_RUNTIME_CREDENTIAL_CONNECTION_INVALID'));
+            return Promise.reject(new MarAgentError('MAR_AGENT_RUNTIME_CREDENTIAL_CONNECTION_INVALID', 'The runtime credential control connection is unavailable.'));
         const parsed = runtimeCredentialResolveRequestSchema.parse(request);
         const envelope = createEnvelope('credential.resolve', parsed);
         const generation = this.#generation;
@@ -56,8 +57,8 @@ export class RuntimeCredentialControlService {
                 pending.cleanup();
                 action(value);
             };
-            const abort = () => settle((error) => reject(error), new Error('MAR_AGENT_RUNTIME_CREDENTIAL_PROVIDER_CLOSED'));
-            const timer = setTimeout(() => settle((error) => reject(error), new Error('MAR_AGENT_RUNTIME_CREDENTIAL_REQUEST_TIMEOUT')), this.#timeoutMs);
+            const abort = () => settle((error) => reject(error), new MarAgentError('MAR_AGENT_RUNTIME_CREDENTIAL_PROVIDER_CLOSED', 'The runtime credential provider is closed.'));
+            const timer = setTimeout(() => settle((error) => reject(error), new MarAgentError('MAR_AGENT_RUNTIME_CREDENTIAL_REQUEST_TIMEOUT', 'The runtime credential request timed out.')), this.#timeoutMs);
             timer.unref();
             this.#pending.set(envelope.id, {
                 generation,
@@ -74,9 +75,7 @@ export class RuntimeCredentialControlService {
                     this.options.send(envelope);
                 }
                 catch (error) {
-                    settle((cause) => reject(cause), error instanceof Error
-                        ? error
-                        : new Error('MAR_AGENT_RUNTIME_CREDENTIAL_REQUEST_SEND_FAILED'));
+                    settle((cause) => reject(cause), new MarAgentError('MAR_AGENT_RUNTIME_CREDENTIAL_REQUEST_SEND_FAILED', 'The runtime credential request could not be sent.', { cause: error }));
                 }
         });
     }
@@ -90,6 +89,6 @@ export class RuntimeCredentialControlService {
     }
     #rejectPending(code) {
         for (const pending of [...this.#pending.values()])
-            pending.reject(new Error(code));
+            pending.reject(new MarAgentError(code, 'The runtime credential control connection is no longer valid.'));
     }
 }

package/dist/service/session-lifecycle-service.js

@@ -178,7 +178,8 @@ export class SessionLifecycleService {
         });
         if (input.bootstrapOnly === true)
             this.options.identity.markBootstrap(session.id);
-        database.saveRunnerDefaults(configuration);
+        if (input.__marctlOrigin === undefined)
+            database.saveRunnerDefaults(configuration);
         if (input.bootstrapOnly !== true)
             this.options.emitSession(session);
         return { session: this.options.present(session) };

package/dist/service/workspace-watch-controller.js

@@ -22,6 +22,12 @@ export class WorkspaceWatchController {
         }
         const topics = this.options.watch.parseTopics(input);
         const existing = this.options.watch.existing(workspace.id, key);
+        const groupOnly = existing !== undefined &&
+            existing.topics.sessions === topics.sessions &&
+            existing.topics.sessionGroup !== topics.sessionGroup &&
+            existing.topics.changes === topics.changes &&
+            JSON.stringify(existing.topics.files) === JSON.stringify(topics.files) &&
+            (existing.prepareFiles === true) === (input.prepareFiles === true);
         if (existing !== undefined &&
             existing.watchId === input.watchId &&
             JSON.stringify(existing.topics) === JSON.stringify(topics) &&
@@ -30,7 +36,7 @@ export class WorkspaceWatchController {
             return this.accepted(existing);
         }
         const watch = this.options.watch.create(workspace.id, input.watchId, this.options.watch.sessionHash(input), input.workbenchConnectionId, this.options.nodeGeneration(), topics, input.prepareFiles === true);
-        void this.options.snapshots.initial(workspace, watch);
+        void this.options.snapshots.initial(workspace, watch, groupOnly ? existing : undefined);
         if (watch.prepareFiles)
             this.options.snapshots.prewarmFiles(workspace, watch);
         return this.accepted(watch);

package/dist/service/workspace-watch-service.js

@@ -59,8 +59,9 @@ export class WorkspaceWatchService {
     create(workspaceId, watchId, sessionHash, workbenchConnectionId, nodeGeneration, topics, prepareFiles = false) {
         const key = `${sessionHash}:${workbenchConnectionId}`;
         for (const [activeWorkspaceId, watches] of this.state.watches)
-            if (watches.has(key))
+            if (activeWorkspaceId !== workspaceId && watches.has(key))
                 this.remove(activeWorkspaceId, key);
+        const previous = this.state.watches.get(workspaceId)?.get(key);
         const watch = {
             workspaceId,
             watchId,
@@ -76,6 +77,12 @@ export class WorkspaceWatchService {
         const watches = this.state.watches.get(workspaceId) ?? new Map();
         watches.set(key, watch);
         this.state.watches.set(workspaceId, watches);
+        if (previous !== undefined) {
+            clearTimeout(previous.timer);
+            this.onWatchRemoved(previous);
+            if (previous.topics.sessions && !this.topicActive(workspaceId, 'sessions'))
+                this.onSessionWatchUnused(workspaceId);
+        }
         if (topics.sessions)
             this.onSessionWatchRequired(workspaceId);
         return watch;

package/dist/service/workspace-watch-snapshot-service.js

@@ -7,17 +7,28 @@ export class WorkspaceWatchSnapshotService {
     dirty = new Set();
     reads = new Map();
     signatures = new Map();
+    // Handoff only between consecutive group selections on the same page/Workspace.
+    // Weak keys release the two resource payloads with their lease, not a second TTL cache.
+    resourceSnapshots = new WeakMap();
     filesRefreshTimer;
     constructor(options) {
         this.options = options;
     }
-    async initial(workspace, watch) {
+    async initial(workspace, watch, previous) {
         if (watch.topics.files !== undefined)
             this.ensureFilesRefreshTimer();
         await Promise.all(this.subscribedTopics(watch).map(async (topic) => {
             const revision = this.readRevision(workspace.id, topic);
             try {
-                const payload = await this.read(workspace, topic, watch);
+                const retained = topic === 'sessions' || previous === undefined
+                    ? undefined
+                    : this.resourceSnapshots.get(previous)?.[topic];
+                const payload = retained !== undefined &&
+                    retained.revision === revision &&
+                    !this.readActive(workspace.id, topic, watch) &&
+                    !this.refreshes.has(`${workspace.id}:${topic}`)
+                    ? retained.payload
+                    : await this.read(workspace, topic, watch);
                 if (!this.matches(workspace.id, watch))
                     return;
                 if (revision !== this.readRevision(workspace.id, topic)) {
@@ -218,7 +229,9 @@ export class WorkspaceWatchSnapshotService {
             ? `${workspaceId}:files:${JSON.stringify(watch.topics.files)}`
             : `${workspaceId}:${topic}:${watch.topics.sessionGroup ?? 'ALL'}`;
     }
-    readActive(workspaceId, topic) {
+    readActive(workspaceId, topic, watch) {
+        if (topic === 'files' && watch !== undefined)
+            return this.reads.has(this.viewKey(workspaceId, topic, watch));
         const prefix = `${workspaceId}:${topic}`;
         return [...this.reads.keys()].some((key) => key === prefix || key.startsWith(`${prefix}:`));
     }
@@ -237,6 +250,11 @@ export class WorkspaceWatchSnapshotService {
     deliver(workspace, watch, topic, payload) {
         if (!this.matches(workspace.id, watch))
             return;
+        if (topic !== 'sessions') {
+            const snapshots = this.resourceSnapshots.get(watch) ?? {};
+            snapshots[topic] = { payload, revision: this.readRevision(workspace.id, topic) };
+            this.resourceSnapshots.set(watch, snapshots);
+        }
         this.options.emitWatchEvent({
             type: 'watch.workspace.snapshot',
             workbenchConnectionId: watch.workbenchConnectionId,
@@ -254,6 +272,11 @@ export class WorkspaceWatchSnapshotService {
     fail(workspaceId, watch, topic) {
         if (!this.matches(workspaceId, watch))
             return;
+        if (topic !== 'sessions') {
+            const snapshots = this.resourceSnapshots.get(watch);
+            if (snapshots !== undefined)
+                delete snapshots[topic];
+        }
         this.options.emitWatchEvent({
             type: 'watch.failed',
             workbenchConnectionId: watch.workbenchConnectionId,

package/dist/util/node-operation-parsers.js

@@ -131,11 +131,15 @@ export function validUserAuthorization(value, envelope, operation, nodeId, now =
     if (typeof value !== 'object' || value === null || nodeId === undefined)
         return false;
     const authorization = value;
-    return (typeof authorization.userId === 'number' &&
-        Number.isSafeInteger(authorization.userId) &&
-        authorization.userId > 0 &&
-        typeof authorization.sessionHash === 'string' &&
-        /^[A-Za-z0-9_-]{43}$/.test(authorization.sessionHash) &&
+    const modelResourceCapability = operation === 'model.resource.read' &&
+        authorization.userId === 0 &&
+        authorization.sessionHash === 'model-resource';
+    return ((modelResourceCapability ||
+        (typeof authorization.userId === 'number' &&
+            Number.isSafeInteger(authorization.userId) &&
+            authorization.userId > 0 &&
+            typeof authorization.sessionHash === 'string' &&
+            /^[A-Za-z0-9_-]{43}$/.test(authorization.sessionHash))) &&
         authorization.nodeId === nodeId &&
         authorization.operation === operation &&
         authorization.requestId === envelope.id &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/node",
-  "version": "0.11.20",
+  "version": "0.11.22",
   "description": "MyAgentRoam Node runtime CLI.",
   "license": "Apache-2.0 AND GPL-2.0-or-later",
   "type": "module",
@@ -37,10 +37,10 @@
     "playwright": "1.62.1",
     "ws": "^8.21.3",
     "zod": "4.4.3",
-    "@myagentroam/agent": "0.11.20",
-    "@myagentroam/protocol": "0.11.20",
-    "@myagentroam/code-navigation": "0.11.0",
-    "@myagentroam/marctl": "0.11.0"
+    "@myagentroam/agent": "0.11.22",
+    "@myagentroam/marctl": "0.11.0",
+    "@myagentroam/protocol": "0.11.22",
+    "@myagentroam/code-navigation": "0.11.0"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"