@aerode/pish 0.8.0

package/dist/hooks.js

@@ -0,0 +1,198 @@
+/**
+ * Shell hook rcfile generation.
+ *
+ * Generates a temporary rcfile that sources the user's original rc
+ * and appends pish hooks (OSC signals, FIFO, CNF handler, etc.).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+export function generateRcfile(config) {
+    // zsh needs ZDOTDIR/.zshrc; bash uses --rcfile.
+    // zsh ZDOTDIR must be a separate dir to avoid conflicts with user .zshrc.
+    const rcDir = config.shell === 'zsh'
+        ? fs.mkdtempSync(path.join(os.tmpdir(), 'pish-rc-'))
+        : config.tmpDir;
+    const rcName = config.shell === 'zsh' ? '.zshrc' : 'rc.bash';
+    const rcPath = path.join(rcDir, rcName);
+    let content;
+    if (config.shell === 'bash') {
+        content = generateBashRc(config);
+    }
+    else {
+        content = generateZshRc(config);
+    }
+    fs.writeFileSync(rcPath, content, 'utf-8');
+    return rcPath;
+}
+function generateBashRc(c) {
+    return `
+# === pish rcfile (bash) ===
+
+# 1. Source user startup files — simulate login shell sourcing order
+#    bash --rcfile is non-login: it skips /etc/profile and ~/.*profile.
+#    We source them here so PATH and env from login files take effect.
+#    Order: /etc/profile → first of ~/.bash_profile, ~/.bash_login, ~/.profile
+#    Then always source ~/.bashrc (idempotent; may already be sourced by profile).
+if [[ -z "\${PISH_NORC:-}" ]]; then
+  [[ -f /etc/profile ]] && source /etc/profile
+  if [[ -f ~/.bash_profile ]]; then
+    source ~/.bash_profile
+  elif [[ -f ~/.bash_login ]]; then
+    source ~/.bash_login
+  elif [[ -f ~/.profile ]]; then
+    source ~/.profile
+  fi
+  [[ -f ~/.bashrc ]] && source ~/.bashrc
+else
+  PS1='PISH_READY\$ '
+fi
+
+# 2. Version check — requires bash 4.4+
+if [[ "\${BASH_VERSINFO[0]}" -lt 4 || \\
+      ( "\${BASH_VERSINFO[0]}" -eq 4 && "\${BASH_VERSINFO[1]}" -lt 4 ) ]]; then
+  printf '\\033]9154;E;bash %s not supported (requires 4.4+)\\007' "$BASH_VERSION"
+  return 0 2>/dev/null || exit 0
+fi
+
+# 3. Environment
+export PISH_FIFO="${c.fifoPath}"
+
+# 4. Debug
+__pish_debug() {
+  [[ -n "\${PISH_DEBUG:-}" ]] &&
+    printf '[%s] HOOK %s\\n' "$(date +%H:%M:%S.%3N)" "$*" >> "$PISH_DEBUG"
+}
+
+# 5. D signal — precmd (non-blocking)
+__pish_precmd() {
+  local rc=$?
+  __pish_debug "precmd rc=$rc"
+  printf '\\033]9154;D;%d\\007' "$rc"
+  return "$rc"
+}
+PROMPT_COMMAND="__pish_precmd\${PROMPT_COMMAND:+;$PROMPT_COMMAND}"
+
+# 6. C signal — truncation boundary (PS0)
+PS0='$(printf "\\033]9154;C\\007")'
+
+# 7. P signal — CNF agent entry
+command_not_found_handle() {
+  __pish_debug "CNF: $*"
+  printf '\\033]9154;P;%s\\007' "$*"
+  read -r _ <&"\${PISH_RFD}"
+  return 0
+}
+
+# 8. R signal — reverse / pi command
+pi() {
+  if [[ $# -eq 0 ]]; then
+    __pish_debug "reverse"
+    printf '\\033]9154;R\\007'
+    local sig
+    read -r sig <&"\${PISH_RFD}"
+    local session="\${sig#SESSION:}"
+    if [[ -n "$session" ]]; then
+      command pi --session "$session"
+    else
+      command pi
+    fi
+  else
+    command pi "$@"
+  fi
+}
+
+# 9. Control commands
+/compact()  { local a; [[ $# -gt 0 ]] && a=" $*" || a=""; printf '\\033]9154;P;/compact%s\\007' "$a";  read -r _ <&"\${PISH_RFD}"; }
+/model()    { local a; [[ $# -gt 0 ]] && a=" $*" || a=""; printf '\\033]9154;P;/model%s\\007' "$a";    read -r _ <&"\${PISH_RFD}"; }
+/think()    { local a; [[ $# -gt 0 ]] && a=" $*" || a=""; printf '\\033]9154;P;/think%s\\007' "$a";    read -r _ <&"\${PISH_RFD}"; }
+
+# 10. Open FIFO fd + send S signal
+exec {PISH_RFD}<>"${c.fifoPath}"
+export PISH_RFD
+__pish_debug "shell ready, fd=\${PISH_RFD}"
+printf '\\033]9154;S\\007'
+`;
+}
+function generateZshRc(c) {
+    return `
+# === pish rcfile (zsh) ===
+
+# 0. Restore ZDOTDIR (we temporarily set it to load this .zshrc)
+[[ -n "\${__PISH_ORIG_ZDOTDIR+x}" ]] && ZDOTDIR="\$__PISH_ORIG_ZDOTDIR" || unset ZDOTDIR
+
+# 1. Source user startup files — simulate login shell sourcing order
+#    pish starts zsh -i (non-login) with ZDOTDIR override, which skips:
+#    - ~/.zshenv (ZDOTDIR changed, zsh read $ZDOTDIR/.zshenv instead)
+#    - /etc/zprofile, ~/.zprofile (login-only)
+#    - /etc/zshrc (ZDOTDIR override)
+#    On macOS this is critical: /etc/zprofile runs path_helper,
+#    and ~/.zprofile often has Homebrew PATH setup.
+if [[ -z "\${PISH_NORC:-}" ]]; then
+  [[ -f ~/.zshenv ]]    && source ~/.zshenv
+  [[ -f /etc/zprofile ]]     && source /etc/zprofile
+  [[ -f /etc/zsh/zprofile ]] && source /etc/zsh/zprofile
+  [[ -f ~/.zprofile ]]       && source ~/.zprofile
+  [[ -f ~/.zshrc ]]          && source ~/.zshrc
+else
+  PS1='PISH_READY%% '
+fi
+
+# 2. Version check — requires zsh 5.0+
+if [[ "\${ZSH_VERSION%%.*}" -lt 5 ]]; then
+  printf '\\033]9154;E;zsh %s not supported (requires 5.0+)\\007' "$ZSH_VERSION"
+  return 0
+fi
+
+# 3. Environment
+export PISH_FIFO="${c.fifoPath}"
+
+# 4. D signal — precmd (non-blocking)
+__pish_precmd() {
+  local rc=$?
+  printf '\\033]9154;D;%d\\007' "$rc"
+  return "$rc"
+}
+precmd_functions+=(__pish_precmd)
+
+# 5. C signal — preexec
+__pish_preexec() {
+  printf '\\033]9154;C\\007'
+}
+preexec_functions+=(__pish_preexec)
+
+# 6. P signal — CNF
+command_not_found_handler() {
+  printf '\\033]9154;P;%s\\007' "$*"
+  read -r _ <&"\${PISH_RFD}"
+  return 0
+}
+
+# 7. R signal — reverse / pi command
+pi() {
+  if [[ $# -eq 0 ]]; then
+    printf '\\033]9154;R\\007'
+    local sig
+    read -r sig <&"\${PISH_RFD}"
+    local session="\${sig#SESSION:}"
+    if [[ -n "$session" ]]; then
+      command pi --session "$session"
+    else
+      command pi
+    fi
+  else
+    command pi "$@"
+  fi
+}
+
+# 8. Control commands
+/compact()  { local a; [[ $# -gt 0 ]] && a=" $*" || a=""; printf '\\033]9154;P;/compact%s\\007' "$a";  read -r _ <&"\${PISH_RFD}"; }
+/model()    { local a; [[ $# -gt 0 ]] && a=" $*" || a=""; printf '\\033]9154;P;/model%s\\007' "$a";    read -r _ <&"\${PISH_RFD}"; }
+/think()    { local a; [[ $# -gt 0 ]] && a=" $*" || a=""; printf '\\033]9154;P;/think%s\\007' "$a";    read -r _ <&"\${PISH_RFD}"; }
+
+# 9. Open FIFO fd + send S signal
+exec {PISH_RFD}<>"${c.fifoPath}"
+export PISH_RFD
+printf '\\033]9154;S\\007'
+`;
+}

package/dist/log.js

@@ -0,0 +1,49 @@
+/**
+ * Structured JSON event log.
+ *
+ * Controlled by PISH_LOG env var:
+ *   unset          → no output
+ *   "1" | "stderr" → stderr
+ *   file path      → append to file
+ */
+import * as fs from 'node:fs';
+let logFd = null;
+let logToStderr = false;
+export function initLog() {
+    const target = process.env.PISH_LOG;
+    if (!target)
+        return;
+    if (target === '1' || target === 'stderr') {
+        logToStderr = true;
+    }
+    else {
+        logFd = fs.openSync(target, 'a');
+    }
+}
+export function closeLog() {
+    if (logFd !== null) {
+        try {
+            fs.closeSync(logFd);
+        }
+        catch {
+            /* fd may already be closed */
+        }
+        logFd = null;
+    }
+}
+export function log(event, fields) {
+    if (!logToStderr && logFd === null)
+        return;
+    const entry = {
+        ts: new Date().toISOString(),
+        event,
+        ...fields,
+    };
+    const line = `${JSON.stringify(entry)}\n`;
+    if (logToStderr) {
+        process.stderr.write(line);
+    }
+    if (logFd !== null) {
+        fs.writeSync(logFd, line);
+    }
+}

