@framers/agentos-ext-account-sources 0.0.0-stage → 0.2.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,124 @@
-# Temporary Holding Version
+# @framers/agentos-ext-account-sources
 
-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.
+A person's own accounts as sources. This library defines `AccountSourceConnector` and the `SourceRef` every passage carries, with helpers for line ranges, links, bounded body reads, requests under the shared public-sources limiter and the cache lifetime of a read.
+
+Install `@framers/agentos-ext-account-sources` with its peer `@framers/agentos` 0.10.40 or later. Node.js 20.19 or later is required. The runtime dependency is `@framers/agentos-ext-public-sources`.
+
+## Connector
+
+An `AccountSourceConnector` exposes its `kind` and four operations:
+
+- `list(selection, signal?)` answers selected `SourceItem`s and `SourceGone` entries.
+- `read(item, signal?)` answers a `SourceRead` or a `SourceGone` entry.
+- `changesSince(cursor, selection, signal?)` answers changed items, gone items and the next cursor. A null cursor starts a listing.
+- `revoke()` ends the access the connector holds where the account supports revocation.
+
+A selection holds account item ids. A read carries text or bytes with a media type, the item and its attribution. A gone item names its id and the reason: `removed`, `no_access` or `not_owned`.
+
+Connectors obtain their grants through AgentOS's auth module and store them through its sealed token store. This library holds no grants and performs no sealing.
+
+## Attribution
+
+`SourceRef` carries `kind`, `title`, `url`, `version` and `readAt` (ISO 8601), with optional `path` and `lines`. An absent address or version is null. The kind is open to later connectors. `isSourceRef(value)` checks the field types and that optional lines form an ordered pair of positive integers; it does not parse dates or authorize an address.
+
+```ts
+import { lineRange, sourceRefLink, type SourceRef } from '@framers/agentos-ext-account-sources';
+
+const text = 'one\ntwo\nthree\nfour';
+const ref: SourceRef = {
+  kind: 'github',
+  title: 'Guide',
+  url: 'https://github.com/example/example/blob/fake-commit/docs/guide.md',
+  version: 'fake-commit',
+  readAt: '2026-10-08T12:00:00Z',
+  path: 'docs/guide.md',
+  lines: lineRange(text, 4, 16),
+};
+const link = sourceRefLink(ref); // Ends in #L2-L4.
+```
+
+`lineRange(text, start, end)` takes valid UTF-16 offsets with an exclusive end and answers 1-based line numbers. CRLF counts as one break. An empty span belongs to the line at its start. `sourceRefLink` adds a GitHub line anchor, replacing an existing fragment; other addresses are unchanged and an absent address stays null.
+
+## Reads and limits
+
+`readCapped(response, maxBytes)` returns a `Uint8Array`. It cancels and throws `ReadCapExceeded` when the declared content length exceeds the cap, before reading, or when the streamed bytes pass it. It reads at most the first chunk past the cap. The error carries `maxBytes`; a response without a body answers an empty array. Pass a finite nonnegative byte cap.
+
+`readThroughLimiter(limiter, call, signal?)` runs a response-producing call under `SourceLimiter`. A 429 or 503 blocks the limiter using `Retry-After`, cancels the response body and throws `LimiterRefused('blocked')`. Other responses are returned for the caller to inspect and consume. A blocked call is refused before it runs.
+
+Share a limiter across callers to the same account source in a process and configure its limits for that source. `SourceLimiter`, `LimiterRefused` and `retryAfterMs` are re-exported unchanged from public-sources. The optional signal cancels admission and waiting; pass it to the fetch inside `call` as well to cancel the request. The limiter holds its slot until `call` and the status check finish; consuming a returned body is the caller's work.
+
+```ts
+import { readCapped, readThroughLimiter, SourceLimiter } from '@framers/agentos-ext-account-sources';
+
+const limiter = new SourceLimiter({ concurrency: 3, spacingMs: 250 });
+
+/** Reads a caller-supplied source address under a shared limiter and byte cap. */
+async function readSource(url: string, signal?: AbortSignal): Promise<Uint8Array> {
+  /** Fetches with the caller's cancellation signal. */
+  const call = (): Promise<Response> => fetch(url, { signal });
+  const response = await readThroughLimiter(limiter, call, signal);
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw new Error(`source returned ${response.status}`);
+  }
+  return readCapped(response, 2_000_000);
+}
+```
+
+## Cache retention
+
+```ts
+import { decideSourceCache, type SourceCacheDecision, type SourceCachePermission } from '@framers/agentos-ext-account-sources';
+
+/** Decides whether a response whose read began at `readStartedAt` may be stored, and until when. */
+function cacheDecision(
+  response: Response,
+  permission: SourceCachePermission | null,
+  readStartedAt: number,
+  windowExpiresAt: number,
+): SourceCacheDecision {
+  return decideSourceCache({
+    permission,
+    maximumCacheMs: 86_400_000,
+    readStartedAt,
+    receivedAt: Date.now(),
+    windowExpiresAt,
+    headers: {
+      cacheControl: response.headers.get('cache-control'),
+      date: response.headers.get('date'),
+      age: response.headers.get('age'),
+      expires: response.headers.get('expires'),
+    },
+  });
+}
+```
+
+`decideSourceCache(input)` answers `{ kind: 'cache', expiresAt, evidenceId }` or `{ kind: 'skip', reason }`. Its input holds the permission record, the host's maximum lifetime, three times in epoch milliseconds and four response headers; it takes no response body, URL or token.
+
+`permission` is the host's record of an approved retention policy: an opaque `evidenceId` and a `retentionMs`. The library applies the record; it does not establish that a provider allows caching. A missing record, a blank `evidenceId` or a `retentionMs` that is not a positive safe integer answers `not_permitted`, whatever the headers allow.
+
+`expiresAt` is the earliest of:
+
+- `readStartedAt` plus the smaller of `retentionMs` and `maximumCacheMs`, less the response's `Age`;
+- `windowExpiresAt`, the end of the retained material's window (the earliest end when a read holds several items);
+- the `max-age` and `s-maxage` lifetimes, counted from `receivedAt` and reduced by the corrected age of [RFC 9111, section 4.2.3](https://www.rfc-editor.org/rfc/rfc9111#section-4.2.3): the larger of the age the `Date` header implies and `Age` plus the time the read took;
+- the `Expires` lifetime (its distance from `Date`, or from `readStartedAt` when `Date` is absent), counted and reduced the same way, and the `Expires` time itself.
+
+A skip carries one of these reasons:
+
+| Reason | When |
+|---|---|
+| `not_permitted` | No permission record, a blank `evidenceId`, or a `retentionMs` that is not a positive safe integer |
+| `no_store` | `Cache-Control` holds `no-store` |
+| `revalidation_required` | `Cache-Control` holds `no-cache`, with or without field names |
+| `invalid_cache_header` | A malformed or repeated `Cache-Control` directive; a `max-age` or `s-maxage` without a whole number of seconds or past the safe-integer range; an `Age` that is not a whole number of seconds or is past the safe-integer range; a `Date` or `Expires` before 1970 or outside the IMF-fixdate form of [RFC 9110, section 5.6.7](https://www.rfc-editor.org/rfc/rfc9110#section-5.6.7), exactly as `Date.prototype.toUTCString()` writes it (`Tue, 14 Nov 2023 22:13:20 GMT`) |
+| `invalid_bounds` | A clock value that is not a nonnegative safe integer, a `receivedAt` before `readStartedAt`, a `maximumCacheMs` that is not a positive safe integer, or a lifetime past the safe-integer range |
+| `expired` | The lifetime ends at or before `receivedAt` |
+
+Directive names match in any case and values may be quoted. Other directives, such as `private` and `immutable`, neither grant nor extend a lifetime. The obsolete HTTP date forms are refused rather than parsed.
+
+A skip stores nothing: record its reason and keep no content. Store `expiresAt` with the content and check it on every read. Neither a later sync checkpoint nor a second call with the old response extends it; a new read takes a new decision.
+
+## License
+
+Apache-2.0. This pack carries a copy of the repository's license.

package/dist/cachePolicy.d.ts

@@ -0,0 +1,39 @@
+/** Host-verified permission; this module does not establish provider authorization. */
+export interface SourceCachePermission {
+    readonly evidenceId: string;
+    readonly retentionMs: number;
+}
+/** Cache metadata only; no request URL, token or response content enters the policy. */
+export interface SourceCacheHeaders {
+    readonly cacheControl: string | null;
+    readonly date: string | null;
+    readonly age: string | null;
+    readonly expires: string | null;
+}
+/** Clock and retention bounds for one obtained source response. */
+export interface SourceCacheInput {
+    readonly permission: SourceCachePermission | null;
+    readonly maximumCacheMs: number;
+    readonly readStartedAt: number;
+    readonly receivedAt: number;
+    readonly windowExpiresAt: number;
+    readonly headers: SourceCacheHeaders;
+}
+/** Fixed reasons safe to aggregate without content-bearing provider messages. */
+export type SourceCacheSkipReason = 'not_permitted' | 'no_store' | 'revalidation_required' | 'invalid_cache_header' | 'invalid_bounds' | 'expired';
+/** A finite allowed lifetime, or an explicit refusal to persist any source content. */
+export type SourceCacheDecision = {
+    readonly kind: 'cache';
+    readonly expiresAt: number;
+    readonly evidenceId: string;
+} | {
+    readonly kind: 'skip';
+    readonly reason: SourceCacheSkipReason;
+};
+/**
+ * Applies explicit permission and conservative provider/cache/window limits.
+ * Returned expiry is never extended by a history checkpoint or by calling this
+ * function again with the old response. A new read needs its own permission check.
+ */
+export declare function decideSourceCache(input: SourceCacheInput): SourceCacheDecision;
+//# sourceMappingURL=cachePolicy.d.ts.map

package/dist/cachePolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cachePolicy.d.ts","sourceRoot":"","sources":["../src/cachePolicy.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;CACtC;AAED,iFAAiF;AACjF,MAAM,MAAM,qBAAqB,GAC7B,eAAe,GAAG,UAAU,GAAG,uBAAuB,GACtD,sBAAsB,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAE1D,uFAAuF;AACvF,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACnF;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAiCtE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,mBAAmB,CAiD9E"}

package/dist/cachePolicy.js

@@ -0,0 +1,97 @@
+const integer = (value) => Number.isSafeInteger(value) && value >= 0;
+const positive = (value) => integer(value) && value > 0;
+const skip = (reason) => ({ kind: 'skip', reason });
+/** Whole seconds written in digits only, as safe-integer milliseconds; anything else is null. */
+function milliseconds(value) {
+    if (!/^\d+$/.test(value))
+        return null;
+    const converted = Number(value) * 1_000;
+    return integer(converted) ? converted : null;
+}
+/** An HTTP date accepted only in the exact form `toUTCString` writes, so a loose parse cannot invent a time. */
+function date(value) {
+    if (value === null)
+        return null;
+    const parsed = Date.parse(value);
+    return integer(parsed) && new Date(parsed).toUTCString() === value ? parsed : null;
+}
+/** Cache-Control directives by lower-case name; a malformed or repeated directive answers null. */
+function directives(value) {
+    const found = new Map();
+    if (value === null || value.trim() === '')
+        return found;
+    for (const part of value.split(',')) {
+        const match = /^([a-z][a-z0-9-]*)(?:\s*=\s*(?:"([^"]*)"|([^\s",]+)))?$/i.exec(part.trim());
+        const name = match?.[1]?.toLowerCase();
+        if (!match || !name || found.has(name))
+            return null;
+        found.set(name, match[2] ?? match[3] ?? null);
+    }
+    return found;
+}
+/**
+ * Applies explicit permission and conservative provider/cache/window limits.
+ * Returned expiry is never extended by a history checkpoint or by calling this
+ * function again with the old response. A new read needs its own permission check.
+ */
+export function decideSourceCache(input) {
+    const permission = input.permission;
+    if (!permission || typeof permission.evidenceId !== 'string'
+        || permission.evidenceId.trim().length === 0 || !positive(permission.retentionMs)) {
+        return skip('not_permitted');
+    }
+    if (!positive(input.maximumCacheMs) || !integer(input.readStartedAt)
+        || !integer(input.receivedAt) || !integer(input.windowExpiresAt)
+        || input.receivedAt < input.readStartedAt)
+        return skip('invalid_bounds');
+    const policyEnd = input.readStartedAt + Math.min(permission.retentionMs, input.maximumCacheMs);
+    if (!integer(policyEnd))
+        return skip('invalid_bounds');
+    const rules = directives(input.headers.cacheControl);
+    if (rules === null)
+        return skip('invalid_cache_header');
+    if (rules.has('no-store'))
+        return skip('no_store');
+    if (rules.has('no-cache'))
+        return skip('revalidation_required');
+    const age = input.headers.age === null ? 0 : milliseconds(input.headers.age.trim());
+    const responseDate = date(input.headers.date);
+    const responseExpires = date(input.headers.expires);
+    if (age === null || (input.headers.date !== null && responseDate === null)
+        || (input.headers.expires !== null && responseExpires === null)) {
+        return skip('invalid_cache_header');
+    }
+    const elapsed = input.receivedAt - input.readStartedAt;
+    const apparentAge = responseDate === null ? 0 : Math.max(0, input.receivedAt - responseDate);
+    const correctedAge = Math.max(apparentAge, age + elapsed);
+    if (!integer(correctedAge))
+        return skip('invalid_cache_header');
+    let expiresAt = Math.min(policyEnd - age, input.windowExpiresAt);
+    for (const name of ['max-age', 's-maxage']) {
+        if (!rules.has(name))
+            continue;
+        const value = rules.get(name);
+        if (value === null || value === undefined)
+            return skip('invalid_cache_header');
+        const freshFor = milliseconds(value);
+        if (freshFor === null)
+            return skip('invalid_cache_header');
+        const freshUntil = input.receivedAt + freshFor - correctedAge;
+        if (!Number.isSafeInteger(freshUntil))
+            return skip('invalid_cache_header');
+        expiresAt = Math.min(expiresAt, freshUntil);
+    }
+    if (responseExpires !== null) {
+        const freshFor = responseExpires - (responseDate ?? input.readStartedAt);
+        const freshUntil = input.receivedAt + freshFor - correctedAge;
+        if (!Number.isSafeInteger(freshUntil))
+            return skip('invalid_cache_header');
+        expiresAt = Math.min(expiresAt, freshUntil, responseExpires);
+    }
+    if (!Number.isSafeInteger(expiresAt))
+        return skip('invalid_bounds');
+    if (expiresAt <= input.receivedAt)
+        return skip('expired');
+    return { kind: 'cache', expiresAt, evidenceId: permission.evidenceId };
+}
+//# sourceMappingURL=cachePolicy.js.map

