@awak-app/simy-cli 0.7.40 → 0.7.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.7.40",
+  "version": "0.7.42",
   "description": "Local SIMY executor for non-coding Local Tasks and Agentic Loop runs.",
   "type": "module",
   "bin": {

package/src/cli-contract.js

@@ -14,7 +14,7 @@ import {
 } from "./durable-local-task-steps-contract.js";
 import { buildExecutionCapabilityContract } from "./execution-capability-contract.js";
 
-export const CLI_VERSION = "0.7.40";
+export const CLI_VERSION = "0.7.42";
 export const CLI_API_CONTRACT_VERSION = 10;
 
 export function narrativeImageCapabilityMetadata() {

package/src/desktop-catalog-frames.js

@@ -0,0 +1,85 @@
+import { isDeepStrictEqual } from 'node:util';
+
+const catalogScope = status => JSON.stringify([status.webOrigin, status.auth?.userId, status.auth?.state,
+  status.access?.organizationId, status.access?.revision, status.access?.state]);
+
+function updateRows(previous, incoming, full, { unchanged = false, immutableInput = false, copyOnWrite = false } = {}) {
+  if (full || previous === null || previous.length !== incoming.length) {
+    const rows = immutableInput ? incoming : structuredClone(incoming);
+    return { rows, payload: { rows } };
+  }
+  if (unchanged) return { rows: previous, payload: { count: previous.length, changes: [] } };
+  const changes = [];
+  let rows = previous;
+  for (let index = 0; index < incoming.length; index++) {
+    if (!isDeepStrictEqual(previous[index], incoming[index])) {
+      const row = immutableInput ? incoming[index] : structuredClone(incoming[index]);
+      if (!immutableInput) {
+        if (copyOnWrite && rows === previous) rows = previous.slice();
+        rows[index] = row;
+      }
+      changes.push([index, row]);
+    }
+  }
+  return { rows: immutableInput ? incoming : rows, payload: { count: incoming.length, changes } };
+}
+
+// Detach mutable producer data once. Unchanged catalog rows may be shared only
+// between these owned read-only snapshots; changed rows get detached copies and
+// a new array. Older queued frames and durable writes must remain immutable.
+export function createDesktopStatusSnapshot() {
+  let rows = null, candidates = null, scope = null;
+  return status => {
+    const supervision = status?.sessionSupervision;
+    if (!Array.isArray(supervision?.sessions)) {
+      rows = candidates = scope = null;
+      return structuredClone(status);
+    }
+    const nextScope = catalogScope(status);
+    if (nextScope !== scope) { rows = candidates = null; scope = nextScope; }
+    const hasCandidates = Array.isArray(supervision.selectionCandidates);
+    const detached = structuredClone({ ...status, sessionSupervision: { ...supervision,
+      sessions: [], ...(hasCandidates ? { selectionCandidates: [] } : {}) } });
+    rows = updateRows(rows, supervision.sessions, false, { copyOnWrite: true }).rows;
+    detached.sessionSupervision.sessions = rows;
+    if (hasCandidates) {
+      candidates = updateRows(candidates, supervision.selectionCandidates, false, { copyOnWrite: true }).rows;
+      detached.sessionSupervision.selectionCandidates = candidates;
+    } else candidates = null;
+    return detached;
+  };
+}
+
+// One encoder per ordered output stream. Call only when a frame actually enters
+// that stream, after replaceable/backpressured snapshots have been coalesced.
+// This cache is transport state; it never authorizes work or provider dispatch.
+export function createDesktopCatalogEncoder({ immutableInput = false } = {}) {
+  let rows = null, candidates = null, sourceRows = null, sourceCandidates = null, scope = null, revision = 0;
+  const reset = () => { rows = null; candidates = null; sourceRows = null; sourceCandidates = null; scope = null; };
+  return { reset, encode(frame) {
+    if (frame.type !== 'status' || !Array.isArray(frame.status?.sessionSupervision?.sessions)) {
+      if (frame.type === 'status') reset();
+      return JSON.stringify(frame) + '\n';
+    }
+    const status = frame.status;
+    const incoming = status.sessionSupervision.sessions;
+    const identity = catalogScope(status);
+    const previous = revision++;
+    const full = rows === null || scope !== identity || rows.length !== incoming.length;
+    const snapshot = updateRows(rows, incoming, full, { immutableInput, unchanged: immutableInput && sourceRows === incoming });
+    rows = snapshot.rows; sourceRows = incoming; scope = identity;
+    const catalog = { version: 1, revision, scope, ...(full ? {} : { baseRevision: previous }), ...snapshot.payload };
+    const { sessions, ...metadata } = status.sessionSupervision;
+    let supervision = metadata;
+    if (Array.isArray(metadata.selectionCandidates)) {
+      // This is another complete directory, used by the conversation picker.
+      // Do not silently retransmit it as supposedly small status metadata.
+      const snapshot = updateRows(candidates, metadata.selectionCandidates, full,
+        { immutableInput, unchanged: immutableInput && sourceCandidates === metadata.selectionCandidates });
+      candidates = snapshot.rows; sourceCandidates = metadata.selectionCandidates; catalog.selectionCandidates = snapshot.payload;
+      const { selectionCandidates, ...small } = metadata;
+      supervision = small;
+    } else { candidates = null; sourceCandidates = null; }
+    return JSON.stringify({ ...frame, status: { ...status, sessionSupervision: supervision }, catalog }) + '\n';
+  } };
+}

package/src/desktop-frame-writer.js

@@ -1,7 +1,8 @@
 // Status snapshots are replaceable; command receipts and stop notifications are
 // not. Never enqueue periodic snapshots behind a native reader that has paused.
 // Control frames retain the stream's FIFO order and never wait for GUI drain.
-export function createDesktopFrameWriter(output) {
+export function createDesktopFrameWriter(output, { encode = frame => frame,
+  capture = frame => typeof frame === 'string' ? frame : structuredClone(frame) } = {}) {
   let blocked = false, pendingStatus = null, statusClosed = false;
   const drain = () => {
     blocked = false;
@@ -11,11 +12,11 @@ export function createDesktopFrameWriter(output) {
   };
   const write = (frame, isStatus = false) => {
     if (isStatus && statusClosed) return;
-    if (isStatus && blocked) { pendingStatus = frame; return; }
+    if (isStatus && blocked) { pendingStatus = capture(frame); return; }
     // A control frame must not be followed by a snapshot captured before it.
     // The next authorized projection will publish fresh state.
     if (!isStatus) pendingStatus = null;
-    const accepted = output.write(frame);
+    const accepted = output.write(encode(frame));
     if (accepted === false && !blocked && !statusClosed) {
       blocked = true;
       output.once('drain', drain);

package/src/desktop-host.js

@@ -1,4 +1,5 @@
 import { createDesktopFrameWriter } from './desktop-frame-writer.js';
+import { createDesktopCatalogEncoder, createDesktopStatusSnapshot } from './desktop-catalog-frames.js';
 import { boundedDiscovery } from './session-supervision/progressive-discovery.js';
 import { createCatalogRefreshPolicy } from './session-supervision/catalog-refresh.js';
 import { supervisedSession } from './session-supervision/discovery-window.js';
@@ -159,7 +160,12 @@ export { createDesktopFrameWriter } from './desktop-frame-writer.js';
 
 export async function startDesktopHost({ input = process.stdin, output = process.stdout, env = process.env,
   updatePackageRoot, dependencies = {}, exit = (code) => process.exit(code) } = {}) {
-  const frames = createDesktopFrameWriter(output);
+  let catalogEncoder = env.SIMY_REMOTE_CHILD !== '1' && env.SIMY_DESKTOP_CATALOG_DELTA === '1'
+    ? createDesktopCatalogEncoder({ immutableInput: true }) : null;
+  // Object frames below own detached snapshots. Queue their references rather
+  // than copying multi-MiB history again whenever a native reader is paused.
+  const frames = createDesktopFrameWriter(output, { capture: frame => frame,
+    encode: frame => typeof frame === 'string' ? frame : catalogEncoder.encode(frame) });
   const pendingRemoteReceipts = new Map();
   let operationJournal, ownerTransport;
   // An explicitly requested window update releases only its viewer. The same
@@ -177,7 +183,7 @@ export async function startDesktopHost({ input = process.stdin, output = process
     }
     ownerTransport?.publish(event);
     if (event.type === 'status') ownerTransport?.publishDesktop?.(event);
-    if (!viewerDetached) frames.write(`${JSON.stringify(event)}\n`, event.type === 'status');
+    if (!viewerDetached) frames.write(catalogEncoder ? structuredClone(event) : `${JSON.stringify(event)}\n`, event.type === 'status');
   };
   const emit = (event) => {
     const pending = event.type === 'result' ? pendingRemoteReceipts.get(event.id) : null;
@@ -186,10 +192,12 @@ export async function startDesktopHost({ input = process.stdin, output = process
       void operationJournal.finish(pending.scope, pending.command, event).then(() => writeEvent(event)).catch(() => writeEvent({ type: 'result', id: event.id, ok: false, code: 'remote_operation_unknown' }));
     } else writeEvent(event);
   };
-  // A heartbeat remains a complete native frame. Only its observation time is
-  // volatile; reuse the encoded body after comparing freshly authorized data.
-  // Detach the comparison value because registries may mutate nested objects.
-  let encodedStatus = null, lastStatus = null, updateProgress = null;
+  // Retain complete logical snapshots for authorization-independent display.
+  // Legacy streams reuse the encoded body; opted-in native streams encode row
+  // deltas later, after backpressure coalescing. Registries may mutate objects,
+  // so the comparison snapshot must remain detached from producer references.
+  let encodedStatus = null, lastStatus = null, lastStatusFrame = null, updateProgress = null;
+  const snapshotStatus = createDesktopStatusSnapshot();
   let projectCatalogFrame = status => status;
   let resolveFirstStatus;
   const firstStatus = new Promise(resolve => { resolveFirstStatus = resolve; });
@@ -199,6 +207,7 @@ export async function startDesktopHost({ input = process.stdin, output = process
   let acceptanceReadbackSequence = 0;
   let remoteHosts;
   const emitStatus = status => {
+    let catalogObservation;
     status = projectCatalogFrame(status);
     status = { ...status, windowUpdate: { version: 1, preservesWork: Boolean(ownerTransport), prepared: windowUpdatePrepared } };
     const updateSettings = updater?.snapshot?.() || {};
@@ -222,18 +231,26 @@ export async function startDesktopHost({ input = process.stdin, output = process
     if (preferenceScope && desktopAccessReady(status.access) && status.sessionSupervision?.sessions) {
       const catalogScope = preferenceScope;
       status = { ...status, sessionSupervision: { ...status.sessionSupervision, sessions: status.sessionSupervision.sessions.filter(row => controllerPreferences.get(catalogScope, row).deleted !== true).map(row => { const saved = controllerPreferences.get(catalogScope, row); return { ...row, controllerPreferences: saved, ...(saved.pinned === undefined ? {} : { listPinned: saved.pinned, listPinScopes: saved.pinScopes }), ...(saved.hidden === undefined ? {} : { localHidden: saved.hidden }) }; }) } };
-      const catalog = { observedAt: Date.now(), sessions: status.sessionSupervision.sessions, hosts: status.remoteHosts?.items || [], providerLinks };
-      void controllerPreferences.replaceCatalog(catalogScope, catalog).catch(() => {});
+      catalogObservation = { scope: catalogScope, observedAt: Date.now() };
     }
     if (updateProgress) status = { ...status, update: { ...status.update, ...updateProgress } };
-    ownerTransport?.publishDesktop?.({ type: 'status', status });
     const { sampledAt, ...content } = status;
     if (!lastStatus || !isDeepStrictEqual(content, lastStatus)) {
-      encodedStatus = JSON.stringify(content).slice(1, -1);
-      lastStatus = structuredClone(content);
+      if (!catalogEncoder) encodedStatus = JSON.stringify(content).slice(1, -1);
+      lastStatus = snapshotStatus(content);
     }
+    const ownedStatus = { ...lastStatus, ...(sampledAt === undefined ? {} : { sampledAt }) };
+    if (catalogObservation) {
+      const catalog = { observedAt: catalogObservation.observedAt, sessions: ownedStatus.sessionSupervision.sessions,
+        hosts: ownedStatus.remoteHosts?.items || [], providerLinks: structuredClone(providerLinks) };
+      void controllerPreferences.replaceCatalog(catalogObservation.scope, catalog, { immutableInput: true }).catch(() => {});
+    }
+    lastStatusFrame = ownedStatus;
+    ownerTransport?.publishDesktop?.({ type: 'status', status: ownedStatus });
     const observation = sampledAt === undefined ? '' : `"sampledAt":${JSON.stringify(sampledAt)}${encodedStatus ? ',' : ''}`;
-    if (!viewerDetached) frames.write(`{"type":"status","status":{${observation}${encodedStatus}}}\n`, true);
+    if (!viewerDetached) frames.write(catalogEncoder
+      ? { type: 'status', status: ownedStatus }
+      : `{"type":"status","status":{${observation}${encodedStatus}}}\n`, true);
     resolveFirstStatus?.(); resolveFirstStatus = null;
   };
   const root = env.SIMY_HOME?.trim() || join(homedir(), ".simy");
@@ -1314,7 +1331,9 @@ export async function startDesktopHost({ input = process.stdin, output = process
       try { child = (dependencies.spawn || spawn)(installation.executablePath,
         [join(dirname(installation.entryPath), "desktop-host.js")], {
           stdio: ["pipe", "pipe", "pipe"],
-          env: { ...updateConnectionEnvironment({ env, root, webOrigin }), SIMY_DESKTOP_SUPERVISOR_TOKEN: supervisorToken, ...(transferToken ? {SIMY_UPDATE_TRANSFER_TOKEN:transferToken} : {}) },
+          // The parent validates complete candidate frames and owns encoding for
+          // its native viewer. Never chain delta baselines through a handoff.
+          env: { ...updateConnectionEnvironment({ env, root, webOrigin }), SIMY_DESKTOP_CATALOG_DELTA: '0', SIMY_DESKTOP_SUPERVISOR_TOKEN: supervisorToken, ...(transferToken ? {SIMY_UPDATE_TRANSFER_TOKEN:transferToken} : {}) },
         }); } catch (error) {
           if(transferToken)await updateRuntime.reclaimFailedHandoff();
           actionAssociations = makeActionAssociations();
@@ -1498,6 +1517,20 @@ export async function startDesktopHost({ input = process.stdin, output = process
     if (line.length > 16384) return;
     let command; try { command = JSON.parse(line); } catch { return; }
     if (typeof command.id !== "string" || command.id.length > 128) return;
+    if (command.action === 'desktop_status_resync') {
+      catalogEncoder?.reset();
+      if (command.catalogDeltas === false && catalogEncoder) {
+        catalogEncoder = null;
+        if (lastStatus) encodedStatus = JSON.stringify(lastStatus).slice(1, -1);
+      }
+      emit({ type: 'result', id: command.id, ok: true });
+      // Send after the receipt: a control may discard a pending snapshot.
+      const snapshot = relay ? relayStatus?.value : lastStatusFrame;
+      if (!viewerDetached && snapshot) frames.write(catalogEncoder
+        ? { type: 'status', status: structuredClone(snapshot) }
+        : JSON.stringify({ type: 'status', status: snapshot }) + '\n', true);
+      return;
+    }
     if (relay) {
       if (['prepare_window_update', 'cancel_window_update'].includes(command.action)) {
         const authorized = Boolean(ownerTransport) && relayStatus && Date.now() - relayStatus.at < 10_000 && desktopAccessReady(relayStatus.value.access);
@@ -2520,7 +2553,8 @@ export function startDesktopEntry(options = {}) {
 if (isDesktopHostEntry()) {
   try {
     const root = process.env.SIMY_HOME?.trim() || join(homedir(), '.simy');
-    if (process.env.SIMY_DESKTOP_ATTACH_OWNER === '1' && await relayToOwner({ root, webOrigin: resolveWebOrigin(null, process.env), desktopClient: true })) process.exit(0);
+    if (process.env.SIMY_DESKTOP_ATTACH_OWNER === '1' && await relayToOwner({ root, webOrigin: resolveWebOrigin(null, process.env), desktopClient: true,
+      catalogDeltas: process.env.SIMY_DESKTOP_CATALOG_DELTA === '1' })) process.exit(0);
     try { await adoptInstalledRuntime({ root }); }
     catch (error) {
       if (error.code === PROCESS_CONFLICT_CODE) throw error;

package/src/session-supervision/controller-store.js

@@ -41,11 +41,13 @@ export function createControllerStore(root) {
       await persist(scope, next); return result;
     });
   }
-  function replaceCatalog(scope, catalog) {
+  function replaceCatalog(scope, catalog, { immutableInput = false } = {}) {
     // Own the incoming snapshot immediately, but do not clone the previous
     // multi-MiB catalog just to replace it. Preference writes still serialize
     // on the same queue and commit only after their atomic write succeeds.
-    const snapshot = structuredClone(catalog);
+    // Only the desktop's detached read-only snapshots may be borrowed. Generic
+    // callers retain immediate mutation isolation, including while queued.
+    const snapshot = immutableInput ? catalog : structuredClone(catalog);
     return enqueue(async () => {
       const settings = { ...await load(scope) };
       delete settings.catalog;

package/src/session-supervision/owner-transport.js

@@ -1,4 +1,5 @@
 import { createDesktopFrameWriter } from '../desktop-frame-writer.js';
+import { createDesktopCatalogEncoder } from '../desktop-catalog-frames.js';
 import { createServer, createConnection } from 'node:net';
 import { chmod, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -14,6 +15,7 @@ const socketPath = ownerSocketPath;
 // account/provider checks still run in the owner's ordinary command handler.
 export async function createOwnerTransport({ root, nonce, allowedActions, dispatch, allowControllerArchive = false, allowDesktopClient = false }) {
   const writers = new WeakMap();
+  const catalogEncoders = new WeakMap();
   const peers = new Set(), subscribers = new Set(), desktopSubscribers = new Set(), requests = new Map();
   let latest, latestDesktop;
   const send = (peer, frame) => {
@@ -22,11 +24,11 @@ export async function createOwnerTransport({ root, nonce, allowedActions, dispat
     // socket queue. Preserve room for bounded control receipts rather than
     // disconnecting the viewer as soon as it requests a result behind it.
     if (frame.type !== 'status' && peer.writableLength > (64 + 8) * 1024 * 1024) { peer.destroy(); return; }
-    writers.get(peer).write(JSON.stringify(frame) + '\n', frame.type === 'status');
+    writers.get(peer).write(catalogEncoders.has(peer) ? frame : JSON.stringify(frame) + '\n', frame.type === 'status');
   };
   const server = createServer(peer => {
     peer.setEncoding('utf8');
-    const writer = createDesktopFrameWriter(peer);
+    const writer = createDesktopFrameWriter(peer, { encode: frame => typeof frame === 'string' ? frame : catalogEncoders.get(peer).encode(frame) });
     writers.set(peer, writer);
     let authenticated = false, controllerArchive = false, desktopClient = false, buffer = '';
     const timeout = setTimeout(() => peer.destroy(), 5000);
@@ -43,7 +45,8 @@ export async function createOwnerTransport({ root, nonce, allowedActions, dispat
         if (!authenticated) {
           if (command.nonce !== nonce) { peer.destroy(); return; }
           authenticated = true; desktopClient = allowDesktopClient && command.client === 'desktop'; controllerArchive = allowControllerArchive && command.client === 'archive-controller'; clearTimeout(timeout); peers.add(peer);
-          if (command.desktopProtocol === 1 && desktopClient) send(peer, { type: 'desktop_owner_ready', version: 1 });
+          if (desktopClient && (command.desktopProtocol === 2 || command.catalogDeltas === 1)) catalogEncoders.set(peer, createDesktopCatalogEncoder());
+          if ([1, 2].includes(command.desktopProtocol) && desktopClient) send(peer, { type: 'desktop_owner_ready', version: catalogEncoders.has(peer) ? 2 : 1 });
           // One-shot controls need their result, not multi-megabyte broadcasts
           // that can fill the write queue before the result is sent.
           if (command.subscribeStatus !== false) {
@@ -53,6 +56,13 @@ export async function createOwnerTransport({ root, nonce, allowedActions, dispat
           }
           continue;
         }
+        if (desktopClient && command.action === 'desktop_status_resync' && typeof command.id === 'string' && command.id.length <= 128) {
+          catalogEncoders.get(peer)?.reset();
+          if (command.catalogDeltas === false) catalogEncoders.delete(peer);
+          send(peer, { type: 'result', id: command.id, ok: true });
+          if (latestDesktop) send(peer, latestDesktop);
+          continue;
+        }
         if ((!desktopClient && !allowedActions.has(command.action)) || typeof command.id !== 'string' || command.id.length > 128 || command.hostId && command.hostId !== 'local' && !desktopClient && !(controllerArchive && ['session_archive', 'session_restore', 'session_provider_setup'].includes(command.action))) {
           send(peer, { type: 'result', id: command.id, ok: false, code: 'unsupported_remote_action' }); continue;
         }
@@ -91,7 +101,7 @@ export async function createOwnerTransport({ root, nonce, allowedActions, dispat
 
 // Returns false only when no compatible owner endpoint exists. Never starts a
 // second owner, kills a process, or converts a disconnect into an execution retry.
-export async function relayToOwner({ root, webOrigin, input = process.stdin, output = process.stdout, desktopClient = false }) {
+export async function relayToOwner({ root, webOrigin, input = process.stdin, output = process.stdout, desktopClient = false, catalogDeltas = false }) {
   let owner;
   try { owner = JSON.parse(await readFile(join(root, 'desktop-app.lock', 'owner.json'), 'utf8')); }
   catch (error) { if (error.code === 'ENOENT') return false; throw error; }
@@ -107,7 +117,9 @@ export async function relayToOwner({ root, webOrigin, input = process.stdin, out
     if (webOrigin && (!owner.webOrigin || normalizeWebOrigin(owner.webOrigin) !== normalizeWebOrigin(webOrigin)))
       throw Object.assign(new Error('The existing SIMY owner belongs to another Web address. Keep its tasks and reconnect using its saved environment.'), { code: 'remote_owner_origin_mismatch' });
   } catch (error) { peer.destroy(); throw error; }
-  peer.write(JSON.stringify({ nonce: owner.nonce, ...(desktopClient ? { client: 'desktop', desktopProtocol: 1 } : {}) }) + '\n');
+  // A protocol-1 owner replies with complete frames. New native windows accept
+  // both versions, so attaching never requires replacing its execution owner.
+  peer.write(JSON.stringify({ nonce: owner.nonce, ...(desktopClient ? { client: 'desktop', desktopProtocol: 1, ...(catalogDeltas ? { catalogDeltas: 1 } : {}) } : {}) }) + '\n');
   // Old owners ignore unknown hello fields and expose only the restricted SSH
   // projection. Never attach a native window or forward its controls as though
   // that were a complete desktop endpoint. Keep the original owner untouched.
@@ -139,7 +151,7 @@ function confirmDesktopOwner(peer) {
       buffer = Buffer.concat([buffer, line]);
       if (newline < 0) return;
       let frame; try { frame = JSON.parse(buffer.toString('utf8')); } catch { finish(incompatible()); return; }
-      if (frame?.type !== 'desktop_owner_ready' || frame.version !== 1) { finish(incompatible()); return; }
+      if (frame?.type !== 'desktop_owner_ready' || ![1, 2].includes(frame.version)) { finish(incompatible()); return; }
       peer.pause();
       if (newline + 1 < chunk.length) peer.unshift(chunk.subarray(newline + 1));
       finish();