@holon-run/agentinbox 0.3.0 → 0.5.0

package/README.md

@@ -136,12 +136,40 @@ Create a local source and publish an event:
 agentinbox source add local_event local-demo
 agentinbox subscription add <source_id>
 agentinbox subscription add <source_id> --agent-id <agent_id>
+agentinbox source schema <source_id>
+agentinbox subscription add <source_id> --shortcut pr --shortcut-args-json '{"number":373}'
 agentinbox subscription add <source_id> --tracked-resource-ref pr:373 --cleanup-policy-json '{"mode":"manual"}'
 agentinbox subscription add <source_id> --filter-file ./filter.json
 cat filter.json | agentinbox subscription add <source_id> --filter-stdin
 agentinbox source event <source_id> --native-id demo-1 --event local.demo
 agentinbox inbox read
 agentinbox inbox read --agent-id <agent_id>
+agentinbox inbox ack --agent-id <agent_id> --through <last_item_id>
+```
+
+When acking a reviewed batch, prefer `--through <last_item_id>` over `--all`.
+That preserves the boundary of the items you actually inspected. Use
+`ack --all` only when you have intentionally verified that every current
+unacked item should be cleared.
+
+Send a direct text message into an agent inbox:
+
+```bash
+agentinbox inbox send --agent-id <agent_id> --message "Please review PR #87"
+agentinbox inbox send --agent-id <agent_id> --message "CI failed on main" --sender operator
+```
+
+Schedule reminder messages with timers:
+
+```bash
+agentinbox timer add --agent-id <agent_id> --at <RFC3339_TIMESTAMP> --message "Check the morning build"
+agentinbox timer add --agent-id <agent_id> --every 24h --message "Review today's open PRs"
+agentinbox timer add --agent-id <agent_id> --cron "0 8 * * *" --timezone Asia/Shanghai --message "Daily triage"
+agentinbox timer list
+agentinbox timer list --agent-id <agent_id>
+agentinbox timer pause <schedule_id>
+agentinbox timer resume <schedule_id>
+agentinbox timer remove <schedule_id>
 ```
 
 Update an existing source in place:
@@ -164,6 +192,16 @@ Remove a task-specific subscription without deleting the whole agent:
 agentinbox subscription remove <subscription_id>
 ```
 
+For implementation-backed sources, inspect resolved subscription capabilities
+before adding task-scoped subscriptions:
+
+```bash
+agentinbox source schema <source_id>
+```
+
+If the source advertises subscription shortcuts, prefer them over manually
+repeating the equivalent filter, tracked resource ref, and cleanup policy.
+
 ## Docs
 
 Public docs live in the mdorigin site under [`docs/site`](./docs/site).

package/dist/src/cli.js

@@ -213,6 +213,14 @@ async function main() {
         await printRemote(client, `/agents/${encodeURIComponent(agentId)}`, undefined, "DELETE");
         return;
     }
