@retinue/agentkit 0.2.0 → 0.3.1

package/dist/connections/oauth/service.js

@@ -0,0 +1,132 @@
+/**
+ * Connect, disconnect, list — the operations a host mounts — task #262, AC-1, AC-7, AC-8 and AC-9.
+ *
+ * The flow in `./index.ts` produces a URL and consumes a callback. This is what turns that into a stored
+ * connection, and what takes one away.
+ *
+ * Deliberately not a router. A host mounts these on its own paths with its own authentication, exactly as
+ * `./mcp-server` leaves the transport alone: every method here takes an already-authenticated
+ * `ExecutionContext`, so a host that has not authenticated has nothing to pass.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { assertSecureEndpoint } from "./index.js";
+/**
+ * What a connection is missing, for a caller deciding whether to send somebody back through consent — AC-9.
+ *
+ * Reads what was **granted**, never what the deployment's app requests: a tenant using their own OAuth app
+ * (#263) may have granted a different set, and the whole point is to say *reconnect and grant X* rather than
+ * surfacing a vendor 403 that names nothing actionable.
+ *
+ * A connection with no recorded grant returns `[]` rather than "everything is missing" — the provider did not
+ * tell us, and inventing a refusal from an absence would block working connections.
+ */
+export const missingScopes = (connection, required) => {
+    if (connection.grantedScopes === undefined)
+        return [];
+    const granted = new Set(connection.grantedScopes);
+    return required.filter((scope) => !granted.has(scope));
+};
+export const createOAuthConnectionService = (deps) => {
+    // Same reasoning as the flow's: a revocation request carries the token and the client secret.
+    if (deps.config.revocationUrl !== undefined)
+        assertSecureEndpoint("revocationUrl", deps.config.revocationUrl);
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const newId = deps.newId ?? (() => `${deps.config.provider}-${Math.random().toString(36).slice(2, 10)}`);
+    return {
+        /**
+         * Stores the result of a completed exchange — AC-8.
+         *
+         * The token is sealed on the way in and the non-secret parts are not, which is what lets a connection list
+         * render without a key. `metadata` carries whatever the provider disclosed at consent time — Atlassian's
+         * cloud id, Slack's team id — because those are needed on every subsequent request and are per connection.
+         */
+        async complete(input) {
+            return deps.store.create({
+                tenantId: input.context.tenantId,
+                connection: {
+                    id: newId(),
+                    provider: deps.config.provider,
+                    ...(input.label === undefined ? {} : { label: input.label }),
+                    mode: input.mode ?? "oauth2",
+                    scheme: input.scheme ?? "bearer",
+                    ...(input.tokens.metadata === undefined && input.metadata === undefined
+                        ? {}
+                        : { metadata: { ...input.tokens.metadata, ...input.metadata } }),
+                    ...(input.tokens.grantedScopes === undefined ? {} : { grantedScopes: input.tokens.grantedScopes }),
+                    sealed: await deps.cipher.seal(input.tokens.accessToken),
+                    ...(input.tokens.expiresAt === undefined ? {} : { expiresAt: input.tokens.expiresAt }),
+                },
+            });
+        },
+        /** A tenant's live connections for this provider. Never decrypts anything. */
+        async list(context) {
+            return deps.store.list({ tenantId: context.tenantId, provider: deps.config.provider });
+        },
+        /**
+         * Revokes at the provider, then locally — AC-7.
+         *
+         * **In that order.** Deleting first and then failing to revoke leaves a live token nobody can see and
+         * nobody can stop, which is strictly the worst outcome: the credential still works and the record of it is
+         * gone. Revoking first means a provider failure leaves a connection that is still listed and still
+         * revocable, which a person can retry.
+         *
+         * A provider with no revocation endpoint is **reported**, not silently skipped: a caller that believes a
+         * token was revoked when it was not will not go and remove it by hand.
+         */
+        async disconnect(input) {
+            const connection = await deps.store.get({ tenantId: input.context.tenantId, id: input.id });
+            if (connection === null)
+                throw new AgentPlatformError({
+                    code: "not_found",
+                    message: `no connection "${input.id}" for this workspace`,
+                    retryable: false,
+                });
+            let revokedAtProvider = false;
+            let reason;
+            if (deps.config.revocationUrl === undefined) {
+                reason = `${deps.config.provider} publishes no token revocation endpoint, so the token remains valid at the provider until it expires or is removed there by hand`;
+            }
+            else {
+                try {
+                    const token = await deps.cipher.open(connection.sealed);
+                    const body = new URLSearchParams({
+                        [deps.config.tokenParam ?? "token"]: token,
+                        client_id: deps.config.clientId,
+                    });
+                    if (deps.config.clientSecret !== undefined)
+                        body.set("client_secret", deps.config.clientSecret);
+                    const response = await fetchImpl(deps.config.revocationUrl, {
+                        method: "POST",
+                        headers: { "content-type": "application/x-www-form-urlencoded" },
+                        body: body.toString(),
+                    });
+                    revokedAtProvider = response.ok;
+                    if (!response.ok)
+                        reason = `the provider answered ${response.status} to the revocation request`;
+                }
+                catch (thrown) {
+                    // Reported, not thrown: the local revocation below must still happen, or a provider outage leaves a
+                    // connection nobody can remove.
+                    reason = thrown instanceof Error ? thrown.message : String(thrown);
+                }
+            }
+            await deps.store.revoke({ tenantId: input.context.tenantId, id: input.id });
+            return { revokedAtProvider, ...(reason === undefined ? {} : { reason }) };
+        },
+        /**
+         * What a caller should tell somebody when a tool needs a scope this connection lacks — AC-9.
+         *
+         * Returns the message rather than throwing, because the caller decides what to do with it: #264 turns it
+         * into a login URL and pauses the run, and a simpler host may just show it.
+         */
+        scopeGap(connection, required) {
+            const missing = missingScopes(connection, required);
+            if (missing.length === 0)
+                return null;
+            return (`this ${deps.config.provider} connection was granted ${(connection.grantedScopes ?? []).join(", ") || "no scopes"} ` +
+                `and this needs ${missing.join(", ")}. Reconnect and grant ${missing.join(", ")} — the provider will ` +
+                "otherwise answer 403, which names nothing you can act on.");
+        },
+    };
+};
+//# sourceMappingURL=service.js.map

