@crouton-kit/humanloop 0.3.33 → 0.3.35

package/dist/tui/tmux.js

@@ -1,74 +1,198 @@
-import { execFileSync } from 'child_process';
-import { existsSync, mkdtempSync, readFileSync, rmdirSync, unlinkSync } from 'fs';
-import { tmpdir } from 'os';
-import { join } from 'path';
-function shellQuote(s) {
-    if (s.length > 0 && /^[a-zA-Z0-9_\-./:@%+=]+$/.test(s))
-        return s;
-    return "'" + s.replace(/'/g, `'\\''`) + "'";
-}
-function buildChildCmd(file, resultPath, opts) {
-    const scriptPath = process.argv[1];
-    if (!scriptPath) {
-        throw new Error('Cannot determine hl script path from process.argv[1]');
+import { createHash } from 'node:crypto';
+import { execFileSync, spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+const DEFAULT_KEY = 'M-i';
+const POPUP_TITLE = 'humanloop · inbox';
+const POPUP_STYLE = 'bg=#20242d';
+const POPUP_BORDER_STYLE = 'fg=#5c6370';
+function runtimeDirectory() {
+    const base = process.env['XDG_RUNTIME_DIR'] || process.env['TMPDIR'] || tmpdir();
+    return join(base, `humanloop-${process.getuid?.() ?? process.env['UID'] ?? 'user'}`);
+}
+export function popupPaths(target) {
+    const identity = createHash('sha256').update(`${target.socket}\0${target.client}`).digest('hex').slice(0, 16);
+    const base = join(runtimeDirectory(), 'inbox');
+    return { controlSocket: join(base, `${identity}.sock`), startupLock: join(base, `${identity}.lock`) };
+}
+function tmux(socket, args) {
+    return execFileSync('tmux', ['-S', socket, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+function quote(value) { return `'${value.replace(/'/g, `'\\''`)}'`; }
+function bindingCommand() {
+    // --quiet keeps the background `run-shell -b` binding from printing its result JSON, which
+    // tmux would otherwise surface as a view-mode overlay on the active pane. The popup opening
+    // is the feedback; a genuine failure still prints (see the CLI toggle action).
+    return 'hl inbox toggle --quiet --tmux-socket "#{socket_path}" --tmux-client "#{client_name}" --target-pane "#{pane_id}"';
+}
+function configuredKeyPath() {
+    const state = process.env['XDG_STATE_HOME'] || join(homedir(), '.local', 'state');
+    return join(state, 'humanloop', 'inbox-key');
+}
+function configuredKey() {
+    try {
+        return readFileSync(configuredKeyPath(), 'utf8').trim() || DEFAULT_KEY;
+    }
+    catch {
+        return DEFAULT_KEY;
     }
-    const parts = [
-        shellQuote(process.execPath),
-        shellQuote(scriptPath),
-        'ask',
-        shellQuote(file),
-        '--dir',
-        shellQuote(opts.dir),
-        '--write-to',
-        shellQuote(resultPath),
-    ];
-    if (opts.sessionId) {
-        parts.push('--session-id', shellQuote(opts.sessionId));
+}
+function writeConfiguredKey(key) {
+    mkdirSync(join(configuredKeyPath(), '..'), { recursive: true, mode: 0o700 });
+    writeFileSync(configuredKeyPath(), `${key}\n`, { mode: 0o600 });
+}
+function rootBinding(socket, key) {
+    try {
+        const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const match = tmux(socket, ['list-keys', '-T', 'root']).split('\n').map((row) => new RegExp(`^bind-key\\s+-T root\\s+${escaped}\\s+(.*)$`).exec(row)).find((entry) => entry !== null);
+        return match?.[1];
     }
-    if (!opts.visuals) {
-        parts.push('--no-visuals');
+    catch {
+        return undefined;
     }
-    return parts.join(' ');
-}
-export async function dispatchToTmuxPane(file, opts) {
-    const parentTmp = mkdtempSync(join(tmpdir(), 'hl-'));
-    const resultPath = join(parentTmp, 'result.json');
-    const cmd = buildChildCmd(file, resultPath, opts);
-    // Capture the spawned pane id so we can detect if the user closes it
-    // without finishing — otherwise the parent would poll forever.
-    const paneId = execFileSync('tmux', ['split-window', '-P', '-F', '#{pane_id}', '-h', '-d', cmd], { encoding: 'utf8' }).trim();
-    await new Promise((resolve, reject) => {
-        const poll = setInterval(() => {
-            if (existsSync(resultPath)) {
-                clearInterval(poll);
-                resolve();
-                return;
-            }
-            // Check the pane is still alive. If it's gone and there's still no
-            // result file, the child died (closed pane, crash, etc).
-            try {
-                const panes = execFileSync('tmux', ['list-panes', '-a', '-F', '#{pane_id}'], {
-                    encoding: 'utf8',
-                });
-                if (!panes.split('\n').map((s) => s.trim()).includes(paneId)) {
-                    clearInterval(poll);
-                    reject(new Error(`tmux pane ${paneId} closed before writing a result`));
-                }
-            }
-            catch (err) {
-                clearInterval(poll);
-                reject(new Error(`tmux list-panes failed: ${err instanceof Error ? err.message : String(err)}`));
-            }
-        }, 150);
-    });
-    const json = readFileSync(resultPath, 'utf8');
+}
+function isCanonical(command) {
+    const normalized = command?.replace(/\\"/g, '"');
+    return normalized !== undefined && normalized.includes('hl inbox toggle') && normalized.includes('--tmux-socket "#{socket_path}"') && normalized.includes('--tmux-client "#{client_name}"') && normalized.includes('--target-pane "#{pane_id}"');
+}
+export function inspectInboxBinding(socket = tmuxSocketFromEnvironment()) {
+    const key = configuredKey();
+    if (socket === undefined)
+        return { state: 'unbound', key, isDefault: key === DEFAULT_KEY };
+    const command = rootBinding(socket, key);
+    return { state: command === undefined ? 'unbound' : isCanonical(command) ? 'installed' : 'collision', key, isDefault: key === DEFAULT_KEY };
+}
+export function installInboxBinding(opts = {}) {
+    const socket = opts.socket ?? tmuxSocketFromEnvironment();
+    const key = opts.key ?? configuredKey();
+    if (socket === undefined)
+        return { state: 'unbound', key, isDefault: key === DEFAULT_KEY };
+    const existing = rootBinding(socket, key);
+    if (existing !== undefined && !isCanonical(existing))
+        return { state: 'collision', key, isDefault: key === DEFAULT_KEY };
+    if (existing === undefined)
+        tmux(socket, ['bind-key', '-T', 'root', key, 'run-shell', '-b', bindingCommand()]);
+    if (opts.key !== undefined) {
+        // Switching to a new key: drop the previous configured key iff it still holds the
+        // canonical toggle, so bindings don't accrete and inspect/unbind track a single live key.
+        const previous = configuredKey();
+        if (previous !== key && isCanonical(rootBinding(socket, previous)))
+            tmux(socket, ['unbind-key', '-T', 'root', previous]);
+        writeConfiguredKey(key);
+    }
+    return { state: 'installed', key, isDefault: key === DEFAULT_KEY };
+}
+export function unbindInboxBinding(socket = tmuxSocketFromEnvironment()) {
+    const key = configuredKey();
+    if (socket !== undefined && isCanonical(rootBinding(socket, key)))
+        tmux(socket, ['unbind-key', '-T', 'root', key]);
+    return inspectInboxBinding(socket);
+}
+export function tmuxSocketFromEnvironment() {
+    const value = process.env['TMUX'];
+    return value?.split(',')[0] || undefined;
+}
+export function inferTmuxClient(socket, pane = process.env['TMUX_PANE']) {
+    if (pane === undefined)
+        return undefined;
+    const matches = tmux(socket, ['list-clients', '-F', '#{client_name}\t#{pane_id}']).split('\n')
+        .map((line) => line.split('\t')).filter((parts) => parts[1] === pane).map((parts) => parts[0]);
+    return matches.length === 1 ? matches[0] : matches.length > 1 ? 'ambiguous' : undefined;
+}
+function acquireStartupLock(path) {
     try {
-        unlinkSync(resultPath);
+        mkdirSync(path, { mode: 0o700 });
+        return true;
+    }
+    catch {
+        return false;
     }
-    catch { /* ignore */ }
+}
+export async function toggleInboxPopup(target) {
+    const socket = target?.socket ?? tmuxSocketFromEnvironment();
+    if (socket === undefined)
+        return 'not_in_tmux';
+    const inferred = target?.client ?? inferTmuxClient(socket, target?.targetPane);
+    if (inferred === 'ambiguous')
+        return 'ambiguous_client';
+    if (inferred === undefined)
+        return 'ambiguous_client';
+    const resolved = { socket, client: inferred, targetPane: target?.targetPane };
+    const paths = popupPaths(resolved);
+    mkdirSync(join(paths.controlSocket, '..'), { recursive: true, mode: 0o700 });
+    if (await requestPopupClose(paths.controlSocket))
+        return 'closed';
+    // A concurrent toggle for this same client won the startup lock and is opening the popup.
+    // This gesture must not launch a second one; report a benign no-op close rather than a
+    // generic failure, so exactly one popup exists and the loser never exits with an error.
+    if (!acquireStartupLock(paths.startupLock))
+        return 'closed';
     try {
-        rmdirSync(parentTmp);
+        // Re-probe under the lock: between the first probe and acquiring the lock a concurrent
+        // toggle may have brought a live popup up. Deleting its control socket now would orphan
+        // that popup, so close it instead. The finally below releases the lock on every path.
+        if (await requestPopupClose(paths.controlSocket))
+            return 'closed';
+        if (existsSync(paths.controlSocket))
+            rmSync(paths.controlSocket, { force: true });
+        const command = `${quote(process.execPath)} ${quote(fileURLToPath(new URL('../cli.js', import.meta.url)))} inbox open --control-socket ${quote(paths.controlSocket)}`;
+        return await launchPopup(socket, resolved, paths.controlSocket, command);
     }
-    catch { /* ignore */ }
-    return JSON.parse(json);
+    finally {
+        rmSync(paths.startupLock, { recursive: true, force: true });
+    }
+}
+/** Connect to the control socket and, if a live popup owns it, ask it to close. Resolves true when a popup answered. */
+async function requestPopupClose(controlSocket) {
+    const { Socket } = await import('node:net');
+    return new Promise((resolve) => {
+        const client = new Socket();
+        const done = (value) => { client.destroy(); resolve(value); };
+        client.setTimeout(300, () => done(false));
+        client.once('error', () => done(false));
+        client.connect(controlSocket, () => { client.end('close\n'); done(true); });
+    });
+}
+/** Launch one popup and report `opened` only once its controller owns the control socket. */
+async function launchPopup(socket, target, controlSocket, command) {
+    const args = ['-S', socket, 'display-popup', '-E', '-c', target.client, ...inboxPopupFlags(), ...(target.targetPane === undefined ? [] : ['-t', target.targetPane]), command];
+    const child = spawn('tmux', args, { stdio: ['ignore', 'ignore', 'pipe'], detached: true });
+    let stderr = '';
+    child.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+    const exited = new Promise((resolve) => {
+        // `display-popup -E` blocks until our popup closes, so a successful open keeps the child
+        // alive while the control socket comes up (detected below). An early exit before that means
+        // the popup command never ran: tmux 3.x silently declines to stack a popup on a client that
+        // already shows one (exit 0, command dropped), which is exactly the foreign-popup case the
+        // design must report as `other_popup` without disturbing the existing popup or its process.
+        child.once('exit', (code) => resolve(code === 0 || /popup/i.test(stderr) ? 'other_popup' : 'failed'));
+        child.once('error', () => resolve('failed'));
+    });
+    const { Socket } = await import('node:net');
+    for (let attempt = 0; attempt < 50; attempt++) {
+        const outcome = await Promise.race([
+            exited,
+            new Promise((resolve) => {
+                const probe = new Socket();
+                const done = (value) => { probe.destroy(); setTimeout(() => resolve(value), value === 'pending' ? 100 : 0); };
+                probe.setTimeout(200, () => done('pending'));
+                probe.once('error', () => done('pending'));
+                probe.connect(controlSocket, () => done('opened'));
+            }),
+        ]);
+        if (outcome === 'opened') {
+            child.unref();
+            return 'opened';
+        }
+        if (outcome !== 'pending')
+            return outcome;
+    }
+    return 'failed';
+}
+/** The static tmux `display-popup` geometry and style flags; the client and target pane are added per-invocation. */
+export function inboxPopupFlags() {
+    return ['-w', '90%', '-h', '90%', '-b', 'rounded', '-T', POPUP_TITLE, '-s', POPUP_STYLE, '-S', POPUP_BORDER_STYLE];
 }
+export const inboxPopupStyle = { width: '90%', height: '90%', border: 'rounded', title: POPUP_TITLE, background: '#20242d', chrome: '#2b3245', borderColor: '#5c6370' };

package/dist/types.d.ts

@@ -137,8 +137,7 @@ export interface TuiState {
 }
 /**
  * Resolution contract returned by `ask`/`inbox`. On-disk `response.json` stays
- * `{ responses, completedAt }`; `responsePath` points at it. `hl schema
- * response` returns the JSON Schema this `schema` id names.
+ * `{ responses, completedAt }`; `responsePath` points at it.
  */
 export interface ResolutionEnvelope {
     /** 1 line/interaction "<title>: <option label>[ — <freetext>]"; deterministic, no LLM. */
@@ -155,15 +154,76 @@ export interface ResolutionEnvelope {
  * One pending interaction discovered by `scanInbox`. Read from the
  * `deck.json` header only — never the full deck.
  */
-export interface InboxItem {
+export interface ClaimSummary {
+    owner: string;
+    claimedAt: string;
+    heartbeatAt: string;
+}
+interface TicketSummaryBase {
     dir: string;
     id: string;
-    title?: string;
+    title: string;
     subtitle?: string;
-    kind?: InteractionKind;
-    /** `deck.source.blockedSince` ?? `statSync(deck.json).mtime` (ISO). */
     blockedSince: string;
-    source?: DeckSource;
+    source: DeckSource;
+    claim?: ClaimSummary;
+}
+export interface DeckTicketSummary extends TicketSummaryBase {
+    kind: 'deck';
+    interactionKind?: InteractionKind;
+}
+export interface ReviewTicketSummary extends TicketSummaryBase {
+    kind: 'review';
+    file: string;
+    output: string;
+}
+/** The only pending-ticket shape scanners expose. */
+export type TicketSummary = DeckTicketSummary | ReviewTicketSummary;
+/** Compatibility name retained only while the list adapter is moved in H2. */
+export type InboxItem = TicketSummary;
+export interface ReviewDescriptor {
+    schema: 'humanloop.review/v1';
+    file: string;
+    output: string;
+    title: string;
+    source: DeckSource;
+    blockedSince: string;
+}
+export interface DeckTicketResult {
+    schema: 'humanloop.response/v2';
+    kind: 'deck';
+    responses: InteractionResponse[];
+    summary: string;
+    completedAt: string;
+}
+export interface ReviewTicketResult {
+    schema: 'humanloop.review-response/v1';
+    kind: 'review';
+    result: FeedbackResult;
+    completedAt: string;
+}
+export interface CanceledTicketResult {
+    schema: 'humanloop.cancel/v1';
+    kind: 'canceled';
+    canceledAt: string;
+    reason?: string;
+    actor?: string;
+}
+/** The sole canonical response.json union. */
+export type TicketResult = DeckTicketResult | ReviewTicketResult | CanceledTicketResult;
+export interface InboxBindingState {
+    state: 'installed' | 'collision' | 'unbound';
+    key: string;
+    isDefault: boolean;
+}
+export interface CompletionEvent {
+    schema: 'humanloop.completion/v1';
+    root: string;
+    dir: string;
+    ticketId: string;
+    kind: 'deck' | 'review' | 'canceled';
+    outcome: 'resolved' | 'canceled';
+    responsePath: string;
 }
 /** Options for `display()` — the live-watch tmux pane surface. The pane always
  *  watches the file and live-updates on edits; there is no non-watched mode. */
@@ -223,3 +283,4 @@ export interface MountedPanel {
      */
     setInputBuffer(text: string): void;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.3.33",
+  "version": "0.3.35",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "dev": "tsx src/cli.ts",
     "link": "npm link",
     "postinstall": "node dist/scripts/install-renderer.js || true",
-    "test": "tsx src/__tests__/mount-panel.test.ts && tsx src/__tests__/feedback.test.ts && tsx src/__tests__/browser-server.test.ts && tsx web/src/__tests__/review-sourcemap.test.ts && tsx web/src/__tests__/review-reducer.test.ts && tsx web/src/__tests__/review-keymap.test.ts && tsx web/src/__tests__/review-markdown-instrumentation.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/app-deck-regression.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-conflict.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/app-ws-close.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-takeback.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-submit-race.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-stale-submit-failure.test.ts"
+    "test": "tsx src/__tests__/inbox-core.test.ts && tsx src/__tests__/inbox-controller.test.ts && tsx src/__tests__/review-adapter.test.ts && tsx src/__tests__/mount-panel.test.ts && tsx src/__tests__/feedback.test.ts && tsx src/__tests__/browser-server.test.ts && tsx web/src/__tests__/review-sourcemap.test.ts && tsx web/src/__tests__/review-reducer.test.ts && tsx web/src/__tests__/review-keymap.test.ts && tsx web/src/__tests__/review-markdown-instrumentation.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/app-deck-regression.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-conflict.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/app-ws-close.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-takeback.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-submit-race.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-stale-submit-failure.test.ts && tsx src/__tests__/inbox-popup.test.ts"
   },
   "dependencies": {
     "@r-cli/sdk": "^1.3.0",