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

@@ -180,6 +180,7 @@ async function main() {
             backend: detected.backend,
             runtimeKind: detected.runtimeKind,
             runtimeSessionId: detected.runtimeSessionId ?? undefined,
+            runtimePid: detected.runtimePid ?? undefined,
             tmuxPaneId: detected.tmuxPaneId ?? undefined,
             tty: detected.tty ?? undefined,
             termProgram: detected.termProgram ?? undefined,
@@ -212,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");
@@ -242,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, [
@@ -344,6 +361,62 @@ async function main() {
         });
         return;
     }
+    if (command === "timer" && normalized[1] === "add") {
+        const args = normalized.slice(2);
+        const allowedFlags = ["--agent-id", "--at", "--every", "--cron", "--timezone", "--message", "--sender"];
+        if (positionalArgs(args, ["--agent-id", "--at", "--every", "--cron", "--timezone", "--message", "--sender"]).length > 0 || unexpectedFlags(args, allowedFlags).length > 0) {
+            throw new Error("usage: agentinbox timer add --agent-id ID (--at ISO8601 | --every DURATION | --cron EXPR) --message TEXT [--timezone TZ] [--sender SENDER]");
+        }
+        const agentId = takeFlagValue(normalized, "--agent-id");
+        const message = takeFlagValue(normalized, "--message");
+        const at = takeFlagValue(normalized, "--at");
+        const every = takeFlagValue(normalized, "--every");
+        const cron = takeFlagValue(normalized, "--cron");
+        if (!agentId || !message || [at, every, cron].filter(Boolean).length !== 1) {
+            throw new Error("usage: agentinbox timer add --agent-id ID (--at ISO8601 | --every DURATION | --cron EXPR) --message TEXT [--timezone TZ] [--sender SENDER]");
+        }
+        await printRemote(client, "/timers", {
+            agentId,
+            at: at ?? undefined,
+            every: every ? parseDurationMs(every) : undefined,
+            cron: cron ?? undefined,
+            timezone: takeFlagValue(normalized, "--timezone") ?? undefined,
+            message,
+            sender: takeFlagValue(normalized, "--sender") ?? undefined,
+        });
+        return;
+    }
+    if (command === "timer" && normalized[1] === "list") {
+        const query = buildQuery({
+            agent_id: takeFlagValue(normalized, "--agent-id"),
+        });
+        await printRemote(client, `/timers${query}`, undefined, "GET");
+        return;
+    }
+    if (command === "timer" && normalized[1] === "pause") {
+        const scheduleId = normalized[2];
+        if (!scheduleId) {
+            throw new Error("usage: agentinbox timer pause <scheduleId>");
+        }
+        await printRemote(client, `/timers/${encodeURIComponent(scheduleId)}/pause`, {});
+        return;
+    }
+    if (command === "timer" && normalized[1] === "resume") {
+        const scheduleId = normalized[2];
+        if (!scheduleId) {
+            throw new Error("usage: agentinbox timer resume <scheduleId>");
+        }
+        await printRemote(client, `/timers/${encodeURIComponent(scheduleId)}/resume`, {});
+        return;
+    }
+    if (command === "timer" && normalized[1] === "remove") {
+        const scheduleId = normalized[2];
+        if (!scheduleId) {
+            throw new Error("usage: agentinbox timer remove <scheduleId>");
+        }
+        await printRemote(client, `/timers/${encodeURIComponent(scheduleId)}`, undefined, "DELETE");
+        return;
+    }
     if (command === "inbox" && normalized[1] === "list") {
         await printRemote(client, "/agents", undefined, "GET");
         return;
@@ -374,6 +447,23 @@ async function main() {
         console.log((0, util_1.jsonResponse)(withCommandMetadata(response.data, selection)));
         return;
     }
+    if (command === "inbox" && normalized[1] === "send") {
+        const args = normalized.slice(2);
+        const allowedFlags = ["--agent-id", "--message", "--sender"];
+        if (positionalArgs(args, ["--agent-id", "--message", "--sender"]).length > 0 || unexpectedFlags(args, allowedFlags).length > 0) {
+            throw new Error("usage: agentinbox inbox send --agent-id ID --message TEXT [--sender SENDER]");
+        }
+        const agentId = takeFlagValue(normalized, "--agent-id");
+        const message = takeFlagValue(normalized, "--message");
+        if (!agentId || !message) {
+            throw new Error("usage: agentinbox inbox send --agent-id ID --message TEXT [--sender SENDER]");
+        }
+        await printRemote(client, `/agents/${encodeURIComponent(agentId)}/inbox/items`, {
+            message,
+            sender: takeFlagValue(normalized, "--sender") ?? undefined,
+        });
+        return;
+    }
     if (command === "inbox" && normalized[1] === "watch") {
         const args = normalized.slice(2);
         if (positionalArgs(args, ["--agent-id", "--after-item", "--heartbeat-ms"]).length > 0) {
@@ -592,6 +682,7 @@ async function selectAgentForCommand(client, options) {
         backend: contextForCurrent.backend,
         runtimeKind: contextForCurrent.runtimeKind,
         runtimeSessionId: contextForCurrent.runtimeSessionId ?? undefined,
+        runtimePid: contextForCurrent.runtimePid ?? undefined,
         tmuxPaneId: contextForCurrent.tmuxPaneId ?? undefined,
         tty: contextForCurrent.tty ?? undefined,
         termProgram: contextForCurrent.termProgram ?? undefined,
@@ -648,6 +739,30 @@ function parseOptionalNumber(value) {
     }
     return parsed;
 }
+function parseDurationMs(value) {
+    if (/^\d+$/.test(value)) {
+        return Number(value);
+    }
+    const match = /^(\d+)(ms|s|m|h|d)$/.exec(value);
+    if (!match) {
+        throw new Error(`invalid duration: ${value}`);
+    }
+    const amount = Number(match[1]);
+    switch (match[2]) {
+        case "ms":
+            return amount;
+        case "s":
+            return amount * 1_000;
+        case "m":
+            return amount * 60_000;
+        case "h":
+            return amount * 60 * 60_000;
+        case "d":
+            return amount * 24 * 60 * 60_000;
+        default:
+            throw new Error(`invalid duration: ${value}`);
+    }
+}
 function normalizeHelpArgs(args) {
     if (args[0] !== "help") {
         return args;
@@ -762,6 +877,7 @@ Commands:
   daemon
   source
   agent
+  timer
   subscription
   inbox
   gc
@@ -805,9 +921,20 @@ 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
+
+Usage:
+  agentinbox timer add --agent-id ID (--at ISO8601 | --every DURATION | --cron EXPR) --message TEXT [--timezone TZ] [--sender SENDER]
+  agentinbox timer list [--agent-id ID]
+  agentinbox timer pause <scheduleId>
+  agentinbox timer resume <scheduleId>
+  agentinbox timer remove <scheduleId>
 `,
         subscription: `agentinbox subscription
 
@@ -826,6 +953,7 @@ Usage:
   agentinbox inbox list
   agentinbox inbox show <agentId>
   agentinbox inbox read [--agent-id ID] [--after-item ID] [--include-acked]
+  agentinbox inbox send --agent-id ID --message TEXT [--sender SENDER]
   agentinbox inbox watch [--agent-id ID] [--after-item ID] [--include-acked] [--heartbeat-ms N]
   agentinbox inbox ack [--agent-id ID] (--through <itemId> | --item <itemId> | --all)
   agentinbox inbox compact <agentId>

package/dist/src/current_agent.js

@@ -16,6 +16,7 @@ function summarizeActivationTarget(target) {
             itermSessionId: target.itermSessionId ?? null,
             runtimeKind: target.runtimeKind ?? null,
             runtimeSessionId: target.runtimeSessionId ?? null,
+            runtimePid: target.runtimePid ?? null,
         };
     }
     return {

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

@@ -419,6 +419,7 @@ function buildFastifyServer(service) {
                     backend: { type: "string", minLength: 1 },
                     runtimeKind: { type: "string" },
                     runtimeSessionId: { type: "string" },
+                    runtimePid: { type: "integer", minimum: 1 },
                     tmuxPaneId: { type: "string" },
                     tty: { type: "string" },
                     termProgram: { type: "string" },
@@ -439,6 +440,7 @@ function buildFastifyServer(service) {
             backend: String(body.backend),
             runtimeKind: optionalString(body.runtimeKind),
             runtimeSessionId: optionalString(body.runtimeSessionId),
+            runtimePid: typeof body.runtimePid === "number" ? body.runtimePid : null,
             mode: "agent_prompt",
             tmuxPaneId: optionalString(body.tmuxPaneId),
             tty: optionalString(body.tty),
@@ -485,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"],
@@ -563,6 +583,142 @@ 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"],
+            querystring: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    agent_id: { type: "string" },
+                },
+            },
+            response: {
+                200: {
+                    type: "object",
+                    required: ["timers"],
+                    properties: {
+                        timers: { type: "array", items: jsonObjectSchema },
+                    },
+                },
+            },
+        },
+    }, async (request) => {
+        const query = request.query;
+        return { timers: service.listTimers(query.agent_id) };
+    });
+    app.post("/timers", {
+        schema: {
+            tags: ["timers"],
+            body: {
+                type: "object",
+                additionalProperties: false,
+                required: ["agentId", "message"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                    at: { type: "string", minLength: 1 },
+                    every: { type: "integer", minimum: 60000 },
+                    cron: { type: "string", minLength: 1 },
+                    timezone: { type: "string", minLength: 1 },
+                    message: { type: "string", minLength: 1 },
+                    sender: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                400: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const body = request.body;
+        return service.registerTimer({
+            agentId: String(body.agentId),
+            at: optionalString(body.at) ?? null,
+            every: typeof body.every === "number" ? body.every : null,
+            cron: optionalString(body.cron) ?? null,
+            timezone: optionalString(body.timezone) ?? null,
+            message: String(body.message),
+            sender: optionalString(body.sender) ?? null,
+        });
+    });
+    app.post("/timers/:scheduleId/pause", {
+        schema: {
+            tags: ["timers"],
+            params: {
+                type: "object",
+                required: ["scheduleId"],
+                properties: {
+                    scheduleId: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                400: errorResponseSchema,
+                404: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        return service.pauseTimer(decodeURIComponent(params.scheduleId));
+    });
+    app.post("/timers/:scheduleId/resume", {
+        schema: {
+            tags: ["timers"],
+            params: {
+                type: "object",
+                required: ["scheduleId"],
+                properties: {
+                    scheduleId: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                400: errorResponseSchema,
+                404: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        return service.resumeTimer(decodeURIComponent(params.scheduleId));
+    });
+    app.delete("/timers/:scheduleId", {
+        schema: {
+            tags: ["timers"],
+            params: {
+                type: "object",
+                required: ["scheduleId"],
+                properties: {
+                    scheduleId: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                404: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        return service.removeTimer(decodeURIComponent(params.scheduleId));
+    });
     app.get("/subscriptions", {
         schema: {
             tags: ["subscriptions"],
@@ -812,6 +968,39 @@ function buildFastifyServer(service) {
             }),
         };
     });
+    app.post("/agents/:agentId/inbox/items", {
+        schema: {
+            tags: ["inbox"],
+            params: {
+                type: "object",
+                required: ["agentId"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                },
+            },
+            body: {
+                type: "object",
+                additionalProperties: false,
+                required: ["message"],
+                properties: {
+                    message: { type: "string", minLength: 1 },
+                    sender: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                400: errorResponseSchema,
+                404: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        const body = request.body;
+        return service.addDirectInboxTextMessage(decodeURIComponent(params.agentId), {
+            message: body.message,
+            sender: body.sender ?? null,
+        });
+    });
     app.get("/agents/:agentId/inbox/watch", {
         schema: {
             tags: ["inbox"],
@@ -1060,7 +1249,11 @@ function normalizeValidationMessage(message) {
     return message;
 }
 function isBadRequestError(message) {
-    return (message.startsWith("manual append is not supported") ||
+    return (message.startsWith("direct inbox ") ||
+        message.startsWith("timers require ") ||
+        message.startsWith("timer ") ||
+        message.startsWith("invalid timezone: ") ||
+        message.startsWith("manual append is not supported") ||
         message.startsWith("sources/events requires") ||
         message.startsWith("source remove requires") ||
         message.startsWith("deliveryHandle requires") ||