@holon-run/agentinbox 1.0.0-beta.2 → 1.0.0-beta.4

package/README.md

@@ -85,7 +85,7 @@ database.
 Requires:
 
 - Node.js 20 or newer
-- `uxc` 0.15.0 or newer if you want to use GitHub or Feishu adapters:
+- `uxc` 0.15.3 or newer if you want to use GitHub or Feishu adapters:
   https://github.com/holon-run/uxc
 
 Install globally:

package/dist/src/adapters.js

@@ -44,7 +44,9 @@ class AdapterRegistry {
     remoteModuleRegistry;
     constructor(store, appendSourceEvent, options) {
         this.homeDir = options?.homeDir ?? (0, paths_1.resolveAgentInboxHome)(process.env);
-        this.remoteModuleRegistry = options?.remoteModuleRegistry ?? new remote_modules_1.RemoteSourceModuleRegistry();
+        this.remoteModuleRegistry = options?.remoteModuleRegistry ?? new remote_modules_1.RemoteSourceModuleRegistry({
+            githubCallClient: options?.githubCallClient,
+        });
         this.remoteSource = new remote_1.RemoteSourceRuntime(store, appendSourceEvent, {
             homeDir: this.homeDir,
             client: options?.remoteSourceClient,
@@ -140,6 +142,31 @@ class AdapterRegistry {
         }
         return this.remoteSource.expandSubscriptionShortcut(source, input);
     }
+    async listFollowTemplates(source) {
+        if (source.sourceType === "local_event") {
+            return [];
+        }
+        return this.remoteSource.listFollowTemplates(source);
+    }
+    async expandFollowTemplate(source, input) {
+        if (source.sourceType === "local_event") {
+            return null;
+        }
+        return this.remoteSource.expandFollowTemplate(source, input);
+    }
+    followPreviewRefsForProviderOrKind(providerOrKind, config) {
+        const trimmed = providerOrKind.trim();
+        if (trimmed.length === 0) {
+            throw new Error("follow requires a providerOrKind");
+        }
+        if (isExplicitFollowPreviewRef(trimmed)) {
+            return [trimmed];
+        }
+        const candidates = hasRemoteSourceModulePath(config)
+            ? ["remote_source", ...(0, remote_modules_1.builtinRemoteSourceTypes)()]
+            : (0, remote_modules_1.builtinRemoteSourceTypes)();
+        return Array.from(new Set(candidates));
+    }
     async deriveInlinePreview(source, item) {
         if (source.sourceType === "local_event") {
             return null;
@@ -152,6 +179,15 @@ class AdapterRegistry {
         }
         return this.remoteSource.deriveNotificationGrouping(source, item);
     }
+    async getSourceRuntime(source) {
+        if (source.sourceType === "local_event") {
+            return null;
+        }
+        return this.remoteSource.getSourceRuntime(source);
+    }
+    async listSourceRuntimes(sources) {
+        return this.remoteSource.listSourceRuntimes(sources);
+    }
     async summarizeDigestThread(source, items, grouping) {
         if (source.sourceType === "local_event") {
             return null;
@@ -194,6 +230,18 @@ class AdapterRegistry {
     }
 }
 exports.AdapterRegistry = AdapterRegistry;
+function isExplicitFollowPreviewRef(value) {
+    return (value === "local_event" ||
+        value === "remote_source" ||
+        value === "github_repo" ||
+        value === "github_repo_ci" ||
+        value === "feishu_bot" ||
+        value.startsWith("remote:"));
+}
+function hasRemoteSourceModulePath(config) {
+    const modulePath = config?.modulePath;
+    return typeof modulePath === "string" && modulePath.trim().length > 0;
+}
 function syntheticBuiltinSource(sourceType) {
     return {
         sourceId: `builtin:${sourceType}`,

package/dist/src/cli.js

@@ -182,6 +182,47 @@ async function main() {
         await printRemote(client, `/streams/${encodeURIComponent(streamRef)}/schema`, undefined, "GET");
         return;
     }
+    if (command === "follow") {
+        const args = normalized.slice(1);
+        const positionals = positionalArgs(args, [
+            "--agent-id",
+            "--args-json",
+            "--arg",
+            "--config-json",
+            "--config-ref",
+            "--start-policy",
+            "--start-offset",
+            "--start-time",
+        ]);
+        const [providerOrKind, template] = positionals;
+        if (!providerOrKind || !template || positionals[2]) {
+            throw new Error("usage: agentinbox follow <providerOrKind> <template> [--agent-id ID] [--args-json JSON | --arg KEY=VALUE ...] [--config-json JSON] [--config-ref REF] [--start-policy POLICY] [--start-offset N] [--start-time ISO8601]");
+        }
+        const argsJson = takeFlagValue(normalized, "--args-json");
+        const hasArgFlags = hasFlag(normalized, "--arg");
+        if (argsJson != null && hasArgFlags) {
+            throw new Error("follow accepts either --args-json or repeated --arg flags, but not both");
+        }
+        const selection = await selectAgentForCommand(client, {
+            explicitAgentId: takeFlagValue(normalized, "--agent-id"),
+            autoRegister: true,
+        });
+        const response = await requestRemote(client, "/follow", {
+            agentId: selection.agentId,
+            providerOrKind,
+            template,
+            templateArgs: argsJson != null
+                ? (0, util_1.parseJsonArg)(argsJson, "--args-json")
+                : readFollowTemplateArgs(normalized),
+            configRef: takeFlagValue(normalized, "--config-ref") ?? undefined,
+            config: (0, util_1.parseJsonArg)(takeFlagValue(normalized, "--config-json")),
+            startPolicy: takeFlagValue(normalized, "--start-policy") ?? undefined,
+            startOffset: parseOptionalNumber(takeFlagValue(normalized, "--start-offset")),
+            startTime: takeFlagValue(normalized, "--start-time") ?? undefined,
+        });
+        console.log((0, util_1.jsonResponse)(withCommandMetadata(response.data, selection)));
+        return;
+    }
     if (command === "stream" && normalized[1] === "poll") {
         const streamId = normalized[2];
         if (!streamId) {
@@ -871,7 +912,7 @@ async function printCurrentAgent(client) {
     const records = await listAgentsWithTargets(client);
     const current = (0, current_agent_1.resolveCurrentAgent)(records, context);
     if (!current) {
-        throw new Error("no current agent is registered for this terminal/runtime context; run `agentinbox agent register`");
+        throw new Error(noCurrentAgentMessage());
     }
     console.log((0, util_1.jsonResponse)(current));
 }
@@ -907,7 +948,7 @@ async function selectAgentForCommand(client, options) {
         };
     }
     if (!options.autoRegister) {
-        throw new Error("no current agent is registered for this terminal/runtime context; run `agentinbox agent register`");
+        throw new Error(noCurrentAgentMessage());
     }
     await requestRemote(client, "/agents", {
         backend: contextForCurrent.backend,
@@ -946,6 +987,9 @@ async function requestRemote(client, endpoint, body, method = "POST") {
     }
     return { data: response.data };
 }
+function noCurrentAgentMessage() {
+    return "no current agent is registered for this terminal/runtime context; run `agentinbox agent list` to inspect offline agents, then `agentinbox agent register` or `agentinbox agent register --force-rebind --agent-id <agentId>` to rebind one";
+}
 function takeFlagValue(args, flag) {
     const index = args.indexOf(flag);
     if (index === -1) {
@@ -1062,6 +1106,50 @@ function readSubscriptionFilter(args) {
     }
     return {};
 }
+function readFollowTemplateArgs(args) {
+    const parsed = {};
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] !== "--arg") {
+            continue;
+        }
+        const raw = args[index + 1];
+        if (!raw || raw.startsWith("--")) {
+            throw new Error("flag --arg requires KEY=VALUE");
+        }
+        const separator = raw.indexOf("=");
+        if (separator <= 0) {
+            throw new Error("flag --arg requires KEY=VALUE");
+        }
+        const key = raw.slice(0, separator).trim();
+        const rawValue = raw.slice(separator + 1);
+        if (key.length === 0) {
+            throw new Error("flag --arg requires a non-empty key");
+        }
+        parsed[key] = parseFollowTemplateArgValue(rawValue);
+        index += 1;
+    }
+    return parsed;
+}
+function parseFollowTemplateArgValue(raw) {
+    if (raw === "true") {
+        return true;
+    }
+    if (raw === "false") {
+        return false;
+    }
+    if (/^-?\d+(?:\.\d+)?$/.test(raw)) {
+        return Number(raw);
+    }
+    if ((raw.startsWith("[") && raw.endsWith("]")) || (raw.startsWith("{") && raw.endsWith("}")) || raw === "null") {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    return raw;
+}
 function withCommandMetadata(data, selection) {
     return {
         ...data,
@@ -1139,6 +1227,7 @@ Usage:
 Commands:
   serve
   daemon
+  follow
   source
   agent
   timer
@@ -1184,6 +1273,11 @@ Usage:
   agentinbox stream schema preview <sourceKind|sourceType> [--config-json JSON] [--config-ref REF]
   agentinbox stream poll <streamId>
   agentinbox stream event <streamId> --native-id ID --event EVENT [--occurred-at ISO8601] [--metadata-json JSON] [--payload-json JSON]
+`,
+        follow: `agentinbox follow
+
+Usage:
+  agentinbox follow <providerOrKind> <template> [--agent-id ID] [--args-json JSON | --arg KEY=VALUE ...] [--config-json JSON] [--config-ref REF] [--start-policy POLICY] [--start-offset N] [--start-time ISO8601]
 `,
         source: `agentinbox source
 

package/dist/src/current_agent.js

@@ -39,6 +39,9 @@ function resolveCurrentAgent(agents, context) {
         matchesCurrentTerminal: matchesCurrentTerminal(agent, context),
         matchesCurrentRuntime: matchesCurrentRuntime(agent, context),
         terminalIdentity: terminalIdentityForAgent(agent),
+        notifyCapable: notifyCapableForAgent(agent),
+        activeTargetCount: activeActivationTargetCount(agent),
+        offlineTargetCount: offlineActivationTargetCount(agent),
     };
 }
 function annotateAgents(agents, context) {
@@ -52,24 +55,27 @@ function annotateAgents(agents, context) {
             matchesCurrentRuntime: context ? matchesCurrentRuntime(entry, context) : false,
             terminalIdentity: terminalIdentityForAgent(entry),
             isCurrent: current?.agentId === entry.agent.agentId,
+            notifyCapable: notifyCapableForAgent(entry),
+            activeTargetCount: activeActivationTargetCount(entry),
+            offlineTargetCount: offlineActivationTargetCount(entry),
         })),
     };
 }
 function resolveAgentRecord(agents, context) {
     if (context.tmuxPaneId) {
-        const match = agents.find((agent) => activeTerminalTargets(agent).some((target) => target.backend === "tmux" && target.tmuxPaneId === context.tmuxPaneId));
+        const match = agents.find((agent) => terminalTargetsForCurrentMatch(agent).some((target) => target.backend === "tmux" && target.tmuxPaneId === context.tmuxPaneId));
         if (match) {
             return match;
         }
     }
     if (context.itermSessionId) {
-        const match = agents.find((agent) => activeTerminalTargets(agent).some((target) => target.backend === "iterm2" && target.itermSessionId === context.itermSessionId));
+        const match = agents.find((agent) => terminalTargetsForCurrentMatch(agent).some((target) => target.backend === "iterm2" && target.itermSessionId === context.itermSessionId));
         if (match) {
             return match;
         }
     }
     if (context.tty) {
-        const match = agents.find((agent) => activeTerminalTargets(agent).some((target) => target.tty === context.tty));
+        const match = agents.find((agent) => terminalTargetsForCurrentMatch(agent).some((target) => target.tty === context.tty));
         if (match) {
             return match;
         }
@@ -94,6 +100,18 @@ function activeTerminalTargets(agent) {
     }
     return terminalTargets(agent).filter((target) => target.status === "active");
 }
+function terminalTargetsForCurrentMatch(agent) {
+    return activeTerminalTargets(agent);
+}
+function activeActivationTargetCount(agent) {
+    return agent.activationTargets.filter((target) => target.status === "active").length;
+}
+function offlineActivationTargetCount(agent) {
+    return agent.activationTargets.filter((target) => target.status === "offline").length;
+}
+function notifyCapableForAgent(agent) {
+    return agent.agent.status === "active" && activeActivationTargetCount(agent) > 0;
+}
 function terminalIdentityForAgent(agent) {
     const target = activeTerminalTargets(agent)[0];
     if (!target) {
@@ -111,7 +129,7 @@ function terminalIdentityForAgent(agent) {
     return null;
 }
 function matchesCurrentTerminal(agent, context) {
-    return activeTerminalTargets(agent).some((target) => (context.tmuxPaneId != null && target.tmuxPaneId === context.tmuxPaneId)
+    return terminalTargetsForCurrentMatch(agent).some((target) => (context.tmuxPaneId != null && target.tmuxPaneId === context.tmuxPaneId)
         || (context.itermSessionId != null && target.itermSessionId === context.itermSessionId)
         || (context.tty != null && target.tty === context.tty));
 }

package/dist/src/http.js

@@ -29,6 +29,10 @@ const errorResponseSchema = {
         error: { type: "string" },
     },
 };
+const subscriptionStartPolicySchema = {
+    type: "string",
+    enum: ["latest", "earliest", "at_offset", "at_time"],
+};
 const subscriptionCollectionSchema = {
     type: "object",
     required: ["subscriptions"],
@@ -286,7 +290,7 @@ function buildFastifyServer(service) {
                 },
             },
         },
-    }, async () => ({ sources: service.listSources() }));
+    }, async () => ({ sources: await service.listSourceViews() }));
     app.post("/sources", {
         schema: {
             tags: ["sources"],
@@ -464,6 +468,48 @@ function buildFastifyServer(service) {
             },
         },
     }, async (request) => service.previewSourceSchema(request.body));
+    app.post("/follow", {
+        schema: {
+            tags: ["subscriptions"],
+            body: {
+                type: "object",
+                additionalProperties: false,
+                required: ["agentId", "providerOrKind", "template"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                    providerOrKind: { type: "string", minLength: 1 },
+                    template: { type: "string", minLength: 1 },
+                    templateArgs: jsonObjectSchema,
+                    configRef: { anyOf: [{ type: "string" }, { type: "null" }] },
+                    config: jsonObjectSchema,
+                    startPolicy: subscriptionStartPolicySchema,
+                    startOffset: { type: "integer" },
+                    startTime: { type: "string" },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                400: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const body = request.body;
+        return service.follow({
+            agentId: String(body.agentId),
+            providerOrKind: String(body.providerOrKind),
+            template: String(body.template),
+            templateArgs: body.templateArgs && typeof body.templateArgs === "object"
+                ? body.templateArgs
+                : undefined,
+            configRef: optionalString(body.configRef) ?? null,
+            config: body.config && typeof body.config === "object"
+                ? body.config
+                : undefined,
+            startPolicy: optionalString(body.startPolicy),
+            startOffset: typeof body.startOffset === "number" ? body.startOffset : undefined,
+            startTime: optionalString(body.startTime) ?? undefined,
+        });
+    });
     app.post("/streams/:streamId/poll", {
         schema: {
             tags: ["sources"],
@@ -1083,7 +1129,7 @@ function buildFastifyServer(service) {
                     filter: jsonObjectSchema,
                     trackedResourceRef: { type: "string" },
                     cleanupPolicy: jsonObjectSchema,
-                    startPolicy: { type: "string" },
+                    startPolicy: subscriptionStartPolicySchema,
                     startOffset: { type: "integer" },
                     startTime: { type: "string" },
                 },
@@ -1204,7 +1250,7 @@ function buildFastifyServer(service) {
                 additionalProperties: false,
                 required: ["startPolicy"],
                 properties: {
-                    startPolicy: { type: "string", minLength: 1 },
+                    startPolicy: subscriptionStartPolicySchema,
                     startOffset: { type: "integer" },
                     startTime: { type: "string" },
                 },
@@ -1690,6 +1736,10 @@ function isBadRequestError(message) {
         message.startsWith("cleanupPolicy ") ||
         message.startsWith("trackedResourceRef ") ||
         message.startsWith("preview failed: ") ||
+        message.startsWith("follow preview failed: ") ||
+        message.startsWith("follow template ") ||
+        message.startsWith("unknown follow template ") ||
+        message.startsWith("follow requires a providerOrKind") ||
         message.startsWith("unknown source kind or type for preview") ||
         message.startsWith("preview source kind ") ||
         message.startsWith("subscription add shortcut") ||