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

package/dist/src/service.js

@@ -147,6 +147,9 @@ class AgentInboxService {
     listSources() {
         return this.store.listSources();
     }
+    async listSourceViews() {
+        return this.attachSourceRuntimes(this.store.listSources());
+    }
     listHosts() {
         return this.store.listSourceHosts();
     }
@@ -191,8 +194,10 @@ class AgentInboxService {
                 ? schema
                 : (0, source_resolution_1.withResolvedIdentity)(source.sourceId, fallbackSchema, resolvedIdentity))
             : fallbackSchema;
+        const runtime = await this.adapters.getSourceRuntime(source);
         return {
             source,
+            runtime,
             host: source.hostId ? this.store.getSourceHost(source.hostId) : null,
             resolvedIdentity,
             ...(resolutionError ? { resolutionError } : {}),
@@ -299,6 +304,112 @@ class AgentInboxService {
             throw new Error(`preview failed: ${message}`);
         }
     }
+    async follow(input) {
+        const templateArgs = input.templateArgs ?? {};
+        const resolved = await this.resolveFollowTemplate(input, templateArgs);
+        validateFollowTemplateArgs(resolved.templateSpec.argsSchema ?? [], templateArgs, resolved.templateSpec.templateId);
+        const plan = await this.adapters.expandFollowTemplate(resolved.source, {
+            template: input.template,
+            args: templateArgs,
+            source: resolved.source,
+        });
+        if (!plan) {
+            throw new Error(`unknown follow template ${input.providerOrKind}.${input.template}`);
+        }
+        validateExpandedFollowPlan(plan, resolved.templateSpec.templateId);
+        const sourceRefs = new Map();
+        const sourceResults = [];
+        for (const ensuredSource of plan.sources) {
+            const result = await this.ensureFollowSource(ensuredSource);
+            sourceRefs.set(ensuredSource.logicalName, result.source);
+            sourceResults.push({
+                sourceId: result.source.sourceId,
+                streamKind: result.source.streamKind,
+                created: result.created,
+            });
+        }
+        const createdSubscriptions = [];
+        const subscriptionResults = [];
+        try {
+            for (const ensuredSubscription of plan.subscriptions) {
+                const source = sourceRefs.get(ensuredSubscription.sourceLogicalName);
+                if (!source) {
+                    throw new Error(`follow template ${plan.templateId} references unknown ensured source ${ensuredSubscription.sourceLogicalName}`);
+                }
+                const result = await this.ensureSubscription({
+                    agentId: input.agentId,
+                    sourceId: source.sourceId,
+                    filter: ensuredSubscription.filter,
+                    trackedResourceRef: ensuredSubscription.trackedResourceRef ?? null,
+                    cleanupPolicy: ensuredSubscription.cleanupPolicy ?? null,
+                    startPolicy: ensuredSubscription.startPolicy ?? input.startPolicy,
+                    startOffset: ensuredSubscription.startOffset ?? input.startOffset ?? null,
+                    startTime: ensuredSubscription.startTime ?? input.startTime ?? null,
+                });
+                if (result.created) {
+                    createdSubscriptions.push(result.subscription);
+                }
+                subscriptionResults.push({
+                    subscriptionId: result.subscription.subscriptionId,
+                    sourceId: result.subscription.sourceId,
+                    created: result.created,
+                });
+            }
+        }
+        catch (error) {
+            await this.rollbackRegisteredSubscriptions(createdSubscriptions);
+            throw error;
+        }
+        return {
+            templateId: plan.templateId,
+            agentId: input.agentId,
+            sources: sourceResults,
+            subscriptions: subscriptionResults,
+        };
+    }
+    async resolveFollowTemplate(input, templateArgs) {
+        const previewInput = {
+            configRef: input.configRef ?? null,
+            config: mergeFollowPreviewConfig(input.config, templateArgs),
+        };
+        const candidates = this.adapters.followPreviewRefsForProviderOrKind(input.providerOrKind, previewInput.config);
+        let previewFailure = null;
+        for (const sourceRef of candidates) {
+            try {
+                const source = buildPreviewSource({
+                    sourceRef,
+                    configRef: previewInput.configRef,
+                    config: previewInput.config,
+                });
+                const templateSpec = (await this.adapters.listFollowTemplates(source)).find((candidate) => (candidate.providerOrKind === input.providerOrKind || sourceRef === input.providerOrKind) &&
+                    followTemplateName(candidate.templateId) === input.template);
+                if (!templateSpec) {
+                    continue;
+                }
+                await this.adapters.sourceAdapterFor(source.sourceType).validateSource?.(source);
+                return { source, templateSpec };
+            }
+            catch (error) {
+                if (!previewFailure || sourceRef === input.providerOrKind || candidates.length === 1) {
+                    previewFailure = error instanceof Error ? error : new Error(String(error));
+                }
+            }
+        }
+        if (previewFailure) {
+            throw new Error(`follow preview failed: ${previewFailure.message}`);
+        }
+        throw new Error(`unknown follow template ${input.providerOrKind}.${input.template}`);
+    }
+    async ensureFollowSource(input) {
+        const existing = this.store.getSourceByKey(input.sourceType, input.sourceKey);
+        if (existing) {
+            return { source: existing, created: false };
+        }
+        return {
+            source: await this.registerSource(input),
+            created: true,
+        };
+    }
     async removeSource(sourceId, options = {}) {
         const source = this.store.getSource(sourceId);
         if (!source) {
@@ -505,7 +616,7 @@ class AgentInboxService {
         return { removed: true };
     }
     registerTimer(input) {
-        this.getAgent(input.agentId);
+        this.assertAgentNotifyCapable(input.agentId, "timer add");
         const normalized = normalizeTimerInput(input);
         const timezone = normalized.timezone ?? detectHostTimezone();
         assertValidTimeZone(timezone);
@@ -724,6 +835,38 @@ class AgentInboxService {
         }
         return [await this.registerSingleSubscription(input)];
     }
+    async ensureSubscription(input) {
+        if (input.shortcut) {
+            throw new Error("follow ensureSubscription does not support shortcuts");
+        }
+        const source = this.store.getSource(input.sourceId);
+        if (!source) {
+            throw new Error(`unknown source: ${input.sourceId}`);
+        }
+        const normalized = await this.normalizeSubscriptionRegistrationInput(input);
+        const existing = this.store.listSubscriptionsForAgent(input.agentId).find((subscription) => subscription.sourceId === source.sourceId &&
+            subscription.startPolicy === normalized.startPolicy &&
+            (subscription.startOffset ?? null) === normalized.startOffset &&
+            (subscription.startTime ?? null) === normalized.startTime &&
+            stableJson(subscription.filter) === stableJson(normalized.filter) &&
+            normalizeTrackedResourceRef(subscription.trackedResourceRef) === normalized.trackedResourceRef &&
+            stableJson(subscription.cleanupPolicy) === stableJson(normalized.cleanupPolicy));
+        if (existing) {
+            return { subscription: existing, created: false };
+        }
+        return {
+            subscription: await this.registerSingleSubscription({
+                ...input,
+                filter: normalized.filter,
+                trackedResourceRef: normalized.trackedResourceRef,
+                cleanupPolicy: normalized.cleanupPolicy,
+                startPolicy: normalized.startPolicy,
+                startOffset: normalized.startOffset,
+                startTime: normalized.startTime,
+            }),
+            created: true,
+        };
+    }
     async expandShortcutRegistration(input) {
         if (!input.shortcut) {
             return null;
@@ -794,13 +937,12 @@ class AgentInboxService {
         return sibling;
     }
     async registerSingleSubscription(input) {
-        this.getAgent(input.agentId);
+        this.assertAgentNotifyCapable(input.agentId, "subscription add");
         const source = this.store.getSource(input.sourceId);
         if (!source) {
             throw new Error(`unknown source: ${input.sourceId}`);
         }
-        await (0, filter_1.validateSubscriptionFilter)(input.filter ?? {});
-        const cleanupPolicy = normalizeCleanupPolicy(input.cleanupPolicy ?? null);
+        const normalized = await this.normalizeSubscriptionRegistrationInput(input);
         const idleState = this.store.getSourceIdleState(source.sourceId);
         if (idleState?.autoPausedAt) {
             await this.resumeSource(source.sourceId);
@@ -812,12 +954,12 @@ class AgentInboxService {
             subscriptionId: (0, util_1.generateCanonicalId)("sub"),
             agentId: input.agentId,
             sourceId: input.sourceId,
-            filter: input.filter ?? {},
-            trackedResourceRef: normalizeTrackedResourceRef(input.trackedResourceRef),
-            cleanupPolicy,
-            startPolicy: input.startPolicy ?? "latest",
-            startOffset: input.startOffset ?? null,
-            startTime: input.startTime ?? null,
+            filter: normalized.filter,
+            trackedResourceRef: normalized.trackedResourceRef,
+            cleanupPolicy: normalized.cleanupPolicy,
+            startPolicy: normalized.startPolicy,
+            startOffset: normalized.startOffset,
+            startTime: normalized.startTime,
             createdAt: (0, util_1.nowIso)(),
         };
         this.ensureInboxForAgent(subscription.agentId);
@@ -842,6 +984,22 @@ class AgentInboxService {
             throw error;
         }
     }
+    async normalizeSubscriptionRegistrationInput(input) {
+        await (0, filter_1.validateSubscriptionFilter)(input.filter ?? {});
+        const start = normalizeSubscriptionStartPosition({
+            startPolicy: input.startPolicy ?? "latest",
+            startOffset: input.startOffset ?? null,
+            startTime: input.startTime ?? null,
+        });
+        return {
+            filter: input.filter ?? {},
+            trackedResourceRef: normalizeTrackedResourceRef(input.trackedResourceRef),
+            cleanupPolicy: normalizeCleanupPolicy(input.cleanupPolicy ?? null),
+            startPolicy: start.startPolicy,
+            startOffset: start.startOffset,
+            startTime: start.startTime,
+        };
+    }
     async removeSubscription(subscriptionId) {
         const subscription = this.getSubscription(subscriptionId);
         await this.backend.deleteConsumer({ subscriptionId });
@@ -889,18 +1047,16 @@ class AgentInboxService {
     }
     async resetSubscription(input) {
         this.getSubscription(input.subscriptionId);
-        if (!SUBSCRIPTION_START_POLICIES.has(input.startPolicy)) {
-            throw new Error(`unsupported start policy: ${input.startPolicy}`);
-        }
+        const normalizedStart = normalizeSubscriptionStartPosition(input);
         const consumer = await this.backend.getConsumer({ subscriptionId: input.subscriptionId });
         if (!consumer) {
             throw new Error(`unknown consumer for subscription: ${input.subscriptionId}`);
         }
         const reset = await this.backend.reset({
             consumerId: consumer.consumerId,
-            startPolicy: input.startPolicy,
-            startOffset: input.startOffset ?? null,
-            startTime: input.startTime ?? null,
+            startPolicy: normalizedStart.startPolicy,
+            startOffset: normalizedStart.startOffset,
+            startTime: normalizedStart.startTime,
         });
         return {
             subscription: this.getSubscription(input.subscriptionId),
@@ -1474,7 +1630,8 @@ class AgentInboxService {
         const input = payload.text != null ? { ...payload, body: String(payload.text) } : payload;
         return this.adapters.invokeDeliveryOperation(source, handle, canonicalOperation.name, input, attempt);
     }
-    status() {
+    async status() {
+        const sources = await this.listSourceViews();
         return {
             retention: {
                 ackedInboxItemsMs: this.ackedRetentionMs,
@@ -1483,7 +1640,7 @@ class AgentInboxService {
             },
             counts: this.store.getCounts(),
             agents: this.store.listAgents(),
-            sources: this.store.listSources(),
+            sources,
             subscriptions: this.store.listSubscriptions(),
             inboxes: this.store.listInboxes(),
             activationTargets: this.store.listActivationTargets(),
@@ -1500,6 +1657,13 @@ class AgentInboxService {
             },
         };
     }
+    async attachSourceRuntimes(sources) {
+        const runtimes = await this.adapters.listSourceRuntimes(sources);
+        return sources.map((source) => ({
+            ...source,
+            runtime: runtimes.get(source.sourceId) ?? null,
+        }));
+    }
     ensureInboxForAgent(agentId) {
         const existing = this.store.getInboxByAgentId(agentId);
         if (existing) {
@@ -1595,6 +1759,19 @@ class AgentInboxService {
             watcher.onItems(items);
         }
     }
+    assertAgentNotifyCapable(agentId, operation) {
+        this.getAgent(agentId);
+        const targets = this.store.listActivationTargetsForAgent(agentId);
+        const activeTargetCount = targets.filter((target) => target.status === "active").length;
+        if (activeTargetCount > 0) {
+            return;
+        }
+        const offlineTargetCount = targets.filter((target) => target.status === "offline").length;
+        const targetSummary = targets.length === 0
+            ? "it has no activation targets"
+            : `all ${offlineTargetCount} activation target(s) are offline`;
+        throw new Error(`agent ${agentId} is not notify-capable: ${targetSummary}; refusing ${operation} to avoid a silent notification black hole. Rebind with \`agentinbox agent register --force-rebind --agent-id ${agentId}\` or resume/add a target first.`);
+    }
     resolveAutoAgentId(input) {
         for (let attempt = 0; attempt < 32; attempt += 1) {
             const candidate = (0, terminal_1.assignedAgentIdFromContext)({
@@ -2170,6 +2347,7 @@ class AgentInboxService {
                     targetKind: target.kind,
                     subscriptionIds: input.subscriptionIds,
                     sourceIds: input.sourceIds,
+                    latestEntryId: latestEntryIdForNotification(input.entries),
                     newEntryCount: input.entries.length,
                     newItemCount: input.newItemCount,
                     summary,
@@ -2302,6 +2480,7 @@ class AgentInboxService {
             totalUnackedCount,
             summary,
             preview,
+            latestEntryId: latestEntryIdForNotification(entries),
         });
         return {
             prompt,
@@ -2753,6 +2932,12 @@ function buildPreviewSource(input) {
         updatedAt: now,
     };
 }
+function mergeFollowPreviewConfig(config, templateArgs) {
+    return {
+        ...(config ?? {}),
+        ...templateArgs,
+    };
+}
 function sourceTypeForPreviewRef(sourceRef) {
     if (sourceRef === "local_event" || sourceRef === "remote_source" || sourceRef === "github_repo" || sourceRef === "github_repo_ci" || sourceRef === "feishu_bot") {
         return sourceRef;
@@ -2762,6 +2947,67 @@ function sourceTypeForPreviewRef(sourceRef) {
     }
     throw new Error(`unknown source kind or type for preview: ${sourceRef}`);
 }
+function followTemplateName(templateId) {
+    const trimmed = templateId.trim();
+    const separator = trimmed.lastIndexOf(".");
+    return separator === -1 ? trimmed : trimmed.slice(separator + 1);
+}
+function validateFollowTemplateArgs(argsSchema, args, templateId) {
+    for (const field of argsSchema) {
+        const value = args[field.name];
+        if (field.required && value === undefined) {
+            throw new Error(`follow template ${templateId} requires argument ${field.name}`);
+        }
+        if (value === undefined) {
+            continue;
+        }
+        if (!matchesFollowArgType(value, field.type)) {
+            throw new Error(`follow template ${templateId} expected ${field.name} to be ${field.type}`);
+        }
+    }
+}
+function matchesFollowArgType(value, type) {
+    if (type === "string") {
+        return typeof value === "string";
+    }
+    if (type === "number") {
+        return typeof value === "number" && Number.isFinite(value);
+    }
+    if (type === "boolean") {
+        return typeof value === "boolean";
+    }
+    if (type === "string[]") {
+        return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+    }
+    if (type === "number[]") {
+        return Array.isArray(value) && value.every((entry) => typeof entry === "number" && Number.isFinite(entry));
+    }
+    return true;
+}
+function validateExpandedFollowPlan(plan, expectedTemplateId) {
+    if (plan.templateId !== expectedTemplateId) {
+        throw new Error(`follow template ${expectedTemplateId} expanded to unexpected templateId ${plan.templateId}`);
+    }
+    if (plan.sources.length === 0) {
+        throw new Error(`follow template ${plan.templateId} did not produce any sources`);
+    }
+    const logicalNames = new Set();
+    for (const source of plan.sources) {
+        const logicalName = source.logicalName.trim();
+        if (logicalName.length === 0) {
+            throw new Error(`follow template ${plan.templateId} returned an empty source logicalName`);
+        }
+        if (logicalNames.has(logicalName)) {
+            throw new Error(`follow template ${plan.templateId} returned duplicate source logicalName ${logicalName}`);
+        }
+        logicalNames.add(logicalName);
+    }
+    for (const subscription of plan.subscriptions) {
+        if (!logicalNames.has(subscription.sourceLogicalName)) {
+            throw new Error(`follow template ${plan.templateId} references unknown ensured source ${subscription.sourceLogicalName}`);
+        }
+    }
+}
 function normalizeTrackedResourceRef(value) {
     if (value == null) {
         return null;
@@ -2769,6 +3015,38 @@ function normalizeTrackedResourceRef(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : null;
 }
+function normalizeSubscriptionStartPosition(input) {
+    if (!SUBSCRIPTION_START_POLICIES.has(input.startPolicy)) {
+        throw new Error(`unsupported start policy: ${input.startPolicy}`);
+    }
+    const startOffset = input.startOffset ?? null;
+    const startTime = input.startTime ?? null;
+    if (input.startPolicy === "at_offset") {
+        if (startOffset == null || !Number.isInteger(startOffset) || startOffset < 1) {
+            throw new Error("subscriptions requires positive integer startOffset when startPolicy=at_offset");
+        }
+        return {
+            startPolicy: input.startPolicy,
+            startOffset,
+            startTime: null,
+        };
+    }
+    if (input.startPolicy === "at_time") {
+        if (!startTime || !isValidIsoTimestamp(startTime)) {
+            throw new Error("subscriptions requires valid ISO8601 startTime when startPolicy=at_time");
+        }
+        return {
+            startPolicy: input.startPolicy,
+            startOffset: null,
+            startTime: canonicalIsoTimestamp(startTime),
+        };
+    }
+    return {
+        startPolicy: input.startPolicy,
+        startOffset: null,
+        startTime: null,
+    };
+}
 function normalizeCleanupPolicy(input) {
     if (!input) {
         return { mode: "manual" };
@@ -2815,6 +3093,23 @@ function normalizeGracePeriodSecs(value) {
     }
     return value;
 }
+function stableJson(value) {
+    return JSON.stringify(sortJsonValue(value));
+}
+function sortJsonValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => sortJsonValue(entry));
+    }
+    if (!value || typeof value !== "object") {
+        return value;
+    }
+    return Object.keys(value)
+        .sort()
+        .reduce((acc, key) => {
+        acc[key] = sortJsonValue(value[key]);
+        return acc;
+    }, {});
+}
 function normalizeLifecycleSignal(signal, fallbackOccurredAt) {
     const ref = typeof signal.ref === "string" ? signal.ref.trim() : "";
     if (ref.length === 0) {
@@ -3117,6 +3412,9 @@ function summarizeActivation(inboxId, newItemCount, firstSummary) {
     }
     return `${newItemCount} new ${itemWord} in ${inboxId}`;
 }
+function latestEntryIdForNotification(entries) {
+    return entries.length > 0 ? entries[entries.length - 1]?.entryId ?? null : null;
+}
 function latestSummary(entries) {
     for (let index = entries.length - 1; index >= 0; index -= 1) {
         const summary = entries[index]?.summary;

package/dist/src/source_resolution.js

@@ -65,6 +65,9 @@ async function resolveSourceSchema(source, context = {}) {
             shortcuts: typeof module?.listSubscriptionShortcuts === "function"
                 ? module.listSubscriptionShortcuts(moduleInputSource(source))
                 : [],
+            followTemplates: typeof module?.listFollowTemplates === "function"
+                ? module.listFollowTemplates(moduleInputSource(source))
+                : undefined,
         }
         : undefined);
 }
@@ -87,6 +90,13 @@ function withResolvedIdentity(sourceId, schema, identity, capabilityMetadata) {
                 shortcuts: capabilityMetadata.shortcuts ?? [],
             },
         } : {}),
+        ...(capabilityMetadata?.followTemplates && capabilityMetadata.followTemplates.length > 0
+            ? {
+                followSchema: {
+                    templates: capabilityMetadata.followTemplates,
+                },
+            }
+            : {}),
     };
 }
 function moduleInputSource(source) {

package/dist/src/source_schema.js

@@ -88,7 +88,9 @@ const SOURCE_SCHEMAS = {
             { name: "conclusion", type: "string|null", description: "Workflow run conclusion when completed." },
             { name: "event", type: "string|null", description: "GitHub trigger event for the workflow run." },
             { name: "headBranch", type: "string|null", description: "Head branch for the workflow run." },
+            { name: "headRepositoryFullName", type: "string|null", description: "Head repository full name for the workflow run when available." },
             { name: "headSha", type: "string|null", description: "Head commit SHA for the workflow run." },
+            { name: "pullRequestNumbers", type: "number[]", description: "Pull request numbers associated with the workflow run." },
             { name: "actor", type: "string|null", description: "Actor login for the workflow run." },
             { name: "commitMessage", type: "string|null", description: "Head commit message when present." },
             { name: "htmlUrl", type: "string|null", description: "GitHub Actions run URL." },
@@ -101,6 +103,8 @@ const SOURCE_SCHEMAS = {
                 conclusion: "failure",
                 event: "pull_request",
                 head_branch: "main",
+                head_repository: { full_name: "holon-run/agentinbox" },
+                pull_requests: [{ number: 93 }],
                 actor: "jolestar",
                 head_commit: { message: "fix ci" },
             },