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

package/dist/src/sources/github.js

@@ -6,9 +6,12 @@ exports.invokeGithubDeliveryOperation = invokeGithubDeliveryOperation;
 exports.normalizeGithubRepoEvent = normalizeGithubRepoEvent;
 exports.hydrateGithubRepoEventIfNeeded = hydrateGithubRepoEventIfNeeded;
 exports.canonicalGithubPullRequestRef = canonicalGithubPullRequestRef;
+exports.canonicalGithubIssueRef = canonicalGithubIssueRef;
 exports.deriveGithubTrackedResource = deriveGithubTrackedResource;
 exports.githubSubscriptionShortcutSpec = githubSubscriptionShortcutSpec;
+exports.githubFollowTemplateSpec = githubFollowTemplateSpec;
 exports.expandGithubSubscriptionShortcut = expandGithubSubscriptionShortcut;
+exports.expandGithubFollowTemplate = expandGithubFollowTemplate;
 exports.projectGithubLifecycleSignal = projectGithubLifecycleSignal;
 exports.parseGithubSourceConfig = parseGithubSourceConfig;
 const uxc_daemon_client_1 = require("@holon-run/uxc-daemon-client");
@@ -88,6 +91,24 @@ class GithubUxcClient {
             options: { auth: input.auth },
         });
     }
+    async getPullRequestDetails(input) {
+        const response = await this.client.call({
+            endpoint: exports.GITHUB_ENDPOINT,
+            operation: "get:/repos/{owner}/{repo}/pulls/{pull_number}",
+            payload: {
+                owner: input.owner,
+                repo: input.repo,
+                pull_number: input.pullNumber,
+            },
+            options: { auth: input.auth },
+        });
+        const data = asRecord(response.data);
+        const head = asRecord(data.head);
+        return {
+            headRefName: asString(head.ref),
+            headRepositoryFullName: asString(asRecord(head.repo).full_name),
+        };
+    }
 }
 exports.GithubUxcClient = GithubUxcClient;
 class GithubDeliveryAdapter {
@@ -336,6 +357,10 @@ function canonicalGithubPullRequestRef(source, number) {
     const config = parseGithubSourceConfig(source);
     return `repo:${config.owner}/${config.repo}:pr:${number}`;
 }
+function canonicalGithubIssueRef(source, number) {
+    const config = parseGithubSourceConfig(source);
+    return `repo:${config.owner}/${config.repo}:issue:${number}`;
+}
 function deriveGithubTrackedResource(filter, source) {
     const metadata = asRecord(filter.metadata);
     const payload = asRecord(filter.payload);
@@ -356,7 +381,43 @@ function githubSubscriptionShortcutSpec() {
             ],
         }];
 }
