@holon-run/agentinbox 0.1.3 → 0.2.0

package/dist/src/source_resolution.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSourceIdentity = resolveSourceIdentity;
+exports.resolveSourceSchema = resolveSourceSchema;
+exports.withResolvedIdentity = withResolvedIdentity;
+const paths_1 = require("./paths");
+const remote_profiles_1 = require("./sources/remote_profiles");
+const source_schema_1 = require("./source_schema");
+async function resolveSourceIdentity(source, context = {}) {
+    if (source.sourceType === "local_event") {
+        return {
+            hostType: "local_event",
+            sourceKind: "local_event",
+            implementationId: "builtin.local_event",
+        };
+    }
+    const builtinImplementationId = (0, remote_profiles_1.builtInProfileIdForSourceType)(source.sourceType);
+    if (builtinImplementationId) {
+        return {
+            hostType: "remote_source",
+            sourceKind: source.sourceType,
+            implementationId: builtinImplementationId,
+        };
+    }
+    if (source.sourceType !== "remote_source") {
+        throw new Error(`unsupported source type for source resolution: ${source.sourceType}`);
+    }
+    const profileRegistry = context.profileRegistry ?? new remote_profiles_1.RemoteSourceProfileRegistry();
+    const homeDir = context.homeDir ?? (0, paths_1.resolveAgentInboxHome)(process.env);
+    const profile = await profileRegistry.resolve(source, homeDir);
+    const capabilityDescription = typeof profile.describeCapabilities === "function"
+        ? profile.describeCapabilities(profileInputSource(source))
+        : undefined;
+    return {
+        hostType: "remote_source",
+        sourceKind: capabilityDescription?.sourceKind?.trim() || `remote:${profile.id}`,
+        implementationId: profile.id,
+    };
+}
+async function resolveSourceSchema(source, context = {}) {
+    const profileRegistry = context.profileRegistry ?? new remote_profiles_1.RemoteSourceProfileRegistry();
+    const homeDir = context.homeDir ?? (0, paths_1.resolveAgentInboxHome)(process.env);
+    const resolvedContext = { ...context, profileRegistry, homeDir };
+    const identity = await resolveSourceIdentity(source, resolvedContext);
+    const staticSchema = (0, source_schema_1.getSourceSchema)(source.sourceType);
+    let capabilityDescription;
+    let profile = null;
+    if (identity.hostType === "remote_source") {
+        profile = await profileRegistry.resolve(source, homeDir);
+        capabilityDescription = typeof profile.describeCapabilities === "function"
+            ? profile.describeCapabilities(profileInputSource(source))
+            : undefined;
+    }
+    return withResolvedIdentity(source.sourceId, {
+        sourceType: staticSchema.sourceType,
+        metadataFields: capabilityDescription?.metadataFields ?? staticSchema.metadataFields,
+        payloadExamples: capabilityDescription?.payloadExamples ?? staticSchema.payloadExamples,
+        eventVariantExamples: capabilityDescription?.eventVariantExamples ?? staticSchema.eventVariantExamples,
+        configFields: capabilityDescription?.configSchema ?? staticSchema.configFields,
+    }, identity, identity.hostType === "remote_source"
+        ? {
+            aliases: capabilityDescription?.aliases,
+            supportsTrackedResourceRef: typeof profile?.deriveTrackedResource === "function",
+            supportsLifecycleSignals: typeof profile?.projectLifecycleSignal === "function",
+            shortcuts: typeof profile?.listSubscriptionShortcuts === "function"
+                ? profile.listSubscriptionShortcuts(profileInputSource(source))
+                : [],
+        }
+        : undefined);
+}
+function withResolvedIdentity(sourceId, schema, identity, capabilityMetadata) {
+    return {
+        sourceId,
+        sourceType: schema.sourceType,
+        metadataFields: schema.metadataFields,
+        payloadExamples: schema.payloadExamples,
+        eventVariantExamples: schema.eventVariantExamples,
+        configFields: schema.configFields,
+        hostType: identity.hostType,
+        sourceKind: identity.sourceKind,
+        implementationId: identity.implementationId,
+        ...(capabilityMetadata?.aliases?.length ? { aliases: capabilityMetadata.aliases } : {}),
+        ...(capabilityMetadata ? {
+            subscriptionSchema: {
+                supportsTrackedResourceRef: capabilityMetadata.supportsTrackedResourceRef ?? false,
+                supportsLifecycleSignals: capabilityMetadata.supportsLifecycleSignals ?? false,
+                shortcuts: capabilityMetadata.shortcuts ?? [],
+            },
+        } : {}),
+    };
+}
+function profileInputSource(source) {
+    if (source.sourceType !== "remote_source") {
+        return source;
+    }
+    return {
+        ...source,
+        config: (0, remote_profiles_1.profileConfigForSource)(source),
+    };
+}