package/dist/main.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * pish — Pi-Integrated Shell.
+ *
+ * Entry point: bootstrap resources, wire I/O, delegate to App.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as pty from 'node-pty';
+import { AgentManager } from './agent.js';
+import { App } from './app.js';
+import { loadConfig } from './config.js';
+import { generateRcfile } from './hooks.js';
+import { initLog, log } from './log.js';
+import { Recorder } from './recorder.js';
+// ═══════════════════════════════════════
+// Nesting detection
+// ═══════════════════════════════════════
+if (process.env.PISH_PID) {
+    process.stderr.write('\x1b[31mpish: already running (nested launch blocked)\x1b[0m\n');
+    process.exit(1);
+}
+// ═══════════════════════════════════════
+// Bootstrap
+// ═══════════════════════════════════════
+const cfg = loadConfig();
+initLog();
+// ── Infrastructure ──
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pish-'));
+const fifoPath = path.join(tmpDir, 'fifo');
+execFileSync('mkfifo', [fifoPath]);
+const rcPath = generateRcfile({ shell: cfg.shell, fifoPath, tmpDir });
+// ── Objects ──
+const recorder = new Recorder({
+    maxContext: cfg.maxContext,
+    truncate: {
+        headLines: cfg.headLines,
+        tailLines: cfg.tailLines,
+        maxLineWidth: cfg.lineWidth,
+    },
+});
+const agent = new AgentManager(cfg.piPath);
+// ── PTY ──
+const shellArgs = cfg.shell === 'bash' ? ['--rcfile', rcPath, '-i'] : ['-i'];
+const env = {
+    ...process.env,
+    PISH_PID: String(process.pid),
+};
+if (cfg.shell === 'zsh') {
+    if (process.env.ZDOTDIR !== undefined) {
+        env.__PISH_ORIG_ZDOTDIR = process.env.ZDOTDIR;
+    }
+    env.ZDOTDIR = path.dirname(rcPath);
+}
+const ptyProcess = pty.spawn(cfg.shellPath, shellArgs, {
+    name: 'xterm-256color',
+    cols: process.stdout.columns || 120,
+    rows: process.stdout.rows || 30,
+    cwd: process.cwd(),
+    env,
+});
+log('start', { shell: cfg.shell, pid: ptyProcess.pid });
+// ═══════════════════════════════════════
+// App + wiring
+// ═══════════════════════════════════════
+const app = new App({ cfg, pty: ptyProcess, recorder, agent }, { fifoPath, tmpDir, rcPath });
+ptyProcess.onData((data) => app.onPtyData(data));
+ptyProcess.onExit(({ exitCode }) => app.onPtyExit(exitCode ?? 0));
+process.stdin.setRawMode?.(true);
+process.stdin.resume();
+process.stdin.on('data', (data) => app.onStdin(data));
+process.stdout.on('resize', () => {
+    app.onResize(process.stdout.columns || 120, process.stdout.rows || 30);
+});
+// ═══════════════════════════════════════
+// Signals
+// ═══════════════════════════════════════
+const quit = () => {
+    app.cleanup();
+    process.exit(0);
+};
+process.on('SIGTERM', quit);
+process.on('SIGHUP', quit);
+process.on('SIGINT', quit);
+process.on('unhandledRejection', (err) => {
+    log('unhandled_rejection', { error: String(err) });
+});

