@myagentroam/node 0.12.1 → 0.12.3

package/dist/hosting/hosted-conversation-node-service.js

@@ -450,7 +450,7 @@ export class HostedConversationNodeService {
     async startMessage(payload, input, steerPrompt) {
         if (this.disablePrepared)
             throw new Error('CONVERSATION_HOSTING_UNAVAILABLE');
-        let conversation = this.options.store.requireConversation(payload.userId, input.conversationId);
+        const conversation = this.options.store.requireConversation(payload.userId, input.conversationId);
         this.assertTemplateContext(payload, conversation);
         if (this.cleanupLocks.has(conversation.id))
             throw new Error('HOSTED_CONVERSATION_STATE_INVALID');

package/dist/marctl/package.json

@@ -1 +1 @@
-{"type":"module","version":"0.12.1"}
+{"type":"module","version":"0.12.3"}

package/dist/marctl/src/direct-transport.mjs

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
-import { DirectFallbackError, DirectUnsafeError, directControlError } from './direct-errors.mjs';
-import { cancelSession, withTimeout, rawToString, isRecord } from './direct-control.mjs';
+import { DirectFallbackError, directControlError } from './direct-errors.mjs';
+import { rawToString, isRecord } from './direct-control.mjs';
 
 export class DirectTerminalTransport extends EventEmitter {
   #channel;

package/dist/marctl/src/direct.mjs

@@ -310,8 +310,8 @@ export async function openDirectTerminal(options) {
       signal
     );
     return transport;
-  } catch (error) {
-    error = preparationError ?? error;
+  } catch (caughtError) {
+    const error = preparationError ?? caughtError;
     transportControlCleanup?.();
     transportControlCleanup = undefined;
     unsafeFallback = transport?.openSent === true;

package/dist/marctl-guidance.js

@@ -28,7 +28,7 @@ export const marctlInstructions = [
     'Prefer agents send <id> --steer -m <text> for timely communication or course correction. --queue is best reserved for deferred input explicitly requested by the user or recipient: it is consumed after current work and earlier queued inputs finish, and with an active Goal it is not consumed until that Goal exits. Acceptance is not a guarantee of immediate processing.',
     'An accepted message normally needs no separate acknowledgment. Requests for receipt-only replies and immediate agents view checks solely to confirm receipt are usually unnecessary.',
     'Send can update a Goal alone with --goal <objective> or --clear-goal; omitted Goal leaves it unchanged. Decide an authorized Agent approval with send <id> --approval <approval-id> --decision approve|reject.',
-    'List accepts only --scope tree|active, optional --query <title-fragment> and --limit <1..100> (default 10). With a current Session it defaults to the containing collaboration tree, including idle Sessions; without one it defaults to active Workspace Sessions (running or sleeping), and explicit tree is rejected. Active Sessions come first, then recent activity descending. Returns currentAgentId (null without a Session), flat sessions with id, parentSessionId, title and status, and truncated; no cursor or pagination. Reuse known IDs directly.',
+    'List accepts only --scope tree|active, optional --query <title-fragment> and --limit <1..100> (default 10). With a current Session it defaults to the containing collaboration tree, including idle Sessions; without one it defaults to active Workspace Sessions (running or sleeping), and explicit tree is rejected. Active Sessions come first, then recent activity descending. Returns scope, currentAgentId (null without a Session), flat sessions with id, parentSessionId, title and status, and truncated; no cursor or pagination. Reuse known IDs directly.',
     'Only direct-child updates are collected automatically. Sending to a non-child never subscribes; an explicit wait observes it only for that call.',
     'Use agents config, rename, prompt and schedule for management. marctl nodes, ssh and scp use authorized Nodes.',
     marctlSafety

package/dist/native-session-history.js

@@ -365,7 +365,7 @@ function deleteTranscriptIndex(key) {
 export async function locateNativeSessionPath(runner, workspacePath, externalSessionId) {
     const wanted = canonical(workspacePath);
     const key = indexKey(runner, wanted, externalSessionId);
-    let path = getTranscriptIndex(key);
+    const path = getTranscriptIndex(key);
     if (path !== undefined)
         return path;
     const candidates = await nativeTranscriptAdapter(runner)?.locateCandidates?.(externalSessionId);

package/dist/runner/codex-runner.js

@@ -394,7 +394,7 @@ export class CodexRunner extends AbstractRunner {
         const threads = [];
         const cursors = new Set();
         let cursor;
-        do {
+        for (;;) {
             const result = await this.client.listThreads({
                 limit: 200,
                 ...(cursor === undefined ? {} : { cursor })
@@ -415,7 +415,7 @@ export class CodexRunner extends AbstractRunner {
                 throw new Error('CODEX_THREAD_LIST_INVALID');
             cursors.add(next);
             cursor = next;
-        } while (true);
+        }
     }
     async discoverSessions(context, workspace) {
         const [threads, nativeSessions] = context.cleanup

package/dist/runner/mar-agent/codex-imagegen-skill.js

@@ -1,36 +1,28 @@
 export function codexImagegenSkill() {
     return `## Working with images
 
-Use codex_image_gen only when the user requests image generation or editing, or explicitly authorizes that work as part of the task. An opportunity to add a visual is not authorization. Loading this skill does not itself generate anything.
+Use codex_image_gen only for image generation or editing the user requests or explicitly authorizes. Loading this skill is not authorization to add visuals.
 
 ### Choose the operation
-- Use AI image generation for requested raster artwork, photographs, textures, or visual variants. Prefer existing editable vector/code-native sources for deterministic changes to those assets; do not replace them with generated bitmaps merely because this tool exists.
-- Distinguish a new composition, an edit target, and a reference for style or subject. Label each supplied image by index and role in the prompt. A reference-guided new composition still needs the reference pixels: pass an image selector rather than silently omitting them.
-- Inspect an unseen local input with view_image when that tool is available. With a TEXT-only model, use the user-supplied reference path and instructions without claiming to have inspected pixels. Prefer referenced_image_paths when all necessary images have valid absolute paths. The Host's file boundaries still apply.
-- Use num_last_images_to_include only when a necessary image has no usable path, and choose the smallest suffix containing all inputs. This is the current Execution's available in-memory images, not a permanent conversation gallery. After a new Execution or Compact, use valid saved paths or ask for missing inputs again.
-- The selectors are mutually exclusive and include at most five images. Omit both only for generation without input images. Do not pretend an unavailable reference was used.
+- Use generated raster artwork for photos, illustrations, textures, and visual variants. Prefer direct source edits for existing SVG, icons, and other code-native assets.
+- Omit both selectors for generation without references. Otherwise use up to five absolute referenced_image_paths, or the smallest num_last_images_to_include containing all needed images, never both. Prefer paths when all inputs have them. Recent images belong to this Execution, not a permanent gallery; after recovery or Compact, use saved paths or ask for missing inputs.
+- Identify each reference's role. Inspect unseen PNG/JPEG/WebP inputs with view_image when available; TEXT-only models must not claim visual inspection. Do not silently omit required references.
 
 ### Shape the prompt
-- Preserve the user's specifics and exact requested text. Organize them into subject, intended use, composition, style, input-image roles, and constraints as useful; a fixed template is not required.
-- For a vague request, supply only details that support its stated goal. Do not invent brands, slogans, additional subjects, or unrelated requirements.
-- For edits, identify the target and state what changes and what must remain unchanged, including identity, layout, text, or other important details. Carry these invariants into follow-up edits.
-- For lettering, quote the literal text and specify placement and typography when relevant. For multiple images, explain which image supplies each element.
-- Ask for a missing decision only if it materially blocks the requested result; do not request a second approval for an already authorized operation.
+- State the subject, composition, style, and essential constraints; preserve exact requested lettering. For edits, specify what changes and what stays unchanged. Add only details that support the user's goal; clarify only when a missing decision blocks the result.
+- Set transparent_background: true for cutouts, background removal, or transparency; preserve existing transparency during edits unless the user asks to change it. Preserve real alpha, not a drawn checkerboard.
+- For a simple looping animation, set gif: {} or specify frame_count (2–16) and frame_duration_ms (20–2000). Defaults are 9 frames and 200 ms. Describe the motion and loop seam; keep subjects and camera stable unless asked otherwise.
+- To edit a GIF, first inspect its frames and use available tools to make a PNG spritesheet with equal-sized cells in a regular grid. Pass that spritesheet through referenced_image_paths and set gif. Do not pass the GIF itself as an edit input; if preparation is unavailable, explain the limitation.
+- For complex animation or more than 16 frames, use suitable available tools or explain the limit rather than stretching this tool's bounds.
 
 ### Generate and check
-- Call codex_image_gen with its actual schema. It produces one PNG per call; use separate calls for separately requested assets. Do not add unsupported parameters for model, dimensions, quality, masks, output format, or destination.
-- In Code Mode, call tools.codex_image_gen. Independent calls can run with Promise.all; await earlier results when later images depend on them.
-- The service configuration controls model and automatic size/quality/background. A prompt can request an aspect ratio or transparency, but these are not guaranteed API settings. Check the actual result before claiming compliance.
-- Generation may take minutes. Await the tool result; do not blindly repeat a timed-out or interrupted request because the upstream operation may already have run. Report failures rather than claiming an artifact exists.
-- A successful result returns the saved path, not inspected pixels. When view_image is available, use it for visual acceptance: subject, exact text, composition, edit invariants, and unwanted elements. Otherwise explicitly state that visual acceptance was not performed. Make targeted corrections only within the requested scope.
-- For transparent deliverables, verify actual transparency rather than treating a drawn checkerboard as alpha. Preserve the alpha channel when copying or processing the result.
+- One PNG or GIF is saved per call. Model, quality, and size remain service-controlled; do not invent API parameters, output paths, SVG support, or fallback tools.
+- In Code Mode, call tools.codex_image_gen. Independent calls may use Promise.all; dependent edits must await their inputs. Generation can take minutes: await the result and do not blindly replay an interrupted or timed-out request. Report failures rather than claiming an artifact exists.
+- Verify the actual format and requested transparency, then check PNG content (subject, lettering, and edit invariants) with view_image when available. For GIFs, check frames, timing, and the loop with available animation-aware tools; a first-frame preview does not verify animation. If inspection is unavailable, say so. Correct only issues within the requested scope.
 
 ### Keep and deliver
-- Treat the tool-returned path as authoritative; do not guess a product HOME or generated-image directory.
-- Keep the managed original. Copy selected assets into the user-requested, Host-permitted destination when needed by the project. Do not leave a project dependency pointing only at private Session storage.
-- Avoid overwriting existing assets unless replacement was requested. For preview-only work the managed file can remain in place.
-- If the user asks to reuse an existing image, inspect or copy it rather than generating a replacement. If it is missing, state that fact; generate again only when authorized.
-- Report the actual final path and any material unmet constraints. Do not dump a long generation prompt unless the user requests it.
+- Trust the returned path and keep the managed original. Copy assets into the authorized project destination when needed; do not leave project dependencies in private Session storage. Do not overwrite existing assets unless replacement was requested.
+- Reuse existing images when requested rather than regenerating them. Report the final path and material unmet constraints, not a long prompt dump.
 
-This Host-provided skill has no bundled command-line fallback, install step, or separate API-key requirement. Do not invent scripts or switch credentials, endpoints, or models. If the tool or a required capability is unavailable, explain the limitation. Workspace instructions can supply additional authorized workflows without changing the tool schema or Host boundaries.`;
+This Host-provided skill has no bundled CLI fallback or separate API-key setup. Do not switch credentials, endpoints, or models. Follow the tool schema and Host file boundaries.`;
 }

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

@@ -174,14 +174,27 @@ export class MarAgentConversationNormalizer {
             const state = this.#tools.get(event.callId);
             if (!state?.active ||
                 state.toolName !== event.toolName ||
-                !agentOperationAction(event.toolName))
+                state.executionId !== event.executionId ||
+                (state.turnId !== undefined && event.turnId !== undefined && state.turnId !== event.turnId))
                 return [];
-            const operation = agentOperationPresentationSchema.safeParse(record(event.data)?.agentOperation);
-            if (!operation.success || operation.data.action !== agentOperationAction(event.toolName))
-                return [];
-            this.#tools.set(event.callId, { ...state, presentationData: event.data });
+            let data;
+            if (event.toolName === 'exec_wait' ||
+                event.toolName === 'code_exec_wait' ||
+                (event.toolName === 'exec' && state.commandOrigin === undefined)) {
+                const source = executionSource(record(event.data)?.executionSource).source;
+                if (!source)
+                    return [];
+                data = { executionSource: source };
+            }
+            else {
+                const operation = agentOperationPresentationSchema.safeParse(record(event.data)?.agentOperation);
+                if (!operation.success || operation.data.action !== agentOperationAction(event.toolName))
+                    return [];
+                data = event.data;
+            }
+            this.#tools.set(event.callId, { ...state, presentationData: data });
             return [
-                genericToolItem(state.itemId, state.toolName, 'IN_PROGRESS', state.input, null, null, false, event.data, state.subagentTitle, state.subagentDetails, undefined, undefined, state.inputTruncated)
+                genericToolItem(state.itemId, state.toolName, 'IN_PROGRESS', state.input, null, null, false, data, state.subagentTitle, state.subagentDetails, undefined, undefined, state.inputTruncated)
             ];
         }
         if (event.type === 'sleep.started') {
@@ -323,6 +336,7 @@ export class MarAgentConversationNormalizer {
                 return [];
             return [
                 genericToolItem(state.itemId, toolName, 'IN_PROGRESS', state.input, snapshot.outputPreview, null, snapshot.truncated, {
+                    ...record(state.presentationData),
                     processId: output.processId,
                     displayOutput: snapshot.displayOutput,
                     outputHeadTruncated: snapshot.displayOutput.stdoutDroppedBytes > 0 ||
@@ -397,7 +411,7 @@ export class MarAgentConversationNormalizer {
         const command = target.commandOrigin === undefined ? undefined : this.#commands.get(target.commandOrigin);
         const item = command
             ? commandItem(command, 'IN_PROGRESS')
-            : genericToolItem(target.itemId, target.toolName, 'IN_PROGRESS', target.input, null, null, false, undefined, undefined, undefined, undefined, undefined, target.inputTruncated);
+            : genericToolItem(target.itemId, target.toolName, 'IN_PROGRESS', target.input, null, null, false, target.presentationData, undefined, undefined, undefined, undefined, target.inputTruncated);
         const blocks = [
             ...(output.stdout ? [{ channel: 'STDOUT', text: output.stdout }] : []),
             ...(output.stderr ? [{ channel: 'STDERR', text: output.stderr }] : [])
@@ -451,6 +465,7 @@ export class MarAgentConversationNormalizer {
         const bounded = publicOutputSnapshot(combined, entries.some((entry) => entry.truncated));
         return [
             genericToolItem(target.itemId, target.toolName, 'IN_PROGRESS', target.input, bounded.text, null, bounded.truncated, {
+                ...record(target.presentationData),
                 outputHeadTruncated: entries.some((entry) => entry.displayOutput.stdoutDroppedBytes > 0 ||
                     entry.displayOutput.stderrDroppedBytes > 0),
                 displayOutput: {
@@ -602,7 +617,7 @@ export class MarAgentConversationNormalizer {
         this.#clearCodeModeOutputSnapshots(sourceCallId);
     }
     #startExecution(executionId) {
-        for (const [callId, state] of this.#tools)
+        for (const state of this.#tools.values())
             if (state.executionId !== executionId) {
                 state.active = false;
             }
@@ -687,7 +702,7 @@ export class MarAgentConversationNormalizer {
         }
         const item = genericToolItem(state?.itemId ?? itemId('tool', event.callId), event.toolName, 'COMPLETED', state?.input, generatedImages.length === 0
             ? event.summary
-            : generatedImages.map((image) => image.name).join(', '), null, event.outputTruncation !== undefined, mergeAgentOperationData(event.toolName, state?.presentationData, event.data), agentId === undefined ? state?.subagentTitle : this.#subagentTitles.get(agentId), details, state?.sleepStartedAt, event.outputTruncation, state?.inputTruncated, event.summaryTruncated === true);
+            : generatedImages.map((image) => image.name).join(', '), null, event.outputTruncation !== undefined, mergeToolPresentationData(event.toolName, state?.presentationData, event.data), agentId === undefined ? state?.subagentTitle : this.#subagentTitles.get(agentId), details, state?.sleepStartedAt, event.outputTruncation, state?.inputTruncated, event.summaryTruncated === true);
         return [
             {
                 ...item,
@@ -718,11 +733,7 @@ export class MarAgentConversationNormalizer {
         return [
             genericToolItem(state?.itemId ?? itemId('tool', event.callId), event.toolName, event.code === 'MAR_AGENT_CANCELLED' || event.code === 'MAR_AGENT_EXECUTION_CANCELLED'
                 ? 'CANCELLED'
-                : 'FAILED', state?.input, event.message ?? event.code, event.code, event.truncated === true, agentOperationAction(event.toolName)
-                ? mergeAgentOperationData(event.toolName, state?.presentationData, event.data)
-                : event.data === undefined
-                    ? state?.presentationData
-                    : event.data, state?.subagentTitle, state?.subagentDetails, state?.sleepStartedAt, event.outputTruncation, state?.inputTruncated)
+                : 'FAILED', state?.input, event.message ?? event.code, event.code, event.truncated === true, mergeToolPresentationData(event.toolName, state?.presentationData, event.data === undefined ? state?.presentationData : event.data), state?.subagentTitle, state?.subagentDetails, state?.sleepStartedAt, event.outputTruncation, state?.inputTruncated)
         ];
     }
     #codeModeToolResults(event) {
@@ -1045,7 +1056,12 @@ function codeExecutionError(data) {
         message: compactRunnerText(error.message, 1000)
     };
 }
-function mergeAgentOperationData(toolName, previous, current) {
+function mergeToolPresentationData(toolName, previous, current) {
+    if (toolName === 'exec_wait' || toolName === 'code_exec_wait' || toolName === 'exec') {
+        const source = executionSource(record(current)?.executionSource).source ??
+            executionSource(record(previous)?.executionSource).source;
+        return source ? { ...record(current), executionSource: source } : current;
+    }
     if (!agentOperationAction(toolName))
         return current;
     const before = agentOperationPresentationSchema.safeParse(record(previous)?.agentOperation);
@@ -1734,20 +1750,6 @@ function truncateCharacters(value, maximumCharacters) {
         ? value
         : characters.slice(0, maximumCharacters).join('');
 }
-function boundedToolSummary(value) {
-    const maximumCodeUnits = 10_000;
-    if (value.length <= maximumCodeUnits)
-        return value;
-    let end = maximumCodeUnits - 1;
-    const lastIncluded = value.charCodeAt(end - 1);
-    const firstExcluded = value.charCodeAt(end);
-    if (lastIncluded >= 0xd800 &&
-        lastIncluded <= 0xdbff &&
-        firstExcluded >= 0xdc00 &&
-        firstExcluded <= 0xdfff)
-        end--;
-    return `${value.slice(0, end)}…`;
-}
 function marAgentAgentId(value) {
     const data = structuredRecord(value);
     if (data === undefined)
@@ -1798,7 +1800,7 @@ function imageArtifacts(event) {
         const name = typeof artifact?.name === 'string' ? compactRunnerText(artifact.name, 255) : '';
         const byteSize = nonnegativeInteger(artifact?.byteSize);
         if (artifact?.kind !== 'image' ||
-            artifact.mimeType !== 'image/png' ||
+            (artifact.mimeType !== 'image/png' && artifact.mimeType !== 'image/gif') ||
             typeof artifact.sha256 !== 'string' ||
             !/^[a-f0-9]{64}$/iu.test(artifact.sha256) ||
             name.length === 0 ||
@@ -1810,8 +1812,8 @@ function imageArtifacts(event) {
             fileName === '..' ||
             fileName.includes('/') ||
             fileName.includes('\\') ||
-            !fileName.toLocaleLowerCase().endsWith('.png'))
+            !fileName.endsWith(artifact.mimeType === 'image/gif' ? '.gif' : '.png'))
             return [];
-        return [{ name, mime: 'image/png', byteSize, fileName }];
+        return [{ name, mime: artifact.mimeType, byteSize, fileName }];
     });
 }

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

@@ -19,7 +19,7 @@ export function createImageGenerationExtensions(input) {
             {
                 name: codex ? 'codex-imagegen' : 'byted_ark-imagegen',
                 description: codex
-                    ? 'Generate or edit raster images with codex_image_gen only when explicitly requested. Load before calling the image tool.'
+                    ? 'Generate or edit PNG images and looping GIFs with codex_image_gen only when explicitly requested. Load before calling the image tool.'
                     : 'Generate or edit one image with byted_ark_image_gen only when explicitly requested. Load before calling the image tool.',
                 requiredTools: [tool.name],
                 load: async () => codex

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

@@ -26,7 +26,7 @@ export const codexImageGenToolDefinition = {
     agentScope: 'ROOT_ONLY',
     allowedCallers: ['direct', 'programmatic'],
     parallelSafety: 'safe',
-    description: 'Only when the user requests or explicitly authorizes image generation or editing, use the configured Codex Images API. First load and follow skill({name:"codex-imagegen"}); reload if its guidance is no longer in context. Do not generate unsolicited visuals. Omit both selectors for a new image without references. For image inputs, inspect unseen local images with view_image when available; TEXT-only models must not claim visual inspection. Use referenced_image_paths when every image has an absolute path; otherwise use num_last_images_to_include for the smallest sufficient number of currently available conversation images. Never provide both selectors. Include at most five images; if required inputs are missing, ask for them rather than silently omitting them. Recent images are in-memory in the current Execution, not a permanent history library. One PNG is saved in the current Session and its path is returned, not inspected pixels. Use view_image when available to check the result; otherwise report that visual acceptance was not performed. Full workflow guidance is in the codex-imagegen skill.',
+    description: 'Generate or edit one PNG or simple looping GIF with the configured Codex Images API, only when requested or explicitly authorized. First load skill({name:"codex-imagegen"}); reuse it while in context. Omit selectors only for generation without references; otherwise use up to five absolute referenced_image_paths OR the smallest sufficient num_last_images_to_include from this Execution. Set transparent_background for transparency and gif for 2–16 animation frames. Returns a managed file path, not inspected pixels.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -44,6 +44,19 @@ export const codexImageGenToolDefinition = {
                 minimum: 1,
                 maximum: MAX_EDIT_IMAGES,
                 description: 'Number of most recent in-memory conversation images to edit.'
+            },
+            transparent_background: {
+                type: 'boolean',
+                description: 'Request a transparent background; defaults to false.'
+            },
+            gif: {
+                type: 'object',
+                description: 'Request a simple looping GIF. Use {} for 9 frames at 200 ms per frame.',
+                properties: {
+                    frame_count: { type: 'integer', minimum: 2, maximum: 16 },
+                    frame_duration_ms: { type: 'integer', minimum: 20, maximum: 2000 }
+                },
+                additionalProperties: false
             }
         },
         required: ['prompt'],
@@ -53,6 +66,10 @@ export const codexImageGenToolDefinition = {
 export const bytedArkImageGenToolDefinition = {
     ...codexImageGenToolDefinition,
     name: 'byted_ark_image_gen',
+    inputSchema: {
+        ...codexImageGenToolDefinition.inputSchema,
+        properties: Object.fromEntries(Object.entries(codexImageGenToolDefinition.inputSchema.properties ?? {}).filter(([key]) => key !== 'transparent_background' && key !== 'gif'))
+    },
     description: 'Generate or edit one PNG using the configured Ark Images API, only when explicitly requested. First load skill({name:"byted_ark-imagegen"}). Omit both selectors for text-to-image; use absolute referenced_image_paths or num_last_images_to_include for image-to-image, never both. Up to five references, exactly one output; no group generation. Returns a managed image path, not inspected pixels.'
 };
 export async function executeCodexImageGen(arguments_, input) {
@@ -60,11 +77,11 @@ export async function executeCodexImageGen(arguments_, input) {
     const capability = input.configuration.imageGeneration;
     if (capability === undefined || capability.credentialProvider === undefined)
         throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Image generation requires an independent credential provider.');
-    const request = parseInput(arguments_);
-    const images = await selectedEditImages(request, input);
     const ark = capability.provider === 'BYTED_ARK';
     if (!ark && capability.provider !== 'CODEX')
         throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Unsupported image provider.');
+    const request = parseInput(arguments_, ark);
+    const images = await selectedEditImages(request, input);
     const endpoint = images.length === 0 ? capability.generateEndpoint : capability.editEndpoint;
     const body = JSON.stringify(ark
         ? {
@@ -93,11 +110,11 @@ export async function executeCodexImageGen(arguments_, input) {
                     }))
                 }),
             prompt: request.prompt,
-            background: 'auto',
+            background: request.transparentBackground ? 'transparent' : 'opaque',
             model: capability.imageModelId,
-            n: 1,
             quality: 'auto',
-            size: 'auto'
+            size: 'auto',
+            ...(request.gif === undefined ? {} : { output_format: 'gif', ...request.gif })
         });
     const turnId = randomUUID();
     let reason = 'REQUEST';
@@ -136,8 +153,10 @@ export async function executeCodexImageGen(arguments_, input) {
         if (!response.ok)
             throw imageGenerationResponseError(response.status, payload);
         const encoded = imageBase64(payload);
-        const data = decodePng(encoded);
-        const fileName = generatedFileName(input.callId);
+        const { data, format } = decodeImage(encoded);
+        if (ark && format !== 'png')
+            throw new AgentError('MAR_AGENT_IMAGE_GENERATION_RESPONSE_INVALID', 'Ark image response must be a PNG.');
+        const fileName = generatedFileName(input.callId, format);
         const directory = join(input.sessionDirectory, 'generated_images');
         const path = join(directory, fileName);
         const displayPath = input.displayDirectory === undefined ? path : posix.join(input.displayDirectory, fileName);
@@ -160,7 +179,7 @@ export async function executeCodexImageGen(arguments_, input) {
                 {
                     kind: 'image',
                     name: fileName,
-                    mimeType: 'image/png',
+                    mimeType: format === 'gif' ? 'image/gif' : 'image/png',
                     byteSize: data.byteLength,
                     sha256,
                     fileName
@@ -170,16 +189,21 @@ export async function executeCodexImageGen(arguments_, input) {
     }
     throw new AgentError('MAR_AGENT_IMAGE_GENERATION_FAILED', 'Image generation failed.');
 }
-function parseInput(value) {
+function parseInput(value, ark) {
     if (value === null || typeof value !== 'object' || Array.isArray(value))
         return invalidInput();
     const input = value;
     const referencedImagePaths = input.referenced_image_paths === null ? undefined : input.referenced_image_paths;
     const numLastImagesToInclude = input.num_last_images_to_include === null ? undefined : input.num_last_images_to_include;
-    if (Object.keys(input).some((key) => key !== 'prompt' && key !== 'referenced_image_paths' && key !== 'num_last_images_to_include') ||
+    const transparentBackground = input.transparent_background ?? false;
+    if (Object.keys(input).some((key) => key !== 'prompt' &&
+        key !== 'referenced_image_paths' &&
+        key !== 'num_last_images_to_include' &&
+        (ark || (key !== 'gif' && key !== 'transparent_background'))) ||
         typeof input.prompt !== 'string' ||
         input.prompt.trim().length === 0 ||
         input.prompt.length > 32_768 ||
+        typeof transparentBackground !== 'boolean' ||
         (referencedImagePaths !== undefined &&
             (!Array.isArray(referencedImagePaths) ||
                 referencedImagePaths.length > MAX_EDIT_IMAGES ||
@@ -194,12 +218,32 @@ function parseInput(value) {
         return invalidInput();
     return {
         prompt: input.prompt,
+        transparentBackground,
+        ...(input.gif === undefined || input.gif === null ? {} : { gif: parseGif(input.gif) }),
         ...(paths?.length ? { referencedImagePaths: [...paths] } : {}),
         ...(numLastImagesToInclude === undefined
             ? {}
             : { numLastImagesToInclude: numLastImagesToInclude })
     };
 }
+function parseGif(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return invalidInput();
+    const options = value;
+    if (Object.keys(options).some((key) => key !== 'frame_count' && key !== 'frame_duration_ms'))
+        return invalidInput();
+    const count = options.frame_count ?? undefined;
+    const duration = options.frame_duration_ms ?? undefined;
+    if ((count !== undefined &&
+        (!Number.isInteger(count) || count < 2 || count > 16)) ||
+        (duration !== undefined &&
+            (!Number.isInteger(duration) || duration < 20 || duration > 2000)))
+        return invalidInput();
+    return {
+        ...(count === undefined ? {} : { frame_count: count }),
+        ...(duration === undefined ? {} : { frame_duration_ms: duration })
+    };
+}
 async function selectedEditImages(request, input) {
     if (request.referencedImagePaths !== undefined) {
         const images = [];
@@ -310,31 +354,36 @@ function imageBase64(value) {
         throw new AgentError('MAR_AGENT_IMAGE_GENERATION_RESPONSE_INVALID', 'Image response is invalid.');
     return first;
 }
-function decodePng(encoded) {
+function decodeImage(encoded) {
     if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/u.test(encoded))
         throw new AgentError('MAR_AGENT_IMAGE_GENERATION_RESPONSE_INVALID', 'Image response is invalid.');
     const data = Buffer.from(encoded, 'base64');
+    const signature = data.subarray(0, 6);
+    const format = signature.equals(Buffer.from('GIF87a')) || signature.equals(Buffer.from('GIF89a'))
+        ? 'gif'
+        : 'png';
     if (data.byteLength === 0 ||
         data.byteLength > IMAGE_MAX_BYTES ||
         data.toString('base64') !== encoded ||
-        !data.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE))
-        throw new AgentError('MAR_AGENT_IMAGE_GENERATION_RESPONSE_INVALID', 'Image response is not a supported PNG.');
-    return data;
+        (format === 'png' && !data.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)))
+        throw new AgentError('MAR_AGENT_IMAGE_GENERATION_RESPONSE_INVALID', 'Image response is not a supported PNG or GIF.');
+    return { data, format };
 }
-function generatedFileName(callId) {
+function generatedFileName(callId, format) {
     const normalized = callId
         .normalize('NFKC')
         .replace(/[^a-zA-Z0-9._-]+/gu, '_')
         .replace(/^[_\-.]+|[_\-.]+$/gu, '')
         .slice(0, 96);
     const stem = normalized.length > 0 ? normalized : createHash('sha256').update(callId).digest('hex');
-    const fileName = `${stem.startsWith('image_') ? stem : `image_${stem}`}.png`;
+    const fileName = `${stem.startsWith('image_') ? stem : `image_${stem}`}.${format}`;
     return basename(fileName);
 }
 function imageGenerationResponseError(status, value) {
-    const error = value !== null && typeof value === 'object' && !Array.isArray(value)
-        ? value.error
+    const payload = value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
         : undefined;
+    const error = payload?.error;
     const record = error !== null && typeof error === 'object' && !Array.isArray(error)
         ? error
         : undefined;
@@ -343,7 +392,11 @@ function imageGenerationResponseError(status, value) {
     const code = /^[a-zA-Z0-9._-]{1,80}$/u.test(rawCode)
         ? rawCode
         : 'MAR_AGENT_IMAGE_GENERATION_FAILED';
-    const rawMessage = typeof record?.message === 'string' ? record.message.trim() : '';
+    const rawMessage = typeof record?.message === 'string'
+        ? record.message.trim()
+        : typeof payload?.detail === 'string'
+            ? payload.detail.trim()
+            : '';
     const message = rawMessage.length > 0 &&
         rawMessage.length <= 1_000 &&
         !/\b(?:authorization|bearer|api[_ -]?key|access[_ -]?token|refresh[_ -]?token|password|secret|proxy-authorization|chatgpt-account-id)\b|socks5:\/\//iu.test(rawMessage)

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

@@ -78,11 +78,13 @@ export class MarAgentSessionRuntimeRegistry {
                         this.#assertUsable(entry, lifetime);
                     }
                     const request = nativeId === undefined ? input : { ...input, externalSessionId: nativeId };
-                    let created;
-                    created = await createSessionRuntime(request, nativeId ?? input.sessionId, fingerprint, configuration, this.resources, () => created !== undefined && entry.runtime === created && entry.release === undefined
+                    const created = {};
+                    created.runtime = await createSessionRuntime(request, nativeId ?? input.sessionId, fingerprint, configuration, this.resources, () => created.runtime !== undefined &&
+                        entry.runtime === created.runtime &&
+                        entry.release === undefined
                         ? entry.current?.runId
                         : undefined);
-                    uncommitted = created;
+                    uncommitted = created.runtime;
                     this.#addAlias(entry, uncommitted.session.id);
                     nodeLog('runner.mar-agent.runtime.created', {
                         runtimeId: uncommitted.runtimeId,

package/dist/workspace/workspace-git-exclude-service.js

@@ -65,7 +65,7 @@ async function gitExcludeTarget(workspace, includeParentRepository) {
         .relative(root, await realpath(workspace))
         .split(path.sep)
         .join('/');
-    const escaped = relative.replace(/[\\*?\[\]#! ]/g, '\\$&');
+    const escaped = relative.replace(/[\\*?[\]#! ]/g, '\\$&');
     return { exclude: await resolveGitExclude(root), prefix: relative === '' ? '/' : `/${escaped}/` };
 }
 async function mutateGitExclude(workspace, mutate, includeParentRepository) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/node",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "description": "MyAgentRoam Node runtime CLI.",
   "license": "Apache-2.0 AND GPL-2.0-or-later",
   "type": "module",
@@ -42,14 +42,14 @@
     "turndown-plugin-gfm": "^1.0.2",
     "ws": "^8.21.3",
     "zod": "4.4.3",
-    "@myagentroam/protocol": "0.12.1",
-    "@myagentroam/agent": "0.12.1"
+    "@myagentroam/agent": "0.12.3",
+    "@myagentroam/protocol": "0.12.3"
   },
   "devDependencies": {
     "@types/turndown": "^5.0.6",
     "@types/ws": "^8.18.1",
     "@myagentroam/code-navigation": "0.11.1",
-    "@myagentroam/marctl": "0.12.1"
+    "@myagentroam/marctl": "0.12.3"
   },
   "exports": {
     "./config": {