package/dist/src/source_schema.js

@@ -32,6 +32,7 @@ const SOURCE_SCHEMAS = {
             { name: "action", type: "string", description: "GitHub event action suffix such as created." },
             { name: "author", type: "string|null", description: "Actor login for the event." },
             { name: "isPullRequest", type: "boolean", description: "Whether the event targets a pull request surface." },
+            { name: "reviewState", type: "string|null", description: "Review decision state for PullRequestReviewEvent such as approved or changes_requested." },
             { name: "labels", type: "string[]", description: "Labels extracted from the issue or pull request." },
             { name: "mentions", type: "string[]", description: "Mention handles extracted from title/body/comment text." },
             { name: "number", type: "number|null", description: "Issue or pull request number when present." },
@@ -49,8 +50,29 @@ const SOURCE_SCHEMAS = {
                 issue: { number: 12, title: "Track filtering work" },
                 comment: { body: "@alpha please look" },
             },
+            {
+                id: "1234567891",
+                type: "PullRequestReviewEvent",
+                action: "created",
+                actor: "Copilot",
+                pull_request: { number: 67, title: "feat: add remote module capability hooks" },
+                review: { state: "commented", body: "review summary" },
+            },
+            {
+                id: "1234567892",
+                type: "PullRequestEvent",
+                action: "closed",
+                actor: "jolestar",
+                pull_request: { number: 72, title: "feat: add cleanup policy lifecycle engine", merged: true },
+            },
+        ],
+        eventVariantExamples: [
+            "IssueCommentEvent.created",
+            "PullRequestEvent.opened",
+            "PullRequestEvent.closed",
+            "PullRequestReviewEvent.created",
+            "PullRequestReviewCommentEvent.created",
         ],
