amalgm 0.1.96 → 0.1.97

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.96",
+  "version": "0.1.97",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/browser/attach.js

@@ -34,7 +34,7 @@
 const cli = require('./cli');
 const backend = require('./backend');
 const cdp = require('./cdp');
-const { surfaces, knownSessions } = require('./sessions');
+const { surfaces, knownSessions, backendFor } = require('./sessions');
 
 const SURFACE_EVENT_RESOURCE = 'browser_surfaces';
 const WEBVIEW_MARKER_PREFIX = 'amalgm-bsid-';
@@ -58,10 +58,10 @@ function guardCommand(session) {
     + `throw new Error(${JSON.stringify(GUARD_ERROR)}); })()`];
 }
 
-/** Options every cli call needs for the current backend. */
+/** Options every cli call needs for this session's backend. */
 function cliOptions(session, extra = {}) {
   const options = { session, ...extra };
-  if (backend.mode() === 'attached') options.cdp = backend.cdpEndpoint();
+  if (backendFor(session) === 'attached') options.cdp = backend.cdpEndpoint();
   return options;
 }
 
@@ -224,7 +224,7 @@ async function focusSurface(session, surface) {
  * target it names.
  */
 async function ensureReady(session, context) {
-  if (backend.mode() !== 'attached') return null;
+  if (backendFor(session) !== 'attached') return null;
   const live = surfaces.get(session);
   if (live) return live;
 

package/runtime/scripts/amalgm-mcp/browser/auth-tools.js

@@ -82,11 +82,12 @@ module.exports = [
             || ctx?.callerSessionId
             || `login-${Date.now().toString(36)}`,
         );
-        // In the desktop app, the login happens on the visible surface this
-        // session already drives — open the page there and say so. The link
-        // is the web/remote path, where a separate live view (noVNC today)
-        // shows the headless browser.
-        const attached = engine.mode() === 'attached';
+        // A desktop-born conversation logs in on the visible surface this
+        // session already drives — open the page there and say so. Everyone
+        // else gets the link, where a separate live view (noVNC today) shows
+        // the headless browser. sessionFor records the login session's home
+        // from the caller's birth stamp, same as every other verb.
+        const attached = engine.backendFor(engine.sessionFor({ session: profileId }, ctx)) === 'attached';
         const result = createBrowserLoginSession({
           ...args,
           transport: args.transport || (attached ? 'electron-splitview' : undefined),

package/runtime/scripts/amalgm-mcp/browser/backend.js

@@ -1,18 +1,22 @@
 'use strict';
 
 /**
- * Backend routing — which browser this runtime drives.
+ * Backend routing — which browser a session drives.
  *
  * Exactly two backends:
  *  - "attached": the visible chromium the Amalgm desktop app advertises over
  *    CDP (or an explicit AMALGM_BROWSER_CDP_URL endpoint). The user watches
  *    this browser in the app's split view.
  *  - "cli": a standalone agent-browser chromium, headless. The deterministic
- *    path for npm-only machines, servers, Fly workers, and the web client.
+ *    path for npm-only machines, servers, Fly workers, web chats, sub-agents,
+ *    and automations.
  *
- * The rule: a fresh advertisement (or explicit CDP env) ⇒ attached;
- * otherwise ⇒ cli. "Fresh" means the advertising pid is alive. Nothing else
- * may influence the choice — visibility must be deterministic per entrypoint.
+ * The rule: a browser session inherits its home from the conversation that
+ * created it. Conversations born in the desktop app carry client:'desktop'
+ * in their session metadata (stamped at creation, immutable); only those get
+ * the visible browser, and only while the app's advertisement is fresh
+ * ("fresh" = the advertising pid is alive). Everything else — web chats,
+ * sub-agents, automations, anything unstamped — is headless by construction.
  * AMALGM_BROWSER_BACKEND forces a backend for debugging.
  */
 
@@ -84,10 +88,26 @@ function cdpEndpoint() {
   return cdpFlagValue(advertisement.cdpUrl);
 }
 
-function mode() {
+/** The debug override, or null when the owner's stamp decides. */
+function forcedMode() {
   const requested = (process.env.AMALGM_BROWSER_BACKEND || '').toLowerCase();
   if (['agent-browser', 'external', 'cli', 'headless'].includes(requested)) return 'cli';
   if (['attached', 'cdp', 'electron'].includes(requested)) return 'attached';
+  return null;
+}
+
+/**
+ * The backend for a session whose owner conversation carries `client` in its
+ * metadata. Pure: same stamp, same answer. 'desktop' is the only value that
+ * earns the visible browser, and only while the app is actually there.
+ */
+function modeFor(client) {
+  const forced = forcedMode();
+  if (forced) return forced;
+  // An explicit CDP endpoint is an operator instruction to drive that
+  // chromium, regardless of who asks.
+  if (process.env.AMALGM_BROWSER_CDP_URL) return 'attached';
+  if (client !== 'desktop') return 'cli';
   return cdpEndpoint() ? 'attached' : 'cli';
 }
 
@@ -95,6 +115,7 @@ module.exports = {
   bridgeFileCandidates,
   cdpEndpoint,
   cdpFlagValue,
-  mode,
+  forcedMode,
+  modeFor,
   readBridgeAdvertisement,
 };

package/runtime/scripts/amalgm-mcp/browser/capture.js

@@ -26,6 +26,7 @@ const backend = require('./backend');
 const cli = require('./cli');
 const attach = require('./attach');
 const cdp = require('./cdp');
+const { backendFor } = require('./sessions');
 
 // An on-screen surface answers captureScreenshot in well under 100ms
 // (measured 54–100ms live); one that has not answered in 4s is not going to.
@@ -51,7 +52,7 @@ async function pageTargetWsUrl(endpoint) {
  *   is normalized to CSS pixels so coordinates map 1:1 onto cua_* input.
  */
 async function plan(session, context) {
-  if (backend.mode() !== 'attached') {
+  if (backendFor(session) !== 'attached') {
     const raw = await daemonCdpUrl(session);
     if (!raw) throw new Error('Could not resolve a CDP endpoint for this browser session.');
     const wsUrl = /\/devtools\/browser\//.test(raw) ? await pageTargetWsUrl(raw) : raw;

package/runtime/scripts/amalgm-mcp/browser/engine.js

@@ -20,8 +20,9 @@ const backend = require('./backend');
 const attach = require('./attach');
 const capture = require('./capture');
 const sessions = require('./sessions');
+const typing = require('./typing');
 
-const { sessionFor, sessionInfo } = sessions;
+const { backendFor, sessionFor, sessionInfo } = sessions;
 const { run, runBatch, readText } = attach;
 
 /**
@@ -96,18 +97,33 @@ async function fill(args = {}, context) {
   const session = sessionFor(args, context);
   const target = String(args.target || '');
   const text = String(args.text ?? '');
-  const fillCommand = target.startsWith('text=') ? findArgs(target, 'fill', text) : ['fill', target, text];
-  if (args.submit) {
-    await runBatch(session, [fillCommand, ['press', 'Enter']], { context });
+  if (backendFor(session) === 'attached') {
+    // Shared window: synthesized keystrokes follow window focus and can land
+    // in the user's chat box (typing.js). Focus the element through the
+    // daemon (in-page, resolves @ref/CSS/text= alike), then set the value
+    // inside the page — the text cannot leave the session's page.
+    const focusCommand = target.startsWith('text=') ? findArgs(target, 'focus') : ['focus', target];
+    const commands = [focusCommand, ['eval', typing.setValueScript(text)]];
+    if (args.submit) commands.push(['eval', typing.keyScript('Enter')]);
+    await runBatch(session, commands, { context });
   } else {
-    await run(session, fillCommand, { context });
+    const fillCommand = target.startsWith('text=') ? findArgs(target, 'fill', text) : ['fill', target, text];
+    if (args.submit) {
+      await runBatch(session, [fillCommand, ['press', 'Enter']], { context });
+    } else {
+      await run(session, fillCommand, { context });
+    }
   }
   return sessionInfo(session, { filled: target, submitted: Boolean(args.submit) });
 }
 
 async function press(args = {}, context) {
   const session = sessionFor(args, context);
-  await run(session, ['press', args.key], { context });
+  if (backendFor(session) === 'attached') {
+    await run(session, ['eval', typing.keyScript(String(args.key || ''))], { context });
+  } else {
+    await run(session, ['press', args.key], { context });
+  }
   return sessionInfo(session, { pressed: args.key });
 }
 
@@ -174,7 +190,7 @@ async function passthrough(args = {}, context) {
   const session = sessionFor(args, context);
   const commandArgs = (args.args || []).map(String);
   if (!commandArgs.length) throw new Error('args is required, e.g. ["scroll", "down"] or ["get", "text", "@e1"]');
-  if (backend.mode() === 'attached' && commandArgs[0] === 'tab' && commandArgs.length > 1) {
+  if (sessions.backendFor(session) === 'attached' && commandArgs[0] === 'tab' && commandArgs.length > 1) {
     // In the desktop app a session IS its surface; hopping targets is how a
     // session ends up driving another session's page. Listing stays allowed.
     throw new Error(
@@ -328,9 +344,10 @@ module.exports = {
   // Routing façade (backend.js) — kept here so engine stays the one import.
   bridgeFileCandidates: backend.bridgeFileCandidates,
   cdpEndpoint: backend.cdpEndpoint,
-  mode: backend.mode,
+  modeFor: backend.modeFor,
   readBridgeAdvertisement: backend.readBridgeAdvertisement,
   // Session façade (sessions.js).
+  backendFor: sessions.backendFor,
   knownSessions: sessions.knownSessions,
   sessionFor,
   sessionInfo,

package/runtime/scripts/amalgm-mcp/browser/recorder.js

@@ -25,7 +25,6 @@ const path = require('path');
 const { spawn } = require('child_process');
 
 const cli = require('./cli');
-const backend = require('./backend');
 const capture = require('./capture');
 const sessions = require('./sessions');
 
@@ -246,7 +245,7 @@ async function start(args = {}, context = {}) {
     path: file,
     fps,
     mimeType: 'video/webm',
-    backend: backend.mode(),
+    backend: sessions.backendFor(session),
     source: source.guest ? 'visible surface' : 'page',
   };
 }

package/runtime/scripts/amalgm-mcp/browser/sessions.js

@@ -23,8 +23,21 @@ const surfaces = new Map();
 /** Per-session bookkeeping: webviewTabId, lastActiveAt, last url/title. */
 const knownSessions = new Map();
 
+/**
+ * Each session's home backend, decided once at first use from the owner
+ * conversation's birth stamp (metadata.client) and never re-decided — a
+ * session does not migrate between a visible surface and a headless browser
+ * mid-life. An MCP restart clears the map; the next call re-derives the same
+ * answer from the same stamp.
+ */
+const homes = new Map();
+
+function backendFor(session) {
+  return homes.get(session) || backend.modeFor(undefined);
+}
+
 function sessionFor(args = {}, context = {}) {
-  return cli.safeId(
+  const session = cli.safeId(
     args.session
       || args.profile
       || args.browserProfileId
@@ -34,6 +47,10 @@ function sessionFor(args = {}, context = {}) {
       || context?.callerSessionId
       || cli.DEFAULT_SESSION,
   );
+  if (!homes.has(session)) {
+    homes.set(session, backend.modeFor(context?.sessionMetadata?.client));
+  }
+  return session;
 }
 
 function rememberProfile(session) {
@@ -53,7 +70,7 @@ function sessionInfo(session, extra = {}) {
     session,
     browserSessionId: session,
     browserProfileId: session,
-    backend: backend.mode(),
+    backend: backendFor(session),
     ...extra,
   };
   knownSessions.set(session, { ...knownSessions.get(session), ...info, lastActiveAt: Date.now() });
@@ -61,6 +78,8 @@ function sessionInfo(session, extra = {}) {
 }
 
 module.exports = {
+  backendFor,
+  homes,
   knownSessions,
   rememberProfile,
   sessionFor,

package/runtime/scripts/amalgm-mcp/browser/typing.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * In-page typing — the scripts behind fill and press in attached mode.
+ *
+ * In the desktop app the agent and the user share one chromium window, and
+ * synthesized keystrokes (CDP Input events) are routed by *window focus* —
+ * an agent "typing" while the user's caret sits in the chat box lands the
+ * text in the chat box (observed live). These scripts act inside the
+ * session's page instead, through the same stamp-guarded transport as every
+ * other command, so agent input physically cannot reach anything but the
+ * page it was meant for.
+ *
+ * The boundary: page-level semantics work (value setting with real
+ * input/change events, key handlers, Enter activating buttons and
+ * submitting forms); OS-level editing defaults (Tab focus traversal,
+ * arrow-key scrolling) are real-input territory — that is what the cua_*
+ * verbs are for, and they stay focus-dependent by design.
+ */
+
+/**
+ * Set the focused field's value the way the page expects: through the
+ * native prototype setter (so frameworks tracking the value descriptor —
+ * React — see the change), followed by real input/change events.
+ */
+function setValueScript(text) {
+  return `(() => {
+    const el = document.activeElement;
+    if (!el || el === document.body) throw new Error('focus did not land on a field');
+    const text = ${JSON.stringify(String(text))};
+    if (el.isContentEditable) {
+      el.textContent = text;
+    } else {
+      const proto = el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype
+        : el instanceof HTMLInputElement ? HTMLInputElement.prototype
+        : null;
+      if (!proto && !('value' in el)) {
+        throw new Error('focused element <' + el.tagName.toLowerCase() + '> is not fillable');
+      }
+      const setter = proto && Object.getOwnPropertyDescriptor(proto, 'value').set;
+      if (setter) setter.call(el, text); else el.value = text;
+    }
+    el.dispatchEvent(new InputEvent('input', { bubbles: true, data: text, inputType: 'insertReplacementText' }));
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+    return true;
+  })()`;
+}
+
+/** "KeyA" for letters, "Digit1" for digits, the key's own name otherwise. */
+function codeFor(key) {
+  if (/^[a-z]$/i.test(key)) return `Key${key.toUpperCase()}`;
+  if (/^[0-9]$/.test(key)) return `Digit${key}`;
+  if (key === ' ') return 'Space';
+  return key;
+}
+
+/**
+ * Dispatch a key combination ("Enter", "Escape", "Control+a") to the focused
+ * element, mirroring the browser's own Enter defaults when no handler
+ * prevents them: buttons and links activate, single-line form fields submit
+ * their form (through requestSubmit, so submit handlers and validation run).
+ */
+function keyScript(combo) {
+  const parts = String(combo).split('+');
+  const key = parts.pop() || '';
+  const mods = parts.map((part) => part.toLowerCase());
+  const init = {
+    key,
+    code: codeFor(key),
+    bubbles: true,
+    cancelable: true,
+    ctrlKey: mods.includes('control') || mods.includes('ctrl'),
+    shiftKey: mods.includes('shift'),
+    altKey: mods.includes('alt') || mods.includes('option'),
+    metaKey: mods.includes('meta') || mods.includes('cmd') || mods.includes('command'),
+  };
+  return `(() => {
+    const el = document.activeElement || document.body;
+    const init = ${JSON.stringify(init)};
+    const proceed = el.dispatchEvent(new KeyboardEvent('keydown', init));
+    if (proceed) {
+      el.dispatchEvent(new KeyboardEvent('keypress', init));
+      if (init.key === 'Enter') {
+        if (el instanceof HTMLButtonElement || el instanceof HTMLAnchorElement) {
+          el.click();
+        } else if (el instanceof HTMLInputElement && el.form) {
+          if (el.form.requestSubmit) el.form.requestSubmit(); else el.form.submit();
+        }
+      }
+    }
+    el.dispatchEvent(new KeyboardEvent('keyup', init));
+    return true;
+  })()`;
+}
+
+module.exports = { codeFor, keyScript, setValueScript };

package/runtime/scripts/amalgm-mcp/tests/browser-routing.test.js

@@ -48,35 +48,36 @@ function writeAdvertisement(dir, data) {
   );
 }
 
-test('entrypoint routing: no advertisement means headless cli', () => {
+test('ownership routing: no advertisement means headless for everyone', () => {
   withEnv({ AMALGM_DIR: tempDir('empty') }, () => {
-    assert.equal(engine.mode(), 'cli');
+    assert.equal(engine.modeFor('desktop'), 'cli');
+    assert.equal(engine.modeFor('web'), 'cli');
     assert.equal(engine.cdpEndpoint(), null);
   });
 });
 
-test('entrypoint routing: AMALGM_BROWSER_BACKEND forces a backend', () => {
+test('ownership routing: AMALGM_BROWSER_BACKEND forces a backend for everyone', () => {
   withEnv({ AMALGM_BROWSER_BACKEND: 'cli', AMALGM_BROWSER_CDP_URL: 'ws://127.0.0.1:9242/x' }, () => {
-    assert.equal(engine.mode(), 'cli');
+    assert.equal(engine.modeFor('desktop'), 'cli');
   });
   withEnv({ AMALGM_BROWSER_BACKEND: 'attached' }, () => {
-    assert.equal(engine.mode(), 'attached');
+    assert.equal(engine.modeFor('web'), 'attached');
   });
   // Old override value keeps meaning "the visible desktop browser".
   withEnv({ AMALGM_BROWSER_BACKEND: 'electron' }, () => {
-    assert.equal(engine.mode(), 'attached');
+    assert.equal(engine.modeFor(undefined), 'attached');
   });
 });
 
-test('entrypoint routing: explicit AMALGM_BROWSER_CDP_URL attaches', () => {
+test('ownership routing: explicit AMALGM_BROWSER_CDP_URL attaches regardless of owner', () => {
   withEnv({ AMALGM_BROWSER_CDP_URL: 'ws://127.0.0.1:9999/devtools/browser/abc' }, () => {
-    assert.equal(engine.mode(), 'attached');
+    assert.equal(engine.modeFor('web'), 'attached');
     // --cdp takes a port; URLs are reduced to their port.
     assert.equal(engine.cdpEndpoint(), '9999');
   });
 });
 
-test('entrypoint routing: fresh advertisement in the runtime state dir attaches', () => {
+test('ownership routing: a fresh advertisement attaches desktop-born chats ONLY', () => {
   const stateDir = tempDir('state');
   writeAdvertisement(stateDir, {
     cdpUrl: 'ws://127.0.0.1:9242/devtools/browser/live',
@@ -84,35 +85,72 @@ test('entrypoint routing: fresh advertisement in the runtime state dir attaches'
     pid: process.pid,
   });
   withEnv({ AMALGM_RUNTIME_STATE_DIR: stateDir }, () => {
-    assert.equal(engine.mode(), 'attached');
+    assert.equal(engine.modeFor('desktop'), 'attached');
+    // The app being alive is not enough: web chats, sub-agents, automations,
+    // and anything unstamped stay headless — the 2026-06-11 leak was a web
+    // chat's browser mounting visibly inside the user's open splitview.
+    assert.equal(engine.modeFor('web'), 'cli');
+    assert.equal(engine.modeFor(undefined), 'cli');
     assert.equal(engine.cdpEndpoint(), '9242');
   });
 });
 
-test('entrypoint routing: stale advertisement (dead pid) means headless', () => {
+test('ownership routing: stale advertisement (dead pid) means headless', () => {
   const stateDir = tempDir('stale');
   writeAdvertisement(stateDir, {
     cdpUrl: 'ws://127.0.0.1:9242/devtools/browser/dead',
     pid: 2 ** 30, // not a real pid
   });
   withEnv({ AMALGM_RUNTIME_STATE_DIR: stateDir, AMALGM_DIR: tempDir('empty2') }, () => {
-    assert.equal(engine.mode(), 'cli');
+    assert.equal(engine.modeFor('desktop'), 'cli');
   });
 });
 
-test('entrypoint routing: AMALGM_DIR + label derives the state dir path', () => {
+test('ownership routing: AMALGM_DIR + label derives the state dir path', () => {
   const amalgmDir = tempDir('scoped');
   writeAdvertisement(path.join(amalgmDir, 'runtimes', 'main'), {
     cdpUrl: 'ws://127.0.0.1:9242/devtools/browser/scoped',
     pid: process.pid,
   });
   withEnv({ AMALGM_DIR: amalgmDir, AMALGM_RUNTIME_LABEL: 'main' }, () => {
-    assert.equal(engine.mode(), 'attached');
+    assert.equal(engine.modeFor('desktop'), 'attached');
     assert.equal(engine.cdpEndpoint(), '9242');
   });
   // A different label does not see it (branch isolation).
   withEnv({ AMALGM_DIR: amalgmDir, AMALGM_RUNTIME_LABEL: 'preview' }, () => {
-    assert.equal(engine.mode(), 'cli');
+    assert.equal(engine.modeFor('desktop'), 'cli');
+  });
+});
+
+test('ownership routing: a session home is decided at first use and sticks', () => {
+  const sessions = require('../browser/sessions');
+  const stateDir = tempDir('homes');
+  writeAdvertisement(stateDir, {
+    cdpUrl: 'ws://127.0.0.1:9242/devtools/browser/live',
+    cdpPort: 9242,
+    pid: process.pid,
+  });
+  withEnv({ AMALGM_RUNTIME_STATE_DIR: stateDir }, () => {
+    sessions.homes.clear();
+    // Desktop-born conversation: visible browser.
+    const desktopSession = sessions.sessionFor(
+      { session: 'home-desktop' },
+      { callerSessionId: 'chat-1', sessionMetadata: { client: 'desktop' } },
+    );
+    assert.equal(sessions.backendFor(desktopSession), 'attached');
+    // Web-born conversation: headless, even with the app alive.
+    const webSession = sessions.sessionFor(
+      { session: 'home-web' },
+      { callerSessionId: 'chat-2', sessionMetadata: { client: 'web' } },
+    );
+    assert.equal(sessions.backendFor(webSession), 'cli');
+    // Unstamped caller (sub-agent, automation, legacy session): headless.
+    const unstampedSession = sessions.sessionFor({ session: 'home-none' }, { callerSessionId: 'chat-3' });
+    assert.equal(sessions.backendFor(unstampedSession), 'cli');
+    // Decided at birth: a later call with different metadata does not migrate it.
+    sessions.sessionFor({ session: 'home-desktop' }, { sessionMetadata: { client: 'web' } });
+    assert.equal(sessions.backendFor(desktopSession), 'attached');
+    sessions.homes.clear();
   });
 });