+    if (command === "agent" && normalized[1] === "resume") {
+        const agentId = normalized[2];
+        if (!agentId) {
+            throw new Error("usage: agentinbox agent resume <agentId>");
+        }
+        await printRemote(client, `/agents/${encodeURIComponent(agentId)}/resume`, {});
+        return;
+    }
     if (command === "agent" && normalized[1] === "target" && normalized[2] === "add" && normalized[3] === "webhook") {
         const agentId = normalized[4];
         const url = takeFlagValue(normalized, "--url");
@@ -243,6 +251,14 @@ async function main() {
         await printRemote(client, `/agents/${encodeURIComponent(agentId)}/targets/${encodeURIComponent(targetId)}`, undefined, "DELETE");
         return;
     }
+    if (command === "agent" && normalized[1] === "target" && normalized[2] === "resume") {
+        const [agentId, targetId] = normalized.slice(3, 5);
+        if (!agentId || !targetId) {
+            throw new Error("usage: agentinbox agent target resume <agentId> <targetId>");
+        }
+        await printRemote(client, `/agents/${encodeURIComponent(agentId)}/targets/${encodeURIComponent(targetId)}/resume`, {});
+        return;
+    }
     if (command === "subscription" && normalized[1] === "add") {
         const args = normalized.slice(2);
         const positionals = positionalArgs(args, [
@@ -905,9 +921,11 @@ Usage:
   agentinbox agent current
   agentinbox agent show <agentId>
   agentinbox agent remove <agentId>
+  agentinbox agent resume <agentId>
   agentinbox agent target add webhook <agentId> --url URL [--activation-mode MODE] [--notify-lease-ms N]
   agentinbox agent target list <agentId>
   agentinbox agent target remove <agentId> <targetId>
+  agentinbox agent target resume <agentId> <targetId>
 `,
         timer: `agentinbox timer
 

package/dist/src/daemon.js

@@ -15,6 +15,7 @@ const node_child_process_1 = require("node:child_process");
 const client_1 = require("./client");
 const paths_1 = require("./paths");
 const START_TIMEOUT_MS = 15_000;
+const PACKAGE_VERSION = readOwnPackageVersion();
 async function ensureDaemonForClient(options = {}) {
     const transport = resolveDaemonClientTransport(options);
     if (options.noAutoStart || transport.kind !== "socket") {
@@ -95,14 +96,23 @@ async function daemonStatus(options = {}) {
         return {
             running: false,
             pid: null,
+            version: null,
+            startedAt: null,
+            command: null,
+            nodeVersion: null,
             pidPath,
             logPath,
             transport,
         };
     }
+    const processInfo = pid == null ? null : readProcessMetadata(pid);
     return {
         running: await canReachHealthz(transport),
         pid,
+        version: pid == null ? null : PACKAGE_VERSION,
+        startedAt: processInfo?.startedAt ?? null,
+        command: processInfo?.command ?? null,
+        nodeVersion: processInfo?.nodeVersion ?? null,
         pidPath,
         logPath,
         transport,
@@ -179,6 +189,24 @@ async function canReachHealthz(transport) {
         return false;
     }
 }
+function readOwnPackageVersion() {
+    const candidatePaths = [
+        node_path_1.default.join(__dirname, "..", "package.json"),
+        node_path_1.default.join(__dirname, "..", "..", "package.json"),
+    ];
+    for (const candidate of candidatePaths) {
+        try {
+            const parsed = JSON.parse(node_fs_1.default.readFileSync(candidate, "utf8"));
+            if (typeof parsed.version === "string" && parsed.version.length > 0) {
+                return parsed.version;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
 async function waitForHealthz(transport, timeoutMs) {
     const startedAt = Date.now();
     while (Date.now() - startedAt < timeoutMs) {
@@ -222,6 +250,47 @@ function readPidFile(pidPath) {
         return null;
     }
 }
+function readProcessMetadata(pid) {
+    try {
+        const output = (0, node_child_process_1.execFileSync)("ps", ["-o", "lstart=", "-o", "command=", "-p", String(pid)], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trimEnd();
+        if (!output) {
+            return null;
+        }
+        const firstNonSpace = output.search(/\S/);
+        if (firstNonSpace < 0) {
+            return null;
+        }
+        const trimmed = output.slice(firstNonSpace);
+        const match = trimmed.match(/^([A-Z][a-z]{2}\s+[A-Z][a-z]{2}\s+\d{1,2}\s+\d\d:\d\d:\d\d\s+\d{4})\s+(.*)$/);
+        if (!match) {
+            return {
+                startedAt: null,
+                command: trimmed,
+                nodeVersion: inferNodeVersionFromCommand(trimmed),
+            };
+        }
+        const [, startedAtRaw, command] = match;
+        const startedAtMs = Date.parse(startedAtRaw);
+        return {
+            startedAt: Number.isNaN(startedAtMs) ? null : new Date(startedAtMs).toISOString(),
+            command: command || null,
+            nodeVersion: inferNodeVersionFromCommand(command),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function inferNodeVersionFromCommand(command) {
+    if (!command) {
+        return null;
+    }
+    const match = command.match(/node\/(v\d+\.\d+\.\d+)\//);
+    return match ? match[1] : null;
+}
 function isProcessAlive(pid) {
     try {
         process.kill(pid, 0);

package/dist/src/http.js

@@ -487,6 +487,24 @@ function buildFastifyServer(service) {
         const params = request.params;
         return service.removeAgent(decodeURIComponent(params.agentId));
     });
+    app.post("/agents/:agentId/resume", {
+        schema: {
+            tags: ["agents"],
+            params: {
+                type: "object",
+                required: ["agentId"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        return service.resumeAgent(decodeURIComponent(params.agentId));
+    });
     app.get("/agents/:agentId/targets", {
         schema: {
             tags: ["agents"],
@@ -565,6 +583,25 @@ function buildFastifyServer(service) {
         const params = request.params;
         return service.removeActivationTarget(decodeURIComponent(params.agentId), decodeURIComponent(params.targetId));
     });
+    app.post("/agents/:agentId/targets/:targetId/resume", {
+        schema: {
+            tags: ["agents"],
+            params: {
+                type: "object",
+                required: ["agentId", "targetId"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                    targetId: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        return service.resumeActivationTarget(decodeURIComponent(params.agentId), decodeURIComponent(params.targetId));
+    });
     app.get("/timers", {
         schema: {
             tags: ["timers"],

package/dist/src/runtime_gate.js

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ClaudeCodeTerminalStateProbe = exports.ClaudeCodeRuntimePresenceProbe = exports.TmuxTerminalStateProbe = exports.Iterm2TerminalStateProbe = exports.CodexRuntimePresenceProbe = exports.DefaultActivationGate = void 0;
+exports.ClaudeCodeTerminalStateProbe = exports.ClaudeCodeRuntimePresenceProbe = exports.TmuxTerminalStateProbe = exports.Iterm2TerminalStateProbe = exports.CodexTerminalStateProbe = exports.CodexRuntimePresenceProbe = exports.DefaultActivationGate = void 0;
+exports.readFirstLine = readFirstLine;
 const node_child_process_1 = require("node:child_process");
 const node_util_1 = require("node:util");
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -28,6 +29,7 @@ class DefaultActivationGate {
         new CodexRuntimePresenceProbe(),
         new ClaudeCodeRuntimePresenceProbe(),
     ], terminalProbes = [
+        new CodexTerminalStateProbe(),
         new Iterm2TerminalStateProbe(),
         new ClaudeCodeTerminalStateProbe(),
         new TmuxTerminalStateProbe(),
@@ -38,27 +40,32 @@ class DefaultActivationGate {
     async evaluate(target) {
         const runtimeProbe = this.runtimeProbes.find((probe) => probe.supports(target));
         const runtimePresence = runtimeProbe ? await runtimeProbe.check(target) : "unknown";
+        if (runtimePresence === "gone") {
+            return { outcome: "offline", reason: "runtime_gone" };
+        }
         const terminalProbe = this.terminalProbes.find((probe) => probe.supports(target));
         const terminalState = terminalProbe
             ? await terminalProbe.check(target)
             : { presence: "unknown", busy: "unknown" };
-        if (runtimePresence === "gone") {
-            return { outcome: "offline", reason: "runtime_gone" };
-        }
         if (terminalState.presence === "gone") {
             return { outcome: "offline", reason: "terminal_gone" };
         }
         if (terminalState.busy === "busy") {
             return { outcome: "defer", reason: "terminal_busy" };
         }
+        if (target.runtimeKind === "codex" && terminalState.busy === "idle") {
+            return { outcome: "defer", reason: "terminal_recently_active" };
+        }
         return { outcome: "inject", reason: "gate_unknown_or_idle" };
     }
 }
 exports.DefaultActivationGate = DefaultActivationGate;
 class CodexRuntimePresenceProbe {
     killFn;
-    constructor(killFn = (pid, signal) => process.kill(pid, signal)) {
+    sessionFileReader;
+    constructor(killFn = (pid, signal) => process.kill(pid, signal), sessionFileReader) {
         this.killFn = killFn;
+        this.sessionFileReader = sessionFileReader;
     }
     supports(target) {
         return target.runtimeKind === "codex" && Number.isInteger(target.runtimePid);
@@ -69,6 +76,16 @@ class CodexRuntimePresenceProbe {
         }
         try {
             this.killFn(target.runtimePid, 0);
+            if (!target.runtimeSessionId) {
+                return "unknown";
+            }
+            const sessionInfo = await (this.sessionFileReader ?? defaultCodexSessionFileReader)(target.runtimeSessionId);
+            if (sessionInfo === "unknown") {
+                return "unknown";
+            }
+            if (!sessionInfo || sessionInfo.sessionId !== target.runtimeSessionId) {
+                return "gone";
+            }
             return "alive";
         }
         catch (error) {
@@ -81,6 +98,58 @@ class CodexRuntimePresenceProbe {
     }
 }
 exports.CodexRuntimePresenceProbe = CodexRuntimePresenceProbe;
+class CodexTerminalStateProbe {
+    iTermProbe;
+    tmuxProbe;
+    sessionFileReader;
+    statReader;
+    nowFn;
+    constructor(iTermProbe = new Iterm2TerminalStateProbe(), tmuxProbe = new TmuxTerminalStateProbe(), sessionFileReader, statReader, nowFn = () => Date.now()) {
+        this.iTermProbe = iTermProbe;
+        this.tmuxProbe = tmuxProbe;
+        this.sessionFileReader = sessionFileReader;
+        this.statReader = statReader;
+        this.nowFn = nowFn;
+    }
+    supports(target) {
+        return target.runtimeKind === "codex";
+    }
+    async check(target) {
+        const terminalState = await this.readTerminalState(target);
+        if (!target.runtimeSessionId) {
+            return terminalState;
+        }
+        const sessionInfo = await (this.sessionFileReader ?? defaultCodexSessionFileReader)(target.runtimeSessionId);
+        if (sessionInfo === "unknown" || !sessionInfo || sessionInfo.sessionId !== target.runtimeSessionId) {
+            return terminalState;
+        }
+        const stat = await (this.statReader ?? defaultFileStatReader)(sessionInfo.filePath);
+        if (!stat) {
+            return terminalState;
+        }
+        if (terminalState.busy === "busy" || terminalState.presence === "gone") {
+            return terminalState;
+        }
+        const ageMs = this.nowFn() - stat.mtimeMs;
+        if (ageMs < 5000) {
+            return { presence: terminalState.presence, busy: "busy" };
+        }
+        if (ageMs < 30000) {
+            return { presence: terminalState.presence, busy: "idle" };
+        }
+        return terminalState;
+    }
+    async readTerminalState(target) {
+        if (this.iTermProbe.supports(target)) {
+            return this.iTermProbe.check(target);
+        }
+        if (this.tmuxProbe.supports(target)) {
+            return this.tmuxProbe.check(target);
+        }
+        return { presence: "unknown", busy: "unknown" };
+    }
+}
+exports.CodexTerminalStateProbe = CodexTerminalStateProbe;
 class Iterm2TerminalStateProbe {
     execAsync;
     options;
@@ -128,16 +197,16 @@ class Iterm2TerminalStateProbe {
         if (containsActiveBufferMarker(second)) {
             return { presence: "available", busy: "busy" };
         }
+        if (hasVisibleTypingPrompt(second)) {
+            return { presence: "available", busy: "busy" };
+        }
         return { presence: "available", busy: "unknown" };
     }
     async checkSessionPresence(it2api, sessionId) {
         try {
             const result = await this.execAsync(it2api, ["list-sessions"]);
-            const sessions = result.stdout
-                .split(/\r?\n/)
-                .map((line) => line.trim())
-                .filter((line) => line.length > 0);
-            return sessions.includes(sessionId) ? "available" : "gone";
+            const sessionIds = parseIterm2SessionIds(result.stdout);
+            return sessionIds.includes(sessionId) ? "available" : "gone";
         }
         catch {
             return "unknown";
@@ -284,6 +353,114 @@ function resolveIterm2ApiPath(override) {
 async function sleep(ms) {
     await new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function defaultFileStatReader(filePath) {
+    try {
+        const stats = await node_fs_1.default.promises.stat(filePath);
+        return { mtimeMs: stats.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+async function defaultCodexSessionFileReader(sessionId) {
+    const sessionsRoot = node_path_1.default.join(node_os_1.default.homedir(), ".codex", "sessions");
+    const filePath = await findCodexSessionFile(sessionsRoot, sessionId).catch(() => "unknown");
+    if (filePath === "unknown") {
+        return "unknown";
+    }
+    if (!filePath) {
+        return null;
+    }
+    try {
+        const firstLine = await readFirstLine(filePath);
+        if (!firstLine) {
+            return "unknown";
+        }
+        const record = JSON.parse(firstLine);
+        const parsedSessionId = typeof record.payload?.id === "string" ? record.payload.id : null;
+        if (record.type !== "session_meta" || parsedSessionId !== sessionId) {
+            return "unknown";
+        }
+        return {
+            sessionId: parsedSessionId,
+            filePath,
+            cwd: typeof record.payload?.cwd === "string" ? record.payload.cwd : null,
+        };
+    }
+    catch {
+        return "unknown";
+    }
+}
+async function findCodexSessionFile(root, sessionId) {
+    let years;
+    try {
+        years = await node_fs_1.default.promises.readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    for (const year of years) {
+        if (!year.isDirectory()) {
+            continue;
+        }
+        const yearPath = node_path_1.default.join(root, year.name);
+        const match = await walkCodexSessionLevel(yearPath, sessionId, 2);
+        if (match) {
+            return match;
+        }
+    }
+    return null;
+}
+async function walkCodexSessionLevel(dir, sessionId, depth) {
+    let entries;
+    try {
+        entries = await node_fs_1.default.promises.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        const entryPath = node_path_1.default.join(dir, entry.name);
+        if (entry.isFile() && entry.name.endsWith(`${sessionId}.jsonl`)) {
+            return entryPath;
+        }
+        if (entry.isDirectory() && depth > 0) {
+            const match = await walkCodexSessionLevel(entryPath, sessionId, depth - 1);
+            if (match) {
+                return match;
+            }
+        }
+    }
+    return null;
+}
+async function readFirstLine(filePath) {
+    const handle = await node_fs_1.default.promises.open(filePath, "r");
+    try {
+        const chunkSize = 4096;
+        const chunks = [];
+        let position = 0;
+        while (true) {
+            const buffer = Buffer.alloc(chunkSize);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+            if (bytesRead <= 0) {
+                break;
+            }
+            const chunk = buffer.toString("utf8", 0, bytesRead);
+            const newline = chunk.indexOf("\n");
+            if (newline >= 0) {
+                chunks.push(chunk.slice(0, newline));
+                break;
+            }
+            chunks.push(chunk);
+            position += bytesRead;
+        }
+        const firstLine = chunks.join("").trim();
+        return firstLine.length > 0 ? firstLine : null;
+    }
+    finally {
+        await handle.close();
+    }
+}
 function isTmuxMissingPaneError(error) {
     if (!(error instanceof Error)) {
         return false;
@@ -446,14 +623,7 @@ class ClaudeCodeTerminalStateProbe {
         try {
             const it2api = resolveIterm2ApiPath();
             const result = await execFileAsync(it2api, ["list-sessions"]);
-            const lines = result.stdout.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
-            // Parse session IDs from iTerm2 output format: "Session \"...\" id=<UUID> ..."
-            const sessionIds = lines
-                .map((line) => {
-                const match = line.match(/id=([A-F0-9-]+)/);
-                return match ? match[1] : null;
-            })
-                .filter((id) => id !== null);
+            const sessionIds = parseIterm2SessionIds(result.stdout);
             return sessionIds.includes(itermSessionId) ? "available" : "gone";
         }
         catch {
@@ -462,3 +632,14 @@ class ClaudeCodeTerminalStateProbe {
     }
 }
 exports.ClaudeCodeTerminalStateProbe = ClaudeCodeTerminalStateProbe;
+function parseIterm2SessionIds(stdout) {
+    return stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        const match = line.match(/\bid=([A-F0-9-]+)/i);
+        return match ? match[1] : null;
+    })
+        .filter((id) => id !== null);
+}

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");
@@ -531,6 +532,57 @@ class AgentInboxService {
         this.reconcileAgentStatus(agentId);
         return { removed: true };
     }
+    async resumeAgent(agentId) {
+        this.getAgent(agentId);
+        const targets = this.store.listActivationTargetsForAgent(agentId);
+        const results = [];
+        for (const target of targets) {
+            results.push(await this.resumeActivationTarget(agentId, target.targetId));
+        }
+        this.reconcileAgentStatus(agentId);
+        return {
+            resumed: results.some((result) => result.resumed),
+            agent: this.getAgent(agentId),
+            targets: results,
+        };
+    }
+    async resumeActivationTarget(agentId, targetId) {
+        const target = this.getActivationTarget(targetId);
+        if (target.agentId !== agentId) {
+            throw new Error(`activation target ${targetId} does not belong to agent ${agentId}`);
+        }
+        if (target.status === "active") {
+            return {
+                targetId: target.targetId,
+                resumed: false,
+                status: target.status,
+                reason: "already_active",
+            };
+        }
+        let result;
+        if (target.kind === "terminal") {
+            result = await this.resumeTerminalActivationTarget(target);
+        }
+        else {
+            const now = (0, util_1.nowIso)();
+            this.store.updateActivationTargetRuntime(target.targetId, {
+                status: "active",
+                offlineSince: null,
+                consecutiveFailures: 0,
+                lastError: null,
+                updatedAt: now,
+                lastSeenAt: now,
+            });
+            result = {
+                targetId: target.targetId,
+                resumed: true,
+                status: "active",
+                reason: "webhook_resumed",
+            };
+        }
+        this.reconcileAgentStatus(agentId);
+        return result;
+    }
     async registerSubscription(input) {
         if (input.shortcut) {
             const source = this.store.getSource(input.sourceId);
@@ -1355,14 +1407,27 @@ class AgentInboxService {
         try {
             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,
-                    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);
@@ -1374,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)(),
@@ -1424,10 +1490,25 @@ 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,
             newItemCount: state.pendingNewItemCount > 0 ? state.pendingNewItemCount : unacked,
+            totalUnackedCount: unacked,
             summary: state.pendingSummary,
             subscriptionIds: state.pendingSubscriptionIds,
             sourceIds: state.pendingSourceIds,
@@ -1461,8 +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);
@@ -1477,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),
@@ -1485,11 +1570,32 @@ class AgentInboxService {
                     });
                     return "deferred";
                 }
+                const preview = totalUnackedCount === 1 && input.items.length === 1
+                    ? (0, terminal_1.deriveInlineItemPreview)(input.items[0], input.summary)
+                    : null;
                 const prompt = (0, terminal_1.renderAgentPrompt)({
                     inboxId: inbox.inboxId,
-                    newItemCount: input.newItemCount,
+                    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 {
@@ -1518,6 +1624,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: [],
@@ -1547,8 +1656,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)(),
@@ -1644,6 +1754,46 @@ class AgentInboxService {
             lastSeenAt: agent.lastSeenAt,
         });
     }
+    async resumeTerminalActivationTarget(target) {
+        const probeStatus = await this.terminalDispatcher.probeStatus(target);
+        const now = (0, util_1.nowIso)();
+        if (probeStatus === "available") {
+            this.store.updateActivationTargetRuntime(target.targetId, {
+                status: "active",
+                offlineSince: null,
+                consecutiveFailures: 0,
+                lastError: null,
+                updatedAt: now,
+                lastSeenAt: now,
+            });
+            return {
+                targetId: target.targetId,
+                resumed: true,
+                status: "active",
+                reason: "terminal_available",
+            };
+        }
+        if (probeStatus === "gone") {
+            this.store.updateActivationTargetRuntime(target.targetId, {
+                status: "offline",
+                offlineSince: target.offlineSince ?? now,
+                updatedAt: now,
+                lastError: target.lastError ?? "terminal gone",
+            });
+            return {
+                targetId: target.targetId,
+                resumed: false,
+                status: "offline",
+                reason: "terminal_gone",
+            };
+        }
+        return {
+            targetId: target.targetId,
+            resumed: false,
+            status: "offline",
+            reason: "probe_unknown",
+        };
+    }
     runLifecycleCleanupPass(nowMs) {
         this.lastLifecycleCleanupAt = nowMs;
         const removed = new Set();
@@ -2193,6 +2343,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/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),
@@ -1251,6 +1253,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,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TerminalDispatcher = void 0;
 exports.detectTerminalContext = detectTerminalContext;
 exports.renderAgentPrompt = renderAgentPrompt;
+exports.deriveInlineItemPreview = deriveInlineItemPreview;
 exports.assignedAgentIdFromContext = assignedAgentIdFromContext;
 const node_child_process_1 = require("node:child_process");
 const node_util_1 = require("node:util");
@@ -46,12 +47,44 @@ function detectTerminalContext(env = process.env) {
     throw new Error("unable to detect a supported terminal context");
 }
 function renderAgentPrompt(input) {
-    const base = `AgentInbox: ${input.newItemCount} new items arrived in inbox ${input.inboxId}.`;
+    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 = normalizeInlinePreview(candidate);
+        if (preview) {
+            return preview;
+        }
+    }
+    return null;
+}
 function assignedAgentIdFromContext(input) {
     const primary = normalizeOptionalString(input.runtimeSessionId)
         ?? normalizeOptionalString(input.tmuxPaneId)
@@ -90,31 +123,44 @@ class TerminalDispatcher {
         throw new Error(`unsupported terminal backend: ${String(target.backend)}`);
     }
     async probe(target) {
+        return (await this.probeStatus(target)) === "available";
+    }
+    async probeStatus(target) {
         try {
             if (target.backend === "tmux") {
                 if (!target.tmuxPaneId) {
-                    return false;
+                    return "unknown";
                 }
                 const result = await this.execAsync("tmux", ["display-message", "-p", "-t", target.tmuxPaneId, "#{pane_id}"]);
-                return result.stdout.trim() === target.tmuxPaneId;
+                return result.stdout.trim() === target.tmuxPaneId ? "available" : "gone";
             }
             if (target.backend === "iterm2") {
                 const sessionId = normalizeOptionalString(target.itermSessionId);
                 if (!sessionId) {
-                    return false;
+                    return "unknown";
                 }
                 const it2api = resolveIterm2ApiPath(this.options.iterm2ApiPath);
                 const result = await this.execAsync(it2api, ["list-sessions"]);
-                return result.stdout.includes(sessionId);
+                return result.stdout.includes(sessionId) ? "available" : "gone";
             }
         }
-        catch {
-            return false;
+        catch (error) {
+            if (target.backend === "tmux" && isTmuxMissingPaneError(error)) {
+                return "gone";
+            }
+            return "unknown";
         }
-        return false;
+        return "unknown";
     }
 }
 exports.TerminalDispatcher = TerminalDispatcher;
+function isTmuxMissingPaneError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const candidate = `${error.message} ${"stderr" in error ? String(error.stderr ?? "") : ""}`;
+    return candidate.includes("can't find pane");
+}
 function detectTty(env) {
     const direct = tryReadCurrentTty();
     if (direct) {
@@ -161,6 +207,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/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(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {
@@ -49,8 +49,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"