-        eventVariantExamples: ["IssueCommentEvent.created", "PullRequestEvent.opened", "PullRequestReviewCommentEvent.created"],
         configFields: [
             { name: "owner", type: "string", required: true, description: "GitHub repository owner." },
             { name: "repo", type: "string", required: true, description: "GitHub repository name." },

package/dist/src/sources/github.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GithubDeliveryAdapter = exports.GithubUxcClient = exports.DEFAULT_GITHUB_EVENT_TYPES = exports.GITHUB_ENDPOINT = void 0;
 exports.normalizeGithubRepoEvent = normalizeGithubRepoEvent;
+exports.deriveGithubTrackedResource = deriveGithubTrackedResource;
+exports.githubSubscriptionShortcutSpec = githubSubscriptionShortcutSpec;
+exports.expandGithubSubscriptionShortcut = expandGithubSubscriptionShortcut;
+exports.projectGithubLifecycleSignal = projectGithubLifecycleSignal;
 exports.parseGithubSourceConfig = parseGithubSourceConfig;
 const uxc_daemon_client_1 = require("@holon-run/uxc-daemon-client");
 exports.GITHUB_ENDPOINT = "https://api.github.com";
@@ -9,6 +13,7 @@ exports.DEFAULT_GITHUB_EVENT_TYPES = [
     "IssuesEvent",
     "IssueCommentEvent",
     "PullRequestEvent",
+    "PullRequestReviewEvent",
     "PullRequestReviewCommentEvent",
 ];
 class GithubUxcClient {
@@ -97,15 +102,18 @@ function normalizeGithubRepoEvent(source, config, raw) {
     const repo = asRecord(event.repo);
     const issue = asRecord(payload.issue);
     const pullRequest = asRecord(payload.pull_request);
+    const review = asRecord(payload.review);
     const comment = asRecord(payload.comment);
     const action = asString(payload.action) ?? "observed";
     const number = asNumber(issue.number) ?? asNumber(pullRequest.number);
     const isPullRequest = eventType.startsWith("PullRequest");
     const title = asString(issue.title) ?? asString(pullRequest.title) ?? null;
-    const body = asString(comment.body) ?? asString(issue.body) ?? asString(pullRequest.body) ?? null;
+    const reviewState = asString(review.state) ?? null;
+    const body = asString(comment.body) ?? asString(review.body) ?? asString(issue.body) ?? asString(pullRequest.body) ?? null;
     const labels = extractLabels(issue.labels);
     const mentions = extractMentions(title, body);
     const url = asString(comment.html_url) ??
+        asString(review.html_url) ??
         asString(issue.html_url) ??
         asString(pullRequest.html_url) ??
         asString(event.url);
@@ -125,6 +133,7 @@ function normalizeGithubRepoEvent(source, config, raw) {
             number,
             author: asString(actor.login) ?? null,
             isPullRequest,
+            reviewState,
             labels,
             mentions,
             title,
@@ -138,11 +147,71 @@ function normalizeGithubRepoEvent(source, config, raw) {
             actor: actor.login ?? null,
             issue,
             pull_request: pullRequest,
+            review,
             comment,
+            merged: asBoolean(pullRequest.merged),
         },
         deliveryHandle,
     };
 }
+function deriveGithubTrackedResource(filter) {
+    const metadata = asRecord(filter.metadata);
+    const payload = asRecord(filter.payload);
+    const number = asNumber(metadata.number) ?? asNumber(payload.number) ?? asNumber(payload.ref);
+    const isPullRequest = asBoolean(metadata.isPullRequest);
+    if (!number || isPullRequest !== true) {
+        return null;
+    }
+    return { ref: `pr:${number}` };
+}
+function githubSubscriptionShortcutSpec() {
+    return [{
+            name: "pr",
+            description: "Follow one pull request and auto-retire when it closes.",
+            argsSchema: [{ name: "number", type: "number", required: true, description: "Pull request number." }],
+        }];
+}
+function expandGithubSubscriptionShortcut(input) {
+    if (input.name !== "pr") {
+        return null;
+    }
+    const number = typeof input.args?.number === "number" ? input.args.number : null;
+    if (!number || !Number.isInteger(number) || number <= 0) {
+        throw new Error("subscription shortcut pr requires a positive integer number");
+    }
+    return {
+        filter: {
+            metadata: {
+                number,
+                isPullRequest: true,
+            },
+        },
+        trackedResourceRef: `pr:${number}`,
+        cleanupPolicy: { mode: "on_terminal" },
+    };
+}
+function projectGithubLifecycleSignal(rawPayload) {
+    const eventType = asString(rawPayload.type);
+    if (eventType !== "PullRequestEvent") {
+        return null;
+    }
+    const action = asString(rawPayload.action);
+    if (action !== "closed" && action !== "merged") {
+        return null;
+    }
+    const pullRequest = asRecord(rawPayload.pull_request);
+    const number = asNumber(pullRequest.number);
+    if (!number) {
+        return null;
+    }
+    const merged = action === "merged" || asBoolean(rawPayload.merged) === true || asBoolean(pullRequest.merged) === true;
+    return {
+        ref: `pr:${number}`,
+        terminal: true,
+        state: "closed",
+        result: merged ? "merged" : "closed",
+    };
+}
 function buildGithubDeliveryHandle(config, eventType, number, comment) {
     if (!number) {
         return null;
@@ -243,6 +312,9 @@ function asString(value) {
 function asNumber(value) {
     return typeof value === "number" ? value : null;
 }
+function asBoolean(value) {
+    return typeof value === "boolean" ? value : null;
+}
 function asStringArray(value) {
     if (!Array.isArray(value)) {
         return null;

package/dist/src/sources/remote.js

@@ -167,6 +167,30 @@ class RemoteSourceRuntime {
             erroredSourceIds: Array.from(this.errorCounts.keys()).sort(),
         };
     }
+    async projectLifecycleSignal(source, rawPayload) {
+        if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
+            return null;
+        }
+        const profile = await this.profileRegistry.resolve(source, this.homeDir);
+        if (typeof profile.projectLifecycleSignal !== "function") {
+            return null;
+        }
+        return profile.projectLifecycleSignal(rawPayload, profileInputSource(source));
+    }
+    async expandSubscriptionShortcut(source, input) {
+        if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
+            return null;
+        }
+        const profile = await this.profileRegistry.resolve(source, this.homeDir);
+        if (typeof profile.expandSubscriptionShortcut !== "function") {
+            return null;
+        }
+        return profile.expandSubscriptionShortcut({
+            name: input.name,
+            args: input.args,
+            source: profileInputSource(source),
+        });
+    }
     async syncAll() {
         const sources = this.store
             .listSources()

package/dist/src/sources/remote_profiles.js

@@ -90,6 +90,16 @@ function validateProfileContract(profile, sourcePath) {
     if (typeof profile.mapRawEvent !== "function") {
         throw new Error(`remote_source profile missing mapRawEvent(): ${sourcePath}`);
     }
+    validateOptionalHook(profile.describeCapabilities, "describeCapabilities", sourcePath);
+    validateOptionalHook(profile.listSubscriptionShortcuts, "listSubscriptionShortcuts", sourcePath);
+    validateOptionalHook(profile.expandSubscriptionShortcut, "expandSubscriptionShortcut", sourcePath);
+    validateOptionalHook(profile.deriveTrackedResource, "deriveTrackedResource", sourcePath);
+    validateOptionalHook(profile.projectLifecycleSignal, "projectLifecycleSignal", sourcePath);
+}
+function validateOptionalHook(value, name, sourcePath) {
+    if (value !== undefined && typeof value !== "function") {
+        throw new Error(`remote_source profile ${name} must be a function when provided: ${sourcePath}`);
+    }
 }
 function resolveAndValidateProfilePath(profileRoot, profilePath) {
     const resolved = node_path_1.default.isAbsolute(profilePath)
@@ -120,6 +130,71 @@ function asNonEmptyString(value) {
 }
 const GITHUB_REPO_PROFILE = {
     id: "builtin.github_repo",
+    describeCapabilities(source) {
+        const config = (0, github_1.parseGithubSourceConfig)(source);
+        return {
+            sourceKind: "github_repo",
+            aliases: ["github_repo"],
+            configSchema: [
+                { name: "owner", type: "string", required: true, description: "GitHub repository owner." },
+                { name: "repo", type: "string", required: true, description: "GitHub repository name." },
+                { name: "uxcAuth", type: "string", required: false, description: "Optional uxc auth profile." },
+                { name: "eventTypes", type: "string[]", required: false, description: "Optional GitHub event type allowlist." },
+                { name: "perPage", type: "number", required: false, description: `Repository events requested per poll. Default ${config.perPage ?? 10}.` },
+                { name: "pollIntervalSecs", type: "number", required: false, description: `Polling interval in seconds. Default ${config.pollIntervalSecs ?? 30}.` },
+            ],
+            metadataFields: [
+                { name: "eventType", type: "string", description: "GitHub event type such as IssueCommentEvent." },
+                { name: "action", type: "string", description: "GitHub event action suffix such as created." },
+                { name: "author", type: "string|null", description: "Actor login for the event." },
+                { name: "isPullRequest", type: "boolean", description: "Whether the event targets a pull request surface." },
+                { name: "reviewState", type: "string|null", description: "Review decision state for PullRequestReviewEvent such as approved or changes_requested." },
+                { name: "labels", type: "string[]", description: "Labels extracted from the issue or pull request." },
+                { name: "mentions", type: "string[]", description: "Mention handles extracted from title/body/comment text." },
+                { name: "number", type: "number|null", description: "Issue or pull request number when present." },
+                { name: "repoFullName", type: "string", description: "Repository full name in owner/repo form." },
+                { name: "title", type: "string|null", description: "Issue, pull request, or comment title." },
+                { name: "body", type: "string|null", description: "Issue, pull request, or comment body text." },
+                { name: "url", type: "string|null", description: "Primary GitHub HTML URL for the event target." },
+            ],
+            payloadExamples: [
+                {
+                    id: "1234567891",
+                    type: "PullRequestReviewEvent",
+                    action: "created",
+                    actor: "Copilot",
+                    pull_request: { number: 67, title: "feat: add remote module capability hooks" },
+                    review: { state: "commented", body: "review summary" },
+                },
+                {
+                    id: "1234567892",
+                    type: "PullRequestEvent",
+                    action: "closed",
+                    actor: "jolestar",
+                    pull_request: { number: 72, title: "feat: add cleanup policy lifecycle engine", merged: true },
+                },
+            ],
+            eventVariantExamples: [
+                "IssueCommentEvent.created",
+                "PullRequestEvent.opened",
+                "PullRequestEvent.closed",
+                "PullRequestReviewEvent.created",
+                "PullRequestReviewCommentEvent.created",
+            ],
+        };
+    },
+    listSubscriptionShortcuts() {
+        return (0, github_1.githubSubscriptionShortcutSpec)();
+    },
+    expandSubscriptionShortcut(input) {
+        return (0, github_1.expandGithubSubscriptionShortcut)(input);
+    },
+    deriveTrackedResource(filter) {
+        return (0, github_1.deriveGithubTrackedResource)(filter);
+    },
+    projectLifecycleSignal(rawPayload) {
+        return (0, github_1.projectGithubLifecycleSignal)(rawPayload);
+    },
     validateConfig(source) {
         (0, github_1.parseGithubSourceConfig)(source);
     },
@@ -164,6 +239,34 @@ const GITHUB_REPO_PROFILE = {
 };
 const GITHUB_REPO_CI_PROFILE = {
     id: "builtin.github_repo_ci",
+    describeCapabilities() {
+        return {
+            sourceKind: "github_repo_ci",
+            aliases: ["github_repo_ci"],
+            configSchema: [
+                { name: "owner", type: "string", required: true, description: "GitHub repository owner." },
+                { name: "repo", type: "string", required: true, description: "GitHub repository name." },
+                { name: "uxcAuth", type: "string", required: false, description: "Optional uxc auth profile." },
+                { name: "pollIntervalSecs", type: "number", required: false, description: "Polling interval in seconds." },
+                { name: "perPage", type: "number", required: false, description: "Workflow runs requested per poll." },
+                { name: "eventFilter", type: "string", required: false, description: "Optional GitHub workflow event filter." },
+                { name: "branch", type: "string", required: false, description: "Optional branch filter for workflow runs." },
+                { name: "statusFilter", type: "string", required: false, description: "Optional workflow status filter." },
+            ],
+            metadataFields: [
+                { name: "name", type: "string|null", description: "Workflow run name." },
+                { name: "status", type: "string", description: "Normalized workflow run status." },
+                { 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: "headSha", type: "string|null", description: "Head commit SHA for 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." },
+            ],
+            eventVariantExamples: ["workflow_run.ci.completed.failure", "workflow_run.nightly_checks.observed"],
+        };
+    },
     validateConfig(source) {
         (0, github_ci_1.parseGithubCiSourceConfig)(source);
     },
@@ -217,6 +320,36 @@ const GITHUB_REPO_CI_PROFILE = {
 };
 const FEISHU_BOT_PROFILE = {
     id: "builtin.feishu_bot",
+    describeCapabilities() {
+        return {
+            sourceKind: "feishu_bot",
+            aliases: ["feishu_bot"],
+            configSchema: [
+                { name: "appId", type: "string", required: true, description: "Feishu app ID." },
+                { name: "appSecret", type: "string", required: true, description: "Feishu app secret." },
+                { name: "eventTypes", type: "string[]", required: false, description: "Optional Feishu event type allowlist." },
+                { name: "chatIds", type: "string[]", required: false, description: "Optional Feishu chat allowlist." },
+                { name: "schemaUrl", type: "string", required: false, description: "Optional Feishu OpenAPI schema URL." },
+                { name: "replyInThread", type: "boolean", required: false, description: "Reply in thread when sending outbound messages." },
+                { name: "uxcAuth", type: "string", required: false, description: "Optional uxc auth profile." },
+            ],
+            metadataFields: [
+                { name: "eventType", type: "string", description: "Feishu event type." },
+                { name: "chatId", type: "string", description: "Target chat ID." },
+                { name: "chatType", type: "string|null", description: "Feishu chat type." },
+                { name: "messageId", type: "string", description: "Feishu message ID." },
+                { name: "messageType", type: "string", description: "Feishu message type such as text." },
+                { name: "senderOpenId", type: "string|null", description: "Sender open_id when present." },
+                { name: "senderType", type: "string|null", description: "Sender type." },
+                { name: "mentions", type: "string[]", description: "Mention names extracted from the message." },
+                { name: "mentionOpenIds", type: "string[]", description: "Mention open_ids extracted from the message." },
+                { name: "content", type: "string|null", description: "Normalized message content string." },
+                { name: "threadId", type: "string|null", description: "Thread or root message ID when present." },
+                { name: "parentId", type: "string|null", description: "Parent message ID when present." },
+            ],
+            eventVariantExamples: ["im.message.receive_v1.text"],
+        };
+    },
     validateConfig(source) {
         (0, feishu_1.parseFeishuSourceConfig)(source);
     },

package/dist/src/store.js

@@ -16,6 +16,17 @@ function parseJson(value) {
     }
     return JSON.parse(value);
 }
+function earlierLifecycleRetirement(left, right) {
+    const leftAt = Date.parse(left.retireAt);
+    const rightAt = Date.parse(right.retireAt);
+    if (!Number.isNaN(leftAt) && !Number.isNaN(rightAt) && leftAt <= rightAt) {
+        return {
+            ...left,
+            updatedAt: right.updatedAt,
+        };
+    }
+    return right;
+}
 class AgentInboxStore {
     dbPath;
     db;
@@ -193,6 +204,38 @@ class AgentInboxStore {
         const rows = this.getAll("select * from sources order by created_at asc");
         return rows.map((row) => this.mapSource(row));
     }
+    getSourceIdleState(sourceId) {
+        const row = this.getOne("select * from source_idle_states where source_id = ?", [sourceId]);
+        return row ? this.mapSourceIdleState(row) : null;
+    }
+    listSourceIdleStatesDue(cutoffIso) {
+        const rows = this.getAll("select * from source_idle_states where auto_pause_at <= ? and auto_paused_at is null order by auto_pause_at asc", [cutoffIso]);
+        return rows.map((row) => this.mapSourceIdleState(row));
+    }
+    upsertSourceIdleState(idleState) {
+        this.db.run(`
+      insert into source_idle_states (
+        source_id, idle_since, auto_pause_at, auto_paused_at, updated_at
+      ) values (?, ?, ?, ?, ?)
+      on conflict(source_id) do update set
+        idle_since = excluded.idle_since,
+        auto_pause_at = excluded.auto_pause_at,
+        auto_paused_at = excluded.auto_paused_at,
+        updated_at = excluded.updated_at
+    `, [
+            idleState.sourceId,
+            idleState.idleSince,
+            idleState.autoPauseAt,
+            idleState.autoPausedAt ?? null,
+            idleState.updatedAt,
+        ]);
+        this.persist();
+        return this.getSourceIdleState(idleState.sourceId);
+    }
+    deleteSourceIdleState(sourceId) {
+        this.db.run("delete from source_idle_states where source_id = ?", [sourceId]);
+        this.persist();
+    }
     updateSourceDefinition(sourceId, input) {
         const current = this.getSource(sourceId);
         if (!current) {
@@ -245,6 +288,7 @@ class AgentInboxStore {
                 this.db.run("delete from stream_events where stream_id = ?", [stream.streamId]);
                 this.db.run("delete from streams where stream_id = ?", [stream.streamId]);
             }
+            this.db.run("delete from source_idle_states where source_id = ?", [sourceId]);
             this.db.run("delete from sources where source_id = ?", [sourceId]);
         });
         this.persist();
@@ -319,15 +363,15 @@ class AgentInboxStore {
     insertSubscription(subscription) {
         this.db.run(`
       insert into subscriptions (
-        subscription_id, agent_id, source_id, filter_json, lifecycle_mode, expires_at, start_policy, start_offset, start_time, created_at
+        subscription_id, agent_id, source_id, filter_json, tracked_resource_ref, cleanup_policy_json, start_policy, start_offset, start_time, created_at
       ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `, [
             subscription.subscriptionId,
             subscription.agentId,
             subscription.sourceId,
             JSON.stringify(subscription.filter),
-            subscription.lifecycleMode,
-            subscription.expiresAt ?? null,
+            subscription.trackedResourceRef ?? null,
+            JSON.stringify(subscription.cleanupPolicy),
             subscription.startPolicy,
             subscription.startOffset ?? null,
             subscription.startTime ?? null,
@@ -352,10 +396,63 @@ class AgentInboxStore {
         if (!subscription) {
             return null;
         }
-        this.db.run("delete from subscriptions where subscription_id = ?", [subscriptionId]);
+        this.inTransaction(() => {
+            this.db.run("delete from consumer_commits where consumer_id in (select consumer_id from consumers where subscription_id = ?)", [subscriptionId]);
+            this.db.run("delete from consumers where subscription_id = ?", [subscriptionId]);
+            this.db.run("delete from subscription_lifecycle_retirements where subscription_id = ?", [subscriptionId]);
+            this.db.run("delete from subscriptions where subscription_id = ?", [subscriptionId]);
+        });
         this.persist();
         return subscription;
     }
+    getSubscriptionLifecycleRetirement(subscriptionId) {
+        const row = this.getOne("select * from subscription_lifecycle_retirements where subscription_id = ?", [subscriptionId]);
+        return row ? this.mapSubscriptionLifecycleRetirement(row) : null;
+    }
+    listSubscriptionLifecycleRetirements() {
+        const rows = this.getAll("select * from subscription_lifecycle_retirements order by retire_at asc, created_at asc");
+        return rows.map((row) => this.mapSubscriptionLifecycleRetirement(row));
+    }
+    listSubscriptionLifecycleRetirementsDue(cutoffIso) {
+        const rows = this.getAll("select * from subscription_lifecycle_retirements where retire_at <= ? order by retire_at asc, created_at asc", [cutoffIso]);
+        return rows.map((row) => this.mapSubscriptionLifecycleRetirement(row));
+    }
+    upsertSubscriptionLifecycleRetirement(retirement) {
+        const existing = this.getSubscriptionLifecycleRetirement(retirement.subscriptionId);
+        const next = existing
+            ? earlierLifecycleRetirement(existing, retirement)
+            : retirement;
+        this.db.run(`
+      insert into subscription_lifecycle_retirements (
+        subscription_id, source_id, tracked_resource_ref, retire_at, terminal_state, terminal_result, terminal_occurred_at, created_at, updated_at
+      ) values (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      on conflict(subscription_id) do update set
+        source_id = excluded.source_id,
+        tracked_resource_ref = excluded.tracked_resource_ref,
+        retire_at = excluded.retire_at,
+        terminal_state = excluded.terminal_state,
+        terminal_result = excluded.terminal_result,
+        terminal_occurred_at = excluded.terminal_occurred_at,
+        created_at = excluded.created_at,
+        updated_at = excluded.updated_at
+    `, [
+            next.subscriptionId,
+            next.sourceId,
+            next.trackedResourceRef,
+            next.retireAt,
+            next.terminalState ?? null,
+            next.terminalResult ?? null,
+            next.terminalOccurredAt ?? null,
+            next.createdAt,
+            next.updatedAt,
+        ]);
+        this.persist();
+        return this.getSubscriptionLifecycleRetirement(retirement.subscriptionId);
+    }
+    deleteSubscriptionLifecycleRetirement(subscriptionId) {
+        this.db.run("delete from subscription_lifecycle_retirements where subscription_id = ?", [subscriptionId]);
+        this.persist();
+    }
     getActivationTarget(targetId) {
         const row = this.getOne("select * from activation_targets where target_id = ?", [targetId]);
         return row ? this.mapActivationTarget(row) : null;
@@ -507,6 +604,8 @@ class AgentInboxStore {
                 ]);
                 this.db.run("delete from consumers where subscription_id = ?", [subscription.subscriptionId]);
             }
+            this.db.run("delete from subscription_lifecycle_retirements where subscription_id in (select subscription_id from subscriptions where agent_id = ?)", [agentId]);
+            this.db.run("delete from source_idle_states where source_id in (select distinct source_id from subscriptions where agent_id = ?)", [agentId]);
             this.db.run("delete from subscriptions where agent_id = ?", [agentId]);
             this.db.run("delete from activation_dispatch_states where agent_id = ?", [agentId]);
             this.db.run("delete from activation_targets where agent_id = ?", [agentId]);
@@ -895,6 +994,8 @@ class AgentInboxStore {
             agents: this.count("agents"),
             offlineAgents: this.count("agents where status = 'offline'"),
             subscriptions: this.count("subscriptions"),
+            subscriptionLifecycleRetirements: this.count("subscription_lifecycle_retirements"),
+            sourceIdleStates: this.count("source_idle_states"),
             inboxes: this.count("inboxes"),
             activationTargets: this.count("activation_targets"),
             offlineActivationTargets: this.count("activation_targets where status = 'offline'"),
@@ -959,6 +1060,15 @@ class AgentInboxStore {
             updatedAt: String(row.updated_at),
         };
     }
+    mapSourceIdleState(row) {
+        return {
+            sourceId: String(row.source_id),
+            idleSince: String(row.idle_since),
+            autoPauseAt: String(row.auto_pause_at),
+            autoPausedAt: row.auto_paused_at ? String(row.auto_paused_at) : null,
+            updatedAt: String(row.updated_at),
+        };
+    }
     mapAgent(row) {
         return {
             agentId: String(row.agent_id),
@@ -984,14 +1094,27 @@ class AgentInboxStore {
             agentId: String(row.agent_id),
             sourceId: String(row.source_id),
             filter: parseJson(row.filter_json),
-            lifecycleMode: row.lifecycle_mode,
-            expiresAt: row.expires_at ? String(row.expires_at) : null,
+            trackedResourceRef: row.tracked_resource_ref ? String(row.tracked_resource_ref) : null,
+            cleanupPolicy: parseJson(row.cleanup_policy_json),
             startPolicy: row.start_policy,
             startOffset: row.start_offset != null ? Number(row.start_offset) : null,
             startTime: row.start_time ? String(row.start_time) : null,
             createdAt: String(row.created_at),
         };
     }
+    mapSubscriptionLifecycleRetirement(row) {
+        return {
+            subscriptionId: String(row.subscription_id),
+            sourceId: String(row.source_id),
+            trackedResourceRef: String(row.tracked_resource_ref),
+            retireAt: String(row.retire_at),
+            terminalState: row.terminal_state ? String(row.terminal_state) : null,
+            terminalResult: row.terminal_result ? String(row.terminal_result) : null,
+            terminalOccurredAt: row.terminal_occurred_at ? String(row.terminal_occurred_at) : null,
+            createdAt: String(row.created_at),
+            updatedAt: String(row.updated_at),
+        };
+    }
     mapActivationTarget(row) {
         if (String(row.kind) === "webhook") {
             const url = typeof row.url === "string" && row.url.trim().length > 0 ? row.url.trim() : null;