-function expandGithubSubscriptionShortcut(input) {
+function githubFollowTemplateSpec() {
+    const repoArgs = [
+        { name: "owner", type: "string", required: true, description: "GitHub repository owner." },
+        { name: "repo", type: "string", required: true, description: "GitHub repository name." },
+    ];
+    return [
+        {
+            templateId: "github.repo",
+            providerOrKind: "github",
+            label: "GitHub Repository",
+            description: "Follow a repository event stream.",
+            argsSchema: repoArgs,
+        },
+        {
+            templateId: "github.pr",
+            providerOrKind: "github",
+            label: "GitHub Pull Request",
+            description: "Follow one pull request and optionally its CI.",
+            argsSchema: [
+                ...repoArgs,
+                { name: "number", type: "number", required: true, description: "Pull request number." },
+                { name: "withCi", type: "boolean", required: false, description: "Also follow the repository CI stream for that pull request." },
+            ],
+        },
+        {
+            templateId: "github.issue",
+            providerOrKind: "github",
+            label: "GitHub Issue",
+            description: "Follow one issue without automatic terminal cleanup.",
+            argsSchema: [
+                ...repoArgs,
+                { name: "number", type: "number", required: true, description: "Issue number." },
+            ],
+        },
+    ];
+}
+async function expandGithubSubscriptionShortcut(input, client = new GithubUxcClient()) {
     if (input.name !== "pr") {
         return null;
     }
@@ -366,6 +427,9 @@ function expandGithubSubscriptionShortcut(input) {
     }
     const trackedResourceRef = canonicalGithubPullRequestRef(input.source, number);
     const withCi = input.args?.withCi === true;
+    const ciFilter = withCi
+        ? await buildGithubPrCiFilter(input.source, number, client)
+        : null;
     return {
         members: [
             {
@@ -382,6 +446,7 @@ function expandGithubSubscriptionShortcut(input) {
             ...(withCi
                 ? [{
                         streamKind: "ci_runs",
+                        filter: ciFilter ?? undefined,
                         trackedResourceRef,
                         cleanupPolicy: { mode: "on_terminal" },
                     }]
@@ -389,6 +454,152 @@ function expandGithubSubscriptionShortcut(input) {
         ],
     };
 }
+async function expandGithubFollowTemplate(input, client = new GithubUxcClient()) {
+    const config = parseGithubSourceConfig(input.source);
+    if (input.template === "repo") {
+        return {
+            templateId: "github.repo",
+            sources: [
+                {
+                    logicalName: "repo_events",
+                    sourceType: "github_repo",
+                    sourceKey: `${config.owner}/${config.repo}`,
+                    configRef: input.source.configRef ?? null,
+                    config: githubFollowSourceConfig(input.source),
+                },
+            ],
+            subscriptions: [
+                {
+                    sourceLogicalName: "repo_events",
+                    filter: {},
+                    cleanupPolicy: { mode: "manual" },
+                },
+            ],
+        };
+    }
+    const number = typeof input.args?.number === "number" ? input.args.number : null;
+    if (input.template !== "pr" && input.template !== "issue") {
+        return null;
+    }
+    if (!number || !Number.isInteger(number) || number <= 0) {
+        throw new Error(`follow template github.${input.template} requires a positive integer number`);
+    }
+    if (input.template === "pr") {
+        const trackedResourceRef = canonicalGithubPullRequestRef(input.source, number);
+        const withCi = input.args?.withCi === true;
+        const ciFilter = withCi
+            ? await buildGithubPrCiFilter(input.source, number, client)
+            : null;
+        return {
+            templateId: "github.pr",
+            sources: [
+                {
+                    logicalName: "repo_events",
+                    sourceType: "github_repo",
+                    sourceKey: `${config.owner}/${config.repo}`,
+                    configRef: input.source.configRef ?? null,
+                    config: githubFollowSourceConfig(input.source),
+                },
+                ...(withCi
+                    ? [{
+                            logicalName: "ci_runs",
+                            sourceType: "github_repo_ci",
+                            sourceKey: `${config.owner}/${config.repo}`,
+                            configRef: input.source.configRef ?? null,
+                            config: githubFollowSourceConfig(input.source),
+                        }]
+                    : []),
+            ],
+            subscriptions: [
+                {
+                    sourceLogicalName: "repo_events",
+                    filter: {
+                        metadata: {
+                            number,
+                            isPullRequest: true,
+                        },
+                    },
+                    trackedResourceRef,
+                    cleanupPolicy: { mode: "on_terminal" },
+                },
+                ...(withCi
+                    ? [{
+                            sourceLogicalName: "ci_runs",
+                            filter: ciFilter ?? undefined,
+                            trackedResourceRef,
+                            cleanupPolicy: { mode: "on_terminal" },
+                        }]
+                    : []),
+            ],
+        };
+    }
+    return {
+        templateId: "github.issue",
+        sources: [
+            {
+                logicalName: "repo_events",
+                sourceType: "github_repo",
+                sourceKey: `${config.owner}/${config.repo}`,
+                configRef: input.source.configRef ?? null,
+                config: githubFollowSourceConfig(input.source),
+            },
+        ],
+        subscriptions: [
+            {
+                sourceLogicalName: "repo_events",
+                filter: {
+                    metadata: {
+                        number,
+                        isPullRequest: false,
+                    },
+                },
+                trackedResourceRef: canonicalGithubIssueRef(input.source, number),
+                cleanupPolicy: { mode: "manual" },
+            },
+        ],
+    };
+}
+async function buildGithubPrCiFilter(source, number, client) {
+    const config = parseGithubSourceConfig(source);
+    const baseExpr = `contains(metadata.pullRequestNumbers, ${number})`;
+    try {
+        const details = await client.getPullRequestDetails({
+            owner: config.owner,
+            repo: config.repo,
+            pullNumber: number,
+            auth: config.uxcAuth,
+        });
+        if (!details.headRefName) {
+            throw new Error(`could not resolve head branch for PR #${number}`);
+        }
+        return {
+            expr: buildGithubPrCiFilterExpr(number, details.headRefName, details.headRepositoryFullName),
+        };
+    }
+    catch {
+        return { expr: baseExpr };
+    }
+}
+function buildGithubPrCiFilterExpr(number, headRefName, headRepositoryFullName) {
+    const base = `contains(metadata.pullRequestNumbers, ${number})`;
+    const branchExpr = `metadata.headBranch == ${JSON.stringify(headRefName)}`;
+    if (!headRepositoryFullName) {
+        return `${base} || ${branchExpr}`;
+    }
+    return [
+        base,
+        "||",
+        "(",
+        branchExpr,
+        "&&",
+        "(",
+        `metadata.headRepositoryFullName == ${JSON.stringify(headRepositoryFullName)}`,
+        "||",
+        "!exists(metadata.headRepositoryFullName)",
+        ")",
+        ")",
+    ].join(" ");
+}
 function projectGithubLifecycleSignal(rawPayload, source) {
     const eventType = asString(rawPayload.type);
     if (eventType !== "PullRequestEvent") {
@@ -411,6 +622,12 @@ function projectGithubLifecycleSignal(rawPayload, source) {
         result: merged ? "merged" : "closed",
     };
 }
+function githubFollowSourceConfig(source) {
+    const config = { ...(source.config ?? {}) };
+    delete config.number;
+    delete config.withCi;
+    return config;
+}
 function buildGithubDeliveryHandle(config, eventType, number, comment) {
     if (!number) {
         return null;

package/dist/src/sources/github_ci.js

@@ -7,6 +7,7 @@ const uxc_daemon_client_1 = require("@holon-run/uxc-daemon-client");
 exports.GITHUB_CI_ENDPOINT = "https://api.github.com";
 exports.DEFAULT_GITHUB_CI_POLL_INTERVAL_SECS = 30;
 exports.DEFAULT_GITHUB_CI_PER_PAGE = 20;
+const MAX_PAGES_PER_SYNC = 10;
 const MAX_SEEN_KEYS = 512;
 const MAX_ERROR_BACKOFF_MULTIPLIER = 8;
 class GithubActionsUxcClient {
@@ -14,11 +15,12 @@ class GithubActionsUxcClient {
     constructor(client = new uxc_daemon_client_1.UxcDaemonClient({ env: process.env })) {
         this.client = client;
     }
-    async listWorkflowRuns(config) {
+    async listWorkflowRuns(config, page = 1) {
         const payload = {
             owner: config.owner,
             repo: config.repo,
             per_page: config.perPage ?? exports.DEFAULT_GITHUB_CI_PER_PAGE,
+            page,
         };
         if (config.eventFilter) {
             payload.event = config.eventFilter;
@@ -153,30 +155,48 @@ class GithubCiSourceRuntime {
             }
             this.lastPollAt.set(sourceId, Date.now());
             const checkpoint = parseGithubCiCheckpoint(source.checkpoint);
-            const runs = await this.client.listWorkflowRuns(config);
             let appended = 0;
             let deduped = 0;
-            let lastSeenUpdatedAt = checkpoint.lastSeenUpdatedAt ?? undefined;
+            let eventsRead = 0;
+            let pageCount = 0;
+            const checkpointLastSeenUpdatedAt = checkpoint.lastSeenUpdatedAt ?? undefined;
+            let lastSeenUpdatedAt = checkpointLastSeenUpdatedAt;
             const seenKeys = new Set(checkpoint.seenRunKeys ?? []);
-            for (const run of runs.slice().reverse()) {
-                const normalized = normalizeGithubWorkflowRunEvent(source, config, run);
-                if (!normalized) {
-                    continue;
+            const perPage = config.perPage ?? exports.DEFAULT_GITHUB_CI_PER_PAGE;
+            for (let page = 1; page <= MAX_PAGES_PER_SYNC; page += 1) {
+                const runs = await this.client.listWorkflowRuns(config, page);
+                pageCount = page;
+                eventsRead += runs.length;
+                let pageHasNewRuns = false;
+                for (const run of runs.slice().reverse()) {
+                    const normalized = normalizeGithubWorkflowRunEvent(source, config, run);
+                    if (!normalized) {
+                        continue;
+                    }
+                    const eventUpdatedAt = normalized.metadata?.updatedAt;
+                    const runKey = `${normalized.sourceNativeId}:${normalized.eventVariant}`;
+                    const isNewerThanCheckpoint = typeof eventUpdatedAt === "string" &&
+                        (!checkpointLastSeenUpdatedAt || eventUpdatedAt > checkpointLastSeenUpdatedAt);
+                    const isAtCheckpointBoundary = typeof eventUpdatedAt === "string" &&
+                        typeof checkpointLastSeenUpdatedAt === "string" &&
+                        eventUpdatedAt === checkpointLastSeenUpdatedAt;
+                    const shouldProcess = !checkpointLastSeenUpdatedAt ||
+                        isNewerThanCheckpoint ||
+                        (isAtCheckpointBoundary && !seenKeys.has(runKey));
+                    if (!shouldProcess) {
+                        continue;
+                    }
+                    pageHasNewRuns = true;
+                    const result = await this.appendSourceEvent(normalized);
+                    appended += result.appended;
+                    deduped += result.deduped;
+                    seenKeys.add(runKey);
+                    if (typeof eventUpdatedAt === "string" && (!lastSeenUpdatedAt || eventUpdatedAt >= lastSeenUpdatedAt)) {
+                        lastSeenUpdatedAt = eventUpdatedAt;
+                    }
                 }
-                const eventUpdatedAt = normalized.metadata?.updatedAt;
-                const runKey = `${normalized.sourceNativeId}:${normalized.eventVariant}`;
-                const shouldProcess = !lastSeenUpdatedAt ||
-                    (typeof eventUpdatedAt === "string" && eventUpdatedAt > lastSeenUpdatedAt) ||
-                    !seenKeys.has(runKey);
-                if (!shouldProcess) {
-                    continue;
-                }
-                const result = await this.appendSourceEvent(normalized);
-                appended += result.appended;
-                deduped += result.deduped;
-                seenKeys.add(runKey);
-                if (typeof eventUpdatedAt === "string" && (!lastSeenUpdatedAt || eventUpdatedAt >= lastSeenUpdatedAt)) {
-                    lastSeenUpdatedAt = eventUpdatedAt;
+                if (!pageHasNewRuns || runs.length < perPage) {
+                    break;
                 }
             }
             this.store.updateSourceRuntime(sourceId, {
@@ -195,8 +215,8 @@ class GithubCiSourceRuntime {
                 sourceType: "github_repo_ci",
                 appended,
                 deduped,
-                eventsRead: runs.length,
-                note: `workflow runs fetched=${runs.length}`,
+                eventsRead,
+                note: `workflow runs fetched=${eventsRead} pages=${pageCount}`,
             };
         }
         catch (error) {
@@ -240,6 +260,8 @@ function normalizeGithubWorkflowRunEvent(source, config, raw) {
     const variant = buildWorkflowRunVariant(workflowName, status, conclusion);
     const actor = asRecord(run.actor);
     const headCommit = asRecord(run.head_commit);
+    const headRepository = asRecord(run.head_repository);
+    const pullRequestNumbers = extractPullRequestNumbers(run.pull_requests);
     return {
         sourceId: source.sourceId,
         sourceNativeId: `workflow_run:${runId}`,
@@ -259,6 +281,8 @@ function normalizeGithubWorkflowRunEvent(source, config, raw) {
             event: asString(run.event),
             headSha: asString(run.head_sha),
             headBranch: asString(run.head_branch),
+            headRepositoryFullName: asString(headRepository.full_name),
+            pullRequestNumbers,
             runNumber: asNumber(run.run_number),
             runAttempt: asNumber(run.run_attempt),
             actor: asString(actor.login),
@@ -277,6 +301,10 @@ function normalizeGithubWorkflowRunEvent(source, config, raw) {
             event: asString(run.event),
             head_sha: asString(run.head_sha),
             head_branch: asString(run.head_branch),
+            head_repository: {
+                full_name: asString(headRepository.full_name),
+            },
+            pull_requests: pullRequestNumbers.map((number) => ({ number })),
             run_number: asNumber(run.run_number),
             run_attempt: asNumber(run.run_attempt),
             html_url: asString(run.html_url),
@@ -343,6 +371,19 @@ function asString(value) {
 function asNumber(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+function extractPullRequestNumbers(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const numbers = new Set();
+    for (const entry of value) {
+        const number = asNumber(asRecord(entry).number);
+        if (number && Number.isInteger(number) && number > 0) {
+            numbers.add(number);
+        }
+    }
+    return Array.from(numbers).sort((left, right) => left - right);
+}
 function inferWorkflowRunStatus(run, conclusion) {
     return asString(run.status)
         ?? (conclusion ? "completed" : null)

package/dist/src/sources/remote.js

@@ -40,6 +40,12 @@ class RpcUxcRemoteSourceClient {
     async sourceStop(namespace, sourceKey) {
         await this.client.sourceStop(namespace, sourceKey);
     }
+    sourceStatus(namespace, sourceKey) {
+        return this.client.sourceStatus(namespace, sourceKey);
+    }
+    sourceList() {
+        return this.client.sourceList();
+    }
     async sourceDelete(namespace, sourceKey) {
         await this.client.sourceDelete(namespace, sourceKey);
     }
@@ -131,6 +137,8 @@ class RemoteSourceRuntime {
         this.errorCounts.delete(sourceId);
         this.nextRetryAt.delete(sourceId);
         const checkpoint = parseRemoteCheckpoint(source.checkpoint);
+        const pausedAt = (0, util_1.nowIso)();
+        const baseRuntime = checkpoint.managedRuntime ?? checkpointRuntimeFromSource(source, checkpoint) ?? {};
         this.store.updateSourceRuntime(sourceId, {
             status: "paused",
             checkpoint: JSON.stringify({
@@ -142,6 +150,13 @@ class RemoteSourceRuntime {
                         streamId: checkpoint.managedSource.streamId,
                     },
                 } : {}),
+                managedRuntime: {
+                    ...baseRuntime,
+                    status: "stopped",
+                    updatedAt: pausedAt,
+                    stoppedAt: pausedAt,
+                    lastError: null,
+                },
                 lastError: null,
             }),
         });
@@ -167,6 +182,47 @@ class RemoteSourceRuntime {
             erroredSourceIds: Array.from(this.errorCounts.keys()).sort(),
         };
     }
+    async getSourceRuntime(source) {
+        if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
+            return null;
+        }
+        const binding = managedBindingForSource(source);
+        try {
+            const managed = await this.client.sourceStatus(binding.namespace, binding.sourceKey);
+            return runtimeStateFromManagedView(managed, "live");
+        }
+        catch {
+            return runtimeStateFromCheckpoint(source);
+        }
+    }
+    async listSourceRuntimes(sources) {
+        const result = new Map();
+        const remoteSources = sources.filter((source) => REMOTE_SOURCE_TYPES.has(source.sourceType));
+        for (const source of sources) {
+            if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
+                result.set(source.sourceId, null);
+            }
+        }
+        if (remoteSources.length === 0) {
+            return result;
+        }
+        try {
+            const managedSources = await this.client.sourceList();
+            const byBinding = new Map(managedSources.map((entry) => [managedSourceBindingKey(entry.namespace, entry.source_key), entry]));
+            for (const source of remoteSources) {
+                const binding = managedBindingForSource(source);
+                const live = byBinding.get(managedSourceBindingKey(binding.namespace, binding.sourceKey));
+                result.set(source.sourceId, live ? runtimeStateFromManagedSourceListEntry(live, "live") : runtimeStateFromCheckpoint(source));
+            }
+            return result;
+        }
+        catch {
+            for (const source of remoteSources) {
+                result.set(source.sourceId, runtimeStateFromCheckpoint(source));
+            }
+            return result;
+        }
+    }
     async projectLifecycleSignal(source, rawPayload) {
         if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
             return null;
@@ -185,13 +241,37 @@ class RemoteSourceRuntime {
         if (typeof module.expandSubscriptionShortcut !== "function") {
             return null;
         }
-        const expanded = module.expandSubscriptionShortcut({
+        const expanded = await module.expandSubscriptionShortcut({
             name: input.name,
             args: input.args,
             source: moduleInputSource(source),
         });
         return normalizeExpandedSubscriptionPlan(expanded);
     }
+    async listFollowTemplates(source) {
+        if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
+            return [];
+        }
+        const module = await this.moduleRegistry.resolve(source, this.homeDir);
+        if (typeof module.listFollowTemplates !== "function") {
+            return [];
+        }
+        return module.listFollowTemplates(moduleInputSource(source));
+    }
+    async expandFollowTemplate(source, input) {
+        if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
+            return null;
+        }
+        const module = await this.moduleRegistry.resolve(source, this.homeDir);
+        if (typeof module.expandFollowTemplate !== "function") {
+            return null;
+        }
+        return module.expandFollowTemplate({
+            template: input.template,
+            args: input.args,
+            source: moduleInputSource(source),
+        });
+    }
     async deriveInlinePreview(source, item) {
         if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
             return null;
@@ -331,6 +411,7 @@ class RemoteSourceRuntime {
                     streamCursor: {
                         afterOffset: batch.next_after_offset,
                     },
+                    managedRuntime: checkpointRuntimeFromEnsureResponse(ensured, checkpoint.managedRuntime ?? null, (0, util_1.nowIso)()),
                     lastEventAt: (0, util_1.nowIso)(),
                     lastError: null,
                 }),
@@ -357,6 +438,7 @@ class RemoteSourceRuntime {
                     status: source.status === "paused" ? "paused" : "error",
                     checkpoint: JSON.stringify({
                         ...checkpoint,
+                        managedRuntime: checkpointRuntimeWithError(checkpoint.managedRuntime ?? checkpointRuntimeFromSource(source, checkpoint), error instanceof Error ? error.message : String(error), (0, util_1.nowIso)()),
                         lastError: error instanceof Error ? error.message : String(error),
                     }),
                 });
@@ -419,6 +501,9 @@ function managedBindingForSource(source) {
         sourceKey: checkpoint.managedSource?.sourceKey ?? defaultBinding.sourceKey,
     };
 }
+function managedSourceBindingKey(namespace, sourceKey) {
+    return `${namespace}:${sourceKey}`;
+}
 function parseRemoteCheckpoint(checkpoint) {
     if (!checkpoint) {
         return {};
@@ -430,6 +515,103 @@ function parseRemoteCheckpoint(checkpoint) {
         return {};
     }
 }
+function runtimeStateFromManagedView(managed, observation) {
+    return {
+        backend: "uxc",
+        observation,
+        namespace: managed.namespace,
+        sourceKey: managed.source_key,
+        status: managed.status,
+        runId: managed.run_id,
+        streamId: managed.stream_id,
+        lastError: managed.last_error ?? null,
+        updatedAt: unixToIso(managed.updated_at_unix),
+        startedAt: unixToIso(managed.started_at_unix ?? null),
+        stoppedAt: unixToIso(managed.stopped_at_unix ?? null),
+    };
+}
+function runtimeStateFromManagedSourceListEntry(managed, observation) {
+    return {
+        backend: "uxc",
+        observation,
+        namespace: managed.namespace,
+        sourceKey: managed.source_key,
+        status: managed.status,
+        runId: managed.run_id,
+        streamId: managed.stream_id,
+        lastError: managed.last_error ?? null,
+        updatedAt: unixToIso(managed.updated_at_unix),
+        startedAt: null,
+        stoppedAt: null,
+    };
+}
+function runtimeStateFromCheckpoint(source) {
+    const checkpoint = parseRemoteCheckpoint(source.checkpoint);
+    const binding = managedBindingForSource(source);
+    const runtime = checkpoint.managedRuntime;
+    const streamId = runtime?.streamId ?? checkpoint.managedSource?.streamId ?? null;
+    if (!runtime && !checkpoint.managedSource) {
+        return null;
+    }
+    return {
+        backend: "uxc",
+        observation: "cached",
+        namespace: binding.namespace,
+        sourceKey: binding.sourceKey,
+        status: runtime?.status ?? null,
+        runId: runtime?.runId ?? null,
+        streamId,
+        lastError: runtime?.lastError ?? checkpoint.lastError ?? null,
+        updatedAt: runtime?.updatedAt ?? source.updatedAt,
+        startedAt: runtime?.startedAt ?? null,
+        stoppedAt: runtime?.stoppedAt ?? null,
+    };
+}
+function checkpointRuntimeFromEnsureResponse(ensured, previous, observedAt) {
+    return {
+        status: ensured.status,
+        runId: ensured.run_id,
+        streamId: ensured.stream_id,
+        lastError: null,
+        updatedAt: observedAt,
+        startedAt: previous?.runId === ensured.run_id ? previous.startedAt ?? null : null,
+        stoppedAt: null,
+    };
+}
+function checkpointRuntimeWithError(previous, lastError, observedAt) {
+    return {
+        status: previous?.status ?? null,
+        runId: previous?.runId ?? null,
+        streamId: previous?.streamId ?? null,
+        lastError,
+        updatedAt: observedAt,
+        startedAt: previous?.startedAt ?? null,
+        stoppedAt: previous?.stoppedAt ?? null,
+    };
+}
+function checkpointRuntimeFromSource(source, checkpoint = parseRemoteCheckpoint(source.checkpoint)) {
+    if (checkpoint.managedRuntime) {
+        return checkpoint.managedRuntime;
+    }
+    if (!checkpoint.managedSource) {
+        return null;
+    }
+    return {
+        status: null,
+        runId: null,
+        streamId: checkpoint.managedSource.streamId,
+        lastError: checkpoint.lastError ?? null,
+        updatedAt: source.updatedAt,
+        startedAt: null,
+        stoppedAt: null,
+    };
+}
+function unixToIso(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        return null;
+    }
+    return new Date(value * 1000).toISOString();
+}
 function computeErrorBackoffMs(baseIntervalSecs, errorCount) {
     const baseMs = Math.max(1, baseIntervalSecs) * 1000;
     const multiplier = Math.min(2 ** Math.max(0, errorCount - 1), MAX_ERROR_BACKOFF_MULTIPLIER);