@holon-run/agentinbox 0.4.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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ActivationDispatcher = exports.AgentInboxService = void 0;
+const node_crypto_1 = require("node:crypto");
 const backend_1 = require("./backend");
 const util_1 = require("./util");
 const source_schema_1 = require("./source_schema");
@@ -1407,15 +1408,26 @@ class AgentInboxService {
             const state = this.store.getActivationDispatchState(buffer.agentId, buffer.targetId);
             if (!state) {
                 const inbox = this.ensureInboxForAgent(buffer.agentId);
+                const unackedItems = this.store.listInboxItems(inbox.inboxId, { includeAcked: false }).map((item) => ({
+                    itemId: item.itemId,
+                    sourceId: item.sourceId,
+                    sourceNativeId: item.sourceNativeId,
+                    eventVariant: item.eventVariant,
+                    inboxId: item.inboxId,
+                    occurredAt: item.occurredAt,
+                    metadata: item.metadata,
+                    rawPayload: item.rawPayload,
+                    deliveryHandle: item.deliveryHandle,
+                }));
                 const dispatched = await this.dispatchActivationTarget({
                     agentId: buffer.agentId,
                     targetId: buffer.targetId,
                     newItemCount: entries.length,
-                    totalUnackedCount: this.store.countInboxItems(inbox.inboxId, false),
-                    summary: entries[0]?.summary ?? null,
+                    totalUnackedCount: unackedItems.length,
+                    summary: latestSummary(entries),
                     subscriptionIds: uniqueSortedNullable(entries.map((entry) => entry.subscriptionId)),
                     sourceIds: uniqueSorted(entries.map((entry) => entry.sourceId)),
-                    items: entries.map((entry) => entry.item),
+                    items: unackedItems,
                 });
                 if (dispatched === "retryable_failure") {
                     this.upsertDirtyDispatchState(buffer.agentId, buffer.targetId, entries);
@@ -1427,8 +1439,9 @@ class AgentInboxService {
                     targetId: buffer.targetId,
                     status: "dirty",
                     leaseExpiresAt: state.leaseExpiresAt,
+                    lastNotifiedFingerprint: state.lastNotifiedFingerprint,
                     pendingNewItemCount: state.pendingNewItemCount + entries.length,
-                    pendingSummary: state.pendingSummary ?? entries[0]?.summary ?? null,
+                    pendingSummary: latestSummary(entries) ?? state.pendingSummary,
                     pendingSubscriptionIds: uniqueSortedNullable([...state.pendingSubscriptionIds, ...entries.map((entry) => entry.subscriptionId)]),
                     pendingSourceIds: uniqueSorted([...state.pendingSourceIds, ...entries.map((entry) => entry.sourceId)]),
                     updatedAt: (0, util_1.nowIso)(),
@@ -1477,6 +1490,20 @@ class AgentInboxService {
         if (reason === "ack" && state.status !== "dirty") {
             return;
         }
+        if (reason === "lease" && state.status === "notified") {
+            const target = this.getActivationTarget(targetId);
+            if (target.kind !== "terminal") {
+                // Webhook targets keep the existing lease-based behavior.
+            }
+            else {
+                this.store.upsertActivationDispatchState({
+                    ...state,
+                    leaseExpiresAt: new Date(Date.now() + target.notifyLeaseMs).toISOString(),
+                    updatedAt: (0, util_1.nowIso)(),
+                });
+                return;
+            }
+        }
         const dispatched = await this.dispatchActivationTarget({
             agentId,
             targetId,
@@ -1515,9 +1542,11 @@ class AgentInboxService {
         if (target.status === "offline") {
             return "offline";
         }
+        const state = this.store.getActivationDispatchState(input.agentId, input.targetId);
         const inbox = this.ensureInboxForAgent(input.agentId);
         const summary = summarizeActivation(inbox.inboxId, input.newItemCount, input.summary);
         const totalUnackedCount = input.totalUnackedCount ?? this.store.countInboxItems(inbox.inboxId, false);
+        let terminalPrompt = null;
         try {
             if (target.kind === "terminal") {
                 const gate = await this.activationGate.evaluate(target);
@@ -1532,6 +1561,7 @@ class AgentInboxService {
                         targetId: input.targetId,
                         status: "dirty",
                         leaseExpiresAt: new Date(Date.now() + DEFAULT_NOTIFY_RETRY_MS).toISOString(),
+                        lastNotifiedFingerprint: state?.lastNotifiedFingerprint ?? null,
                         pendingNewItemCount: input.newItemCount,
                         pendingSummary: input.summary,
                         pendingSubscriptionIds: uniqueSortedNullable(input.subscriptionIds),
@@ -1540,11 +1570,44 @@ class AgentInboxService {
                     });
                     return "deferred";
                 }
+                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,
                     summary: input.summary,
+                    preview,
                 });
+                terminalPrompt = prompt;
+                const promptFingerprint = terminalReminderFingerprint(prompt, input.items);
+                if (state?.status === "dirty" && state.lastNotifiedFingerprint === promptFingerprint) {
+                    this.store.upsertActivationDispatchState({
+                        agentId: input.agentId,
+                        targetId: input.targetId,
+                        status: "notified",
+                        leaseExpiresAt: new Date(Date.now() + target.notifyLeaseMs).toISOString(),
+                        lastNotifiedFingerprint: promptFingerprint,
+                        pendingNewItemCount: 0,
+                        pendingSummary: null,
+                        pendingSubscriptionIds: [],
+                        pendingSourceIds: [],
+                        updatedAt: (0, util_1.nowIso)(),
+                    });
+                    return "suppressed";
+                }
                 await this.terminalDispatcher.dispatch(target, prompt);
             }
             else {
@@ -1573,6 +1636,9 @@ class AgentInboxService {
                 targetId: input.targetId,
                 status: "notified",
                 leaseExpiresAt: new Date(Date.now() + target.notifyLeaseMs).toISOString(),
+                lastNotifiedFingerprint: target.kind === "terminal"
+                    ? terminalReminderFingerprint(terminalPrompt ?? "", input.items)
+                    : state?.lastNotifiedFingerprint ?? null,
                 pendingNewItemCount: 0,
                 pendingSummary: null,
                 pendingSubscriptionIds: [],
@@ -1602,8 +1668,9 @@ class AgentInboxService {
             targetId,
             status: "dirty",
             leaseExpiresAt: new Date(Date.now() + DEFAULT_NOTIFY_RETRY_MS).toISOString(),
+            lastNotifiedFingerprint: this.store.getActivationDispatchState(agentId, targetId)?.lastNotifiedFingerprint ?? null,
             pendingNewItemCount: entries.length,
-            pendingSummary: entries[0]?.summary ?? null,
+            pendingSummary: latestSummary(entries),
             pendingSubscriptionIds: uniqueSortedNullable(entries.map((entry) => entry.subscriptionId)),
             pendingSourceIds: uniqueSorted(entries.map((entry) => entry.sourceId)),
             updatedAt: (0, util_1.nowIso)(),
@@ -2288,6 +2355,24 @@ function summarizeActivation(inboxId, newItemCount, firstSummary) {
     }
     return `${newItemCount} new ${itemWord} in ${inboxId}`;
 }
+function latestSummary(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const summary = entries[index]?.summary;
+        if (summary) {
+            return summary;
+        }
+    }
+    return null;
+}
+function terminalReminderFingerprint(prompt, items) {
+    const payload = JSON.stringify({
+        prompt,
+        itemIds: items
+            .map((item) => item.itemId)
+            .sort((left, right) => left.localeCompare(right)),
+    });
+    return (0, node_crypto_1.createHash)("sha256").update(payload).digest("hex");
+}
 function summarizeSourceEvent(sourceType, sourceKey, eventVariant) {
     if (sourceType === "github_repo_ci") {
         const parts = eventVariant.split(".");

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

@@ -729,12 +729,13 @@ class AgentInboxStore {
     upsertActivationDispatchState(state) {
         this.db.run(`
       insert into activation_dispatch_states (
-        agent_id, target_id, status, lease_expires_at, pending_new_item_count, pending_summary,
+        agent_id, target_id, status, lease_expires_at, last_notified_fingerprint, pending_new_item_count, pending_summary,
         pending_subscription_ids_json, pending_source_ids_json, updated_at
-      ) values (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       on conflict(agent_id, target_id) do update set
         status = excluded.status,
         lease_expires_at = excluded.lease_expires_at,
+        last_notified_fingerprint = excluded.last_notified_fingerprint,
         pending_new_item_count = excluded.pending_new_item_count,
         pending_summary = excluded.pending_summary,
         pending_subscription_ids_json = excluded.pending_subscription_ids_json,
@@ -745,6 +746,7 @@ class AgentInboxStore {
             state.targetId,
             state.status,
             state.leaseExpiresAt ?? null,
+            state.lastNotifiedFingerprint ?? null,
             state.pendingNewItemCount,
             state.pendingSummary ?? null,
             JSON.stringify(state.pendingSubscriptionIds),
@@ -778,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;
@@ -790,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) {
@@ -816,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}`);
         }
@@ -825,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();
@@ -1251,6 +1259,7 @@ class AgentInboxStore {
             targetId: String(row.target_id),
             status: row.status,
             leaseExpiresAt: row.lease_expires_at ? String(row.lease_expires_at) : null,
+            lastNotifiedFingerprint: row.last_notified_fingerprint ? String(row.last_notified_fingerprint) : null,
             pendingNewItemCount: Number(row.pending_new_item_count),
             pendingSummary: row.pending_summary ? String(row.pending_summary) : null,
             pendingSubscriptionIds: parseJson(row.pending_subscription_ids_json),

package/dist/src/terminal.js

@@ -6,6 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 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");
@@ -49,11 +51,44 @@ function renderAgentPrompt(input) {
     const totalUnackedCount = input.totalUnackedCount ?? input.newItemCount ?? 0;
     const itemWord = totalUnackedCount === 1 ? "item" : "items";
     const base = `AgentInbox: ${totalUnackedCount} unacked ${itemWord} in inbox ${input.inboxId}.`;
+    if (totalUnackedCount === 1 && input.preview) {
+        const suffix = /(?:[.!?…]|\.{3})$/.test(input.preview) ? "" : ".";
+        return `${base} Preview: ${input.preview}${suffix} Read the inbox for full details if needed.`;
+    }
     if (input.summary) {
         return `${base} Summary: ${input.summary}. Please read the inbox, process them, and ack when finished.`;
     }
     return `${base} Please read the inbox, process them, and ack when finished.`;
 }
+const MAX_INLINE_PREVIEW_INPUT_CHARS = 240;
+const MAX_INLINE_PREVIEW_CHARS = 96;
+const INLINE_PREVIEW_KEYS = ["message", "text", "body", "title"];
+function deriveInlineItemPreview(item, summary) {
+    const candidates = [];
+    for (const key of INLINE_PREVIEW_KEYS) {
+        const rawPayloadValue = item.rawPayload[key];
+        if (typeof rawPayloadValue === "string") {
+            candidates.push(rawPayloadValue);
+        }
+        const metadataValue = item.metadata[key];
+        if (typeof metadataValue === "string") {
+            candidates.push(metadataValue);
+        }
+    }
+    if (isPreviewFriendlySummary(summary)) {
+        candidates.push(summary);
+    }
+    for (const candidate of candidates) {
+        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)
@@ -176,6 +211,44 @@ function normalizeItermSessionId(raw) {
     const parts = value.split(":");
     return parts[parts.length - 1] || null;
 }
+function normalizeInlinePreview(value) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (!normalized) {
+        return null;
+    }
+    if (normalized.length > MAX_INLINE_PREVIEW_INPUT_CHARS) {
+        return null;
+    }
+    if (looksStructured(normalized)) {
+        return null;
+    }
+    if (normalized.length <= MAX_INLINE_PREVIEW_CHARS) {
+        return normalized;
+    }
+    return `${normalized.slice(0, MAX_INLINE_PREVIEW_CHARS - 3).trimEnd()}...`;
+}
+function isPreviewFriendlySummary(summary) {
+    if (typeof summary !== "string") {
+        return false;
+    }
+    const normalized = summary.trim();
+    if (!normalized) {
+        return false;
+    }
+    if (!normalized.includes(" ")) {
+        return false;
+    }
+    if (/^[a-z0-9_.-]+:/i.test(normalized)) {
+        return false;
+    }
+    return true;
+}
+function looksStructured(value) {
+    if ((value.startsWith("{") && value.endsWith("}")) || (value.startsWith("[") && value.endsWith("]"))) {
+        return true;
+    }
+    return false;
+}
 function detectRuntimeContext(env) {
     const codexThreadId = normalizeOptionalString(env.CODEX_THREAD_ID);
     if (codexThreadId) {

package/drizzle/migrations/0007_activation_dispatch_last_notified_fingerprint.sql

@@ -0,0 +1,2 @@
+alter table activation_dispatch_states
+  add column last_notified_fingerprint text;

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

@@ -122,6 +122,7 @@ export const activationDispatchStates = sqliteTable("activation_dispatch_states"
   targetId: text("target_id").notNull(),
   status: text("status").notNull(),
   leaseExpiresAt: text("lease_expires_at"),
+  lastNotifiedFingerprint: text("last_notified_fingerprint"),
   pendingNewItemCount: integer("pending_new_item_count").notNull(),
   pendingSummary: text("pending_summary"),
   pendingSubscriptionIdsJson: text("pending_subscription_ids_json").notNull(),
@@ -138,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(),
@@ -146,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.4.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"
@@ -49,8 +50,8 @@
   "devDependencies": {
     "@types/node": "^24.5.2",
     "@types/sql.js": "^1.4.9",
-    "drizzle-kit": "^0.31.6",
-    "drizzle-orm": "^0.44.2",
+    "drizzle-kit": "1.0.0-beta.21",
+    "drizzle-orm": "^0.45.2",
     "mdorigin": "^0.5.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.2"

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()