package/dist/cachePolicy.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/** The account connector and the attribution and item shapes it carries. */
+export * from './types.js';
+/** Attribution guards, line ranges, and source links. */
+export * from './sourceRef.js';
+/** Response body reads under a byte cap and their refusal. */
+export * from './readCapped.js';
+/** The shared limiter and response-producing calls run under it. */
+export * from './limiter.js';
+/** Explicit retention permission and conservative source-cache expiry. */
+export * from './cachePolicy.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,4EAA4E;AAC5E,cAAc,YAAY,CAAC;AAC3B,yDAAyD;AACzD,cAAc,gBAAgB,CAAC;AAC/B,8DAA8D;AAC9D,cAAc,iBAAiB,CAAC;AAChC,oEAAoE;AACpE,cAAc,cAAc,CAAC;AAC7B,0EAA0E;AAC1E,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/** The account connector and the attribution and item shapes it carries. */
+export * from './types.js';
+/** Attribution guards, line ranges, and source links. */
+export * from './sourceRef.js';
+/** Response body reads under a byte cap and their refusal. */
+export * from './readCapped.js';
+/** The shared limiter and response-producing calls run under it. */
+export * from './limiter.js';
+/** Explicit retention permission and conservative source-cache expiry. */
+export * from './cachePolicy.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,4EAA4E;AAC5E,cAAc,YAAY,CAAC;AAC3B,yDAAyD;AACzD,cAAc,gBAAgB,CAAC;AAC/B,8DAA8D;AAC9D,cAAc,iBAAiB,CAAC;AAChC,oEAAoE;AACpE,cAAc,cAAc,CAAC;AAC7B,0EAA0E;AAC1E,cAAc,kBAAkB,CAAC"}

