@holon-run/agentinbox 0.5.0 → 0.6.0

package/dist/src/adapters.js

@@ -140,6 +140,12 @@ class AdapterRegistry {
         }
         return this.remoteSource.expandSubscriptionShortcut(source, input);
     }
+    async deriveInlinePreview(source, item) {
+        if (source.sourceType === "local_event") {
+            return null;
+        }
+        return this.remoteSource.deriveInlinePreview(source, item);
+    }
     status() {
         return {
             remote: this.remoteSource.status?.() ?? {},

package/dist/src/runtime_gate.js

@@ -11,8 +11,8 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
 const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
-const DEFAULT_ITERM2_SAMPLE_DELAY_MS = 250;
-const DEFAULT_TMUX_SAMPLE_DELAY_MS = 250;
+const DEFAULT_ITERM2_SAMPLE_DELAY_MS = 900;
+const DEFAULT_TMUX_SAMPLE_DELAY_MS = 900;
 const ACTIVE_BUFFER_MARKERS = [
     "esc to interrupt",
     "Working (",
@@ -170,6 +170,96 @@ class Iterm2TerminalStateProbe {
         if (!sessionId) {
             return { presence: "unknown", busy: "unknown" };
         }
+        // Try Python API probe first (if enabled)
+        if (this.options.enablePythonProbe !== false) {
+            const pythonResult = await this.tryPythonApiProbe(sessionId, target.runtimeKind);
+            if (pythonResult && pythonResult.presence !== "unknown") {
+                return pythonResult;
+            }
+        }
+        // Fallback to command-line tools
+        return this.checkWithCommandLineTools(sessionId);
+    }
+    async tryPythonApiProbe(sessionId, runtimeKind) {
+        try {
+            const scriptPath = this.options.pythonScriptPath ?? resolvePythonProbeScript();
+            const result = await this.execAsync("python3", [scriptPath, sessionId], {
+                env: { ...process.env, PYTHONIOENCODING: "utf-8" }
+            });
+            const data = JSON.parse(result.stdout);
+            if (data.status === "gone") {
+                return { presence: "gone", busy: "unknown" };
+            }
+            if (data.status === "available") {
+                // If we have cursor and lines data, use cursor-aware detection
+                if (data.cursor && data.lines) {
+                    const bufferTail = data.lines.join("\n");
+                    const cursorPosition = { x: data.cursor.x, y: data.cursor.y };
+                    const screenHeight = data.screen_height;
+                    const startLine = data.start_line ?? 0;
+                    // Perform cursor-aware typing detection
+                    const busyStatus = evaluatePythonCursorAwareTypingPrompt(bufferTail, cursorPosition, screenHeight, startLine, runtimeKind);
+                    // If cursor-aware detection indicates busy, return immediately
+                    if (busyStatus === "busy") {
+                        return { presence: "available", busy: "busy" };
+                    }
+                    // If cursor-aware detection is certain it's not busy, don't apply prompt heuristics
+                    if (busyStatus === "not_busy") {
+                        // Still check for buffer changes and active markers
+                        await (this.options.sleep ?? sleep)(this.options.sampleDelayMs ?? DEFAULT_ITERM2_SAMPLE_DELAY_MS);
+                        const secondResult = await this.execAsync("python3", [scriptPath, sessionId], {
+                            env: { ...process.env, PYTHONIOENCODING: "utf-8" }
+                        });
+                        const secondData = JSON.parse(secondResult.stdout);
+                        if (secondData.status === "available" && secondData.lines) {
+                            const secondBufferTail = secondData.lines.join("\n");
+                            if (bufferTail !== secondBufferTail) {
+                                return { presence: "available", busy: "busy" };
+                            }
+                        }
+                        // Check for active buffer markers
+                        if (containsActiveBufferMarker(bufferTail)) {
+                            return { presence: "available", busy: "busy" };
+                        }
+                        return { presence: "available", busy: "idle" };
+                    }
+                    // If cursor-aware detection is uncertain, fall back to buffer change detection only
+                    // Do NOT use generic typing prompts to avoid false positives (see #116)
+                    if (busyStatus === "unknown") {
+                        await (this.options.sleep ?? sleep)(this.options.sampleDelayMs ?? DEFAULT_ITERM2_SAMPLE_DELAY_MS);
+                        const secondResult = await this.execAsync("python3", [scriptPath, sessionId], {
+                            env: { ...process.env, PYTHONIOENCODING: "utf-8" }
+                        });
+                        const secondData = JSON.parse(secondResult.stdout);
+                        if (secondData.status === "available" && secondData.lines) {
+                            const secondBufferTail = secondData.lines.join("\n");
+                            if (bufferTail !== secondBufferTail) {
+                                return { presence: "available", busy: "busy" };
+                            }
+                        }
+                        // Check for active buffer markers
+                        if (containsActiveBufferMarker(bufferTail)) {
+                            return { presence: "available", busy: "busy" };
+                        }
+                        // Return unknown when cursor-aware detection is uncertain
+                        // Do NOT fall back to generic typing prompts to avoid false positives
+                        return { presence: "available", busy: "unknown" };
+                    }
+                    // This should never be reached as all cases are handled above
+                    return { presence: "available", busy: "unknown" };
+                }
+                // If we don't have cursor data, return unknown to trigger fallback
+                return null;
+            }
+            // Any other status means we should fall back
+            return null;
+        }
+        catch {
+            // Python API probe failed, fall back to command-line tools
+            return null;
+        }
+    }
+    async checkWithCommandLineTools(sessionId) {
         let it2api;
         try {
             it2api = resolveIterm2ApiPath(this.options.iterm2ApiPath);
@@ -197,9 +287,7 @@ class Iterm2TerminalStateProbe {
         if (containsActiveBufferMarker(second)) {
             return { presence: "available", busy: "busy" };
         }
-        if (hasVisibleTypingPrompt(second)) {
-            return { presence: "available", busy: "busy" };
-        }
+        // Do NOT use generic typing prompts to avoid false positives (see #116)
         return { presence: "available", busy: "unknown" };
     }
     async checkSessionPresence(it2api, sessionId) {
@@ -271,21 +359,33 @@ class TmuxTerminalStateProbe {
         if (containsActiveBufferMarker(second)) {
             return { presence: "available", busy: "busy" };
         }
-        if (paneState.active && hasVisibleTypingPrompt(second)) {
+        // Use cursor-aware detection when available
+        const cursorHint = evaluateCursorAwareTypingPrompt(target, paneState, second);
+        if (cursorHint === "busy") {
             return { presence: "available", busy: "busy" };
         }
+        // Do NOT fall back to generic typing prompts when cursorHint is unknown to avoid false positives (see #116)
         return { presence: "available", busy: "unknown" };
     }
     async readPaneState(paneId) {
         try {
-            const result = await this.execAsync("tmux", ["display-message", "-p", "-t", paneId, "#{pane_active} #{pane_dead}"]);
-            const [active, dead] = result.stdout.trim().split(/\s+/, 2);
+            const result = await this.execAsync("tmux", [
+                "display-message",
+                "-p",
+                "-t",
+                paneId,
+                "#{pane_active} #{pane_dead} #{cursor_x} #{cursor_y} #{pane_height}",
+            ]);
+            const [active, dead, cursorX, cursorY, height] = result.stdout.trim().split(/\s+/, 5);
             if (!active || !dead) {
                 return "unknown";
             }
             return {
                 active: active === "1",
                 dead: dead === "1",
+                cursorX: parseOptionalInt(cursorX),
+                cursorY: parseOptionalInt(cursorY),
+                height: parseOptionalInt(height),
             };
         }
         catch (error) {
@@ -309,7 +409,7 @@ exports.TmuxTerminalStateProbe = TmuxTerminalStateProbe;
 function containsActiveBufferMarker(bufferTail) {
     return ACTIVE_BUFFER_MARKERS.some((marker) => bufferTail.includes(marker));
 }
-function hasVisibleTypingPrompt(bufferTail) {
+function hasVisibleTypingPrompt(bufferTail, prefixes = TYPING_PROMPT_PREFIXES) {
     const lines = bufferTail
         .split("\n")
         .map((line) => line.trimEnd())
@@ -318,13 +418,64 @@ function hasVisibleTypingPrompt(bufferTail) {
     if (!lastLine) {
         return false;
     }
-    for (const prefix of TYPING_PROMPT_PREFIXES) {
+    for (const prefix of prefixes) {
         if (lastLine.startsWith(prefix) && lastLine.slice(prefix.length).trim().length > 0) {
             return true;
         }
     }
     return false;
 }
+function evaluateCursorAwareTypingPrompt(target, paneState, bufferTail) {
+    const prefix = runtimeTypingPromptPrefix(target.runtimeKind);
+    if (!prefix) {
+        return "unknown";
+    }
+    if (paneState.cursorX == null || paneState.cursorY == null || paneState.height == null) {
+        return "unknown";
+    }
+    const lines = bufferTail
+        .replace(/\r/g, "")
+        .split("\n")
+        .map((line) => line.trimEnd());
+    if (lines.length === 0) {
+        return "unknown";
+    }
+    const captureStartRow = Math.max(0, paneState.height - lines.length);
+    const lineIndex = paneState.cursorY - captureStartRow;
+    if (lineIndex < 0 || lineIndex >= lines.length) {
+        return "unknown";
+    }
+    const line = lines[lineIndex] ?? "";
+    if (!line.startsWith(prefix)) {
+        return "not_busy";
+    }
+    return paneState.cursorX > prefix.length ? "busy" : "not_busy";
+}
+function runtimeTypingPromptPrefix(runtimeKind) {
+    if (runtimeKind === "codex") {
+        return "› ";
+    }
+    if (runtimeKind === "claude_code") {
+        return "❯ ";
+    }
+    return null;
+}
+function typingPromptPrefixesForRuntime(runtimeKind) {
+    if (runtimeKind === "codex") {
+        return ["› "];
+    }
+    if (runtimeKind === "claude_code") {
+        return ["❯ ", "› "];
+    }
+    return TYPING_PROMPT_PREFIXES;
+}
+function parseOptionalInt(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : null;
+}
 function normalizeBufferTail(buffer) {
     const normalized = buffer
         .replace(/\r/g, "")
@@ -643,3 +794,79 @@ function parseIterm2SessionIds(stdout) {
     })
         .filter((id) => id !== null);
 }
+function resolvePythonProbeScript(override) {
+    if (override) {
+        return override;
+    }
+    const scriptRelativePath = node_path_1.default.join("scripts", "iterm2_cursor_probe.py");
+    const seen = new Set();
+    const candidates = [];
+    const addCandidate = (candidate) => {
+        const normalized = node_path_1.default.normalize(candidate);
+        if (!seen.has(normalized)) {
+            seen.add(normalized);
+            candidates.push(normalized);
+        }
+    };
+    // Search upward from the current module's directory
+    let currentDir = __dirname;
+    for (let i = 0; i < 5; i++) { // Limit upward search depth
+        addCandidate(node_path_1.default.join(currentDir, scriptRelativePath));
+        addCandidate(node_path_1.default.join(currentDir, "dist", scriptRelativePath));
+        addCandidate(node_path_1.default.join(currentDir, "dist", "src", scriptRelativePath));
+        const parentDir = node_path_1.default.dirname(currentDir);
+        if (parentDir === currentDir) {
+            break;
+        }
+        currentDir = parentDir;
+    }
+    // Check process working directory and its dist paths
+    addCandidate(node_path_1.default.join(process.cwd(), scriptRelativePath));
+    addCandidate(node_path_1.default.join(process.cwd(), "dist", scriptRelativePath));
+    addCandidate(node_path_1.default.join(process.cwd(), "dist", "src", scriptRelativePath));
+    // Check all candidates
+    for (const candidate of candidates) {
+        if (node_fs_1.default.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error(`Unable to locate iterm2_cursor_probe.py. Checked: ${candidates.join(", ")}. ` +
+        "Ensure scripts/iterm2_cursor_probe.py is shipped with the package or copied into dist/ during build.");
+}
+function evaluatePythonCursorAwareTypingPrompt(bufferTail, cursorPosition, screenHeight, startLine, runtimeKind) {
+    const lines = bufferTail.split("\n");
+    const lastLineIndex = lines.length - 1;
+    // Cursor coordinates are in full-screen rows, while bufferTail only contains
+    // the lines from startLine to end of screen. First ensure the cursor is on the
+    // terminal's last visible row, then map that row into the captured window.
+    if (cursorPosition.y !== screenHeight - 1) {
+        return "not_busy";
+    }
+    // Map the cursor position into the captured buffer window using startLine
+    const cursorRowInBuffer = cursorPosition.y - startLine;
+    // If the last visible screen row is not represented by the captured tail,
+    // or does not map to the last captured line, we cannot evaluate reliably.
+    if (cursorRowInBuffer < 0 || cursorRowInBuffer > lastLineIndex) {
+        return "unknown";
+    }
+    if (cursorRowInBuffer !== lastLineIndex) {
+        return "not_busy";
+    }
+    const lastLine = lines[lastLineIndex] || "";
+    const promptPrefix = runtimeTypingPromptPrefix(runtimeKind);
+    if (!promptPrefix) {
+        return "unknown";
+    }
+    // Check if the last line starts with the runtime-specific prompt prefix
+    if (lastLine.startsWith(promptPrefix)) {
+        // Check if cursor is after the prompt prefix
+        if (cursorPosition.x > promptPrefix.length) {
+            const afterPrompt = lastLine.slice(promptPrefix.length).trim();
+            // If there's content after the prompt, user is typing
+            if (afterPrompt.length > 0) {
+                return "busy";
+            }
+        }
+    }
+    return "not_busy";
+}

package/dist/src/service.js

@@ -1570,9 +1570,21 @@ class AgentInboxService {
                     });
                     return "deferred";
                 }
-                const preview = totalUnackedCount === 1 && input.items.length === 1
-                    ? (0, terminal_1.deriveInlineItemPreview)(input.items[0], input.summary)
-                    : null;
+                let preview = null;
+                if (totalUnackedCount === 1 && input.items.length === 1) {
+                    const singleItem = input.items[0];
+                    const source = this.store.getSource(singleItem.sourceId);
+                    if (source) {
+                        try {
+                            const sourcePreview = await this.adapters.deriveInlinePreview(source, singleItem);
+                            preview = typeof sourcePreview === "string" ? (0, terminal_1.normalizeInlinePreviewText)(sourcePreview) : null;
+                        }
+                        catch {
+                            preview = null;
+                        }
+                    }
+                    preview ??= (0, terminal_1.deriveInlineItemPreview)(singleItem, input.summary);
+                }
                 const prompt = (0, terminal_1.renderAgentPrompt)({
                     inboxId: inbox.inboxId,
                     totalUnackedCount,

package/dist/src/sources/remote.js

@@ -191,6 +191,16 @@ class RemoteSourceRuntime {
             source: profileInputSource(source),
         });
     }
+    async deriveInlinePreview(source, item) {
+        if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
+            return null;
+        }
+        const profile = await this.profileRegistry.resolve(source, this.homeDir);
+        if (typeof profile.deriveInlinePreview !== "function") {
+            return null;
+        }
+        return profile.deriveInlinePreview(item, profileInputSource(source));
+    }
     async syncAll() {
         const sources = this.store
             .listSources()

package/dist/src/sources/remote_profiles.js

@@ -95,6 +95,7 @@ function validateProfileContract(profile, sourcePath) {
     validateOptionalHook(profile.expandSubscriptionShortcut, "expandSubscriptionShortcut", sourcePath);
     validateOptionalHook(profile.deriveTrackedResource, "deriveTrackedResource", sourcePath);
     validateOptionalHook(profile.projectLifecycleSignal, "projectLifecycleSignal", sourcePath);
+    validateOptionalHook(profile.deriveInlinePreview, "deriveInlinePreview", sourcePath);
 }
 function validateOptionalHook(value, name, sourcePath) {
     if (value !== undefined && typeof value !== "function") {
@@ -267,6 +268,36 @@ const GITHUB_REPO_CI_PROFILE = {
             eventVariantExamples: ["workflow_run.ci.completed.failure", "workflow_run.nightly_checks.observed"],
         };
     },
+    deriveInlinePreview(item) {
+        const repoFullName = asNonEmptyString(item.metadata.repoFullName);
+        const workflowName = asNonEmptyString(item.metadata.name)
+            ?? asNonEmptyString(item.metadata.displayTitle)
+            ?? asNonEmptyString(item.rawPayload.name)
+            ?? asNonEmptyString(item.rawPayload.display_title);
+        const headBranch = asNonEmptyString(item.metadata.headBranch) ?? asNonEmptyString(item.rawPayload.head_branch);
+        const conclusion = asNonEmptyString(item.metadata.conclusion) ?? asNonEmptyString(item.rawPayload.conclusion);
+        const status = asNonEmptyString(item.metadata.status) ?? asNonEmptyString(item.rawPayload.status);
+        const parts = [];
+        if (workflowName) {
+            parts.push(workflowName);
+        }
+        else {
+            parts.push("Workflow run");
+        }
+        if (conclusion) {
+            parts.push(`completed ${conclusion}`);
+        }
+        else if (status) {
+            parts.push(status);
+        }
+        if (repoFullName) {
+            parts.push(`for ${repoFullName}`);
+        }
+        if (headBranch) {
+            parts.push(`on ${headBranch}`);
+        }
+        return parts.join(" ");
+    },
     validateConfig(source) {
         (0, github_ci_1.parseGithubCiSourceConfig)(source);
     },

package/dist/src/store.js

@@ -780,6 +780,12 @@ class AgentInboxStore {
         ]);
         const inserted = this.changes() > before;
         if (inserted) {
+            const rowId = this.lastInsertRowId();
+            this.db.run(`
+        update inbox_items
+        set inbox_sequence = ?
+        where rowid = ? and inbox_sequence is null
+      `, [rowId, rowId]);
             this.persist();
         }
         return inserted;
@@ -792,14 +798,14 @@ class AgentInboxStore {
             filters.push("acked_at is null");
         }
         if (options?.afterItemId) {
-            const anchor = this.getOne("select occurred_at, item_id from inbox_items where inbox_id = ? and item_id = ?", [inboxId, options.afterItemId]);
+            const anchor = this.getOne("select coalesce(inbox_sequence, rowid) as inbox_sequence from inbox_items where inbox_id = ? and item_id = ?", [inboxId, options.afterItemId]);
             if (!anchor) {
                 throw new Error(`unknown inbox item: ${options.afterItemId}`);
             }
-            filters.push("((occurred_at > ?) or (occurred_at = ? and item_id > ?))");
-            params.push(String(anchor.occurred_at), String(anchor.occurred_at), String(anchor.item_id));
+            filters.push("coalesce(inbox_sequence, rowid) > ?");
+            params.push(Number(anchor.inbox_sequence));
         }
-        const rows = this.getAll(`select * from inbox_items where ${filters.join(" and ")} order by occurred_at asc, item_id asc`, params);
+        const rows = this.getAll(`select * from inbox_items where ${filters.join(" and ")} order by coalesce(inbox_sequence, rowid) asc`, params);
         return rows.map((row) => this.mapInboxItem(row));
     }
     ackItems(inboxId, itemIds, ackedAt) {
@@ -818,7 +824,7 @@ class AgentInboxStore {
         return changes;
     }
     ackItemsThrough(inboxId, itemId, ackedAt) {
-        const anchor = this.getOne("select occurred_at, item_id from inbox_items where inbox_id = ? and item_id = ?", [inboxId, itemId]);
+        const anchor = this.getOne("select coalesce(inbox_sequence, rowid) as inbox_sequence from inbox_items where inbox_id = ? and item_id = ?", [inboxId, itemId]);
         if (!anchor) {
             throw new Error(`unknown inbox item: ${itemId}`);
         }
@@ -827,8 +833,8 @@ class AgentInboxStore {
       set acked_at = ?
       where inbox_id = ?
         and acked_at is null
-        and ((occurred_at < ?) or (occurred_at = ? and item_id <= ?))
-    `, [ackedAt, inboxId, String(anchor.occurred_at), String(anchor.occurred_at), String(anchor.item_id)]);
+        and coalesce(inbox_sequence, rowid) <= ?
+    `, [ackedAt, inboxId, Number(anchor.inbox_sequence)]);
         const changes = this.changes();
         if (changes > 0) {
             this.persist();

package/dist/src/terminal.js

@@ -7,6 +7,7 @@ exports.TerminalDispatcher = void 0;
 exports.detectTerminalContext = detectTerminalContext;
 exports.renderAgentPrompt = renderAgentPrompt;
 exports.deriveInlineItemPreview = deriveInlineItemPreview;
+exports.normalizeInlinePreviewText = normalizeInlinePreviewText;
 exports.assignedAgentIdFromContext = assignedAgentIdFromContext;
 const node_child_process_1 = require("node:child_process");
 const node_util_1 = require("node:util");
@@ -78,13 +79,16 @@ function deriveInlineItemPreview(item, summary) {
         candidates.push(summary);
     }
     for (const candidate of candidates) {
-        const preview = normalizeInlinePreview(candidate);
+        const preview = normalizeInlinePreviewText(candidate);
         if (preview) {
             return preview;
         }
     }
     return null;
 }
+function normalizeInlinePreviewText(candidate) {
+    return normalizeInlinePreview(candidate);
+}
 function assignedAgentIdFromContext(input) {
     const primary = normalizeOptionalString(input.runtimeSessionId)
         ?? normalizeOptionalString(input.tmuxPaneId)

package/drizzle/migrations/0008_inbox_item_sequence.sql

@@ -0,0 +1,21 @@
+alter table inbox_items add column inbox_sequence integer;
+
+update inbox_items
+set inbox_sequence = rowid
+where inbox_sequence is null;
+
+create unique index if not exists idx_inbox_items_inbox_sequence
+  on inbox_items(inbox_sequence);
+
+create index if not exists idx_inbox_items_inbox_sequence_order
+  on inbox_items(inbox_id, inbox_sequence);
+
+create trigger if not exists trg_inbox_items_set_sequence_after_insert
+after insert on inbox_items
+for each row
+when new.inbox_sequence is null
+begin
+  update inbox_items
+  set inbox_sequence = new.rowid
+  where rowid = new.rowid;
+end;

package/drizzle/schema.ts

@@ -139,6 +139,7 @@ export const inboxItems = sqliteTable("inbox_items", {
   sourceNativeId: text("source_native_id").notNull(),
   eventVariant: text("event_variant").notNull(),
   inboxId: text("inbox_id").notNull(),
+  inboxSequence: integer("inbox_sequence"),
   occurredAt: text("occurred_at").notNull(),
   metadataJson: text("metadata_json").notNull(),
   rawPayloadJson: text("raw_payload_json").notNull(),
@@ -147,8 +148,10 @@ export const inboxItems = sqliteTable("inbox_items", {
 }, (table) => ({
   sourceNativeEventInboxUnique: uniqueIndex("idx_inbox_items_source_native_event_inbox")
     .on(table.sourceId, table.sourceNativeId, table.eventVariant, table.inboxId),
+  inboxSequenceUnique: uniqueIndex("idx_inbox_items_inbox_sequence").on(table.inboxSequence),
   ackedAtIdx: index("idx_inbox_items_acked_at").on(table.ackedAt),
   inboxAckedAtIdx: index("idx_inbox_items_inbox_acked_at").on(table.inboxId, table.ackedAt),
+  inboxSequenceIdx: index("idx_inbox_items_inbox_sequence_order").on(table.inboxId, table.inboxSequence),
   sourceOccurredAtIdx: index("idx_inbox_items_source_occurred_at").on(table.sourceId, table.occurredAt),
 }));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {
@@ -19,6 +19,7 @@
   },
   "files": [
     "dist/src/",
+    "scripts/",
     "drizzle/",
     "README.md",
     "LICENSE"

package/scripts/iterm2_cursor_probe.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""
+iTerm2 Python API cursor probe for AgentInbox.
+Returns session state including cursor position and buffer contents.
+"""
+
+import sys
+import json
+import asyncio
+
+
+def probe_session(connection, session_id):
+    """Probe iTerm2 session state and return cursor position with buffer contents."""
+    try:
+        import iterm2
+
+        async def get_session_state():
+            try:
+                app = await iterm2.async_get_app(connection)
+                session = app.get_session_by_id(session_id)
+
+                if not session:
+                    return {"status": "gone"}
+
+                screen = await session.async_get_screen_contents()
+                cursor = screen.cursor_coord
+
+                # Get the last few lines of content
+                lines = []
+                start_line = max(0, screen.number_of_lines - 5)
+                for i in range(start_line, screen.number_of_lines):
+                    try:
+                        line = screen.line(i)
+                        line_str = line.string if hasattr(line, 'string') else str(line)
+                        lines.append(line_str)
+                    except Exception:
+                        break
+
+                return {
+                    "status": "available",
+                    "cursor": {"x": cursor.x, "y": cursor.y},
+                    "screen_height": screen.number_of_lines,
+                    "start_line": start_line,
+                    "lines": lines
+                }
+            except Exception as e:
+                return {"status": "error", "error": str(e)}
+
+        return get_session_state()
+
+    except ImportError:
+        return {"status": "error", "error": "iterm2 module not installed"}
+
+
+def main():
+    if len(sys.argv) < 2:
+        result = {"status": "error", "error": "missing session_id argument"}
+        print(json.dumps(result))
+        sys.exit(1)
+
+    session_id = sys.argv[1]
+
+    # Try to import iterm2 and run the probe
+    try:
+        import iterm2
+        result = iterm2.run_until_complete(probe_session, session_id)
+        print(json.dumps(result))
+
+        # Exit with error code if status is not "available" or "gone"
+        if result.get("status") not in ["available", "gone"]:
+            sys.exit(1)
+        else:
+            sys.exit(0)
+
+    except ImportError:
+        result = {"status": "error", "error": "iterm2 module not installed"}
+        print(json.dumps(result))
+        sys.exit(1)
+    except Exception as e:
+        result = {"status": "error", "error": str(e)}
+        print(json.dumps(result))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()