@myagentroam/node 0.12.0 → 0.12.2

package/dist/marctl/src/terminal-relay.mjs

@@ -0,0 +1,305 @@
+import { EventEmitter } from 'node:events';
+import { MarctlError } from './errors.mjs';
+import { TerminalRelaySender } from './terminal-relay-sender.mjs';
+import { parseFrame } from './terminal-frame.mjs';
+import { DirectFallbackError } from './direct-errors.mjs';
+
+export async function openRelayTransport({
+  client,
+  WebSocketClass,
+  nodeId,
+  terminalId,
+  translate,
+  connectionTimeoutMs,
+  signal
+}) {
+  const ticket = await client.createAttachTicket({ nodeId, terminalId });
+  if (signal?.aborted) throw new DirectFallbackError('DIRECT_RACE_CANCELLED');
+  const socket = client.openTerminalWebSocket(WebSocketClass, { terminalId, ticket });
+  const transport = new BufferedRelayTransport({
+    socket,
+    terminalId,
+    translate,
+    connectionTimeoutMs
+  });
+  try {
+    await waitForAttachment(transport, signal);
+    return transport;
+  } catch (error) {
+    transport.close();
+    throw error;
+  }
+}
+
+export async function prepareRelayTransport({
+  client,
+  WebSocketClass,
+  nodeId,
+  terminalId,
+  translate,
+  connectionTimeoutMs,
+  signal,
+  onPrepared
+}) {
+  const ticket = await client.createAttachTicket({ nodeId, terminalId });
+  if (onPrepared) await onPrepared();
+  if (signal?.aborted) throw new MarctlError(translate('errors.terminalAttachConnection'));
+  const socket = client.openTerminalWebSocket(WebSocketClass, {
+    terminalId,
+    ticket,
+    deferred: true
+  });
+  // Keep an error listener after readiness until the socket is discarded.
+  socket.on('error', () => {});
+  let activated = false;
+  const ready = new Promise((resolve, reject) => {
+    const timer = setTimeout(() => fail(), connectionTimeoutMs);
+    const cleanup = () => {
+      clearTimeout(timer);
+      socket.removeListener?.('message', onMessage);
+      socket.removeListener?.('error', fail);
+      socket.removeListener?.('close', fail);
+      signal?.removeEventListener('abort', fail);
+    };
+    const fail = () => {
+      cleanup();
+      try {
+        socket.close();
+      } catch {
+        /* Connection not yet established. */
+      }
+      reject(new MarctlError(translate('errors.terminalAttachConnection')));
+    };
+    const onMessage = (raw) => {
+      let frame;
+      try {
+        frame = JSON.parse(String(raw));
+      } catch {
+        return fail();
+      }
+      if (frame?.type !== 'ready' || frame.terminalId !== terminalId) return fail();
+      cleanup();
+      resolve();
+    };
+    socket.on('message', onMessage);
+    socket.on('error', fail);
+    socket.on('close', fail);
+    signal?.addEventListener('abort', fail, { once: true });
+    if (signal?.aborted) fail();
+  });
+  await ready;
+  return {
+    async activate(signal) {
+      if (signal?.aborted) {
+        socket.close();
+        throw new DirectFallbackError('DIRECT_RACE_CANCELLED');
+      }
+      if (activated || socket.readyState !== 1)
+        throw new MarctlError(translate('errors.terminalAttachConnection'));
+      activated = true;
+      const transport = new BufferedRelayTransport({
+        socket,
+        terminalId,
+        translate,
+        connectionTimeoutMs
+      });
+      try {
+        socket.send(JSON.stringify({ type: 'activate', terminalId }));
+        await waitForAttachment(transport, signal);
+        return transport;
+      } catch (error) {
+        transport.close();
+        throw error;
+      }
+    },
+    close() {
+      socket.close();
+    }
+  };
+}
+
+async function waitForAttachment(transport, signal) {
+  if (!signal) return transport.waitForAttachment();
+  if (signal.aborted) throw new DirectFallbackError('DIRECT_RACE_CANCELLED');
+  let cancel;
+  const cancelled = new Promise((_, reject) => {
+    cancel = () => {
+      transport.close();
+      reject(new DirectFallbackError('DIRECT_RACE_CANCELLED'));
+    };
+    signal.addEventListener('abort', cancel, { once: true });
+  });
+  try {
+    return await Promise.race([transport.waitForAttachment(), cancelled]);
+  } finally {
+    signal.removeEventListener('abort', cancel);
+  }
+}
+
+class BufferedRelayTransport extends EventEmitter {
+  #socket;
+  #sender;
+  #terminalId;
+  #translate;
+  #attached = false;
+  #active = false;
+  #pendingEvents = [];
+  #attachmentResolve;
+  #attachmentReject;
+  #openTimer;
+  #attachTimer;
+  #closed = false;
+  #onOpen;
+  #onMessage;
+  #onError;
+  #onClose;
+
+  constructor({ socket, terminalId, translate, connectionTimeoutMs }) {
+    super();
+    this.#socket = socket;
+    this.#sender = new TerminalRelaySender(socket);
+    this.#terminalId = terminalId;
+    this.#translate = translate;
+    this.#onOpen = () => {
+      clearTimeout(this.#openTimer);
+      this.#armAttachTimer(connectionTimeoutMs);
+    };
+    this.#onMessage = (raw, isBinary) => {
+      try {
+        const frame = parseFrame(raw, isBinary, this.#terminalId, this.#translate);
+        if (!this.#attached) {
+          if (frame.type === 'attach') {
+            this.#attached = true;
+            clearTimeout(this.#attachTimer);
+            this.#attachmentResolve?.();
+            this.#attachmentResolve = undefined;
+            this.#attachmentReject = undefined;
+            return;
+          }
+          if (frame.type === 'error')
+            throw new MarctlError(this.#translate('errors.terminalRemoteError'));
+          this.#queueOrEmit('message', raw, isBinary);
+          return;
+        }
+        this.#queueOrEmit('message', raw, isBinary);
+      } catch (error) {
+        this.#fail(
+          error instanceof MarctlError
+            ? error
+            : new MarctlError(this.#translate('errors.terminalFrameInvalid'))
+        );
+      }
+    };
+    this.#onError = () => {
+      const error = new MarctlError(
+        this.#translate(
+          this.#attached ? 'errors.terminalConnectionFailed' : 'errors.terminalAttachConnection'
+        )
+      );
+      if (this.#attached) this.#queueOrEmit('error', error);
+      else this.#fail(error);
+    };
+    this.#onClose = () => {
+      this.#sender.close();
+      const error = new MarctlError(
+        this.#translate(
+          this.#attached ? 'errors.terminalConnectionLost' : 'errors.terminalAttachLost'
+        )
+      );
+      if (this.#attached) this.#queueOrEmit('close');
+      else this.#fail(error);
+    };
+
+    socket.on?.('open', this.#onOpen);
+    socket.on?.('message', this.#onMessage);
+    socket.on?.('error', this.#onError);
+    socket.on?.('close', this.#onClose);
+    if (socket.readyState === 1) this.#onOpen();
+    else
+      this.#openTimer = setTimeout(
+        () => this.#fail(new MarctlError(this.#translate('errors.terminalConnectionOpen'))),
+        connectionTimeoutMs
+      );
+  }
+
+  waitForAttachment() {
+    return new Promise((resolve, reject) => {
+      if (this.#closed) {
+        reject(new MarctlError(this.#translate('errors.terminalAttachLost')));
+        return;
+      }
+      this.#attachmentResolve = resolve;
+      this.#attachmentReject = reject;
+      if (this.#attached) {
+        this.#attachmentResolve = undefined;
+        this.#attachmentReject = undefined;
+        resolve();
+      }
+    });
+  }
+
+  activate() {
+    if (this.#active) return;
+    this.#active = true;
+    const pendingEvents = this.#pendingEvents;
+    this.#pendingEvents = [];
+    for (const { type, args } of pendingEvents) this.emit(type, ...args);
+  }
+
+  get readyState() {
+    return this.#socket.readyState;
+  }
+
+  send(value) {
+    if (this.#closed) throw new Error('TERMINAL_CONNECTION_LOST');
+    if (JSON.parse(value).type === 'input') return this.#sender.send(value);
+    this.#socket.send(value);
+  }
+
+  close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#attachmentReject?.(new MarctlError(this.#translate('errors.terminalAttachLost')));
+    this.#attachmentReject = undefined;
+    this.#attachmentResolve = undefined;
+    this.#sender.close();
+    clearTimeout(this.#openTimer);
+    clearTimeout(this.#attachTimer);
+    this.#socket.removeListener?.('open', this.#onOpen);
+    this.#socket.removeListener?.('message', this.#onMessage);
+    this.#socket.removeListener?.('error', this.#onError);
+    this.#socket.removeListener?.('close', this.#onClose);
+    try {
+      this.#socket.close();
+    } catch {
+      // The connection is already unavailable.
+    }
+  }
+
+  #armAttachTimer(connectionTimeoutMs) {
+    if (this.#attached) return;
+    this.#attachTimer = setTimeout(
+      () => this.#fail(new MarctlError(this.#translate('errors.terminalAttachTimeout'))),
+      connectionTimeoutMs
+    );
+  }
+
+  #fail(error) {
+    if (this.#closed) return;
+    clearTimeout(this.#openTimer);
+    clearTimeout(this.#attachTimer);
+    this.#attachmentResolve = undefined;
+    const reject = this.#attachmentReject;
+    this.#attachmentReject = undefined;
+    if (!this.#attached) reject?.(error);
+    else this.#queueOrEmit('error', error);
+  }
+
+  #queueOrEmit(type, ...args) {
+    if (this.#active) {
+      if (type !== 'error' || this.listenerCount('error') > 0) this.emit(type, ...args);
+      return;
+    }
+    this.#pendingEvents.push({ type, args });
+  }
+}

package/dist/marctl/src/terminal.mjs

@@ -0,0 +1,152 @@
+import { MarctlError } from './errors.mjs';
+import { DirectRejectedError } from './direct-errors.mjs';
+import { createTranslator } from './i18n/index.mjs';
+import { raceTerminalConnections } from './terminal-race.mjs';
+import { openRelayTransport } from './terminal-relay.mjs';
+import { getDimensions, runAttachedTerminal } from './terminal-interaction.mjs';
+
+const DEFAULT_CONNECTION_TIMEOUT_MS = 15000;
+
+export async function runTerminalSession({
+  client,
+  WebSocketClass,
+  nodeId,
+  command,
+  binary = false,
+  attached,
+  stdin = process.stdin,
+  stdout = process.stdout,
+  signal,
+  translate = createTranslator(),
+  connectionTimeoutMs = DEFAULT_CONNECTION_TIMEOUT_MS,
+  openDirectTerminal: openDirectTerminalImpl,
+  raceConnections = false
+}) {
+  const dimensions = getDimensions(stdout);
+  let terminalId;
+  let transport;
+  let result;
+  let primaryError;
+  let manifest;
+
+  try {
+    if (signal?.aborted) return signal.reason === 'SIGTERM' ? 143 : 130;
+    if (binary) {
+      if (command === undefined)
+        throw new MarctlError(translate('errors.terminalBinaryUnavailable'));
+      manifest = await client.getTerminalManifest(nodeId);
+      if (signal?.aborted) return signal.reason === 'SIGTERM' ? 143 : 130;
+      if (manifest?.binaryTerminal !== true)
+        throw new MarctlError(translate('errors.terminalBinaryUnavailable'));
+    }
+    const created = await client.createTerminal({
+      nodeId,
+      ...dimensions,
+      ...(command === undefined ? {} : { command }),
+      ...(binary ? { binary: true } : {})
+    });
+    terminalId = binary ? created?.terminalId : created;
+    if (binary && created?.binary !== true)
+      throw new MarctlError(translate('errors.terminalBinaryUnavailable'));
+    if (signal?.aborted) return signal.reason === 'SIGTERM' ? 143 : 130;
+    try {
+      const openDirectTerminal =
+        openDirectTerminalImpl ?? (await import('./direct.mjs')).openDirectTerminal;
+      if (raceConnections && manifest === undefined)
+        manifest = await client.getTerminalManifest(nodeId).catch(() => undefined);
+      const directOptions = {
+        client,
+        WebSocketClass,
+        nodeId,
+        terminalId,
+        manifest,
+        afterSequence: 0,
+        timeoutMs: connectionTimeoutMs,
+        signal
+      };
+      const canRace = raceConnections && manifest?.deferredRelay === true;
+      transport = canRace
+        ? await raceTerminalConnections({
+            openDirectTerminal,
+            directOptions,
+            client,
+            WebSocketClass,
+            nodeId,
+            terminalId,
+            translate,
+            connectionTimeoutMs,
+            signal
+          })
+        : await openDirectTerminal(directOptions);
+      if (signal?.aborted) return signal.reason === 'SIGTERM' ? 143 : 130;
+      result =
+        attached === undefined
+          ? await runAttachedTerminal({
+              transport,
+              terminalId,
+              commandMode: command !== undefined,
+              stdin,
+              stdout,
+              signal,
+              translate
+            })
+          : await attached({ transport, terminalId, translate });
+    } catch (error) {
+      if (signal?.aborted) {
+        result = signal.reason === 'SIGTERM' ? 143 : 130;
+      } else {
+        if (error?.name === 'DirectUnsafeError')
+          throw new MarctlError(translate('errors.terminalDirectUnsafeFallback'));
+        if (error?.name !== 'DirectFallbackError') throw error;
+        transport = await openRelayTransport({
+          client,
+          WebSocketClass,
+          nodeId,
+          terminalId,
+          translate,
+          connectionTimeoutMs,
+          signal
+        });
+        if (signal?.aborted) return signal.reason === 'SIGTERM' ? 143 : 130;
+        result =
+          attached === undefined
+            ? await runAttachedTerminal({
+                transport,
+                terminalId,
+                commandMode: command !== undefined,
+                stdin,
+                stdout,
+                signal,
+                translate
+              })
+            : await attached({ transport, terminalId, translate });
+      }
+    }
+  } catch (error) {
+    if (signal?.aborted) result = signal.reason === 'SIGTERM' ? 143 : 130;
+    else primaryError = toMarctlError(error, translate);
+  } finally {
+    transport?.close?.();
+    if (terminalId !== undefined) {
+      try {
+        await client.deleteTerminal({ nodeId, terminalId });
+      } catch {
+        if (primaryError === undefined && result === undefined)
+          primaryError = new MarctlError(translate('errors.terminalCloseFailed'));
+      }
+    }
+  }
+
+  if (primaryError !== undefined) throw primaryError;
+  return result;
+}
+
+function toMarctlError(error, translate) {
+  if (error instanceof DirectRejectedError)
+    return new MarctlError(`${translate('errors.terminalSessionFailed')} [${error.code}]`, {
+      code: error.code
+    });
+  return error instanceof MarctlError
+    ? error
+    : new MarctlError(translate('errors.terminalSessionFailed'));
+}

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/marctl.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 // Keep the CLI implementation in its own package; the Node install exposes the same entrypoint.
-const entrypoint = '@myagentroam/marctl/bin/marctl.mjs';
+const entrypoint = './marctl/bin/marctl.mjs';
 await import(entrypoint);
 export {};

package/dist/marnodes.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-const entrypoint = '@myagentroam/marctl/bin/marnodes.mjs';
+const entrypoint = './marctl/bin/marnodes.mjs';
 await import(entrypoint);
 export {};

package/dist/marscp.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-const entrypoint = '@myagentroam/marctl/bin/marscp.mjs';
+const entrypoint = './marctl/bin/marscp.mjs';
 await import(entrypoint);
 export {};

package/dist/marssh.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-const entrypoint = '@myagentroam/marctl/bin/marssh.mjs';
+const entrypoint = './marctl/bin/marssh.mjs';
 await import(entrypoint);
 export {};

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/ripgrep-binary.js

@@ -1,5 +1,5 @@
 import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 export const BUNDLED_RIPGREP_VERSION = '15.1.0';
 const TARGETS = {
     'linux-x64': ['linux-x64', 'rg'],
@@ -11,8 +11,8 @@ const TARGETS = {
 };
 export function bundledRipgrepDirectory(packageRoot) {
     return packageRoot === undefined
-        ? resolve(dirname(fileURLToPath(import.meta.url)), '..', 'vendor/ripgrep')
-        : resolve(packageRoot, 'mar-node/vendor/ripgrep');
+        ? resolve(dirname(createRequire(import.meta.url).resolve('@myagentroam/binaries/package.json')), 'vendor/ripgrep')
+        : resolve(packageRoot, 'packages/binaries/vendor/ripgrep');
 }
 export function bundledRipgrepPath(platform = process.platform, architecture = process.arch, packageRoot) {
     const target = TARGETS[`${platform}-${architecture}`];

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/agent-operation-presentation.js

@@ -39,22 +39,34 @@ export function agentOperationPresentation(toolName, input, data) {
     if (!action)
         return undefined;
     const parsed = agentOperationPresentationSchema.safeParse(isPlainRecord(data) ? data.agentOperation : undefined);
-    if (parsed.success && parsed.data.action === action)
-        return parsed.data;
     const value = isPlainRecord(input) ? input : {};
     const ids = typeof value.agentId === 'string'
         ? [value.agentId]
         : Array.isArray(value.agentIds)
             ? value.agentIds
             : [];
-    return {
-        action,
-        targets: ids
-            .filter((id) => typeof id === 'string' && id.length > 0 && id.length <= 128)
-            .slice(0, 8)
-            .map((agentId) => ({ agentId })),
-        ...(text(value.scope, 32) ? { scope: text(value.scope, 32) } : {})
-    };
+    const operation = parsed.success && parsed.data.action === action
+        ? parsed.data
+        : {
+            action,
+            targets: ids
+                .filter((id) => typeof id === 'string' && id.length > 0 && id.length <= 128)
+                .slice(0, 8)
+                .map((agentId) => ({ agentId })),
+            ...(text(value.scope, 32) ? { scope: text(value.scope, 32) } : {})
+        };
+    const goal = isPlainRecord(value.goal) ? value.goal : undefined;
+    const objective = action === 'SEND' && !operation.detail?.message && !text(value.content) && goal?.clear !== true
+        ? text(goal?.objective, 2000)
+        : undefined;
+    if (objective)
+        operation.detail = {
+            ...operation.detail,
+            message: objective,
+            messageIsGoal: true,
+            ...(objective !== goal?.objective ? { messageTruncated: true } : {})
+        };
+    return operation;
 }
 /** Whitelist public receipts; never serialize configuration, credentials or full history. */
 export function agentOperationEvent(action, input, result) {

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.`;
 }