@oddessentials/agent-guild 0.1.0

package/src/manager/session.mjs

@@ -0,0 +1,531 @@
+// One terminal session: a node-pty process, a headless terminal that mirrors
+// its screen (so a reconnecting client gets the current screen, not a raw
+// byte replay), and the sub-agents and model the coding tool has reported.
+
+import { EventEmitter } from 'node:events';
+import { execFile } from 'node:child_process';
+import crypto from 'node:crypto';
+import pty from 'node-pty';
+import headless from '@xterm/headless';
+import serializeAddon from '@xterm/addon-serialize';
+
+const { Terminal } = headless;
+const { SerializeAddon } = serializeAddon;
+
+export const OSC_AGENT_CODE = 7777;
+export const OSC_AGENT_PREFIX = 'agent-guild;';
+const AGENT_STATUSES = new Set(['working', 'waiting', 'idle', 'done']);
+const MODEL_SOURCE_RANK = { args: 0, screen: 1, report: 2 };
+const SCREEN_SCAN_DELAY_MS = 400;
+const SCREEN_SCAN_MAX_DELAY_MS = 2000;
+
+/**
+ * Colours reported to programs that query them (OSC 10/11/12), matching the
+ * web page's terminal theme. Tools use these to choose light or dark output.
+ */
+export const REPORTED_COLORS = { 10: '#e6e9ef', 11: '#0f1115', 12: '#e6e9ef' };
+
+function oscColor(hex) {
+  const [r, g, b] = [1, 3, 5].map((i) => hex.slice(i, i + 2));
+  return `rgb:${r}${r}/${g}${g}/${b}${b}`;
+}
+
+/** Clean a user-supplied session name: a trimmed string of at most 80 chars. */
+export function cleanName(name) {
+  return typeof name === 'string' ? name.trim().slice(0, 80) : '';
+}
+const MAX_AGENTS = 64;
+
+export function clampDimension(value, fallback, min, max) {
+  const n = Math.floor(Number(value));
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, n));
+}
+
+export class Session extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.id
+   * @param {object} opts.provider   provider description (id, vendor, tool, color, ...)
+   * @param {{file: string, args: string[]|string}} opts.spawnSpec
+   * @param {string} opts.cwd
+   * @param {object} opts.env
+   * @param {number} opts.cols
+   * @param {number} opts.rows
+   * @param {string} [opts.name]
+   * @param {string|null} [opts.resume]  id of the tool's own session being resumed
+   * @param {string|null} [opts.task]    "install" for a package install, else null
+   * @param {string} opts.reportToken
+   * @param {number} [opts.scrollback]
+   * @param {number} [opts.activityIdleMs]
+   * @param {number} [opts.doneAgentLingerMs]
+   * @param {number} [opts.killGraceMs]  time between hang-up and force kill
+   */
+  constructor(opts) {
+    super();
+    this.id = opts.id;
+    this.provider = opts.provider;
+    this.name = cleanName(opts.name) || opts.provider.tool;
+    this.resume = opts.resume ?? null;
+    this.task = opts.task ?? null;
+    this.cwd = opts.cwd;
+    this.cols = opts.cols;
+    this.rows = opts.rows;
+    this.reportToken = opts.reportToken;
+    this.scrollback = opts.scrollback ?? 5000;
+    this.activityIdleMs = opts.activityIdleMs ?? 2500;
+    this.doneAgentLingerMs = opts.doneAgentLingerMs ?? 15000;
+    this.killGraceMs = opts.killGraceMs ?? 4000;
+    this.createdAt = new Date().toISOString();
+    this.exitedAt = null;
+    this.status = 'running';
+    this.exitCode = null;
+    this.signal = null;
+    this.activity = 'quiet';
+    this.lastOutputAt = null;
+    this.agents = new Map();
+    this.model = null;
+    this.modelRegex = null;
+    if (opts.provider.modelPattern && this.task === null) {
+      try {
+        this.modelRegex = new RegExp(opts.provider.modelPattern, 'gi');
+      } catch (err) {
+        queueMicrotask(() => this.emit('warning', `ignoring modelPattern: ${err.message}`));
+      }
+    }
+    this.subscribers = new Set();
+    this._activityTimer = null;
+    this._agentTimers = new Map();
+    this._killTimer = null;
+    this._scanTimer = null;
+    this._scanDeadline = null;
+    /** Resolves when the process has exited, even after dispose(). */
+    this.exited = new Promise((resolve) => { this._resolveExited = resolve; });
+
+    this.term = new Terminal({
+      cols: this.cols,
+      rows: this.rows,
+      scrollback: this.scrollback,
+      allowProposedApi: true,
+    });
+    this.serializer = new SerializeAddon();
+    this.term.loadAddon(this.serializer);
+    this.term.parser.registerOscHandler(OSC_AGENT_CODE, (payload) => {
+      this._handleOscReport(payload);
+      return true;
+    });
+    // The mirror is the terminal of record: it answers the program's queries
+    // (cursor position, device attributes, modes, colours) exactly once,
+    // whether zero or several clients are attached. Clients must not answer.
+    this.term.onData((reply) => this._reply(reply));
+    for (const code of Object.keys(REPORTED_COLORS)) {
+      this.term.parser.registerOscHandler(Number(code), (payload) => {
+        if (payload !== '?') return false;
+        this._reply(`\x1b]${code};${oscColor(REPORTED_COLORS[code])}\x1b\\`);
+        return true;
+      });
+    }
+
+    this.disposed = false;
+    try {
+      this.pty = pty.spawn(opts.spawnSpec.file, opts.spawnSpec.args, {
+        name: 'xterm-256color',
+        cols: this.cols,
+        rows: this.rows,
+        cwd: this.cwd,
+        env: opts.env,
+        useConpty: true,
+      });
+    } catch (err) {
+      this.term.dispose();
+      throw err;
+    }
+    this.pty.onData((data) => this._onData(data));
+    this.pty.onExit(({ exitCode, signal }) => this._onExit(exitCode, signal));
+  }
+
+  /**
+   * Read live: on Windows node-pty connects the console asynchronously and
+   * reports pid 0 until then. The first output announces the session again.
+   */
+  get pid() {
+    return this.status === 'running' && !this.disposed ? this.pty.pid || null : null;
+  }
+
+  // ---- terminal I/O ------------------------------------------------------
+
+  _onData(data) {
+    if (this.disposed) return;
+    this.term.write(data);
+    this._broadcast({ type: 'data', data });
+    this.lastOutputAt = Date.now();
+    if (this.modelRegex && this.model?.source !== 'report') this._scheduleModelScan();
+    if (this.activity !== 'active') {
+      this.activity = 'active';
+      this._changed();
+    }
+    clearTimeout(this._activityTimer);
+    this._activityTimer = setTimeout(() => {
+      this.activity = 'quiet';
+      this._changed();
+    }, this.activityIdleMs);
+    this._activityTimer.unref?.();
+  }
+
+  _onExit(exitCode, signal) {
+    clearTimeout(this._killTimer);
+    this._resolveExited();
+    if (this.disposed) return;
+    this.exitedAt ??= new Date().toISOString();
+    this.status = 'exited';
+    this.exitCode = exitCode ?? null;
+    this.signal = signal || null;
+    this.activity = 'quiet';
+    clearTimeout(this._activityTimer);
+    clearTimeout(this._killTimer);
+    clearTimeout(this._scanTimer);
+    this._clearAgents();
+    // Let the headless terminal finish parsing before announcing the exit so
+    // any client attaching afterwards still sees the final screen.
+    this.term.write('', () => {
+      this._broadcast({ type: 'exit', exitCode: this.exitCode, signal: this.signal });
+      this._changed();
+      this.emit('exit', this);
+    });
+  }
+
+  _broadcast(message) {
+    for (const sub of this.subscribers) {
+      if (sub.pending) sub.pending.push(message);
+      else sub.send(message);
+    }
+  }
+
+  /**
+   * Attach a client. `send` receives protocol messages. The first message is
+   * always a `snapshot` of the current screen; output produced while the
+   * snapshot is being built is queued and delivered right after it.
+   * Returns a detach function.
+   */
+  attach(send) {
+    const sub = { send, pending: [] };
+    this.subscribers.add(sub);
+    // Everything written to the mirror before this marker is in the snapshot;
+    // everything after it is queued in sub.pending.
+    this.term.write('', () => {
+      if (!this.subscribers.has(sub)) return;
+      send({
+        type: 'snapshot',
+        data: this._serializeScreen(),
+        cols: this.term.cols,
+        rows: this.term.rows,
+        session: this.toJSON(),
+      });
+      const queued = sub.pending;
+      sub.pending = null;
+      for (const message of queued) send(message);
+      if (this.status === 'exited' && !queued.some((m) => m.type === 'exit')) {
+        send({ type: 'exit', exitCode: this.exitCode, signal: this.signal });
+      }
+    });
+    this._changed();
+    return () => {
+      if (this.subscribers.delete(sub)) this._changed();
+    };
+  }
+
+  /**
+   * The current screen as a VT stream. The serialize addon restores the
+   * buffers and most modes; cursor visibility and the mouse encoding are
+   * added here because it omits them.
+   */
+  _serializeScreen() {
+    let data = this.serializer.serialize({ scrollback: this.scrollback });
+    const core = this.term._core;
+    if (core?.coreService?.isCursorHidden) data += '\x1b[?25l';
+    const encoding = core?.coreMouseService?.activeEncoding;
+    if (encoding === 'SGR') data += '\x1b[?1006h';
+    else if (encoding === 'SGR_PIXELS') data += '\x1b[?1016h';
+    return data;
+  }
+
+  write(data) {
+    if (this.disposed || this.status !== 'running' || typeof data !== 'string' || data.length === 0) return;
+    try { this.pty.write(data); } catch { /* process is exiting */ }
+  }
+
+  _reply(data) {
+    this.write(data);
+  }
+
+  resize(cols, rows) {
+    const c = clampDimension(cols, this.cols, 2, 1000);
+    const r = clampDimension(rows, this.rows, 1, 500);
+    if (c === this.cols && r === this.rows) return;
+    this.cols = c;
+    this.rows = r;
+    this.term.resize(c, r);
+    if (this.status === 'running') {
+      try { this.pty.resize(c, r); } catch { /* process may be exiting */ }
+    }
+    this._broadcast({ type: 'resize', cols: c, rows: r });
+  }
+
+  /**
+   * End the process. On macOS and Linux: hang-up first, force after a grace
+   * period. On Windows: end the whole process tree at once. node-pty's own
+   * Windows kill first asks a helper process for the console's process list,
+   * and when that helper fails it waits a fixed five seconds.
+   */
+  kill({ graceMs = this.killGraceMs } = {}) {
+    if (this.status !== 'running') return;
+    if (process.platform === 'win32') {
+      this._killWindowsTree();
+      return;
+    }
+    const force = () => { try { this.pty.kill('SIGKILL'); } catch { /* gone */ } };
+    try { this.pty.kill('SIGHUP'); } catch { force(); }
+    clearTimeout(this._killTimer);
+    this._killTimer = setTimeout(force, graceMs);
+    this._killTimer.unref?.();
+  }
+
+  _killWindowsTree() {
+    const fallback = () => {
+      if (this.status === 'running') { try { this.pty.kill(); } catch { /* gone */ } }
+    };
+    const pid = this.pty.pid;
+    if (!pid) return fallback();
+    execFile('taskkill', ['/PID', String(pid), '/T', '/F'], { windowsHide: true, timeout: 5000 }, (err) => {
+      if (err) fallback();
+    });
+  }
+
+  /**
+   * Detach everything. A still-running process gets the normal hang-up and
+   * is force-killed after the grace period if it ignores it.
+   */
+  dispose({ graceMs } = {}) {
+    if (this.disposed) return;
+    this.kill(graceMs === undefined ? {} : { graceMs });
+    this.disposed = true;
+    clearTimeout(this._activityTimer);
+    clearTimeout(this._scanTimer);
+    for (const t of this._agentTimers.values()) clearTimeout(t);
+    this.subscribers.clear();
+    this.term.dispose();
+  }
+
+  rename(name) {
+    const clean = cleanName(name);
+    if (!clean) return;
+    this.name = clean;
+    this._changed();
+  }
+
+  // ---- sub-agents --------------------------------------------------------
+
+  /**
+   * Record a report about an agent working inside this session. `status`
+   * "done" (or `remove: true`) removes it after a short linger so the UI can
+   * show it finishing. Returns the stored agent or null when removed.
+   */
+  reportAgent(report, source = 'api') {
+    if (!report || typeof report !== 'object') throw badRequest('agent report must be an object');
+    if (this.status !== 'running') throw Object.assign(new Error('session has exited'), { status: 409 });
+    if (report.finishForeground === true && report.agentId === undefined) {
+      // The tool is between turns, so no foreground agent can still be
+      // running; one that is never got its end event.
+      for (const agent of [...this.agents.values()]) {
+        if (agent.foreground && agent.status === 'working') this.reportAgent({ agentId: agent.id, status: 'done' }, source);
+      }
+      return null;
+    }
+    const id = String(report.agentId ?? report.agent ?? report.id ?? '').trim().slice(0, 128);
+    if (!id) throw badRequest('agentId is required');
+
+    if (report.remove === true) {
+      this._removeAgent(id);
+      return null;
+    }
+    const status = report.status === undefined ? 'working' : String(report.status);
+    if (!AGENT_STATUSES.has(status)) {
+      throw badRequest(`status must be one of ${[...AGENT_STATUSES].join(', ')}`);
+    }
+    const now = new Date().toISOString();
+    const existing = this.agents.get(id);
+    // A first report that already says done would only flash an icon:
+    // Claude Code's internal helpers (prompt suggestions, side questions)
+    // stop without ever having started here.
+    if (!existing && status === 'done') return null;
+    // A repeated done (Grok Build ends a sub-agent's session after its
+    // turn) must not restart the linger.
+    if (existing?.status === 'done' && status === 'done') return existing;
+    if (!existing && this.agents.size >= MAX_AGENTS && !this._evictDoneAgent()) {
+      throw badRequest(`too many agents (max ${MAX_AGENTS})`);
+    }
+    const agent = {
+      id,
+      name: String(report.name ?? existing?.name ?? id).slice(0, 80),
+      kind: String(report.kind ?? existing?.kind ?? 'agent').slice(0, 40),
+      status,
+      detail: report.detail === undefined ? existing?.detail ?? '' : String(report.detail).slice(0, 200),
+      // The parent waits for a foreground agent, so a model reported while
+      // it works belongs to the agent, not to the session.
+      foreground: report.foreground === undefined ? existing?.foreground ?? false : report.foreground === true,
+      startedAt: existing?.startedAt ?? now,
+      updatedAt: now,
+      source,
+    };
+    this.agents.set(id, agent);
+    clearTimeout(this._agentTimers.get(id));
+    this._agentTimers.delete(id);
+    if (status === 'done') {
+      const timer = setTimeout(() => this._removeAgent(id), this.doneAgentLingerMs);
+      timer.unref?.();
+      this._agentTimers.set(id, timer);
+    }
+    this._changed();
+    return agent;
+  }
+
+  _removeAgent(id) {
+    clearTimeout(this._agentTimers.get(id));
+    this._agentTimers.delete(id);
+    if (this.agents.delete(id)) this._changed();
+  }
+
+  /** Drop the done agent that has lingered longest, to make room. */
+  _evictDoneAgent() {
+    let oldest = null;
+    for (const agent of this.agents.values()) {
+      if (agent.status === 'done' && (!oldest || agent.updatedAt < oldest.updatedAt)) oldest = agent;
+    }
+    if (!oldest) return false;
+    this._removeAgent(oldest.id);
+    return true;
+  }
+
+  _clearAgents() {
+    for (const t of this._agentTimers.values()) clearTimeout(t);
+    this._agentTimers.clear();
+    this.agents.clear();
+  }
+
+  _handleOscReport(payload) {
+    if (!payload.startsWith(OSC_AGENT_PREFIX)) return;
+    try {
+      const report = JSON.parse(payload.slice(OSC_AGENT_PREFIX.length));
+      const isAgent = report && typeof report === 'object' &&
+        ((report.agentId ?? report.agent ?? report.id) !== undefined || report.finishForeground === true);
+      if (isAgent) this.reportAgent(report, 'terminal');
+      else this.reportModel(report);
+    } catch (err) {
+      this.emit('warning', `ignored in-band report: ${err.message}`);
+    }
+  }
+
+  // ---- model -------------------------------------------------------------
+
+  /**
+   * The main model the tool says it is using. Explicit reports win over
+   * text seen on screen, which wins over a --model argument.
+   */
+  setModel({ name, displayName = null }, source) {
+    if (this.model && MODEL_SOURCE_RANK[this.model.source] > MODEL_SOURCE_RANK[source]) return;
+    const current = this.model;
+    if (current && current.name === name && current.displayName === displayName && current.source === source) return;
+    this.model = { name, displayName, source };
+    this._changed();
+  }
+
+  reportModel(report) {
+    if (!report || typeof report !== 'object') throw badRequest('model report must be an object');
+    if (this.status !== 'running') throw Object.assign(new Error('session has exited'), { status: 409 });
+    const name = String(report.model ?? '').trim().slice(0, 120);
+    if (!name) throw badRequest('model is required');
+    const displayName = report.displayName === undefined || report.displayName === null ? null : String(report.displayName).trim().slice(0, 80) || null;
+    // Gemini CLI fires BeforeModel for a sub-agent's requests too, with the
+    // sub-agent's model and nothing to tell them apart. While a foreground
+    // agent works its parent makes no request, so the report is the agent's.
+    if (this._foregroundAgentWorking()) return this.model;
+    this.setModel({ name, displayName }, 'report');
+    return this.model;
+  }
+
+  _foregroundAgentWorking() {
+    for (const agent of this.agents.values()) {
+      if (agent.foreground && agent.status === 'working') return true;
+    }
+    return false;
+  }
+
+  /**
+   * Scan shortly after output pauses, and at least every couple of seconds
+   * while output keeps coming, so a busy tool still gets scanned.
+   */
+  _scheduleModelScan() {
+    const now = Date.now();
+    this._scanDeadline ??= now + SCREEN_SCAN_MAX_DELAY_MS;
+    clearTimeout(this._scanTimer);
+    const delay = Math.max(0, Math.min(SCREEN_SCAN_DELAY_MS, this._scanDeadline - now));
+    this._scanTimer = setTimeout(() => this._scanScreenForModel(), delay);
+    this._scanTimer.unref?.();
+  }
+
+  _scanScreenForModel() {
+    this._scanDeadline = null;
+    if (this.disposed || !this.modelRegex || this.model?.source === 'report') return;
+    const buffer = this.term.buffer.active;
+    const lines = [];
+    for (let y = 0; y < this.term.rows; y++) lines.push(buffer.getLine(buffer.baseY + y)?.translateToString(true) ?? '');
+    let last = null;
+    for (const match of lines.join('\n').matchAll(this.modelRegex)) last = match[0];
+    if (last) this.setModel({ name: last.replace(/[.,;:)]+$/, '') }, 'screen');
+  }
+
+  // ---- state -------------------------------------------------------------
+
+  _changed() {
+    this.emit('changed', this);
+  }
+
+  toJSON() {
+    return {
+      id: this.id,
+      name: this.name,
+      provider: {
+        id: this.provider.id,
+        vendor: this.provider.vendor,
+        tool: this.provider.tool,
+        color: this.provider.color,
+        monogram: this.provider.monogram,
+        iconUrl: this.provider.iconUrl,
+      },
+      cwd: this.cwd,
+      resume: this.resume,
+      task: this.task,
+      pid: this.pid,
+      status: this.status,
+      exitCode: this.exitCode,
+      signal: this.signal,
+      activity: this.activity,
+      lastOutputAt: this.lastOutputAt ? new Date(this.lastOutputAt).toISOString() : null,
+      createdAt: this.createdAt,
+      exitedAt: this.exitedAt,
+      cols: this.cols,
+      rows: this.rows,
+      attachedClients: this.subscribers.size,
+      model: this.model,
+      agents: [...this.agents.values()],
+    };
+  }
+}
+
+function badRequest(message) {
+  return Object.assign(new Error(message), { status: 400 });
+}
+
+export function newId(bytes = 6) {
+  return crypto.randomBytes(bytes).toString('hex');
+}