package/dist/limiter.d.ts

@@ -0,0 +1,6 @@
+import { SourceLimiter } from '@framers/agentos-ext-public-sources';
+/** The shared per-process limiter, its refusal, and its Retry-After parser. */
+export { SourceLimiter, LimiterRefused, retryAfterMs } from '@framers/agentos-ext-public-sources';
+/** Runs a response-producing call under the limiter and blocks it on a 429 or 503 before throwing. */
+export declare function readThroughLimiter(limiter: SourceLimiter, call: () => Promise<Response>, signal?: AbortSignal): Promise<Response>;
+//# sourceMappingURL=limiter.d.ts.map

package/dist/limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limiter.d.ts","sourceRoot":"","sources":["../src/limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAEpF,+EAA+E;AAC/E,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAElG,sGAAsG;AACtG,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAgBvI"}

package/dist/limiter.js

@@ -0,0 +1,23 @@
+import { LimiterRefused } from '@framers/agentos-ext-public-sources';
+/** The shared per-process limiter, its refusal, and its Retry-After parser. */
+export { SourceLimiter, LimiterRefused, retryAfterMs } from '@framers/agentos-ext-public-sources';
+/** Runs a response-producing call under the limiter and blocks it on a 429 or 503 before throwing. */
+export async function readThroughLimiter(limiter, call, signal) {
+    /** Checks the response while the call still holds the limiter's slot. */
+    const read = async () => {
+        const response = await call();
+        if (response.status === 429 || response.status === 503) {
+            limiter.block(response.headers.get('retry-after'));
+            try {
+                await response.body?.cancel();
+            }
+            catch {
+                // Cleanup failure must not replace the limiter refusal.
+            }
+            throw new LimiterRefused('blocked');
+        }
+        return response;
+    };
+    return limiter.run(read, signal);
+}
+//# sourceMappingURL=limiter.js.map

