@framers/agentos-ext-gmail-source 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,98 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+   (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+   Copyright (c) 2025 Framers
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# Gmail source
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This library provides read-only Gmail authorization on the AgentOS redirect grant and sealed-token contracts. It requests the sole Gmail read-only scope, offline access and incremental consent. It exports no send, reply, label-modification or attachment-download tool.
+
+Install it next to `@framers/agentos` 0.13.134 or later and `@framers/agentos-ext-account-sources` 0.4.0 or later. Both are peer dependencies with a floor and no upper bound. Node.js 20.19 or later is required.
+
+```ts
+import { GmailOAuthFlow } from '@framers/agentos-ext-gmail-source';
+
+const callback = 'https://app.example.com/sources/gmail/callback';
+const client = { clientId, clientSecret, redirectUris: [callback] };
+
+// The request that sends the person to Google: keep the state and the verifier in a short-lived, single-use record.
+const begun = new GmailOAuthFlow(client, null).begin({ redirectUri: callback });
+
+// The request Google sends the person back to. `store` is a SealedTokenStore under the connection's namespace.
+const flow = new GmailOAuthFlow(client, store);
+const grant = await flow.complete({
+  code,
+  state,
+  expectedState: begun.state,
+  codeVerifier: begun.codeVerifier,
+  redirectUri: callback,
+});
+// After the host has consumed the start and rechecked the account: the store receives the refresh token and scope.
+await flow.keep(connectionId, grant);
+```
+
+Construct `GmailOAuthFlow(client, store, options)` on the server. `client` contains the dedicated client id, client secret and exact registered callback URI list. Load credentials through the host's secret mechanism. The default endpoints are Google's HTTPS endpoints. Endpoint overrides are restricted to CI stand-ins; never derive them or callback URIs from a browser request.
+
+`begin({ redirectUri })` returns the authorization URL, state and PKCE verifier. Keep state and verifier under a short-lived, single-use record tied to the signed-in account. `complete(input)` checks state, exchanges the code and verifies the granted scope and refresh material. It returns credentials in memory and does not persist them. The host must atomically consume the start and recheck account liveness and generation before installing the sealed grant. Do not log callback URLs, credentials or errors from arbitrary provider middleware.
+
+Construct a flow for each scheduled token operation, with that operation's sealed store and abort signal, call `accessToken`, and discard the flow at the end of the operation. A store scoped to one operation must never be retained for another worker. The host's durable lifecycle owns disconnect, purge, refresh exclusion across workers and revocation. `forget` on an independently held flow is not a cross-worker lifecycle operation.
+
+OAuth responses are capped at 65,536 bytes and must finish within 15 seconds. Parent cancellation stops dispatch and body consumption. Fixed `GmailOAuthFault` reasons contain no provider message or credential. When an exchange succeeds and `complete` does not return the grant, because the grant fails the checks or because the parent cancelled before `complete` returned, the flow asks Google to revoke the grant before it throws. That revocation has the same byte cap and a 15-second deadline of its own, and the parent's cancellation does not stop it. The fault's `cleanup` field then reads `confirmed` or `unconfirmed`. An unconfirmed outcome needs a provider-permission removal instruction. It does not authorize retaining the grant.
+
+The host supplies informed consent, cache permission, retention policy, account isolation and a truthful availability state. Authorization alone does not establish permission to store or send mailbox content to a model. Do not infer those permissions from this package's successful tests.
+
+Protocol references: https://developers.google.com/identity/protocols/oauth2/web-server and https://developers.google.com/workspace/gmail/api/auth/scopes.

package/dist/GmailOAuthFlow.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Google's read-only Gmail grant on the AgentOS redirect OAuth flow: the read-only scope alone, asked for
+ * offline and incrementally with consent, for registered callbacks only; granted scopes and refresh material checked
+ * before a grant is accepted; every token and revocation call capped at 65,536 bytes, bounded by one 15-second
+ * deadline and stopped by the caller's cancellation, except the revocation of a grant the flow will not hand back.
+ * @module agentos-ext-gmail-source/GmailOAuthFlow
+ */
+import { RedirectOAuthFlow, type IOAuthTokenStore, type OAuthTokenSet, type RedirectOAuthConfig, type RedirectBegin, type RedirectCompleteInput } from '@framers/agentos/auth';
+import { type GmailOAuthClient, type GmailOAuthOptions } from './types.js';
+/**
+ * Google's read-only Gmail grant on the core redirect flow. `begin` asks for the read-only scope alone, offline, with
+ * incremental authorization and consent, for a registered callback; `complete` accepts only that scope with refresh
+ * material and revokes a grant it refuses, or one the caller cancels after the exchange; refreshes and revocations go
+ * through the same capped transport, which the caller's signal stops except during that revocation. A flow built with
+ * an operation's sealed store and signal serves that operation alone.
+ */
+export declare class GmailOAuthFlow extends RedirectOAuthFlow {
+    /** The provider's id. */
+    readonly providerId = "gmail";
+    private readonly client;
+    private readonly endpoints;
+    private readonly signal?;
+    /** The fetch and stand-in endpoints of a withheld grant's revocation, without the caller's signal. */
+    private readonly withheld;
+    /**
+     * @param client The dedicated client and its registered callback addresses (one to sixteen).
+     * @param store Where the grant is kept, a namespaced `SealedTokenStore` on a server; null for a flow that only
+     * begins, completes and revokes.
+     * @param options The fetch, the caller's cancellation and, on CI only, stand-in endpoints.
+     * @throws GmailOAuthFault `configuration` for a malformed client, callback address or endpoint override.
+     */
+    constructor(client: GmailOAuthClient, store: IOAuthTokenStore | null, options?: GmailOAuthOptions);
+    /** Google's endpoints, the read-only scope and the client; a refresh starts a minute before expiry. */
+    protected getConfig(): RedirectOAuthConfig;
+    /** Throws `cancelled` once the caller's signal has aborted. */
+    private active;
+    /** Throws `configuration` for a callback address the client did not register. */
+    private redirect;
+    /**
+     * The authorization address, state and PKCE verifier for a registered callback, asking for the read-only scope
+     * alone with `access_type=offline`, `include_granted_scopes=true` and `prompt=consent`, and no identity hint.
+     * Throws `configuration` for any other scope, any extra parameter or an unregistered callback.
+     */
+    begin(input: Parameters<RedirectOAuthFlow['begin']>[0]): RedirectBegin;
+    /**
+     * Checks the callback address and the inputs' shape before any call, then the state, then exchanges the code. It
+     * answers the accepted grant in memory and saves nothing. When the caller's signal aborts after Google has issued the
+     * grant, the grant is revoked before `cancelled` is thrown, and the fault's `cleanup` says whether that was confirmed.
+     */
+    complete(input: RedirectCompleteInput): Promise<OAuthTokenSet>;
+    /**
+     * Accepts an exchanged grant only with the read-only scope alone, usable refresh material and an unexpired access
+     * token. A refused grant is revoked at Google first; the fault's `cleanup` says whether that was confirmed.
+     */
+    protected postExchange(tokens: OAuthTokenSet): Promise<OAuthTokenSet>;
+    /**
+     * Revokes an exchanged grant the flow will not hand back, by its refresh token or else its access token, and answers
+     * whether Google confirmed it. The call goes through the same capped transport with a 15-second deadline of its own,
+     * on a flow without the caller's signal, so a cancellation cannot leave the grant at Google without an attempt.
+     */
+    private revokeWithheld;
+    /**
+     * Refreshes and checks the answer: a scope it returns must be the read-only scope alone, and a refresh token it
+     * returns must be usable. An omitted scope keeps the kept grant's checked scope.
+     */
+    protected refreshTokens(refreshToken: string): Promise<OAuthTokenSet>;
+    /** Keeps an accepted grant under `key` after the exchange's checks; the store receives its refresh token and scope. */
+    keep(key: string, tokens: OAuthTokenSet): Promise<void>;
+    /**
+     * An access token for the grant kept under `key`, refreshed when needed, only while the kept scope is the read-only
+     * scope alone. Throws `OAuthGrantRefused` with reason `missing` when nothing is kept or the grant changes during the
+     * refresh, and with reason `refresh` when Google refuses it.
+     */
+    accessToken(key: string): Promise<string>;
+    /** Revokes a token at Google; an answer that is not a success throws `OAuthGrantRefused` with reason `revoke`. */
+    revoke(token: string): Promise<void>;
+}
+//# sourceMappingURL=GmailOAuthFlow.d.ts.map

package/dist/GmailOAuthFlow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GmailOAuthFlow.d.ts","sourceRoot":"","sources":["../src/GmailOAuthFlow.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,iBAAiB,EAAqB,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAC/E,KAAK,mBAAmB,EAAE,KAAK,aAAa,EAAE,KAAK,qBAAqB,EACzE,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACkC,KAAK,gBAAgB,EAClC,KAAK,iBAAiB,EACjD,MAAM,YAAY,CAAC;AAgKpB;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,iBAAiB;IACnD,yBAAyB;IACzB,QAAQ,CAAC,UAAU,WAAW;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAc;IACtC,sGAAsG;IACtG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C;;;;;;OAMG;gBACS,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,EAAE,OAAO,GAAE,iBAAsB;IAYrG,uGAAuG;IACvG,SAAS,CAAC,SAAS,IAAI,mBAAmB;IAK1C,+DAA+D;IAC/D,OAAO,CAAC,MAAM;IACd,iFAAiF;IACjF,OAAO,CAAC,QAAQ;IAGhB;;;;OAIG;IACM,KAAK,CAAC,KAAK,EAAE,UAAU,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa;IAO/E;;;;OAIG;IACY,QAAQ,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC;IAQ7E;;;OAGG;cACsB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAOpF;;;;OAIG;YACW,cAAc;IAO5B;;;OAGG;cACsB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAKpF,uHAAuH;IACxG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAGtE;;;;OAIG;IACY,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQxD,kHAAkH;IACnG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIpD"}

package/dist/GmailOAuthFlow.js

@@ -0,0 +1,382 @@
+/**
+ * @fileoverview Google's read-only Gmail grant on the AgentOS redirect OAuth flow: the read-only scope alone, asked for
+ * offline and incrementally with consent, for registered callbacks only; granted scopes and refresh material checked
+ * before a grant is accepted; every token and revocation call capped at 65,536 bytes, bounded by one 15-second
+ * deadline and stopped by the caller's cancellation, except the revocation of a grant the flow will not hand back.
+ * @module agentos-ext-gmail-source/GmailOAuthFlow
+ */
+import { RedirectOAuthFlow, OAuthGrantRefused, } from '@framers/agentos/auth';
+import { readCapped, ReadCapExceeded } from '@framers/agentos-ext-account-sources';
+import { GMAIL_READONLY_SCOPE, GmailOAuthFault, } from './types.js';
+/** Google's production authorization, token and revocation endpoints. */
+const endpoints = Object.freeze({
+    authorization: 'https://accounts.google.com/o/oauth2/v2/auth',
+    token: 'https://oauth2.googleapis.com/token',
+    revoke: 'https://oauth2.googleapis.com/revoke',
+});
+/** The byte cap on one OAuth response body. */
+const maxBytes = 65_536;
+/** One deadline for a call and the consumption of its body. */
+const deadlineMs = 15_000;
+/** A nonempty credential of bounded length with no whitespace or control character. */
+const tokenString = (value) => typeof value === 'string'
+    && value.length > 0 && value.length <= 16_384 && !/[\x00-\x20\x7f]/.test(value);
+/** True when a granted scope string names the read-only scope and nothing else. */
+function scopeOnly(value) {
+    if (typeof value !== 'string')
+        return false;
+    const scopes = value.trim().split(/\s+/);
+    return scopes.length === 1 && scopes[0] === GMAIL_READONLY_SCOPE;
+}
+/**
+ * An absolute HTTPS address with no userinfo, query or fragment; loopback HTTP passes on CI only. A fixture-only
+ * address must also be a loopback or `.invalid` host on CI. The query and fragment marks are looked for in the string
+ * itself: the URL's `search` and `hash` read empty for a bare `?` or `#`.
+ */
+function validUrl(value, fixtureOnly) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new GmailOAuthFault('configuration');
+    }
+    const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    const fixture = local || url.hostname.endsWith('.invalid');
+    if (url.username || url.password || /[?#]/.test(value)
+        || (url.protocol !== 'https:' && !(process.env.CI === 'true' && local && url.protocol === 'http:'))
+        || (fixtureOnly && (process.env.CI !== 'true' || !fixture)))
+        throw new GmailOAuthFault('configuration');
+    return url;
+}
+/** Google's endpoints, or three distinct stand-in endpoints that pass the fixture-only check. */
+function selectedEndpoints(options) {
+    if (!options.endpoints)
+        return endpoints;
+    const chosen = { ...options.endpoints };
+    for (const value of [chosen.authorization, chosen.token, chosen.revoke])
+        validUrl(value, true);
+    if (new Set(Object.values(chosen)).size !== 3)
+        throw new GmailOAuthFault('configuration');
+    return Object.freeze(chosen);
+}
+/** Reject promptly; consume a fetch response that arrives after its caller has stopped. */
+function abortable(work, signal, stopped, discard) {
+    return new Promise((resolve, reject) => {
+        let done = false;
+        const abort = () => { if (!done) {
+            done = true;
+            reject(stopped());
+        } };
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+        work.then((value) => {
+            signal.removeEventListener('abort', abort);
+            if (done) {
+                discard?.(value);
+                return;
+            }
+            done = true;
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', abort);
+            if (!done) {
+                done = true;
+                reject(error);
+            }
+        });
+    });
+}
+/** Cancels a response's body without waiting, discarding any error. */
+function cancel(response) { void response.body?.cancel().catch(() => { }); }
+/**
+ * Reads a body through the released byte cap. The bridge stream turns the signal's abort into a fixed fault, even
+ * while no bytes arrive, and passes a cancellation through to the provider's stream.
+ */
+async function boundedBody(response, signal, stopped) {
+    if (signal.aborted) {
+        cancel(response);
+        throw stopped();
+    }
+    if (!response.body)
+        return new Uint8Array(0);
+    const reader = response.body.getReader();
+    let closed = false;
+    let stop;
+    const bridge = new ReadableStream({
+        start(controller) {
+            stop = () => {
+                if (closed)
+                    return;
+                closed = true;
+                controller.error(stopped());
+                void reader.cancel().catch(() => { });
+            };
+            signal.addEventListener('abort', stop, { once: true });
+            if (signal.aborted)
+                stop();
+        },
+        async pull(controller) {
+            try {
+                const chunk = await reader.read();
+                if (closed)
+                    return;
+                if (chunk.done) {
+                    closed = true;
+                    controller.close();
+                }
+                else
+                    controller.enqueue(chunk.value);
+            }
+            catch {
+                if (!closed) {
+                    closed = true;
+                    controller.error(signal.aborted ? stopped() : new GmailOAuthFault('network'));
+                }
+            }
+        },
+        async cancel() { closed = true; try {
+            await reader.cancel();
+        }
+        catch { /* No provider text escapes. */ } },
+    });
+    try {
+        return await readCapped(new Response(bridge, { headers: response.headers }), maxBytes);
+    }
+    finally {
+        signal.removeEventListener('abort', stop);
+        try {
+            reader.releaseLock();
+        }
+        catch { /* A cancelled provider may still be settling. */ }
+    }
+}
+/**
+ * The fetch the core flow is given: POSTs to the chosen token and revocation endpoints only, no redirect followed, no
+ * credentials or referrer sent, one deadline over the call and its capped body, and fixed faults in place of
+ * transport errors. It answers a fresh response holding the bounded bytes and the provider's status.
+ */
+function oauthFetch(options, chosen) {
+    const send = options.fetchImpl ?? fetch;
+    return async (input, init) => {
+        const url = typeof input === 'string' || input instanceof URL ? String(input) : '';
+        if (![chosen.token, chosen.revoke].includes(url) || init?.method !== 'POST')
+            throw new GmailOAuthFault('configuration');
+        const parents = [options.signal, init?.signal].filter((s) => s !== undefined && s !== null);
+        if (parents.some((s) => s.aborted))
+            throw new GmailOAuthFault('cancelled');
+        const controller = new AbortController();
+        let timedOut = false;
+        const abort = () => controller.abort();
+        const stopped = () => new GmailOAuthFault(timedOut ? 'timeout' : 'cancelled');
+        for (const parent of parents)
+            parent.addEventListener('abort', abort, { once: true });
+        const timer = setTimeout(() => { timedOut = true; controller.abort(); }, deadlineMs);
+        try {
+            if (parents.some((s) => s.aborted))
+                abort();
+            if (controller.signal.aborted)
+                throw stopped();
+            const response = await abortable(send(url, { ...init, signal: controller.signal,
+                redirect: 'error', credentials: 'omit', cache: 'no-store', referrerPolicy: 'no-referrer' }), controller.signal, stopped, cancel);
+            if (controller.signal.aborted) {
+                cancel(response);
+                throw stopped();
+            }
+            if (response.status < 200 || response.status >= 600 || (response.status >= 300 && response.status < 400)) {
+                cancel(response);
+                throw new GmailOAuthFault('invalid_response');
+            }
+            const bytes = await boundedBody(response, controller.signal, stopped);
+            if (controller.signal.aborted)
+                throw stopped();
+            return new Response([204, 205, 304].includes(response.status) ? null : bytes, { status: response.status, headers: { 'content-type': 'application/json' } });
+        }
+        catch (error) {
+            if (error instanceof GmailOAuthFault)
+                throw error;
+            if (controller.signal.aborted)
+                throw stopped();
+            if (error instanceof ReadCapExceeded)
+                throw new GmailOAuthFault('response_too_large');
+            throw new GmailOAuthFault('network');
+        }
+        finally {
+            clearTimeout(timer);
+            for (const parent of parents)
+                parent.removeEventListener('abort', abort);
+        }
+    };
+}
+/**
+ * Checks a token answer and keeps only the access token, the refresh token, the expiry and the read-only scope; an id
+ * token and any other field are dropped.
+ */
+function normalize(tokens, refreshRequired, scopeRequired) {
+    if (!tokenString(tokens.accessToken) || !Number.isFinite(tokens.expiresAt) || tokens.expiresAt <= Date.now()) {
+        throw new GmailOAuthFault('invalid_response');
+    }
+    const scope = tokens.metadata?.scope;
+    if ((scopeRequired || scope !== undefined) && !scopeOnly(scope))
+        throw new GmailOAuthFault('scope');
+    if ((refreshRequired || tokens.refreshToken !== undefined) && !tokenString(tokens.refreshToken)) {
+        throw new GmailOAuthFault('refresh_token');
+    }
+    return { accessToken: tokens.accessToken, refreshToken: tokens.refreshToken, expiresAt: tokens.expiresAt,
+        metadata: scope === undefined ? undefined : { scope: GMAIL_READONLY_SCOPE } };
+}
+/**
+ * Google's read-only Gmail grant on the core redirect flow. `begin` asks for the read-only scope alone, offline, with
+ * incremental authorization and consent, for a registered callback; `complete` accepts only that scope with refresh
+ * material and revokes a grant it refuses, or one the caller cancels after the exchange; refreshes and revocations go
+ * through the same capped transport, which the caller's signal stops except during that revocation. A flow built with
+ * an operation's sealed store and signal serves that operation alone.
+ */
+export class GmailOAuthFlow extends RedirectOAuthFlow {
+    /** The provider's id. */
+    providerId = 'gmail';
+    client;
+    endpoints;
+    signal;
+    /** The fetch and stand-in endpoints of a withheld grant's revocation, without the caller's signal. */
+    withheld;
+    /**
+     * @param client The dedicated client and its registered callback addresses (one to sixteen).
+     * @param store Where the grant is kept, a namespaced `SealedTokenStore` on a server; null for a flow that only
+     * begins, completes and revokes.
+     * @param options The fetch, the caller's cancellation and, on CI only, stand-in endpoints.
+     * @throws GmailOAuthFault `configuration` for a malformed client, callback address or endpoint override.
+     */
+    constructor(client, store, options = {}) {
+        const chosen = selectedEndpoints(options);
+        super(store, oauthFetch(options, chosen));
+        if (!tokenString(client.clientId) || !tokenString(client.clientSecret)
+            || !Array.isArray(client.redirectUris) || client.redirectUris.length === 0 || client.redirectUris.length > 16) {
+            throw new GmailOAuthFault('configuration');
+        }
+        for (const uri of client.redirectUris)
+            validUrl(uri, false);
+        this.client = Object.freeze({ ...client, redirectUris: Object.freeze([...new Set(client.redirectUris)]) });
+        this.endpoints = chosen;
+        this.signal = options.signal;
+        this.withheld = Object.freeze({ fetchImpl: options.fetchImpl, endpoints: options.endpoints ? chosen : undefined });
+    }
+    /** Google's endpoints, the read-only scope and the client; a refresh starts a minute before expiry. */
+    getConfig() {
+        return { clientId: this.client.clientId, clientSecret: this.client.clientSecret, scopes: [GMAIL_READONLY_SCOPE],
+            authorizationEndpoint: this.endpoints.authorization, tokenEndpoint: this.endpoints.token,
+            revocationEndpoint: this.endpoints.revoke, refreshBufferMs: 60_000 };
+    }
+    /** Throws `cancelled` once the caller's signal has aborted. */
+    active() { if (this.signal?.aborted)
+        throw new GmailOAuthFault('cancelled'); }
+    /** Throws `configuration` for a callback address the client did not register. */
+    redirect(uri) {
+        if (!this.client.redirectUris.includes(uri))
+            throw new GmailOAuthFault('configuration');
+    }
+    /**
+     * The authorization address, state and PKCE verifier for a registered callback, asking for the read-only scope
+     * alone with `access_type=offline`, `include_granted_scopes=true` and `prompt=consent`, and no identity hint.
+     * Throws `configuration` for any other scope, any extra parameter or an unregistered callback.
+     */
+    begin(input) {
+        this.active();
+        this.redirect(input.redirectUri);
+        if ((input.scopes && (input.scopes.length !== 1 || input.scopes[0] !== GMAIL_READONLY_SCOPE))
+            || (input.extraParams && Object.keys(input.extraParams).length > 0))
+            throw new GmailOAuthFault('configuration');
+        return super.begin({ redirectUri: input.redirectUri, scopes: [GMAIL_READONLY_SCOPE],
+            extraParams: { access_type: 'offline', include_granted_scopes: 'true', prompt: 'consent' } });
+    }
+    /**
+     * Checks the callback address and the inputs' shape before any call, then the state, then exchanges the code. It
+     * answers the accepted grant in memory and saves nothing. When the caller's signal aborts after Google has issued the
+     * grant, the grant is revoked before `cancelled` is thrown, and the fault's `cleanup` says whether that was confirmed.
+     */
+    async complete(input) {
+        this.active();
+        this.redirect(input.redirectUri);
+        if (!tokenString(input.code) || !/^[A-Za-z0-9._~-]{43,128}$/.test(input.codeVerifier)
+            || input.state.length > 512 || input.expectedState.length > 512)
+            throw new GmailOAuthFault('configuration');
+        const tokens = await super.complete(input);
+        if (this.signal?.aborted)
+            throw new GmailOAuthFault('cancelled', await this.revokeWithheld(tokens));
+        return tokens;
+    }
+    /**
+     * Accepts an exchanged grant only with the read-only scope alone, usable refresh material and an unexpired access
+     * token. A refused grant is revoked at Google first; the fault's `cleanup` says whether that was confirmed.
+     */
+    async postExchange(tokens) {
+        try {
+            return normalize(tokens, true, true);
+        }
+        catch (error) {
+            throw new GmailOAuthFault(error instanceof GmailOAuthFault ? error.reason : 'invalid_response', await this.revokeWithheld(tokens));
+        }
+    }
+    /**
+     * Revokes an exchanged grant the flow will not hand back, by its refresh token or else its access token, and answers
+     * whether Google confirmed it. The call goes through the same capped transport with a 15-second deadline of its own,
+     * on a flow without the caller's signal, so a cancellation cannot leave the grant at Google without an attempt.
+     */
+    async revokeWithheld(tokens) {
+        const token = tokenString(tokens.refreshToken) ? tokens.refreshToken
+            : tokenString(tokens.accessToken) ? tokens.accessToken : null;
+        if (token === null)
+            return 'unconfirmed';
+        try {
+            await new GmailOAuthFlow(this.client, null, this.withheld).revoke(token);
+            return 'confirmed';
+        }
+        catch {
+            return 'unconfirmed';
+        }
+    }
+    /**
+     * Refreshes and checks the answer: a scope it returns must be the read-only scope alone, and a refresh token it
+     * returns must be usable. An omitted scope keeps the kept grant's checked scope.
+     */
+    async refreshTokens(refreshToken) {
+        this.active();
+        const tokens = normalize(await super.refreshTokens(refreshToken), false, false);
+        this.active();
+        return tokens;
+    }
+    /** Keeps an accepted grant under `key` after the exchange's checks; the store receives its refresh token and scope. */
+    async keep(key, tokens) {
+        this.active();
+        await super.keep(key, normalize(tokens, true, true));
+        this.active();
+    }
+    /**
+     * An access token for the grant kept under `key`, refreshed when needed, only while the kept scope is the read-only
+     * scope alone. Throws `OAuthGrantRefused` with reason `missing` when nothing is kept or the grant changes during the
+     * refresh, and with reason `refresh` when Google refuses it.
+     */
+    async accessToken(key) {
+        this.active();
+        if (this.store === null)
+            throw new GmailOAuthFault('configuration');
+        const saved = await this.store.load(key);
+        if (saved === null)
+            throw new OAuthGrantRefused('missing');
+        if (!scopeOnly(saved.metadata?.scope))
+            throw new GmailOAuthFault('scope');
+        const token = await super.accessToken(key);
+        this.active();
+        return token;
+    }
+    /** Revokes a token at Google; an answer that is not a success throws `OAuthGrantRefused` with reason `revoke`. */
+    async revoke(token) {
+        this.active();
+        if (!tokenString(token))
+            throw new GmailOAuthFault('configuration');
+        await super.revoke(token);
+        this.active();
+    }
+}
+//# sourceMappingURL=GmailOAuthFlow.js.map

