inject-steer 0.0.0-stage → 0.1.0

package/src/core/queue.js

@@ -0,0 +1,56 @@
+// In-memory message queue owned by the wrapper process.
+//
+// Node runs the socket handlers one at a time, so a claim is atomic: when the
+// agent fires several hooks at once (parallel tool calls), exactly one of them
+// receives a given message.
+
+import { setFlag } from './session.js';
+
+let nextId = 1;
+
+export class Queue {
+  /** @param {string} dir session directory whose flag files mirror the queue */
+  constructor(dir) {
+    this.dir = dir;
+    /** @type {{id:number,text:string,urgency:'normal'|'urgent',queuedAt:string}[]} */
+    this.items = [];
+  }
+
+  add(text, urgency) {
+    const msg = { id: nextId++, text, urgency, queuedAt: new Date().toISOString() };
+    this.items.push(msg);
+    this.syncFlags();
+    return msg;
+  }
+
+  /**
+   * 'before-tool': if any urgent message is queued, take everything (the tool
+   *   call is about to be denied, so pending notes ride along with the reason).
+   *   Otherwise take nothing.
+   * 'after-tool': take the normal notes; urgent messages wait for the next
+   *   tool call so they can block it.
+   */
+  claim(boundary) {
+    let taken;
+    if (boundary === 'before-tool') {
+      taken = this.items.some((m) => m.urgency === 'urgent') ? this.items : [];
+    } else {
+      taken = this.items.filter((m) => m.urgency === 'normal');
+    }
+    if (taken.length) {
+      const ids = new Set(taken.map((m) => m.id));
+      this.items = this.items.filter((m) => !ids.has(m.id));
+      this.syncFlags();
+    }
+    return taken;
+  }
+
+  get size() {
+    return this.items.length;
+  }
+
+  syncFlags() {
+    setFlag(this.dir, 'normal', this.items.some((m) => m.urgency === 'normal'));
+    setFlag(this.dir, 'urgent', this.items.some((m) => m.urgency === 'urgent'));
+  }
+}

package/src/core/session.js

@@ -0,0 +1,50 @@
+// Per-session runtime directory shared by the wrapper and the agent's hooks.
+//
+// The wrapper creates the directory, listens on <dir>/sock and passes the path
+// to the agent through the INJECT_DIR environment variable. Hooks inherit the
+// agent's environment, so each hook knows which wrapper (terminal) it belongs to.
+//
+// Two empty flag files mirror the queue so a hook can skip starting Node when
+// there is nothing to deliver:
+//   <dir>/normal  exists while at least one normal note is queued
+//   <dir>/urgent  exists while at least one urgent message is queued
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const ENV_DIR = 'INJECT_DIR';
+export const ENV_NODE = 'INJECT_NODE';
+
+export function createSessionDir() {
+  // XDG_RUNTIME_DIR is per-user and private on most Linux systems; macOS has
+  // a per-user TMPDIR. mkdtemp creates the directory with mode 0700.
+  const base = process.env.XDG_RUNTIME_DIR || os.tmpdir();
+  return fs.mkdtempSync(path.join(base, 'inject-'));
+}
+
+export function socketPath(dir) {
+  return path.join(dir, 'sock');
+}
+
+export function flagPath(dir, urgency) {
+  return path.join(dir, urgency === 'urgent' ? 'urgent' : 'normal');
+}
+
+export function setFlag(dir, urgency, on) {
+  const file = flagPath(dir, urgency);
+  try {
+    if (on) fs.writeFileSync(file, '');
+    else fs.rmSync(file, { force: true });
+  } catch {
+    // The directory may already be gone during shutdown.
+  }
+}
+
+export function removeSessionDir(dir) {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // Best effort.
+  }
+}

package/src/wrapper/intercept.js