package/dist/limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limiter.js","sourceRoot":"","sources":["../src/limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAiB,MAAM,qCAAqC,CAAC;AAEpF,+EAA+E;AAC/E,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAElG,sGAAsG;AACtG,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAsB,EAAE,IAA6B,EAAE,MAAoB;IAClH,yEAAyE;IACzE,MAAM,IAAI,GAAG,KAAK,IAAuB,EAAE;QACzC,MAAM,QAAQ,GAAG,MAAM,IAAI,EAAE,CAAC;QAC9B,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvD,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;YACnD,IAAI,CAAC;gBACH,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;YAChC,CAAC;YAAC,MAAM,CAAC;gBACP,wDAAwD;YAC1D,CAAC;YACD,MAAM,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACnC,CAAC"}

package/dist/readCapped.d.ts

@@ -0,0 +1,9 @@
+/** A body past its cap. */
+export declare class ReadCapExceeded extends Error {
+    readonly maxBytes: number;
+    /** Records the byte cap the response exceeded. */
+    constructor(maxBytes: number);
+}
+/** A response's body read under a cap, refused at the header when it states more. */
+export declare function readCapped(response: Response, maxBytes: number): Promise<Uint8Array>;
+//# sourceMappingURL=readCapped.d.ts.map

package/dist/readCapped.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readCapped.d.ts","sourceRoot":"","sources":["../src/readCapped.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,qBAAa,eAAgB,SAAQ,KAAK;IAE5B,QAAQ,CAAC,QAAQ,EAAE,MAAM;IADrC,kDAAkD;gBAC7B,QAAQ,EAAE,MAAM;CAItC;AAED,qFAAqF;AACrF,wBAAsB,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAmC1F"}