package/dist/connections/pause.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A run that needs a connection pauses and asks — REQ-063 (#259), task #264.
+ *
+ * A tool call fails because the tenant has no connection, or the one they have expired or lacks a scope. Before
+ * this, that was `capability_unavailable`: the run died and a person read an error. Now it **pauses**, hands
+ * back a login URL, and resumes when consent completes.
+ *
+ * ## The third pause, not a new mechanism
+ *
+ * The runtime already does exactly this shape twice — `waiting-for-question` and `waiting-for-approval`, each
+ * with an event the engine emits, a status the worker parks in, and a resume to `queued`. Building a bespoke
+ * polling loop, or leaving a failed run for somebody to restart by hand, would be a second mechanism for the
+ * thing the durable runtime exists to do.
+ *
+ * ## Where it does **not** apply
+ *
+ * Only where a login URL exists. A token-based integration has nothing to redirect to, so a missing token must
+ * still fail with the message naming the ref. Getting this backwards produces the worst outcome available: a run
+ * that hangs for ever waiting for a consent screen nobody can reach.
+ *
+ * That decision comes from `ToolkitAuth.modes` (#260) — the reason `AuthMode` and `CredentialScheme` are
+ * separate axes. An OAuth access token is presented as a bearer, so a design that only knew the wire format
+ * could not answer this question at all.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import type { AuthMode } from "../tools/credentials.js";
+/**
+ * Why a connection is not usable. Three triggers, all of which should pause.
+ *
+ * Separate values because a UI says different things: "connect your GitHub" is not "your GitHub connection
+ * expired" is not "grant one more permission", and a person who is told the wrong one goes looking in the wrong
+ * place.
+ */
+export declare const CONNECTION_GAPS: readonly ["absent", "expired", "insufficient-scope"];
+export type ConnectionGap = (typeof CONNECTION_GAPS)[number];
+export type ConnectionNeed = {
+    readonly provider: string;
+    readonly gap: ConnectionGap;
+    /** Scopes the consent must ask for. For `insufficient-scope`, the missing ones plus what was already granted. */
+    readonly scopes: readonly string[];
+    readonly toolName?: string;
+};
+/**
+ * Recognises a failure as *a missing connection* rather than a broken tool.
+ *
+ * Structural rather than a string match on the message: a `details.connectionGap` set by the resolver, so
+ * rewording an error cannot silently turn a pausable failure into a fatal one. The marker is added by the
+ * connection resolver, which is the only code that knows the difference.
+ */
+export declare const connectionNeedOf: (thrown: unknown) => ConnectionNeed | null;
+/** Attaches the marker above to an error, so the engine can recognise it without parsing prose. */
+export declare const withConnectionGap: (error: AgentPlatformError, need: ConnectionNeed) => AgentPlatformError;
+/**
+ * Whether this provider can be connected by sending somebody somewhere — the branch that decides pause or fail.
+ *
+ * `undefined` modes means the host has not declared any, and the honest answer there is **no**: pausing a run
+ * for a provider that turns out to have no flow would hang it for ever, and failing is recoverable.
+ */
+export declare const canPauseForConsent: (modes: readonly AuthMode[] | undefined) => boolean;
+/**
+ * The message a person sees, per gap.
+ *
+ * Written here rather than in a UI so every client says the same thing, and so the distinction between the
+ * three gaps survives — a person told "connect your GitHub" when the real problem is a missing scope will
+ * disconnect and reconnect and land in exactly the same place.
+ */
+export declare const consentPrompt: (need: ConnectionNeed) => string;
+//# sourceMappingURL=pause.d.ts.map

package/dist/connections/pause.js

@@ -0,0 +1,97 @@
+/**
+ * A run that needs a connection pauses and asks — REQ-063 (#259), task #264.
+ *
+ * A tool call fails because the tenant has no connection, or the one they have expired or lacks a scope. Before
+ * this, that was `capability_unavailable`: the run died and a person read an error. Now it **pauses**, hands
+ * back a login URL, and resumes when consent completes.
+ *
+ * ## The third pause, not a new mechanism
+ *
+ * The runtime already does exactly this shape twice — `waiting-for-question` and `waiting-for-approval`, each
+ * with an event the engine emits, a status the worker parks in, and a resume to `queued`. Building a bespoke
+ * polling loop, or leaving a failed run for somebody to restart by hand, would be a second mechanism for the
+ * thing the durable runtime exists to do.
+ *
+ * ## Where it does **not** apply
+ *
+ * Only where a login URL exists. A token-based integration has nothing to redirect to, so a missing token must
+ * still fail with the message naming the ref. Getting this backwards produces the worst outcome available: a run
+ * that hangs for ever waiting for a consent screen nobody can reach.
+ *
+ * That decision comes from `ToolkitAuth.modes` (#260) — the reason `AuthMode` and `CredentialScheme` are
+ * separate axes. An OAuth access token is presented as a bearer, so a design that only knew the wire format
+ * could not answer this question at all.
+ */
+import { AgentPlatformError, isAgentPlatformError } from "../core/errors.js";
+/**
+ * Why a connection is not usable. Three triggers, all of which should pause.
+ *
+ * Separate values because a UI says different things: "connect your GitHub" is not "your GitHub connection
+ * expired" is not "grant one more permission", and a person who is told the wrong one goes looking in the wrong
+ * place.
+ */
+export const CONNECTION_GAPS = ["absent", "expired", "insufficient-scope"];
+/**
+ * Recognises a failure as *a missing connection* rather than a broken tool.
+ *
+ * Structural rather than a string match on the message: a `details.connectionGap` set by the resolver, so
+ * rewording an error cannot silently turn a pausable failure into a fatal one. The marker is added by the
+ * connection resolver, which is the only code that knows the difference.
+ */
+export const connectionNeedOf = (thrown) => {
+    if (!isAgentPlatformError(thrown))
+        return null;
+    const details = thrown.details;
+    const gap = details?.["connectionGap"];
+    const provider = details?.["connectionProvider"];
+    if (typeof gap !== "string" || !CONNECTION_GAPS.includes(gap))
+        return null;
+    if (typeof provider !== "string" || provider === "")
+        return null;
+    const scopes = details?.["connectionScopes"];
+    return {
+        provider,
+        gap: gap,
+        scopes: Array.isArray(scopes) ? scopes.filter((s) => typeof s === "string") : [],
+        ...(typeof details?.["toolName"] === "string" ? { toolName: details["toolName"] } : {}),
+    };
+};
+/** Attaches the marker above to an error, so the engine can recognise it without parsing prose. */
+export const withConnectionGap = (error, need) => new AgentPlatformError({
+    code: error.code,
+    message: error.message,
+    retryable: false,
+    details: {
+        ...(error.details ?? {}),
+        connectionGap: need.gap,
+        connectionProvider: need.provider,
+        connectionScopes: [...need.scopes],
+        ...(need.toolName === undefined ? {} : { toolName: need.toolName }),
+    },
+});
+/**
+ * Whether this provider can be connected by sending somebody somewhere — the branch that decides pause or fail.
+ *
+ * `undefined` modes means the host has not declared any, and the honest answer there is **no**: pausing a run
+ * for a provider that turns out to have no flow would hang it for ever, and failing is recoverable.
+ */
+export const canPauseForConsent = (modes) => modes !== undefined && modes.includes("oauth2");
+/**
+ * The message a person sees, per gap.
+ *
+ * Written here rather than in a UI so every client says the same thing, and so the distinction between the
+ * three gaps survives — a person told "connect your GitHub" when the real problem is a missing scope will
+ * disconnect and reconnect and land in exactly the same place.
+ */
+export const consentPrompt = (need) => {
+    switch (need.gap) {
+        case "absent":
+            return `Connect ${need.provider} to continue.`;
+        case "expired":
+            return `Your ${need.provider} connection expired. Reconnect to continue.`;
+        case "insufficient-scope":
+            return (`Your ${need.provider} connection needs ${need.scopes.join(", ") || "additional permissions"}. ` +
+                "Reconnect and grant them to continue.");
+    }
+};
+//# sourceMappingURL=pause.js.map

package/dist/connections/resolver.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A `CredentialResolver` over stored connections — the half that makes #260 useful, task #261.
+ *
+ * #260 made a credential a typed value and shipped one resolver: a static map, which serves exactly one tenant.
+ * This is the multi-tenant one, and it is the piece the whole integrations milestone was waiting for.
+ *
+ * ## Resolution is per call, and that is not an implementation detail
+ *
+ * `credentials.ts` explains why: a credential read once at startup survives its own rotation, and the failure
+ * looks like the vendor rejecting a token that "has not changed". This resolver therefore reads the store on
+ * every call and caches nothing. A deployment that wants caching adds it knowing its own rotation window —
+ * which is a decision only the deployment can make.
+ */
+import { type CredentialResolver, type CredentialScheme } from "../tools/credentials.js";
+import type { SecretCipher } from "./cipher.js";
+import { type Connection, type ConnectionStore } from "./index.js";
+export type ConnectionResolverDeps = {
+    readonly store: ConnectionStore;
+    readonly cipher: SecretCipher;
+    /**
+     * Which connection a bare `<provider>` ref means when a tenant has several.
+     *
+     * Defaults to the oldest, which is stable and explainable — "the first one you connected" — rather than
+     * newest, which would silently re-point every agent the moment somebody adds a second account.
+     */
+    readonly chooseDefault?: (candidates: readonly Connection[]) => Connection | undefined;
+};
+export declare const createConnectionCredentialResolver: (deps: ConnectionResolverDeps) => CredentialResolver;
+/** Which scheme a connection presents, for `assertToolkitAuth` at wiring time. */
+export declare const schemeOf: (connection: Connection) => CredentialScheme;
+/**
+ * Re-seals every connection that is not already under the current key — task #261 AC-7.
+ *
+ * Rotation without this is theory: `SecretCipher` can *open* an old key's secrets, but nothing moves them
+ * forward, so the old key can never be retired and the first key is permanent in practice.
+ *
+ * The order is what makes it safe to interrupt. Each connection is opened, re-sealed and written **one at a
+ * time**, and a failure leaves everything before it done and everything after it untouched — both readable,
+ * because the old key is still configured. Running it twice is a no-op: a connection already on the current key
+ * is skipped.
+ *
+ * Deliberately not a transaction over the whole tenant. A rotation across thousands of connections held in one
+ * transaction is a long-running write that blocks and, if it fails at the end, achieves nothing.
+ */
+export declare const resealConnections: (input: {
+    readonly store: ConnectionStore;
+    readonly cipher: SecretCipher;
+    readonly tenantId: string;
+    /** Reported per connection, so a long rotation is observable rather than silent. */
+    readonly onProgress?: (progress: {
+        readonly id: string;
+        readonly from: string;
+        readonly to: string;
+    }) => void;
+}) => Promise<{
+    readonly resealed: number;
+    readonly skipped: number;
+}>;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/connections/resolver.js

@@ -0,0 +1,138 @@
+/**
+ * A `CredentialResolver` over stored connections — the half that makes #260 useful, task #261.
+ *
+ * #260 made a credential a typed value and shipped one resolver: a static map, which serves exactly one tenant.
+ * This is the multi-tenant one, and it is the piece the whole integrations milestone was waiting for.
+ *
+ * ## Resolution is per call, and that is not an implementation detail
+ *
+ * `credentials.ts` explains why: a credential read once at startup survives its own rotation, and the failure
+ * looks like the vendor rejecting a token that "has not changed". This resolver therefore reads the store on
+ * every call and caches nothing. A deployment that wants caching adds it knowing its own rotation window —
+ * which is a decision only the deployment can make.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { createCredential, } from "../tools/credentials.js";
+import { parseCredentialRef } from "./index.js";
+import { withConnectionGap } from "./pause.js";
+/**
+ * How the plaintext behind a connection maps back to a `Credential`.
+ *
+ * The sealed blob holds **only** the secret parts — the token, or the password of a basic pair. Everything
+ * non-secret (the username, the header name, the metadata) is stored in readable columns, so listing
+ * connections needs no key and a person can see *which account* a connection is for without decrypting
+ * anything.
+ */
+const toCredential = (connection, plaintext) => {
+    const shared = {
+        mode: connection.mode,
+        ...(connection.metadata === undefined ? {} : { metadata: connection.metadata }),
+    };
+    switch (connection.scheme) {
+        case "bearer":
+            return createCredential({ scheme: "bearer", token: plaintext, ...shared });
+        case "basic": {
+            // The username lives in metadata because it is not a secret and a person needs to see it.
+            const username = connection.metadata?.username;
+            if (username === undefined)
+                throw new AgentPlatformError({
+                    code: "invalid_input",
+                    message: `connection "${connection.id}" is a basic credential with no \`metadata.username\`. The username is ` +
+                        "stored readable on purpose — a connection list should show which account it is for without a key.",
+                    retryable: false,
+                });
+            return createCredential({ scheme: "basic", username, password: plaintext, ...shared });
+        }
+        case "custom-header": {
+            const header = connection.metadata?.header;
+            if (header === undefined)
+                throw new AgentPlatformError({
+                    code: "invalid_input",
+                    message: `connection "${connection.id}" is a custom-header credential with no \`metadata.header\``,
+                    retryable: false,
+                });
+            return createCredential({ scheme: "custom-header", header, value: plaintext, ...shared });
+        }
+    }
+};
+export const createConnectionCredentialResolver = (deps) => {
+    const chooseDefault = deps.chooseDefault ?? ((candidates) => candidates[0]);
+    return {
+        async resolve({ ref, context }) {
+            const { provider, id } = parseCredentialRef(ref);
+            const connection = id === undefined
+                ? chooseDefault(await deps.store.list({ tenantId: context.tenantId, provider }))
+                : ((await deps.store.get({ tenantId: context.tenantId, id })) ?? undefined);
+            if (connection === undefined || connection === null)
+                // Marked, so the engine can recognise it as *a missing connection* rather than a broken tool and pause
+                // the run instead of failing it — #264. Structural, not a string match: rewording this message must not
+                // silently turn a pausable failure into a fatal one.
+                throw withConnectionGap(new AgentPlatformError({
+                    code: "capability_unavailable",
+                    message: `no ${provider} connection for this workspace` +
+                        (id === undefined ? "" : ` with id "${id}"`) +
+                        ". Connect one, or check the credential reference.",
+                    retryable: false,
+                }), { provider, gap: "absent", scopes: [] });
+            // A ref naming one provider must not resolve to another's credential, which is what a wrong id would do.
+            if (id !== undefined && connection.provider !== provider)
+                throw new AgentPlatformError({
+                    code: "invalid_input",
+                    message: `connection "${id}" is a ${connection.provider} connection, not ${provider}`,
+                    retryable: false,
+                });
+            /**
+             * Expiry is reported, not refreshed — refresh is #233's, deliberately.
+             *
+             * Saying "expired" rather than sending it is the difference between a message an operator can act on and
+             * a vendor 401 that says the token is invalid.
+             */
+            if (connection.expiresAt !== undefined && Date.parse(connection.expiresAt) <= Date.now())
+                throw withConnectionGap(new AgentPlatformError({
+                    code: "capability_unavailable",
+                    message: `the ${provider} connection expired at ${connection.expiresAt}. Reconnect, or wire a refresh.`,
+                    retryable: false,
+                }), { provider, gap: "expired", scopes: connection.grantedScopes ?? [] });
+            const plaintext = await deps.cipher.open(connection.sealed);
+            return toCredential(connection, plaintext);
+        },
+    };
+};
+/** Which scheme a connection presents, for `assertToolkitAuth` at wiring time. */
+export const schemeOf = (connection) => connection.scheme;
+/**
+ * Re-seals every connection that is not already under the current key — task #261 AC-7.
+ *
+ * Rotation without this is theory: `SecretCipher` can *open* an old key's secrets, but nothing moves them
+ * forward, so the old key can never be retired and the first key is permanent in practice.
+ *
+ * The order is what makes it safe to interrupt. Each connection is opened, re-sealed and written **one at a
+ * time**, and a failure leaves everything before it done and everything after it untouched — both readable,
+ * because the old key is still configured. Running it twice is a no-op: a connection already on the current key
+ * is skipped.
+ *
+ * Deliberately not a transaction over the whole tenant. A rotation across thousands of connections held in one
+ * transaction is a long-running write that blocks and, if it fails at the end, achieves nothing.
+ */
+export const resealConnections = async (input) => {
+    const current = input.cipher.currentKeyId();
+    const connections = await input.store.list({ tenantId: input.tenantId });
+    let resealed = 0;
+    let skipped = 0;
+    for (const connection of connections) {
+        if (connection.sealed.keyId === current) {
+            skipped += 1;
+            continue;
+        }
+        const plaintext = await input.cipher.open(connection.sealed);
+        await input.store.update({
+            tenantId: input.tenantId,
+            id: connection.id,
+            patch: { sealed: await input.cipher.seal(plaintext) },
+        });
+        input.onProgress?.({ id: connection.id, from: connection.sealed.keyId, to: current });
+        resealed += 1;
+    }
+    return { resealed, skipped };
+};
+//# sourceMappingURL=resolver.js.map

package/dist/connections/resume.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Resuming a run once consent completes — REQ-063 (#259), task #264, AC-3, AC-5, AC-6 and AC-7.
+ *
+ * The mirror of `hitl`'s `resumeRun`: transition back to `queued` and enqueue. The run picks up from its
+ * checkpoint and re-attempts the tool call that paused it, so nothing before the pause is repeated — the same
+ * idempotency the approval path already relies on.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { RunId } from "../core/ids.js";
+import type { RunEventLog } from "../core/events.js";
+import type { JobDispatcher } from "../runtime/index.js";
+import type { RunStore } from "../persistence/index.js";
+export type ConsentResumeDeps = {
+    readonly runs: RunStore;
+    readonly dispatcher: JobDispatcher;
+    readonly events?: RunEventLog;
+    readonly now?: () => string;
+};
+/**
+ * Resumes a run that was waiting for a connection.
+ *
+ * ## Only the right principal — AC-5
+ *
+ * This is the security property of the whole feature, and it is not about the run: it is about the **login
+ * URL**. That URL is rendered in a UI, appears in screenshots and may be pasted into a chat. If completing the
+ * flow it points at could resume *anyone's* run, a leaked URL would let a stranger attach their own account to
+ * somebody else's tenant — and every subsequent action the agent took against that provider would be theirs.
+ *
+ * So the run must belong to the caller's tenant. The OAuth flow has already bound its `state` to the tenant and
+ * the principal who began it (#262), which is the other half: the state cannot be redeemed by another person,
+ * and the resume cannot be driven from another tenant.
+ *
+ * ## Idempotent — AC-6
+ *
+ * A double-click, a retried redirect, a browser prefetch: the callback firing twice must queue the run **once**.
+ * `transition` is guarded by the current status, so a run already moved out of `waiting-for-connection` is
+ * reported as `resumed: false` rather than enqueued again — and a second job would mean the tool call that
+ * paused the run runs twice.
+ */
+export declare const resumeAfterConsent: (deps: ConsentResumeDeps, input: {
+    readonly context: ExecutionContext;
+    readonly runId: RunId;
+    readonly provider: string;
+    readonly connectionId: string;
+}) => Promise<{
+    readonly resumed: boolean;
+    readonly reason?: string;
+}>;
+/**
+ * Fails a run that has been waiting for a connection longer than the deployment allows — AC-7.
+ *
+ * A pause with no ceiling is a run that holds a row for ever, and the reaper does not sweep it: the reaper
+ * exists for *abandoned* runs, and this one is not abandoned — it is waiting for a person who is never coming
+ * back. So it needs its own ceiling, and failing with a reason beats a row nobody can explain.
+ */
+export declare const expireStaleConsents: (deps: ConsentResumeDeps & {
+    readonly listWaiting: (before: string) => Promise<readonly {
+        readonly tenantId: string;
+        readonly id: RunId;
+    }[]>;
+}, input: {
+    readonly olderThanMs: number;
+}) => Promise<number>;
+//# sourceMappingURL=resume.d.ts.map

package/dist/connections/resume.js

@@ -0,0 +1,99 @@
+/**
+ * Resuming a run once consent completes — REQ-063 (#259), task #264, AC-3, AC-5, AC-6 and AC-7.
+ *
+ * The mirror of `hitl`'s `resumeRun`: transition back to `queued` and enqueue. The run picks up from its
+ * checkpoint and re-attempts the tool call that paused it, so nothing before the pause is repeated — the same
+ * idempotency the approval path already relies on.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+/**
+ * Resumes a run that was waiting for a connection.
+ *
+ * ## Only the right principal — AC-5
+ *
+ * This is the security property of the whole feature, and it is not about the run: it is about the **login
+ * URL**. That URL is rendered in a UI, appears in screenshots and may be pasted into a chat. If completing the
+ * flow it points at could resume *anyone's* run, a leaked URL would let a stranger attach their own account to
+ * somebody else's tenant — and every subsequent action the agent took against that provider would be theirs.
+ *
+ * So the run must belong to the caller's tenant. The OAuth flow has already bound its `state` to the tenant and
+ * the principal who began it (#262), which is the other half: the state cannot be redeemed by another person,
+ * and the resume cannot be driven from another tenant.
+ *
+ * ## Idempotent — AC-6
+ *
+ * A double-click, a retried redirect, a browser prefetch: the callback firing twice must queue the run **once**.
+ * `transition` is guarded by the current status, so a run already moved out of `waiting-for-connection` is
+ * reported as `resumed: false` rather than enqueued again — and a second job would mean the tool call that
+ * paused the run runs twice.
+ */
+export const resumeAfterConsent = async (deps, input) => {
+    const now = deps.now ?? (() => new Date().toISOString());
+    const run = await deps.runs.findById({ tenantId: input.context.tenantId, id: input.runId });
+    if (run === null) {
+        /**
+         * Absent and not-yours are the same answer, deliberately.
+         *
+         * Distinguishing them tells a caller whether a run id exists in another tenant, which is exactly the probe
+         * a leaked login URL would be used for. `findById` is already tenant-scoped, so this branch covers both.
+         */
+        throw new AgentPlatformError({
+            code: "not_found",
+            message: `no run "${input.runId}" for this workspace`,
+            retryable: false,
+        });
+    }
+    if (run.status !== "waiting-for-connection") {
+        // Not an error: a retried callback on an already-resumed run is a normal thing a browser does.
+        return { resumed: false, reason: `the run is ${run.status}, not waiting for a connection` };
+    }
+    if (deps.events !== undefined) {
+        // Recorded before the transition, so a crash between the two leaves a log that says what happened rather
+        // than a run that moved for no visible reason.
+        await deps.events.append({
+            tenantId: input.context.tenantId,
+            event: {
+                type: "connection.completed",
+                runId: input.runId,
+                sequence: 0,
+                occurredAt: now(),
+                provider: input.provider,
+                connectionId: input.connectionId,
+            },
+        });
+    }
+    await deps.runs.transition({
+        tenantId: input.context.tenantId,
+        id: input.runId,
+        workerId: "connections",
+        to: "queued",
+        now: now(),
+    });
+    await deps.dispatcher.enqueueRun({ tenantId: input.context.tenantId, runId: input.runId });
+    return { resumed: true };
+};
+/**
+ * Fails a run that has been waiting for a connection longer than the deployment allows — AC-7.
+ *
+ * A pause with no ceiling is a run that holds a row for ever, and the reaper does not sweep it: the reaper
+ * exists for *abandoned* runs, and this one is not abandoned — it is waiting for a person who is never coming
+ * back. So it needs its own ceiling, and failing with a reason beats a row nobody can explain.
+ */
+export const expireStaleConsents = async (deps, input) => {
+    const now = deps.now ?? (() => new Date().toISOString());
+    const cutoff = new Date(Date.parse(now()) - input.olderThanMs).toISOString();
+    const stale = await deps.listWaiting(cutoff);
+    let failed = 0;
+    for (const run of stale) {
+        await deps.runs.transition({
+            tenantId: run.tenantId,
+            id: run.id,
+            workerId: "connections",
+            to: "failed",
+            now: now(),
+        });
+        failed += 1;
+    }
+    return failed;
+};
+//# sourceMappingURL=resume.js.map