package/dist/osc.js

@@ -0,0 +1,157 @@
+/**
+ * OSC 9154 signal parser.
+ *
+ * Strips OSC 9154 sequences from PTY data, extracts signals,
+ * and returns clean data with signal positions.
+ *
+ * Handles cross-chunk splitting: if a partial OSC sequence is at the
+ * end of a chunk, it is buffered and completed on the next feed().
+ *
+ * Format:
+ *   ESC ] 9154 ; <payload> BEL      (BEL = 0x07)
+ *   ESC ] 9154 ; <payload> ESC \    (ST = ESC 0x5c)
+ */
+// Maximum length of a buffered partial OSC before we give up and flush it.
+// OSC 9154 payloads are short (longest: P;cmd, cmd < 4096 chars).
+const MAX_PARTIAL = 8192;
+// Full OSC 9154 regex — matches complete sequences.
+const OSC_RE = /\x1b\]9154;([^\x07\x1b]*?)(?:\x07|\x1b\\)/g;
+// Detects a potential partial OSC 9154 at end of string.
+// Matches any prefix of: ESC ] 9 1 5 4 ; <payload> <terminator>
+// We check if the string ends with an incomplete ESC sequence that could
+// become a valid OSC 9154.
+const OSC_PREFIX = '\x1b]9154;';
+/**
+ * Stateful OSC 9154 parser. Maintains a residual buffer for partial
+ * sequences that span chunk boundaries.
+ */
+export class OscParser {
+    /** Buffered partial OSC sequence from previous feed(). */
+    partial = '';
+    /**
+     * Feed raw PTY data. Returns clean data (OSC stripped) and signals.
+     */
+    feed(data) {
+        let input;
+        if (this.partial) {
+            input = this.partial + data;
+            this.partial = '';
+        }
+        else {
+            input = data;
+        }
+        // Check for partial OSC at end of input
+        const tailStart = this.findPartialTail(input);
+        let processable;
+        if (tailStart >= 0) {
+            this.partial = input.slice(tailStart);
+            processable = input.slice(0, tailStart);
+            // Safety: if partial grows too large, it's not a real OSC — flush it
+            if (this.partial.length > MAX_PARTIAL) {
+                processable += this.partial;
+                this.partial = '';
+            }
+        }
+        else {
+            processable = input;
+        }
+        return parseOsc(processable);
+    }
+    /**
+     * Find the start of a potential partial OSC 9154 at the end of the string.
+     * Returns the index, or -1 if no partial is found.
+     *
+     * Scans backward through all ESC positions to find an unterminated
+     * OSC 9154 prefix. An ESC is "unterminated" if from that ESC to the
+     * end of string there is no BEL and no ST (ESC \\).
+     */
+    findPartialTail(data) {
+        // Scan backward for ESC characters, find the earliest unterminated one
+        let candidate = -1;
+        for (let i = data.length - 1; i >= 0; i--) {
+            if (data[i] !== '\x1b')
+                continue;
+            const tail = data.slice(i);
+            // Check if this ESC starts a valid OSC 9154 prefix
+            if (!this.isOscPrefix(tail))
+                continue;
+            // Check if it's already terminated (BEL or ST after the opening ESC)
+            const hasBel = tail.indexOf('\x07') >= 0;
+            // ST = ESC \\ — look for \x1b\\ after position 1 (skip the leading ESC itself)
+            let hasSt = false;
+            for (let j = 1; j < tail.length - 1; j++) {
+                if (tail[j] === '\x1b' && tail[j + 1] === '\\') {
+                    hasSt = true;
+                    break;
+                }
+            }
+            if (hasBel || hasSt) {
+                // Terminated — regex will handle it. Stop scanning: anything
+                // before a terminated sequence cannot be a partial tail.
+                break;
+            }
+            // Unterminated — record as candidate and keep scanning backward
+            // to find the earliest one (the real start of the partial).
+            candidate = i;
+        }
+        return candidate;
+    }
+    /**
+     * Check if `s` is a valid prefix of an OSC 9154 sequence.
+     * Valid prefixes: \x1b, \x1b], \x1b]9, \x1b]91, \x1b]915, \x1b]9154,
+     * \x1b]9154;, \x1b]9154;<payload...>
+     */
+    isOscPrefix(s) {
+        // Must start with ESC
+        if (s[0] !== '\x1b')
+            return false;
+        if (s.length === 1)
+            return true; // just ESC — could become ESC]...
+        // After ESC must be ]
+        if (s[1] !== ']')
+            return false;
+        if (s.length === 2)
+            return true;
+        // Check that chars 2..6 match "9154;" prefix
+        for (let i = 2; i < s.length && i < OSC_PREFIX.length; i++) {
+            if (s[i] !== OSC_PREFIX[i])
+                return false;
+        }
+        // If we've passed the full prefix, it's payload (waiting for terminator)
+        return true;
+    }
+}
+/** Stateless parse of a complete data chunk (no partial handling). */
+export function parseOsc(data) {
+    const signals = [];
+    let cleanOffset = 0;
+    let lastIndex = 0;
+    const clean = data.replace(OSC_RE, (match, payload, offset) => {
+        cleanOffset += offset - lastIndex;
+        lastIndex = offset + match.length;
+        const sig = parsePayload(payload);
+        if (sig)
+            signals.push({ signal: sig, cleanOffset });
+        return '';
+    });
+    return { clean, signals };
+}
+function parsePayload(payload) {
+    if (payload === 'S')
+        return { type: 'S' };
+    if (payload === 'C')
+        return { type: 'C' };
+    if (payload === 'R')
+        return { type: 'R' };
+    if (payload.startsWith('D;')) {
+        const rc = parseInt(payload.slice(2), 10);
+        return { type: 'D', rc: Number.isNaN(rc) ? 0 : rc };
+    }
+    if (payload.startsWith('P;')) {
+        return { type: 'P', cmd: payload.slice(2) };
+    }
+    if (payload.startsWith('E;')) {
+        return { type: 'E', msg: payload.slice(2) };
+    }
+    return null;
+}