package/dist/readCapped.js

@@ -0,0 +1,52 @@
+/** A body past its cap. */
+export class ReadCapExceeded extends Error {
+    maxBytes;
+    /** Records the byte cap the response exceeded. */
+    constructor(maxBytes) {
+        super(`the body passes ${maxBytes} bytes`);
+        this.maxBytes = maxBytes;
+        this.name = 'ReadCapExceeded';
+    }
+}
+/** A response's body read under a cap, refused at the header when it states more. */
+export async function readCapped(response, maxBytes) {
+    if (response.body === null)
+        return new Uint8Array(0);
+    const declared = Number(response.headers.get('content-length') ?? '0');
+    if (declared > maxBytes) {
+        try {
+            await response.body.cancel();
+        }
+        catch {
+            // Cleanup failure must not replace the cap error.
+        }
+        throw new ReadCapExceeded(maxBytes);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // Cleanup failure must not replace the cap error.
+            }
+            throw new ReadCapExceeded(maxBytes);
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.byteLength;
+    }
+    return out;
+}
+//# sourceMappingURL=readCapped.js.map

package/dist/readCapped.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readCapped.js","sourceRoot":"","sources":["../src/readCapped.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAEnB;IADrB,kDAAkD;IAClD,YAAqB,QAAgB;QACnC,KAAK,CAAC,mBAAmB,QAAQ,QAAQ,CAAC,CAAC;QADxB,aAAQ,GAAR,QAAQ,CAAQ;QAEnC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAkB,EAAE,QAAgB;IACnE,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,GAAG,CAAC,CAAC;IACvE,IAAI,QAAQ,GAAG,QAAQ,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,kDAAkD;QACpD,CAAC;QACD,MAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IACD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;IACzC,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,SAAS,CAAC;QACR,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QAC5C,IAAI,IAAI;YAAE,MAAM;QAChB,KAAK,IAAI,KAAK,CAAC,UAAU,CAAC;QAC1B,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;YACrB,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;YACxB,CAAC;YAAC,MAAM,CAAC;gBACP,kDAAkD;YACpD,CAAC;YACD,MAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,CAAC;QACtC,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACnB,EAAE,IAAI,KAAK,CAAC,UAAU,CAAC;IACzB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/sourceRef.d.ts