package/src/manager/shell-env.mjs

@@ -0,0 +1,150 @@
+// Recover the user's real PATH on macOS and Linux.
+//
+// An app started from Finder, the Dock, or a login item does not inherit the
+// PATH that the user's shell profile builds (Homebrew, nvm, ~/.local/bin, ...),
+// which is exactly where CLI coding tools usually live. Like VS Code, we ask
+// the user's login shell for its PATH and merge it in.
+
+import { execFile, spawn, spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+const START = '__AGENT_GUILD_PATH_START__';
+const END = '__AGENT_GUILD_PATH_END__';
+
+export function mergePathLists(primary, secondary, delimiter = path.delimiter) {
+  const seen = new Set();
+  const out = [];
+  for (const list of [primary, secondary]) {
+    for (const entry of (list || '').split(delimiter)) {
+      if (!entry || seen.has(entry)) continue;
+      seen.add(entry);
+      out.push(entry);
+    }
+  }
+  return out.join(delimiter);
+}
+
+/** Pull PATH out of `env` output captured between the two markers. */
+export function parsePathFromEnvOutput(stdout) {
+  if (typeof stdout !== 'string') return null;
+  const start = stdout.indexOf(START);
+  const end = stdout.indexOf(END, start);
+  if (start === -1 || end === -1) return null;
+  const line = stdout.slice(start + START.length, end).split(/\r?\n/).find((l) => l.startsWith('PATH='));
+  return line ? line.slice('PATH='.length) : null;
+}
+
+export function loginShellPath({ shell = process.env.SHELL, timeoutMs = 8000 } = {}) {
+  if (process.platform === 'win32' || !shell) return null;
+  // Read the exported PATH from `env` rather than expanding $PATH: fish, for
+  // one, expands "$PATH" to a space-separated list.
+  const result = spawnSync(shell, ['-l', '-i', '-c', `printf '%s' ${START}; command env; printf '%s' ${END}`], {
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    env: { ...process.env, AGENT_GUILD_RESOLVING_ENV: '1' },
+  });
+  if (result.error) return null;
+  return parsePathFromEnvOutput(result.stdout);
+}
+
+/**
+ * Returns a copy of process.env whose PATH also contains the login shell's
+ * PATH entries. Set AGENT_GUILD_SKIP_SHELL_ENV=1 to disable the lookup.
+ */
+export function trimPathExt(env, platform = process.platform) {
+  if (platform !== 'win32') return env;
+  const key = Object.keys(env).find((k) => k.toUpperCase() === 'PATHEXT');
+  if (key) env[key] = env[key].split(';').map((ext) => ext.trim()).filter(Boolean).join(';');
+  return env;
+}
+
+export function resolveBaseEnv() {
+  const env = trimPathExt({ ...process.env });
+  if (process.env.AGENT_GUILD_SKIP_SHELL_ENV === '1') return env;
+  const shellPath = loginShellPath();
+  if (shellPath) env.PATH = mergePathLists(shellPath, env.PATH);
+  return env;
+}
+
+export function weavePaths(current, discovered, { delimiter = path.delimiter, caseInsensitive = process.platform === 'win32' } = {}) {
+  const id = (entry) => (caseInsensitive ? entry.toLowerCase() : entry).replace(/(?<=.)[\\/]+$/, '');
+  const unique = (list) => {
+    const seen = new Set();
+    return (list || '').split(delimiter).filter((entry) => entry && !seen.has(id(entry)) && seen.add(id(entry)));
+  };
+  const out = unique(current);
+  const fresh = unique(discovered);
+  const indexOf = (entry) => out.findIndex((e) => id(e) === id(entry));
+  fresh.forEach((entry, i) => {
+    if (indexOf(entry) !== -1) return;
+    for (let j = i - 1; j >= 0; j--) {
+      const at = indexOf(fresh[j]);
+      if (at !== -1) return void out.splice(at + 1, 0, entry);
+    }
+    for (let j = i + 1; j < fresh.length; j++) {
+      const at = indexOf(fresh[j]);
+      if (at !== -1) return void out.splice(at, 0, entry);
+    }
+    out.push(entry);
+  });
+  return out.join(delimiter);
+}
+
+export function parseRegValue(stdout, name = 'Path') {
+  const pattern = new RegExp(`^\\s+${name}\\s+REG_(?:EXPAND_)?SZ\\s+(.*)$`, 'i');
+  for (const line of String(stdout || '').split(/\r?\n/)) {
+    const match = line.match(pattern);
+    if (match) return match[1].trim();
+  }
+  return null;
+}
+
+export function expandWindowsVars(value, env) {
+  return value.replace(/%([^%;]+)%/g, (whole, name) => {
+    const key = Object.keys(env).find((k) => k.toUpperCase() === name.toUpperCase());
+    return key ? env[key] : whole;
+  });
+}
+
+function queryRegistry(key, env, timeoutMs) {
+  const system32 = path.win32.join(env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows', 'System32');
+  return new Promise((resolve) => {
+    execFile(path.win32.join(system32, 'reg.exe'), ['query', key, '/v', 'Path'], { timeout: timeoutMs, windowsHide: true }, (err, stdout) => {
+      resolve(err ? null : stdout);
+    });
+  });
+}
+
+export async function readWindowsPath({ env = process.env, timeoutMs = 5000, query = queryRegistry } = {}) {
+  const machine = parseRegValue(await query('HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment', env, timeoutMs));
+  if (!machine) return null;
+  const user = parseRegValue(await query('HKCU\\Environment', env, timeoutMs));
+  return [machine, user].filter(Boolean).map((value) => expandWindowsVars(value, env)).join(';');
+}
+
+export function readLoginShellPath({ shell = process.env.SHELL, timeoutMs = 8000 } = {}) {
+  if (!shell) return Promise.resolve(null);
+  return new Promise((resolve) => {
+    let stdout = '';
+    let child;
+    try {
+      child = spawn(shell, ['-l', '-i', '-c', `printf '%s' ${START}; command env; printf '%s' ${END}`], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        env: { ...process.env, AGENT_GUILD_RESOLVING_ENV: '1' },
+      });
+    } catch {
+      return resolve(null);
+    }
+    const timer = setTimeout(() => { child.kill(); resolve(null); }, timeoutMs);
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.on('error', () => { clearTimeout(timer); resolve(null); });
+    child.on('close', () => { clearTimeout(timer); resolve(parsePathFromEnvOutput(stdout)); });
+  });
+}
+
+export function pathReader(platform = process.platform, env = process.env) {
+  if (env.AGENT_GUILD_SKIP_SHELL_ENV === '1') return null;
+  return platform === 'win32' ? () => readWindowsPath({ env }) : () => readLoginShellPath({ shell: env.SHELL });
+}