package/dist/recorder.js

@@ -0,0 +1,177 @@
+/**
+ * Recorder — extracts context entries from the PTY stream.
+ *
+ * Core idea:
+ * - Continuously appends PTY data to a buffer.
+ * - C signal marks the prompt/output boundary.
+ * - D signal triggers commit or discard.
+ * - Buffer is not cleared on signal; instead, segment start/end offsets are tracked.
+ */
+import { log } from './log.js';
+import { OscParser } from './osc.js';
+import { DEFAULT_TRUNCATE, isAltScreen, stripAnsi, truncateLines, } from './strip.js';
+import { vtermReplay } from './vterm.js';
+const DEFAULT_OPTIONS = {
+    maxContext: 20,
+    truncate: DEFAULT_TRUNCATE,
+};
+export class Recorder {
+    /**
+     * Complete clean PTY data (OSC 9154 stripped).
+     * Append-only; segStart tracks the current segment origin.
+     */
+    fullBuffer = '';
+    /** Start offset of the current segment (after last D). */
+    segStart = 0;
+    /** Absolute offset of C in fullBuffer (null = no C in this segment). */
+    cAbs = null;
+    discardNext = false;
+    reverseInProgress = false;
+    gotFirstD = false;
+    pending = Promise.resolve();
+    opts;
+    oscParser = new OscParser();
+    /** Committed context entries. */
+    context = [];
+    _onEvent = null;
+    constructor(opts) {
+        this.opts = { ...DEFAULT_OPTIONS, ...opts };
+    }
+    onEvent(cb) {
+        this._onEvent = cb;
+    }
+    /**
+     * Feed raw PTY data. Returns clean data with OSC sequences stripped.
+     */
+    feed(data) {
+        const { clean, signals } = this.oscParser.feed(data);
+        const base = this.fullBuffer.length;
+        this.fullBuffer += clean;
+        for (const ps of signals) {
+            this.handleSignal(ps.signal, base + ps.cleanOffset);
+        }
+        return clean;
+    }
+    handleSignal(sig, absOffset) {
+        switch (sig.type) {
+            case 'S':
+                this.emit({ type: 'shell_ready' });
+                break;
+            case 'C':
+                this.cAbs = absOffset;
+                break;
+            case 'D': {
+                // Snapshot shared mutable state before enqueuing — C/P/R signals
+                // in the same feed() call modify these synchronously while D waits.
+                const snap = {
+                    segStart: this.segStart,
+                    cAbs: this.cAbs,
+                    discardNext: this.discardNext,
+                    reverseInProgress: this.reverseInProgress,
+                };
+                this.pending = this.pending
+                    .then(() => this.handleD(sig.rc, absOffset, snap))
+                    .catch((err) => {
+                    log('vtermReplay_error', { error: String(err) });
+                });
+                break;
+            }
+            case 'P':
+                this.discardNext = true;
+                this.segStart = absOffset;
+                this.cAbs = null;
+                this.emit({ type: 'agent', cmd: sig.cmd });
+                break;
+            case 'R':
+                this.discardNext = true;
+                this.reverseInProgress = true;
+                this.segStart = absOffset;
+                this.cAbs = null;
+                this.emit({ type: 'reverse' });
+                break;
+            case 'E':
+                this.emit({ type: 'error', msg: sig.msg });
+                break;
+        }
+    }
+    async handleD(rc, absOffset, snap) {
+        // First D = startup garbage, skip
+        if (!this.gotFirstD) {
+            this.gotFirstD = true;
+            this.segStart = absOffset;
+            this.cAbs = null;
+            return;
+        }
+        // D after agent or reverse — discard
+        if (snap.discardNext) {
+            this.discardNext = false;
+            if (snap.reverseInProgress) {
+                this.reverseInProgress = false;
+                this.emit({ type: 'reverse_done' });
+            }
+            this.segStart = absOffset;
+            this.cAbs = null;
+            return;
+        }
+        // Current segment: snap.segStart .. absOffset
+        const segData = this.fullBuffer.slice(snap.segStart, absOffset);
+        let promptText;
+        let outputText;
+        if (snap.cAbs !== null && snap.cAbs >= snap.segStart) {
+            const cRel = snap.cAbs - snap.segStart;
+            const promptRaw = segData.slice(0, cRel);
+            const outputRaw = segData.slice(cRel);
+            promptText = await vtermReplay(promptRaw);
+            if (isAltScreen(outputRaw)) {
+                outputText = '[full-screen app]';
+            }
+            else {
+                outputText = truncateLines(stripAnsi(outputRaw).trim(), this.opts.truncate);
+            }
+        }
+        else {
+            // No C = no command executed (empty enter, etc.)
+            this.segStart = absOffset;
+            this.cAbs = null;
+            this.emit({ type: 'context_skip', reason: 'no_c' });
+            return;
+        }
+        // Skip empty entries (C present but no output and rc=0, e.g. `true`)
+        if (!outputText && rc === 0) {
+            this.segStart = absOffset;
+            this.cAbs = null;
+            this.emit({ type: 'context_skip', reason: 'no_output' });
+            return;
+        }
+        const entry = { prompt: promptText, output: outputText, rc };
+        this.context.push(entry);
+        // Discard oldest when over limit
+        while (this.context.length > this.opts.maxContext) {
+            this.context.shift();
+        }
+        this.emit({ type: 'context', entry });
+        this.segStart = absOffset;
+        this.cAbs = null;
+        this.maybeCompact();
+    }
+    /** Release memory periodically (fullBuffer grows indefinitely). */
+    maybeCompact() {
+        if (this.segStart > 100_000) {
+            this.fullBuffer = this.fullBuffer.slice(this.segStart);
+            if (this.cAbs !== null)
+                this.cAbs -= this.segStart;
+            this.segStart = 0;
+        }
+    }
+    /**
+     * Drain context — returns all current entries and clears the list.
+     * Consumed context is not re-sent to the next agent invocation.
+     */
+    drain() {
+        const entries = this.context.splice(0);
+        return entries;
+    }
+    emit(evt) {
+        this._onEvent?.(evt);
+    }
+}