package/dist/GmailOAuthFlow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GmailOAuthFlow.js","sourceRoot":"","sources":["../src/GmailOAuthFlow.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview A read-only Gmail source's grant: Google's read-only scope on the AgentOS redirect OAuth flow and
+ * sealed-token store, with capped, cancellable OAuth calls and fixed failures.
+ * @module agentos-ext-gmail-source
+ */
+export { GmailOAuthFlow } from './GmailOAuthFlow.js';
+export { GMAIL_READONLY_SCOPE, GmailOAuthFault, type GmailOAuthFailure, type GmailGrantCleanup, type GmailOAuthClient, type GmailOAuthEndpoints, type GmailOAuthOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,oBAAoB,EAAE,eAAe,EAAE,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EACrF,KAAK,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,KAAK,iBAAiB,GACxE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview A read-only Gmail source's grant: Google's read-only scope on the AgentOS redirect OAuth flow and
+ * sealed-token store, with capped, cancellable OAuth calls and fixed failures.
+ * @module agentos-ext-gmail-source
+ */
+export { GmailOAuthFlow } from './GmailOAuthFlow.js';
+export { GMAIL_READONLY_SCOPE, GmailOAuthFault, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,oBAAoB,EAAE,eAAe,GAEtC,MAAM,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview The public types of the Gmail grant: Google's read-only scope, the dedicated client, the endpoints, the
+ * transport options and the fixed failures a grant operation answers.
+ * @module agentos-ext-gmail-source/types
+ */
+/** Google's read-only Gmail scope, the only scope the flow asks for or accepts; Google classes it as Restricted. */
+export declare const GMAIL_READONLY_SCOPE = "https://www.googleapis.com/auth/gmail.readonly";
+/** The dedicated web client: its id, its secret and the exact callback addresses registered for it. */
+export interface GmailOAuthClient {
+    /** The client id. */
+    readonly clientId: string;
+    /** The client secret, loaded through the host's secret mechanism. */
+    readonly clientSecret: string;
+    /** The registered callback addresses, from trusted server configuration, with no query, fragment or userinfo. */
+    readonly redirectUris: readonly string[];
+}
+/** Google's authorization, token and revocation addresses. */
+export interface GmailOAuthEndpoints {
+    /** The authorization address the person is sent to. */
+    readonly authorization: string;
+    /** The token address the code is exchanged and the grant refreshed at. */
+    readonly token: string;
+    /** The revocation address. */
+    readonly revoke: string;
+}
+/** How the flow reaches Google: the fetch, the caller's cancellation and, on CI only, stand-in endpoints. */
+export interface GmailOAuthOptions {
+    /** The fetch the token and revocation endpoints are called with; the global fetch by default. */
+    readonly fetchImpl?: typeof fetch;
+    /**
+     * The caller's cancellation: once aborted, a pending call or body read stops as `cancelled` and no other call starts,
+     * except the revocation of a grant the flow has already received, which runs under a 15-second deadline of its own.
+     */
+    readonly signal?: AbortSignal;
+    /** Reserved for loopback or .invalid stand-ins on CI. Never take this from a request. */
+    readonly endpoints?: GmailOAuthEndpoints;
+}
+/** Why a grant operation failed, as a fixed word: never the provider's text, a code or a credential. */
+export type GmailOAuthFailure = 'configuration' | 'cancelled' | 'timeout' | 'network' | 'response_too_large' | 'invalid_response' | 'scope' | 'refresh_token';
+/**
+ * What became at Google of an exchanged grant the flow does not hand back, because its checks refused the grant or the
+ * caller cancelled before `complete` returned: `not_attempted` when the flow held no grant to revoke, `confirmed` when
+ * the revocation endpoint answered a success, `unconfirmed` when it did not, which calls for permission-removal
+ * instructions.
+ */
+export type GmailGrantCleanup = 'not_attempted' | 'confirmed' | 'unconfirmed';
+/** A grant operation's fixed failure; its message is `gmail_oauth_<reason>`. */
+export declare class GmailOAuthFault extends Error {
+    readonly reason: GmailOAuthFailure;
+    readonly cleanup: GmailGrantCleanup;
+    /**
+     * @param reason Why the operation failed.
+     * @param cleanup What became at Google of an exchanged grant the flow does not hand back.
+     */
+    constructor(reason: GmailOAuthFailure, cleanup?: GmailGrantCleanup);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oHAAoH;AACpH,eAAO,MAAM,oBAAoB,mDAAmD,CAAC;AACrF,uGAAuG;AACvG,MAAM,WAAW,gBAAgB;IAC/B,qBAAqB;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iHAAiH;IACjH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AACD,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AACD,6GAA6G;AAC7G,MAAM,WAAW,iBAAiB;IAChC,iGAAiG;IACjG,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,yFAAyF;IACzF,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;CAC1C;AACD,wGAAwG;AACxG,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GACjF,oBAAoB,GAAG,kBAAkB,GAAG,OAAO,GAAG,eAAe,CAAC;AAC1E;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,WAAW,GAAG,aAAa,CAAC;AAC9E,gFAAgF;AAChF,qBAAa,eAAgB,SAAQ,KAAK;IAK5B,QAAQ,CAAC,MAAM,EAAE,iBAAiB;IAAE,QAAQ,CAAC,OAAO,EAAE,iBAAiB;IAJnF;;;OAGG;gBACkB,MAAM,EAAE,iBAAiB,EAAW,OAAO,GAAE,iBAAmC;CAGtG"}

package/dist/types.js

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview The public types of the Gmail grant: Google's read-only scope, the dedicated client, the endpoints, the
+ * transport options and the fixed failures a grant operation answers.
+ * @module agentos-ext-gmail-source/types
+ */
+/** Google's read-only Gmail scope, the only scope the flow asks for or accepts; Google classes it as Restricted. */
+export const GMAIL_READONLY_SCOPE = 'https://www.googleapis.com/auth/gmail.readonly';
+/** A grant operation's fixed failure; its message is `gmail_oauth_<reason>`. */
+export class GmailOAuthFault extends Error {
+    reason;
+    cleanup;
+    /**
+     * @param reason Why the operation failed.
+     * @param cleanup What became at Google of an exchanged grant the flow does not hand back.
+     */
+    constructor(reason, cleanup = 'not_attempted') {
+        super(`gmail_oauth_${reason}`);
+        this.reason = reason;
+        this.cleanup = cleanup;
+        this.name = 'GmailOAuthFault';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oHAAoH;AACpH,MAAM,CAAC,MAAM,oBAAoB,GAAG,gDAAgD,CAAC;AAyCrF,gFAAgF;AAChF,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAKnB;IAAoC;IAJzD;;;OAGG;IACH,YAAqB,MAAyB,EAAW,UAA6B,eAAe;QACnG,KAAK,CAAC,eAAe,MAAM,EAAE,CAAC,CAAC;QADZ,WAAM,GAAN,MAAM,CAAmB;QAAW,YAAO,GAAP,OAAO,CAAqC;QACnE,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChE,CAAC;CACF"}

package/manifest.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://agentos.sh/schemas/extension-manifest-v1.json",
+  "id": "com.framers.productivity.gmail-source",
+  "name": "Gmail Source",
+  "version": "0.1.0",
+  "description": "Read-only OAuth and bounded personal Gmail source helpers",
+  "author": {
+    "name": "Frame",
+    "email": "team@frame.dev",
+    "url": "https://frame.dev"
+  },
+  "license": "Apache-2.0",
+  "keywords": ["gmail", "sources", "oauth"],
+  "agentosVersion": ">=0.13.134",
+  "categories": ["productivity"],
+  "repository": { "type": "git", "url": "https://github.com/framerslab/agentos-extensions" },
+  "extensions": [{
+    "kind": "library", "id": "gmailSource", "displayName": "Gmail source",
+    "description": "Read-only authorization for a personal Gmail source", "entry": "./dist/index.js"
+  }]
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@framers/agentos-ext-gmail-source",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Read-only OAuth and bounded personal Gmail source helpers",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./manifest.json": "./manifest.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "manifest.json",
+    "README.md"
+  ],
+  "keywords": [
+    "agentos",
+    "gmail",
+    "sources",
+    "oauth"
+  ],
+  "author": {
+    "name": "Frame",
+    "email": "team@frame.dev",
+    "url": "https://frame.dev"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/framerslab/agentos-extensions.git",
+    "directory": "registry/curated/productivity/gmail-source"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "peerDependencies": {
+    "@framers/agentos": ">=0.13.134",
+    "@framers/agentos-ext-account-sources": ">=0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "@vitest/coverage-v8": "^3.2.7",
+    "typescript": "5.4.5",
+    "vitest": "^3.2.7",
+    "@framers/agentos": "^0.13.134",
+    "@framers/agentos-ext-account-sources": "^0.6.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
 }