@@ -0,0 +1,349 @@
+// Keystroke interceptor. Pure logic, no I/O: feed() takes raw terminal input
+// and returns what to forward to the agent plus UI events.
+//
+// The agent never sees "/inject ..." lines. To make that work without seeing
+// the agent's input box, we keep a shadow copy of what the user typed since the
+// last submit. When that copy is empty and the user starts typing a prefix of
+// "/inject " or "/inject! ", we hold the keys back. If the prefix completes we
+// switch to capture mode; if it diverges ("/init") we forward the held keys
+// unchanged, so the agent sees exactly what was typed.
+//
+// Cursor keys, tab completion and other editing we can't model make the shadow
+// copy unknown; detection then pauses until the next Enter or Ctrl+C. Things
+// the terminal reports on its own (focus changes, mouse, replies to the
+// agent's queries) are forwarded without affecting detection.
+
+export const TRIGGERS = [
+  { prefix: '/inject! ', urgency: 'urgent' },
+  { prefix: '/inject ', urgency: 'normal' },
+];
+const BARE_WORDS = ['/inject', '/inject!'];
+
+const PASTE_START = '\x1b[200~';
+const PASTE_END = '\x1b[201~';
+
+// ---------------------------------------------------------------------------
+// Tokenizer
+
+/**
+ * @typedef {{kind:'char', ch:string, raw:string}
+ *   | {kind:'key', key:string, raw:string}
+ *   | {kind:'paste', text:string, raw:string}
+ *   | {kind:'report', raw:string}
+ *   | {kind:'other', raw:string}} Token
+ */
+
+// Keys reported through the kitty keyboard protocol (CSI <code>;<mods> u) or
+// xterm modifyOtherKeys (CSI 27;<mods>;<code> ~), which terminals use when the
+// agent turns them on.
+function decodeModifiedKey(code, mods) {
+  const m = (mods || 1) - 1; // bit 0 shift, bit 2 ctrl
+  const shift = m & 1;
+  const ctrl = m & 4;
+  if (code === 13) return shift || ctrl ? 'newline' : m === 0 ? 'enter' : null;
+  if (code === 27 && m === 0) return 'escape';
+  if (code === 127 || code === 8) return m === 0 ? 'backspace' : null;
+  if (ctrl && (code === 99 || code === 67)) return 'ctrl-c';
+  if (ctrl && (code === 117 || code === 85)) return 'ctrl-u';
+  return null;
+}
+
+function keyForControl(ch) {
+  switch (ch) {
+    case '\r': return 'enter';
+    case '\n': return 'newline';
+    case '\x7f':
+    case '\b': return 'backspace';
+    case '\x03': return 'ctrl-c';
+    case '\x15': return 'ctrl-u';
+    default: return null;
+  }
+}
+
+class Tokenizer {
+  constructor() {
+    this.paste = null; // accumulated paste text while inside a bracketed paste
+  }
+
+  /** @returns {Token[]} */
+  tokens(data) {
+    const out = [];
+    let i = 0;
+    while (i < data.length) {
+      if (this.paste !== null) {
+        const end = data.indexOf(PASTE_END, i);
+        if (end === -1) {
+          this.paste += data.slice(i);
+          break;
+        }
+        const text = this.paste + data.slice(i, end);
+        this.paste = null;
+        out.push({ kind: 'paste', text, raw: PASTE_START + text + PASTE_END });
+        i = end + PASTE_END.length;
+        continue;
+      }
+      if (data.startsWith(PASTE_START, i)) {
+        this.paste = '';
+        i += PASTE_START.length;
+        continue;
+      }
+      const ch = data[i];
+      if (ch === '\x1b') {
+        const len = escapeLength(data, i);
+        const raw = data.slice(i, i + len);
+        out.push(classifyEscape(raw));
+        i += len;
+        continue;
+      }
+      const cp = data.codePointAt(i);
+      const s = String.fromCodePoint(cp);
+      i += s.length;
+      const key = keyForControl(s);
+      if (key) out.push({ kind: 'key', key, raw: s });
+      else if (cp < 0x20) out.push({ kind: 'other', raw: s });
+      else out.push({ kind: 'char', ch: s, raw: s });
+    }
+    return out;
+  }
+}
+
+function escapeLength(data, i) {
+  const next = data[i + 1];
+  if (next === undefined) return 1; // lone Esc
+  if (next === '[') {
+    let j = i + 2;
+    while (j < data.length) {
+      const c = data.charCodeAt(j);
+      if (c >= 0x40 && c <= 0x7e) return j - i + 1;
+      j++;
+    }
+    return data.length - i;
+  }
+  if (next === 'O') return Math.min(3, data.length - i);
+  if (next === ']' || next === 'P' || next === '_' || next === '^') {
+    // OSC / DCS / APC / PM string, ended by BEL or ST (ESC \)
+    for (let j = i + 2; j < data.length; j++) {
+      if (data[j] === '\x07') return j - i + 1;
+      if (data[j] === '\x1b' && data[j + 1] === '\\') return j - i + 2;
+    }
+    return data.length - i;
+  }
+  if (next === '\x1b') return 1; // Esc followed by another escape sequence
+  // Alt+<char>: one code point after Esc
+  return 1 + String.fromCodePoint(data.codePointAt(i + 1)).length;
+}
+
+// Input the terminal sends on its own rather than because a key was pressed.
+function isReport(raw) {
+  const intro = raw[1];
+  if (intro === ']' || intro === 'P' || intro === '_' || intro === '^') return true; // query replies
+  if (intro !== '[') return false;
+  if (raw === '\x1b[I' || raw === '\x1b[O') return true; // focus in / out
+  if (/^\x1b\[<[\d;]*[Mm]$/.test(raw)) return true; // SGR mouse
+  if (/^\x1b\[\?[\d;]*[uc]$/.test(raw)) return true; // keyboard-flags / device-attributes replies
+  if (/^\x1b\[[\d;?]*\$y$/.test(raw)) return true; // mode report
+  if (/^\x1b\[\d+;\d+R$/.test(raw)) return true; // cursor position report
+  if (/^\x1b\[\d*n$/.test(raw)) return true; // status report
+  return false;
+}
+
+// A printable character sent as an escape code (kitty protocol or
+// modifyOtherKeys), with no modifier other than Shift.
+function printable(code, mods, shifted) {
+  const m = (mods || 1) - 1;
+  if (m & ~1) return null;
+  const cp = m === 1 && shifted ? shifted : code;
+  if (cp < 0x20 || cp === 0x7f || cp > 0x10ffff) return null;
+  const ch = String.fromCodePoint(cp);
+  return m === 1 && !shifted && /^[a-z]$/.test(ch) ? ch.toUpperCase() : ch;
+}
+
+function classifyEscape(raw) {
+  if (raw === '\x1b') return { kind: 'key', key: 'escape', raw };
+  if (isReport(raw)) return { kind: 'report', raw };
+  // kitty: CSI code[:shifted[:base]] [;mods[:event]] [;text] u
+  let m = /^\x1b\[(\d+)(?::(\d*))?(?::\d*)?(?:;(\d+)(?::\d+)?)?(?:;[\d:]*)?u$/.exec(raw);
+  if (m) {
+    const code = Number(m[1]);
+    const mods = Number(m[3] || 1);
+    const key = decodeModifiedKey(code, mods);
+    if (key) return { kind: 'key', key, raw };
+    const ch = printable(code, mods, m[2] ? Number(m[2]) : 0);
+    if (ch) return { kind: 'char', ch, raw };
+  }
+  // xterm modifyOtherKeys: CSI 27 ; mods ; code ~
+  m = /^\x1b\[27;(\d+);(\d+)~$/.exec(raw);
+  if (m) {
+    const key = decodeModifiedKey(Number(m[2]), Number(m[1]));
+    if (key) return { kind: 'key', key, raw };
+    const ch = printable(Number(m[2]), 1, 0);
+    if (ch && Number(m[1]) <= 2) return { kind: 'char', ch, raw };
+  }
+  if (raw === '\x1b\r') return { kind: 'key', key: 'newline', raw }; // Alt+Enter
+  return { kind: 'other', raw };
+}
+
+function oneLine(text) {
+  return text.replace(/\r\n|\r|\n/g, ' ');
+}
+
+// ---------------------------------------------------------------------------
+// Interceptor
+
+/**
+ * @typedef {{type:'capture', urgency:string, text:string}
+ *   | {type:'submit', urgency:string, text:string}
+ *   | {type:'cancel'}
+ *   | {type:'usage'}} InterceptEvent
+ */
+
+export class Interceptor {
+  constructor() {
+    this.tokenizer = new Tokenizer();
+    /** Shadow of the agent's input since the last submit; null when unknown. */
+    this.line = '';
+    /** Keys held back because they could still become a trigger. */
+    this.heldToks = [];
+    /** @type {{urgency:string, text:string} | null} */
+    this.capture = null;
+  }
+
+  get capturing() {
+    return this.capture !== null;
+  }
+
+  get held() {
+    return this.heldToks.map((t) => (t.kind === 'paste' ? t.text : t.ch)).join('');
+  }
+
+  /** @returns {{forward:string, events:InterceptEvent[]}} */
+  feed(data) {
+    const res = { forward: '', events: [] };
+    for (const tok of this.tokenizer.tokens(data)) {
+      // Always pass terminal reports through: the agent may be waiting on them.
+      if (tok.kind === 'report') res.forward += tok.raw;
+      else if (this.capture) this.captureToken(tok, res);
+      else this.passToken(tok, res);
+    }
+    return res;
+  }
+
+  passToken(tok, res) {
+    const held = this.held;
+    if (held || this.line === '') {
+      if (tok.kind === 'char' || tok.kind === 'paste') {
+        // A pasted "/inject ..." (e.g. copied from docs) is captured just like
+        // a typed one; the rest of the paste lands in the one-line editor.
+        const cand = held + (tok.kind === 'paste' ? tok.text : tok.ch);
+        const trigger = TRIGGERS.find((t) => cand.startsWith(t.prefix));
+        if (trigger) {
+          this.heldToks = [];
+          const text = oneLine(cand.slice(trigger.prefix.length));
+          this.capture = { urgency: trigger.urgency, text };
+          res.events.push({ type: 'capture', urgency: trigger.urgency, text });
+          return;
+        }
+        if (TRIGGERS.some((t) => t.prefix.startsWith(cand))) {
+          this.heldToks.push(tok);
+          return;
+        }
+      }
+      if (held && tok.kind === 'key') {
+        if (tok.key === 'enter' && BARE_WORDS.includes(held)) {
+          this.heldToks = [];
+          res.events.push({ type: 'usage' });
+          return;
+        }
+        if (tok.key === 'backspace') {
+          const last = this.heldToks.pop();
+          if (last.kind === 'paste' && last.text.length > 1) {
+            const text = last.text.slice(0, -1);
+            this.heldToks.push({ kind: 'paste', text, raw: text });
+          }
+          return;
+        }
+        if (tok.key === 'escape' || tok.key === 'ctrl-c') {
+          // The agent never saw the held keys, so dropping them is the whole
+          // cancel. Don't forward: Esc / Ctrl+C would interrupt the agent.
+          this.heldToks = [];
+          return;
+        }
+      }
+      // Not a trigger: release the held keys exactly as they were typed.
+      for (const t of this.heldToks) {
+        res.forward += t.raw;
+        this.track(t);
+      }
+      this.heldToks = [];
+    }
+
+    res.forward += tok.raw;
+    this.track(tok);
+  }
+
+  track(tok) {
+    if (tok.kind === 'key') {
+      switch (tok.key) {
+        case 'enter':
+        case 'ctrl-c':
+        case 'ctrl-u':
+          this.line = '';
+          return;
+        case 'newline':
+          if (this.line !== null) this.line += '\n';
+          return;
+        case 'backspace':
+          if (this.line !== null) this.line = this.line.slice(0, -1);
+          return;
+        default:
+          this.line = null; // Esc may clear, recall or interrupt; we can't tell
+          return;
+      }
+    }
+    if (this.line === null) return;
+    if (tok.kind === 'char') this.line += tok.ch;
+    else if (tok.kind === 'paste') this.line += tok.text;
+    else this.line = null;
+  }
+
+  captureToken(tok, res) {
+    const c = this.capture;
+    if (tok.kind === 'char') c.text += tok.ch;
+    else if (tok.kind === 'paste') c.text += oneLine(tok.text);
+    else if (tok.kind === 'key') {
+      switch (tok.key) {
+        case 'enter': {
+          this.capture = null;
+          this.line = '';
+          const text = c.text.trim();
+          res.events.push(text ? { type: 'submit', urgency: c.urgency, text } : { type: 'cancel' });
+          return;
+        }
+        case 'newline':
+          c.text += ' ';
+          break;
+        case 'backspace':
+          if (c.text === '') return this.cancel(res);
+          c.text = Array.from(c.text).slice(0, -1).join('');
+          break;
+        case 'ctrl-u':
+          c.text = '';
+          break;
+        case 'escape':
+        case 'ctrl-c':
+          return this.cancel(res);
+        default:
+          return;
+      }
+    } else {
+      return; // cursor keys etc. are ignored in the one-line editor
+    }
+    res.events.push({ type: 'capture', urgency: c.urgency, text: c.text });
+  }
+
+  cancel(res) {
+    this.capture = null;
+    this.line = '';
+    res.events.push({ type: 'cancel' });
+  }
+}

package/src/wrapper/overlay.js

@@ -0,0 +1,158 @@
+// One-line status overlay drawn on the terminal's bottom row, on top of the
+// agent's UI. The agent repaints its screen often, so we redraw after its
+// output settles, and only when its output isn't stopped mid escape sequence.
+
+const ESC = '\x1b';
+const SAVE = `${ESC}7`;
+const RESTORE = `${ESC}8`;
+const RESET = `${ESC}[0m`;
+const LABEL = `${ESC}[1;30;46m`; // bold black on cyan
+const LABEL_URGENT = `${ESC}[1;97;41m`; // bold white on red
+const DIM = `${ESC}[2m`;
+const OK = `${ESC}[32m`;
+
+const TOAST_MS = 4000;
+
+export class Overlay {
+  /** @param {NodeJS.WriteStream} out */
+  constructor(out) {
+    this.out = out;
+    /** @type {{urgency:string,text:string}|null} */
+    this.input = null;
+    /** @type {{text:string, until:number}|null} */
+    this.toastMsg = null;
+    this.pending = 0;
+    this.visible = false;
+    this.childState = 'text';
+    this.timer = null;
+    this.toastTimer = null;
+  }
+
+  editing(urgency, text) {
+    this.input = { urgency, text };
+    this.draw();
+  }
+
+  stopEditing() {
+    this.input = null;
+    this.draw();
+  }
+
+  toast(text) {
+    this.toastMsg = { text, until: Date.now() + TOAST_MS };
+    clearTimeout(this.toastTimer);
+    this.toastTimer = setTimeout(() => {
+      this.toastMsg = null;
+      this.draw();
+    }, TOAST_MS);
+    this.toastTimer.unref?.();
+    this.draw();
+  }
+
+  setPending(n) {
+    this.pending = n;
+    this.draw();
+  }
+
+  /** Call after forwarding agent output to the terminal. */
+  afterOutput(chunk) {
+    this.childState = scanEscapeState(chunk, this.childState);
+    if (!this.visible && !this.content()) return;
+    clearTimeout(this.timer);
+    this.timer = setTimeout(() => this.draw(), 30);
+    this.timer.unref?.();
+  }
+
+  content() {
+    const cols = this.out.columns || 80;
+    if (this.input) {
+      const urgent = this.input.urgency === 'urgent';
+      const label = urgent ? `${LABEL_URGENT} inject! ${RESET}` : `${LABEL} inject ${RESET}`;
+      const hint = `${DIM}  Enter send · Esc cancel${RESET}`;
+      const room = Math.max(10, cols - 9 - 2 - 24);
+      let text = this.input.text;
+      if (text.length > room) text = '…' + text.slice(text.length - room + 1);
+      return `${label} ${text}█${hint}`;
+    }
+    if (this.toastMsg) {
+      return clip(this.toastMsg.text, cols - 1);
+    }
+    if (this.pending > 0) {
+      const pill = `${LABEL} inject ${RESET}${DIM} ${this.pending} queued · delivers at next step${RESET}`;
+      return pill;
+    }
+    return '';
+  }
+
+  draw() {
+    if (this.childState !== 'text') {
+      // Don't split the agent's escape sequence; afterOutput() retries.
+      clearTimeout(this.timer);
+      this.timer = setTimeout(() => this.draw(), 30);
+      this.timer.unref?.();
+      return;
+    }
+    const rows = this.out.rows || 24;
+    const content = this.content();
+    if (!content && !this.visible) return;
+    this.out.write(`${SAVE}${ESC}[${rows};1H${ESC}[2K${content}${RESET}${RESTORE}`);
+    this.visible = Boolean(content);
+  }
+}
+
+export function queuedToast(urgency) {
+  return urgency === 'urgent'
+    ? `${LABEL_URGENT} inject! ${RESET} queued · will block the next tool call`
+    : `${LABEL} inject ${RESET} queued · delivers at next step`;
+}
+
+export function deliveredToast(count, urgent, doing) {
+  const what = urgent ? 'blocked the tool call and delivered' : 'delivered';
+  const n = count === 1 ? '' : ` ${count} messages`;
+  const where = doing ? `${DIM} (${doing})${RESET}` : '';
+  return `${OK}✓${RESET} inject: ${what}${n}${where}`;
+}
+
+export function usageToast() {
+  return `${LABEL} inject ${RESET} usage: /inject <note>   ·   /inject! <urgent: blocks the next tool call>`;
+}
+
+// Strip SGR codes for length math; content is short so a rough clip is fine.
+function clip(s, max) {
+  const plain = s.replace(/\x1b\[[0-9;]*m/g, '');
+  if (plain.length <= max) return s;
+  return plain.slice(0, Math.max(0, max - 1)) + '…';
+}
+
+/**
+ * Tracks whether the agent's output stream is inside an escape sequence, so
+ * the overlay never writes into the middle of one. Pass the returned state
+ * back in with the next chunk. Covers CSI, two-byte escapes, and OSC/DCS/APC
+ * strings terminated by BEL or ST.
+ */
+export function scanEscapeState(chunk, state = 'text') {
+  for (let i = 0; i < chunk.length; i++) {
+    const c = chunk.charCodeAt(i);
+    switch (state) {
+      case 'text':
+        if (c === 0x1b) state = 'esc';
+        break;
+      case 'esc':
+        if (c === 0x5b) state = 'csi'; // [
+        else if (c === 0x5d || c === 0x50 || c === 0x5f || c === 0x5e) state = 'str'; // ] P _ ^
+        else state = 'text';
+        break;
+      case 'csi':
+        if (c >= 0x40 && c <= 0x7e) state = 'text';
+        break;
+      case 'str':
+        if (c === 0x07) state = 'text';
+        else if (c === 0x1b) state = 'strEsc';
+        break;
+      case 'strEsc':
+        state = c === 0x5c ? 'text' : 'str';
+        break;
+    }
+  }
+  return state;
+}

package/src/wrapper/pty.js

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+/** Loads node-pty, repairing its macOS helper's permissions if needed. */
+export function loadPty() {
+  ensureSpawnHelperExecutable();
+  try {
+    return require('node-pty');
+  } catch (err) {
+    // Linux has no prebuilt binary; node-pty compiles at install time, which
+    // needs build tools and an install script npm may have skipped.
+    const dir = path.dirname(path.dirname(require.resolve('node-pty/package.json')));
+    throw new Error(
+      `could not load node-pty (${err.message.split('\n')[0]}).\n` +
+        `  Install build tools (python3, make, a C++ compiler), then run:\n` +
+        `  cd "${dir}/.." && npm rebuild node-pty`,
+    );
+  }
+}
+
+// npm 11 skips dependency install scripts unless approved, and node-pty's
+// postinstall is what marks its macOS prebuilt spawn-helper executable.
+function ensureSpawnHelperExecutable() {
+  if (process.platform !== 'darwin') return;
+  const root = path.dirname(require.resolve('node-pty/package.json'));
+  const candidates = [
+    path.join(root, 'prebuilds', `darwin-${process.arch}`, 'spawn-helper'),
+    path.join(root, 'build', 'Release', 'spawn-helper'),
+  ];
+  for (const file of candidates) {
+    try {
+      const { mode } = fs.statSync(file);
+      if ((mode & 0o111) === 0) fs.chmodSync(file, 0o755);
+    } catch (err) {
+      if (err.code === 'EACCES' || err.code === 'EPERM') {
+        throw new Error(`node-pty's spawn-helper is not executable and can't be fixed automatically. Run:\n  chmod +x "${file}"`);
+      }
+    }
+  }
+}