@@ -0,0 +1,11 @@
+import type { SourceRef } from './types.js';
+/**
+ * The 1-based first and last lines of a span at valid UTF-16 offsets, with an exclusive end.
+ * CRLF counts as one break; an empty span belongs to the line at its start.
+ */
+export declare function lineRange(text: string, start: number, end: number): [number, number];
+/** A source's address, with a GitHub file's line anchor when it carries lines. */
+export declare function sourceRefLink(ref: SourceRef): string | null;
+/** Whether an unknown value carries a source's required fields and optional path and line range. */
+export declare function isSourceRef(value: unknown): value is SourceRef;
+//# sourceMappingURL=sourceRef.d.ts.map

package/dist/sourceRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sourceRef.d.ts","sourceRoot":"","sources":["../src/sourceRef.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAIpF;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAK3D;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAa9D"}

package/dist/sourceRef.js

@@ -0,0 +1,40 @@
+/**
+ * The 1-based first and last lines of a span at valid UTF-16 offsets, with an exclusive end.
+ * CRLF counts as one break; an empty span belongs to the line at its start.
+ */
+export function lineRange(text, start, end) {
+    const first = 1 + (text.slice(0, start).match(/\n/gu)?.length ?? 0);
+    const last = 1 + (text.slice(0, Math.max(start, end - 1)).match(/\n/gu)?.length ?? 0);
+    return [first, last];
+}
+/** A source's address, with a GitHub file's line anchor when it carries lines. */
+export function sourceRefLink(ref) {
+    if (ref.url === null || ref.kind !== 'github' || ref.lines === undefined)
+        return ref.url;
+    const [first, last] = ref.lines;
+    const url = ref.url.split('#')[0];
+    return `${url}#L${first}${first === last ? '' : `-L${last}`}`;
+}
+/** Whether an unknown value carries a source's required fields and optional path and line range. */
+export function isSourceRef(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const ref = value;
+    if (typeof ref.kind !== 'string' || typeof ref.title !== 'string' || typeof ref.readAt !== 'string')
+        return false;
+    if (ref.url !== null && typeof ref.url !== 'string')
+        return false;
+    if (ref.version !== null && typeof ref.version !== 'string')
+        return false;
+    if (ref.path !== undefined && typeof ref.path !== 'string')
+        return false;
+    if (ref.lines !== undefined) {
+        if (!Array.isArray(ref.lines) || ref.lines.length !== 2)
+            return false;
+        const [first, last] = ref.lines;
+        if (typeof first !== 'number' || typeof last !== 'number' || !Number.isInteger(first) || !Number.isInteger(last) || first < 1 || last < first)
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=sourceRef.js.map

package/dist/sourceRef.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sourceRef.js","sourceRoot":"","sources":["../src/sourceRef.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAa,EAAE,GAAW;IAChE,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,CAAC;IACtF,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACvB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,GAAc;IAC1C,IAAI,GAAG,CAAC,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC,GAAG,CAAC;IACzF,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC;IAChC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,OAAO,GAAG,GAAG,KAAK,KAAK,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;AAChE,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtF,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClH,IAAI,GAAG,CAAC,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClE,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1E,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACzE,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACtE,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC;QAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK;YAAE,OAAO,KAAK,CAAC;IAC9J,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview A person's own account as a source: what a connector lists, reads and reports as changed, and the
+ * attribution every passage of it carries.
+ * @module agentos-ext-account-sources/types
+ */
+/** Where a passage came from, as a page shows and links it. */
+export interface SourceRef {
+    /** `upload`, `web`, `dropbox`, `google_drive`, `github`, or a later connector's kind. */
+    kind: string;
+    title: string;
+    /** The address a quote links to: a file at its commit, a Drive file, a web page. */
+    url: string | null;
+    /** The version read: a commit, a Drive file's version, a page's date. */
+    version: string | null;
+    /** When it was read, ISO 8601. */
+    readAt: string;
+    /** For a file in a repository: its path. */
+    path?: string;
+    /** For a passage: the first and last lines it spans, 1-based. */
+    lines?: [number, number];
+}
+/** One readable item of an account. */
+export interface SourceItem {
+    /** The account's own id for it (a Drive file id; a repository id and a path). */
+    id: string;
+    title: string;
+    /** What reading it would cost, when known. */
+    size: number | null;
+    version: string | null;
+}
+/** What a connector is asked to list. */
+export interface SourceSelection {
+    /** The account's ids the person chose (picked files, chosen repositories). */
+    ids: readonly string[];
+}
+/** One item read: its bytes or text, its type, its attribution. */
+export interface SourceRead {
+    item: SourceItem;
+    /** Text when the account exported text; bytes for the caller's loaders otherwise. */
+    content: {
+        text: string;
+    } | {
+        bytes: Uint8Array;
+        mediaType: string;
+    };
+    ref: SourceRef;
+}
+/** An item that can no longer be read: removed, unshared, out of the grant. */
+export interface SourceGone {
+    id: string;
+    reason: 'removed' | 'no_access' | 'not_owned';
+}
+/** What changed since a cursor. */
+export interface SourceChanges {
+    changed: SourceItem[];
+    gone: SourceGone[];
+    cursor: string;
+}
+/** A connector to a person's account. */
+export interface AccountSourceConnector {
+    readonly kind: string;
+    /** Lists the selected items and those that can no longer be read. */
+    list(selection: SourceSelection, signal?: AbortSignal): Promise<{
+        items: SourceItem[];
+        gone: SourceGone[];
+    }>;
+    /** Reads one item with its attribution or reports why it is gone. */
+    read(item: SourceItem, signal?: AbortSignal): Promise<SourceRead | SourceGone>;
+    /** Lists changes to the selection since a cursor and answers the next cursor. */
+    changesSince(cursor: string | null, selection: SourceSelection, signal?: AbortSignal): Promise<SourceChanges>;
+    /** Ends the access the connector holds, where the account has a way to. */
+    revoke(): Promise<void>;
+}
+//# 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,+DAA+D;AAC/D,MAAM,WAAW,SAAS;IACxB,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,yEAAyE;IACzE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1B;AAED,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,iFAAiF;IACjF,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,yCAAyC;AACzC,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;CACxB;AAED,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,qFAAqF;IACrF,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,GAAG,EAAE,SAAS,CAAC;CAChB;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;CAC/C;AAED,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yCAAyC;AACzC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,IAAI,CAAC,SAAS,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,IAAI,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAC;IAC7G,qEAAqE;IACrE,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,GAAG,UAAU,CAAC,CAAC;IAC/E,iFAAiF;IACjF,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC9G,2EAA2E;IAC3E,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview A person's own account as a source: what a connector lists, reads and reports as changed, and the
+ * attribution every passage of it carries.
+ * @module agentos-ext-account-sources/types
+ */
+export {};
+//# 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"}

package/manifest.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://agentos.sh/schemas/extension-manifest-v1.json",
+  "id": "com.framers.research.account-sources",
+  "name": "Account Sources",
+  "version": "0.2.0",
+  "description": "A person's own accounts as sources: connector interfaces, passage attribution, capped reads and a shared limiter",
+  "author": {
+    "name": "Frame",
+    "email": "team@frame.dev",
+    "url": "https://frame.dev"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "sources",
+    "connectors",
+    "attribution"
+  ],
+  "agentosVersion": ">=0.10.40",
+  "categories": ["research"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/framerslab/agentos-extensions"
+  },
+  "extensions": [
+    {
+      "kind": "library",
+      "id": "accountSources",
+      "displayName": "Account sources",
+      "description": "Connector interfaces and helpers for attributed passages from a person's accounts",
+      "entry": "./dist/index.js"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@framers/agentos-ext-account-sources",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "A person's own accounts as sources: connector interfaces, passage attribution, capped reads and a shared limiter",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./manifest.json": "./manifest.json",
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "agentos",
+    "sources",
+    "connectors",
+    "attribution"
+  ],
+  "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/research/account-sources"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "peerDependencies": {
+    "@framers/agentos": ">=0.10.40"
+  },
+  "dependencies": {
+    "@framers/agentos-ext-public-sources": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.12",
+    "@vitest/coverage-v8": "^3.2.7",
+    "rimraf": "^5.0.7",
+    "typedoc": "^0.28.20",
+    "typescript": "^5.4.5",
+    "vitest": "^3.2.7",
+    "@framers/agentos": "^0.13.89"
+  },
+  "homepage": "https://github.com/framerslab/agentos-extensions/tree/master/registry/curated/research/account-sources#readme",
+  "bugs": {
+    "url": "https://github.com/framerslab/agentos-extensions/issues"
+  },
+  "files": [
+    "dist",
+    "manifest.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "docs": "typedoc --out docs src/index.ts",
+    "clean": "rimraf dist"
+  }
 }