@zackbart/connecta 0.36.0 → 0.36.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +55 -0
- package/README.md +1 -1
- package/bin/version.mjs +1 -1
- package/dist/auth/downstream-oauth.js +3 -0
- package/dist/auth/oauth-authorization-params.js +52 -0
- package/dist/auth/static-oauth.js +1 -4
- package/dist/connectors/option-shapes.js +1 -0
- package/dist/connectors/remote-mcp.d.ts +4 -1
- package/dist/connectors/remote-mcp.js +12 -1
- package/dist/google.d.ts +13 -0
- package/dist/google.js +42 -0
- package/dist/http/hatch-paging.js +2 -2
- package/dist/http/paging.js +3 -88
- package/dist/http/provider.js +1 -2
- package/dist/http/tools.js +1 -23
- package/dist/program-writes.js +0 -1
- package/dist/providers/_shared/google/service-account.d.ts +1 -1
- package/dist/providers/_shared/google/service-account.js +20 -8
- package/dist/providers/_shared/sensitive-fields.js +0 -16
- package/dist/providers/breeze/api.js +2 -2
- package/dist/providers/ccb/api.js +1 -1
- package/dist/providers/cloudflare/api.js +8 -8
- package/dist/providers/cloudflare/lib/config.d.ts +2 -1
- package/dist/providers/docs/api.js +1 -1
- package/dist/providers/drive/api.js +1 -1
- package/dist/providers/drive/lib/hatch.js +1 -1
- package/dist/providers/drive/tools.js +1 -1
- package/dist/providers/forms/api.js +1 -1
- package/dist/providers/forms/lib/hatch.js +1 -1
- package/dist/providers/forms/tools.js +1 -1
- package/dist/providers/github/api.js +1 -1
- package/dist/providers/github/lib/discovery.js +2 -2
- package/dist/providers/gmail/api.js +1 -1
- package/dist/providers/granola/api.js +155 -0
- package/dist/providers/granola/index.d.ts +10 -0
- package/dist/providers/granola/index.js +68 -0
- package/dist/providers/granola/openapi.generated.js +30 -0
- package/dist/providers/granola/safety.js +37 -0
- package/dist/providers/granola/skill.generated.js +5 -0
- package/dist/providers/granola/tools.js +2 -0
- package/dist/providers/overflow/api.js +26 -26
- package/dist/providers/planning-center/api.js +4 -4
- package/dist/providers/planning-center/lib/constants.d.ts +1 -1
- package/dist/providers/planning-center/lib/json-api.js +2 -2
- package/dist/providers/quickbooks/lib/query.js +1 -1
- package/dist/providers/quickbooks/safety.js +1 -1
- package/dist/providers/sheets/api.js +1 -1
- package/dist/providers/sheets/lib/hatch.js +2 -2
- package/dist/providers/sheets/lib/requests.js +1 -1
- package/dist/providers/slides/api.js +1 -1
- package/dist/providers/stripe/api.js +7 -7
- package/dist/providers/tithely/api.js +2 -2
- package/dist/providers/vercel/api.js +12 -12
- package/dist/providers/vercel/lib/pin.js +1 -1
- package/dist/request-token.d.ts +7 -0
- package/dist/request-token.js +1 -0
- package/dist/routes/mcp.js +1 -1
- package/dist/runtime/admission.js +0 -12
- package/dist/storage/keys.js +2 -3
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/documentation/README.md +13 -12
- package/documentation/architecture.md +148 -76
- package/documentation/auth.md +198 -4
- package/documentation/code-mode.md +6 -6
- package/documentation/meta-tools.md +5 -2
- package/documentation/operator-tests.md +11 -2
- package/documentation/operator-ui.md +1 -2
- package/documentation/providers.md +110 -0
- package/package.json +10 -2
- package/templates/node/package.json +1 -1
|
@@ -763,9 +763,9 @@ adoption, OAuth handoff ownership, single-use connect links, every downstream
|
|
|
763
763
|
OAuth grant write and consent claim, the result stash, and initialization of the cursor signing key.
|
|
764
764
|
|
|
765
765
|
Every key is built in `src/storage/keys.ts`, which lists each family with its
|
|
766
|
-
scope, version, codec, and TTL policy
|
|
767
|
-
|
|
768
|
-
|
|
766
|
+
scope, version, codec, and TTL policy. Deployed-consumer persistence journeys
|
|
767
|
+
check actual owner isolation in the physical database; key probes retain NUL
|
|
768
|
+
refusal. Core hands
|
|
769
769
|
subsystems namespaced views: `conn:<id>:` per connector, `principal:<key>:` per
|
|
770
770
|
personal registry, `results:` and `subject:<key>:` for result paging.
|
|
771
771
|
|
|
@@ -1199,6 +1199,15 @@ meaning. These facts do not change agent error fields or write outcomes.
|
|
|
1199
1199
|
|
|
1200
1200
|
## Configuration
|
|
1201
1201
|
|
|
1202
|
+
Downstream OAuth browser extensions use `auth.authorizationParams` on
|
|
1203
|
+
`remoteMcp()` and `oauth.authorizationParams` on `api()`. Both snapshot and
|
|
1204
|
+
validate the string map at construction, reserve protocol/security parameters
|
|
1205
|
+
case-insensitively, and add entries only when publishing the consent URL.
|
|
1206
|
+
Remote MCP includes canonical sorted entries in its existing client configuration
|
|
1207
|
+
binding (omitted and empty maps remain equivalent); static API OAuth retains
|
|
1208
|
+
its existing token-endpoint binding. The [auth contract](./auth.md#browser-authorization-parameters)
|
|
1209
|
+
owns limits, reserved names, and reconnect requirements.
|
|
1210
|
+
|
|
1202
1211
|
`ConnectaConfig` is one schema (`src/config.ts`, combinators in
|
|
1203
1212
|
`src/config-schema.ts`). The same value produces the TypeScript type a
|
|
1204
1213
|
deployment writes, the unknown-key walk createConnecta runs before reading any
|
|
@@ -1210,8 +1219,8 @@ is resolved in place of the caller's object, so no getter or Proxy trap runs;
|
|
|
1210
1219
|
an accessor on a config object or array is refused by path, as is an object
|
|
1211
1220
|
that cannot be inspected. A closed object or record slot takes a plain object
|
|
1212
1221
|
only: an array or a class instance there is refused by path, unread. String
|
|
1213
|
-
maps (static `headers`, `api()`
|
|
1214
|
-
`tokenRequestHeaders`) are copied the same way and each value must be a
|
|
1222
|
+
maps (static `headers`, remote MCP and `api()` OAuth `authorizationParams`,
|
|
1223
|
+
and `api()` OAuth `tokenRequestHeaders`) are copied the same way and each value must be a
|
|
1215
1224
|
string. A discriminated union (`remoteMcp()`'s `auth.type`,
|
|
1216
1225
|
a provider's `auth.type`) with a missing or unrecognized discriminant throws
|
|
1217
1226
|
with the valid values. Only plain data is copied. Connectors, modules,
|
|
@@ -1266,20 +1275,16 @@ removed. Legacy hosted selectors fail at construction with the generic migration
|
|
|
1266
1275
|
path. GitHub retains its scope-enforced App identity and exposes a bounded repository-read and release-write hatch plus local scope discovery, scoped data search and guarded merge.
|
|
1267
1276
|
|
|
1268
1277
|
[Decision 0011](https://github.com/zackbart/connecta/blob/main/decisions/0011-provider-standard.md)
|
|
1269
|
-
records the provider standard
|
|
1278
|
+
records the provider standard implemented by every maintained provider. It fixes
|
|
1270
1279
|
one folder layout per kind and fixed evidence names. `drift.json` gets a
|
|
1271
1280
|
generated block and the guide a generated Conventions section, and every
|
|
1272
|
-
`api()` surface gets one agent-facing shape.
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
refuses a provider past step 1 that breaks the `drift.json` rules, or one past
|
|
1280
|
-
step 2 that breaks the guide rules: `drift.json` version 2's `generated` block
|
|
1281
|
-
(operations from the kit's `ProviderKitFacts` and evidence digests), and a guide's `## Conventions`, rendered
|
|
1282
|
-
from the definition's declarations into `skill.generated.ts`.
|
|
1281
|
+
`api()` surface gets one agent-facing shape. Every maintained provider meets the
|
|
1282
|
+
standard without a migration exemption. `test/provider-standard.node.test.ts`
|
|
1283
|
+
holds every provider folder to it, and `test/provider-conventions.test.ts`
|
|
1284
|
+
checks the surface rules on Node. `providers:generate` refuses drift (D) and
|
|
1285
|
+
guide (G) violations before writing. It derives `drift.json` version 2's
|
|
1286
|
+
`generated` block from kit operations and evidence digests, and the guide's
|
|
1287
|
+
`## Conventions` from definition declarations into `skill.generated.ts`.
|
|
1283
1288
|
The generator requires `fixtures.ts` to export `createAuthored()` with a
|
|
1284
1289
|
nonempty offline `staticTools` catalog. Its input/output schemas derive one
|
|
1285
1290
|
paging convention, including `get_*`, hatch search and details, excluding
|
|
@@ -1291,8 +1296,9 @@ reports a nonzero explicit refusal count with singular/plural wording and
|
|
|
1291
1296
|
points to the actual prefixed details tool with method/path lookup; it never
|
|
1292
1297
|
embeds the refusal table. Unreviewed operations remain refused.
|
|
1293
1298
|
`ProviderContext.usageGuide` selects a guide's `<!-- when: <key> -->` blocks
|
|
1294
|
-
with the definition's `blocks`.
|
|
1295
|
-
|
|
1299
|
+
with the definition's `blocks`. Maintained drift records use version 2;
|
|
1300
|
+
`providers:check` retains version-1 endpoint/manual record parsing for historical
|
|
1301
|
+
reports, while OpenAPI generation and checks use `evidence/openapi.json`. It reports a manifest operation no endpoint row records at the provider's level,
|
|
1296
1302
|
and lists manual checks last verified more than 180 days ago. Its offline
|
|
1297
1303
|
record validator, `scripts/drift-validate.mjs`, also gates `providers:generate`
|
|
1298
1304
|
and the standard suite, so a record they accept is one `providers:check` reads.
|
|
@@ -1356,8 +1362,10 @@ acknowledgement, then reconciles vendor state with exactly one physical send.
|
|
|
1356
1362
|
`test/provider-privacy-journey.node.test.ts` checks credential echoes over HTTP.
|
|
1357
1363
|
Focused provider suites retain MIME/draft restrictions, revision conflicts,
|
|
1358
1364
|
CCB routing, Planning Center product exclusions and deployment pins. Native
|
|
1359
|
-
HTTP framing, cursor and request-lifetime fault probes remain in the HTTP suites
|
|
1360
|
-
catalog
|
|
1365
|
+
HTTP framing, cursor and request-lifetime fault probes remain in the HTTP suites.
|
|
1366
|
+
The catalog-wide status sweep and its argument roster, catalog/ranking copies
|
|
1367
|
+
and unused paging strategy tests are retired under #1072. Provider workflows
|
|
1368
|
+
belong in the existing shared outcomes; a new tool requires no failure-matrix row.
|
|
1361
1369
|
No legacy REST tool adapter remains.
|
|
1362
1370
|
Large documents opt into generator options that drop restated operation ids
|
|
1363
1371
|
and plain path parameters and cap one operation's details (`opBudget`).
|
|
@@ -1376,7 +1384,7 @@ schemaless and non-JSON responses declare no fields. Request shrinking and
|
|
|
1376
1384
|
endpoint contract digests do not depend on this metadata.
|
|
1377
1385
|
Fields remain optional additive metadata, so a previously compiled
|
|
1378
1386
|
index without the source bytes remains usable without inventing a response
|
|
1379
|
-
contract. Vercel's
|
|
1387
|
+
contract. Vercel's pin includes response metadata from the reviewed public
|
|
1380
1388
|
document; operations without declared response properties still refuse fields. Breeze's pin declares no response
|
|
1381
1389
|
properties. GitHub's immutable official OpenAPI pin supplies its complete index and response fields; a reviewed repository allowlist controls dispatch. Natural queries with reviewed matches scope discovery to those matches and named-only operations; explicit paths and unmatched queries retain full-pin refusal discovery.
|
|
1382
1390
|
`check:providers-generated` checks each index header against its source record
|
|
@@ -1435,14 +1443,12 @@ every vendor ships one reviewed table through one mechanism
|
|
|
1435
1443
|
signing, webhooks, drains, transfer, claim, and invite codes). It is the
|
|
1436
1444
|
union of the detectors Cloudflare and Vercel shipped first, and
|
|
1437
1445
|
deliberately over-inclusive. `providers:spec` writes
|
|
1438
|
-
`evidence/value-safety.json`
|
|
1439
|
-
provider's step 1) when the source record sets
|
|
1446
|
+
`evidence/value-safety.json` when the source record sets
|
|
1440
1447
|
`options.valueSafety` (vendor `operationWords`; Stripe's `expansions: false`
|
|
1441
1448
|
skips id-or-object expansions, which are their own operations' candidates),
|
|
1442
1449
|
stamped with the pinned digest, the detector format, and its options. The
|
|
1443
1450
|
file is test evidence and never ships.
|
|
1444
|
-
2. **One reviewed verdict per candidate**, in the vendor's `safety.ts
|
|
1445
|
-
(`value-safety.ts` until its step 1):
|
|
1451
|
+
2. **One reviewed verdict per candidate**, in the vendor's `safety.ts`:
|
|
1446
1452
|
`refuse` (the generic tools refuse it before transport, naming the
|
|
1447
1453
|
operation and the reason), `redact` (reviewed field paths), or `safe`, each
|
|
1448
1454
|
with a reason. Paths are dot paths into the data a tool returns: a list on
|
|
@@ -1627,14 +1633,13 @@ response schema can return (through `options.valueSafety.dataRoot` for an
|
|
|
1627
1633
|
envelope such as Cloudflare's `result`), and every resource rule path
|
|
1628
1634
|
something the resource's schema can return. It stamps the paths that resolve
|
|
1629
1635
|
into the candidates file and fails on the rest, unless the table's `absent`
|
|
1630
|
-
field
|
|
1636
|
+
field acknowledges
|
|
1631
1637
|
them with a reason (shared verdicts applied to operations whose schema lacks a
|
|
1632
1638
|
path, or fields a schema leaves undeclared; such paths still apply at
|
|
1633
1639
|
runtime).
|
|
1634
1640
|
|
|
1635
1641
|
`test/fixtures/value-safety.ts` is the shared harness each vendor's
|
|
1636
|
-
`
|
|
1637
|
-
runs; `reviewProblems` is pure, and
|
|
1642
|
+
`provider.safety.node.test.ts` runs; `reviewProblems` is pure, and
|
|
1638
1643
|
`test/value-safety-harness.node.test.ts` proves wrong paths fail it. It fails
|
|
1639
1644
|
on candidates from another pin, format, or option set; an unreviewed
|
|
1640
1645
|
candidate; a verdict for an operation the index lacks; a table path the stamp
|
|
@@ -1672,21 +1677,74 @@ capture determinism. Production invariants remain unchanged.
|
|
|
1672
1677
|
Use the existing stateful fixture vendors and published-edge deployment adapters:
|
|
1673
1678
|
|
|
1674
1679
|
- `pnpm run eval:outcomes` drives representative joins, retained paging, endpoint
|
|
1675
|
-
refusal, auth handoff, value safety and
|
|
1680
|
+
refusal, auth handoff, value safety and recovery after committed refunds,
|
|
1681
|
+
cancellations, DNS and environment updates, plus a single GitHub draft release
|
|
1682
|
+
and Google document partial creation and shared-drive permissions. Graders inspect
|
|
1676
1683
|
independent downstream state and the physical mutation ledger, and reject
|
|
1677
1684
|
wrong targets, duplicate writes, missing completion and interrupted trials.
|
|
1685
|
+
Every reference also rejects a fabricated correct answer without the work.
|
|
1686
|
+
Promoted read journeys reject erased MCP data even with the vendor ledger intact.
|
|
1678
1687
|
- `pnpm run eval:smoke` boots the Node template, Node eval deployments and native
|
|
1679
|
-
Workers deployments, including the actual QuickBooks
|
|
1688
|
+
Workers deployments, including the actual QuickBooks and Granola providers, then exercises
|
|
1680
1689
|
MCP and the operator page.
|
|
1690
|
+
- The shared `granola-workspace-journey` outcome uses actual provider reads,
|
|
1691
|
+
independent fake meeting state and physical cursor/filter requests on both
|
|
1692
|
+
Node/SQLite/QuickJS and native Workers/D1. It covers transcript-too-large
|
|
1693
|
+
recovery, empty intermediate pages, selected fields, withheld photo/credential
|
|
1694
|
+
values and shared-vault reuse after application reconstruction. No-op,
|
|
1695
|
+
fabricated-read and erased-delivery controls must fail.
|
|
1696
|
+
- `test/identity-write-journey.node.test.ts` uses the existing Node deployment
|
|
1697
|
+
adapter, stateful MCP fake, SQLite vault and QuickJS to grade admitted human
|
|
1698
|
+
and machine identities, pool isolation, fail-closed discovery, endpoint and
|
|
1699
|
+
connector policy, physical mutation counts, ambiguous-write reconciliation,
|
|
1700
|
+
credential ownership and payload-free activity. Independent decoding checks
|
|
1701
|
+
returned private values and credential echoes; positive record facts must
|
|
1702
|
+
still arrive. An explicitly writable pool also exercises reopening a
|
|
1703
|
+
read-only deployment without bypassing connector policy.
|
|
1704
|
+
- `test/cancellation-journey.node.test.ts` observes a queued client's departure
|
|
1705
|
+
without another vendor send, and an active client's departure after the
|
|
1706
|
+
vendor commits. The vendor must see its held response socket close before
|
|
1707
|
+
releasing it; a later MCP read recovers the committed intent exactly once.
|
|
1708
|
+
`test/cancellation-faults.test.ts` keeps signal-less token-resolution,
|
|
1709
|
+
warmed-credential digest, stalled body-cleanup and abort/grant races on Node
|
|
1710
|
+
and workerd. These replace the universal Promise-method/seam/owner matrix
|
|
1711
|
+
and its enrollment self-test, plus migration-only runtime wrapper checks.
|
|
1712
|
+
- `test/browser/operator-flows.spec.ts` serves the actual operator shell and
|
|
1713
|
+
routes over TCP with file-backed SQLite. Sign-in, Settings provenance, OAuth
|
|
1714
|
+
connect/disconnect and credential save/test/replace/remove survive closing and
|
|
1715
|
+
reopening the app, database and vault. An independent SQL connection reads
|
|
1716
|
+
trigger counts: one save, one replacement, one removal, and no credential
|
|
1717
|
+
writes from reads or a rejected replacement. A real SQL trigger failure leaves the old
|
|
1718
|
+
credential usable after restart. MCP calls verify that those edits preserve
|
|
1719
|
+
the reader pool's actual read access and write refusal. Activity renders
|
|
1720
|
+
successful calls recorded before restart without either credential value.
|
|
1721
|
+
- The existing Node-template `eval:smoke` target constructs invalid config from
|
|
1722
|
+
published imports before any I/O and reuses a stored token after restarting
|
|
1723
|
+
the consumer process. Its Worker-fakes target saves a personal credential in
|
|
1724
|
+
Chromium, refuses another owner's use, saves that owner's invalid credential,
|
|
1725
|
+
then restarts workerd on the same D1 directory. Actual downstream records
|
|
1726
|
+
remain readable only to the correct owner. Direct SQL inspection finds two
|
|
1727
|
+
distinct durable encrypted rows and exactly one committed save for each.
|
|
1728
|
+
- Keep focused SQL batch/schema/retention rollback, clock-skew and absolute
|
|
1729
|
+
expiry, NUL/UTF-8 and literal-prefix, cross-connection claims, cancellation,
|
|
1730
|
+
corrupt-row and tracing-secrecy probes. Keep operator identity/slot fences,
|
|
1731
|
+
deadlines, CSRF, restricted-view projection and sink secrecy probes. These
|
|
1732
|
+
cover faults that a successful browser journey cannot reproduce. Retired
|
|
1733
|
+
evidence includes the key-prefix source scanner, config expected-object
|
|
1734
|
+
matrices, operator structure snapshots and native-composition sentinels.
|
|
1681
1735
|
- `test/provider-privacy-journey.node.test.ts` sends credentials through real
|
|
1682
1736
|
HTTP MCP and a maintained API provider. Unknown vendor fields and keys carry
|
|
1683
1737
|
raw, escaped, percent-encoded, base64 and Basic echoes through direct calls,
|
|
1684
1738
|
QuickJS programs, failure and recovery. The independent decoder in
|
|
1685
1739
|
`test/helpers/secret-echoes.ts` checks the wire responses for secret fragments;
|
|
1686
1740
|
it does not normalize them to placeholders or compare saved output.
|
|
1687
|
-
- `test/provider-
|
|
1688
|
-
|
|
1689
|
-
|
|
1741
|
+
- `test/provider-hostile-response.node.test.ts` reconciles real HTTP mutations
|
|
1742
|
+
after HTML, malformed JSON and oversized acknowledgements with one physical
|
|
1743
|
+
send. It distinguishes Stripe's reviewed pre-execution 401 refusal, and checks
|
|
1744
|
+
read failure facts, secrecy and recovery through direct and QuickJS calls.
|
|
1745
|
+
`test/provider-failure-sweep.test.ts` retains only concrete auxiliary, composite,
|
|
1746
|
+
in-flight and untracked-call fault probes; no provider/tool argument roster or
|
|
1747
|
+
catalog/finalizer agreement sweep remains. Existing
|
|
1690
1748
|
`test/sent-secrets.test.ts`, `test/sent-secret-output-boundary.test.ts`,
|
|
1691
1749
|
`test/request-secret-redaction.test.ts` and `test/catalog-secret-redaction.test.ts`
|
|
1692
1750
|
cover secrecy before projection, truncation, caching, paging and diagnostics.
|
|
@@ -1695,11 +1753,24 @@ Use the existing stateful fixture vendors and published-edge deployment adapters
|
|
|
1695
1753
|
Native transport parity, OAuth and write-provenance suites retain their
|
|
1696
1754
|
workerd coverage. The shared throwaway RSA key in `test/fixtures/rsa.ts` is
|
|
1697
1755
|
used by write-provenance and unknown-write-advice fixtures.
|
|
1698
|
-
- The request, catalog, auxiliary-call
|
|
1756
|
+
- The request, catalog, auxiliary-call and renewal lifetime
|
|
1699
1757
|
suites, plus `test/auth-admission-binding.test.ts`, exercise cancellation,
|
|
1700
1758
|
held native work and garbage collection. These test actual request ownership;
|
|
1701
1759
|
the retired capture scheduler's source guards were only harness constraints.
|
|
1702
1760
|
|
|
1761
|
+
The remaining probes defend distinct reachable failures: auth admission and
|
|
1762
|
+
native scheduler ownership, grant/callback fencing and refresh coordination,
|
|
1763
|
+
SDK replay/redirect/SSE attempts, nested write provenance and refusal evidence,
|
|
1764
|
+
unawaited program drain and failed-program accounting, catalog drift and paging
|
|
1765
|
+
revocation, and hostile serializers, structural echoes, truncation and persisted
|
|
1766
|
+
pages. Broad scripted-executor policy/privacy cross-products and repeated
|
|
1767
|
+
post-401 result/error-shape tables are retired. Protocol claims link executable
|
|
1768
|
+
evidence files in `spec/coverage.json`; the invariant contracts above are defended
|
|
1769
|
+
by the actual behavior assertions in these journeys and focused probes.
|
|
1770
|
+
The required CI gate includes build/declarations, Node and Workers probes,
|
|
1771
|
+
outcomes, browser flows, installed consumers and Docker, audits and real Eve
|
|
1772
|
+
compatibility. Further contributor cleanup is tracked in #1072.
|
|
1773
|
+
|
|
1703
1774
|
Add a compact fault journey only for a meaningful outcome those suites cannot
|
|
1704
1775
|
observe. Reuse their fixtures and adapters; do not reintroduce a snapshot
|
|
1705
1776
|
format, module loader or virtual scheduler. Workerd enrollment is for native
|
|
@@ -1708,6 +1779,19 @@ fetch, streams, Web Crypto, lifetime and request-byte behavior, as listed in
|
|
|
1708
1779
|
|
|
1709
1780
|
## Optional deployment modules
|
|
1710
1781
|
|
|
1782
|
+
`/google` (`src/google.ts`) exports the Promise-based
|
|
1783
|
+
`googleServiceAccountToken` request-token resolver outside the root graph.
|
|
1784
|
+
It reuses `src/providers/_shared/google/service-account.ts` for Web Crypto,
|
|
1785
|
+
in-memory token caching and exact-token invalidation, with an absent subject
|
|
1786
|
+
for service accounts acting as themselves. Workspace providers keep supplying
|
|
1787
|
+
subjects and retain their delegated error guidance. `src/request-token.ts`
|
|
1788
|
+
owns the callable resolver contract and optional HTTP-401 invalidation hook;
|
|
1789
|
+
`remoteMcp()` invokes it without replaying the failed operation.
|
|
1790
|
+
`test/google-service-account-token.test.ts` exercises signing/cache behavior on
|
|
1791
|
+
Node and workerd; `test/google-service-account-remote.node.test.ts` checks
|
|
1792
|
+
real-socket token/MCP requests, invalidation and one physical attempt per write.
|
|
1793
|
+
Operator setup lives in [Google hosted MCP](./auth.md#google-service-account-tokens-and-hosted-mcp).
|
|
1794
|
+
|
|
1711
1795
|
`createConnecta` takes closed typed `ui`, `vault`, and `activity`
|
|
1712
1796
|
slots, with factories at `/ui`, `/credentials`, and `/activity`
|
|
1713
1797
|
and agent tokens at `/auth/access-tokens`. Root exports the contracts, never the implementations, and there
|
|
@@ -1822,9 +1906,9 @@ declarations; elsewhere it lives in an unexported function or in
|
|
|
1822
1906
|
(`ConnectorCallError`, `ExecutorAdmissionError`, `CallAdmissionError`) because
|
|
1823
1907
|
callers and tests check `instanceof`, `name`, and `message`.
|
|
1824
1908
|
|
|
1825
|
-
Effect callers skip the Promise and take the program: `admit`
|
|
1826
|
-
|
|
1827
|
-
|
|
1909
|
+
Effect callers skip the Promise and take the program: `admit` for executor
|
|
1910
|
+
admission (`src/runtime/admission.ts`), `admitCall` and `acquireCallScoped` for
|
|
1911
|
+
call admission, `closeScope` and `closeScopeOnExit`
|
|
1828
1912
|
for a connector scope, `withDeadlineEffect` where Promise code has
|
|
1829
1913
|
`withDeadline`. The build prunes every declaration no `exports` target reaches,
|
|
1830
1914
|
and `pnpm run check:declarations` fails if what remains names an Effect type.
|
|
@@ -2044,8 +2128,8 @@ published storage interfaces.
|
|
|
2044
2128
|
The synchronous state-file parser, validation, file read, and one atomic
|
|
2045
2129
|
SQLite import remain native synchronous leaves because `importStateFile` is a
|
|
2046
2130
|
published synchronous API. `openSqlite` retains file modes, WAL, busy timeout,
|
|
2047
|
-
and database ownership. `test/sql-effect-contract.ts`
|
|
2048
|
-
|
|
2131
|
+
and database ownership. `test/sql-effect-contract.ts` retains affected-row,
|
|
2132
|
+
50-claim, typed-failure, cancellation, and tracing probes on SQLite and native
|
|
2049
2133
|
D1. `test/kv-to-d1.test.ts` also reuses stores across separate workerd requests;
|
|
2050
2134
|
the existing SQL contracts prove rollback, database-clock TTL, encodings,
|
|
2051
2135
|
activity upgrades, and copy recovery.
|
|
@@ -2198,8 +2282,7 @@ ordinary Promise-based Connector factory. The kit stays outside the root
|
|
|
2198
2282
|
graph and its Effect types are internal. In each provider, `api.ts` declares
|
|
2199
2283
|
the vendor and `tools.ts` the tools.
|
|
2200
2284
|
|
|
2201
|
-
|
|
2202
|
-
A `list` without the legacy `key` returns `{ items, page }`, with
|
|
2285
|
+
The standard `list` builder returns `{ items, page }`, with
|
|
2203
2286
|
`page.nextCursor` only while `hasMore`, and the kit appends `limit` (the
|
|
2204
2287
|
declared default and maximum), `cursor` and `fields` to the tool's filters;
|
|
2205
2288
|
`read` and `get` take `fields: true`. `src/http/fields.ts` narrows after every
|
|
@@ -2441,8 +2524,8 @@ after repairing/deleting a corrupt key, restart every process/isolate to clear
|
|
|
2441
2524
|
cached keys. Pre-upgrade cursors require a new first page.
|
|
2442
2525
|
|
|
2443
2526
|
The helper derives connection metadata and probe messages from
|
|
2444
|
-
validated options and
|
|
2445
|
-
|
|
2527
|
+
validated options and renders every maintained guide through
|
|
2528
|
+
`ProviderContext.usageGuide`.
|
|
2446
2529
|
Candidate checks can refuse before authentication while
|
|
2447
2530
|
preserving the provider's exact diagnostic. Its optional `authScope(options)`
|
|
2448
2531
|
selector fixes OAuth grant ownership from deployment mode at construction;
|
|
@@ -2544,7 +2627,7 @@ dispatch.
|
|
|
2544
2627
|
|
|
2545
2628
|
The generator's `allSuccessResponses: true` option unions JSON response fields
|
|
2546
2629
|
from every 2xx. Existing providers keep the first JSON success contract until
|
|
2547
|
-
their own reviewed regeneration
|
|
2630
|
+
their own reviewed regeneration.
|
|
2548
2631
|
|
|
2549
2632
|
`src/providers/_shared/google/hatch.ts` supplies JSON framing over the existing
|
|
2550
2633
|
confined `Connection.sendPath`. It retains the hatch's origin/media guards,
|
|
@@ -2571,8 +2654,7 @@ For example, a direct value-mode result has outer `result.data`, the hatch's
|
|
|
2571
2654
|
`result.data.page.nextCursor`, and vendor JSON at `result.data.data`:
|
|
2572
2655
|
`call_tool({ address: "crm.forms_api_read", args: { path:
|
|
2573
2656
|
"/forms/form_1/responses", cursor: previous.data.page.nextCursor },
|
|
2574
|
-
resultMode: "value" })`.
|
|
2575
|
-
provider, not a claim that the Forms migration has shipped.
|
|
2657
|
+
resultMode: "value" })`. Google Forms uses this continuation envelope.
|
|
2576
2658
|
|
|
2577
2659
|
`googleErrors(product, { standard: true })` declares the product's 404 meaning
|
|
2578
2660
|
and uses common status fallbacks; revision-conflict meanings require a
|
|
@@ -2602,7 +2684,7 @@ Sheets declares its seven API methods in `src/providers/sheets/api.ts`; its
|
|
|
2602
2684
|
kit tools retain the private digest-bound cell cursor, legacy A1 path encoding,
|
|
2603
2685
|
and create/append recovery advice. Its projections and the Google failure
|
|
2604
2686
|
classifier read fields by the names Google gave them, which the kit's parse pass
|
|
2605
|
-
keeps.
|
|
2687
|
+
keeps.
|
|
2606
2688
|
|
|
2607
2689
|
Google's request adapter also offers a reviewed binary send. It marks the
|
|
2608
2690
|
operation `googleBytes` for the product's `binaryBodies` selector and forwards
|
|
@@ -2814,8 +2896,8 @@ result handling, reviewed value safety and the deployment privacy projection
|
|
|
2814
2896
|
before paging or provider projections can read it. Read methods beyond GET
|
|
2815
2897
|
and HEAD require a review. Construction fixes each write step's capacity;
|
|
2816
2898
|
the guarded transport reserves it before preparation and the shared core
|
|
2817
|
-
decides the whole call's write outcome.
|
|
2818
|
-
|
|
2899
|
+
decides the whole call's write outcome. Drive uploads use write builders over
|
|
2900
|
+
reviewed raw-body sends.
|
|
2819
2901
|
|
|
2820
2902
|
Reviewed path calls resolve their actual method and path through an indexed
|
|
2821
2903
|
safety adapter; a provider-supplied template cannot bypass the policy.
|
|
@@ -3026,7 +3108,8 @@ compiling and configuring the real thing.
|
|
|
3026
3108
|
rejections are observed; dispatch and lease guards still contain detached
|
|
3027
3109
|
work. Per-await I/O cancellation remains useful for releasing resources,
|
|
3028
3110
|
while prompt refusal is enforced at the boundary
|
|
3029
|
-
(`test/
|
|
3111
|
+
(`test/cancellation-faults.test.ts`, `test/operation-cancellation.test.ts`
|
|
3112
|
+
and `test/cancellation-journey.node.test.ts`). Invocation owns
|
|
3030
3113
|
the recovery and logical-call records it reads after teardown. Closing an
|
|
3031
3114
|
outer call also revokes nested calls paused in preparation. Request-owned
|
|
3032
3115
|
MCP sessions and token flights outlive individual calls and close with the
|
|
@@ -3119,8 +3202,9 @@ compiling and configuring the real thing.
|
|
|
3119
3202
|
at construction) and the predicate matched, which the ledger records on the
|
|
3120
3203
|
request. Only Stripe declares it (`src/providers/stripe/api.ts`, reviewed
|
|
3121
3204
|
as a `manual` check in its `drift.json`): an API v1 answer carrying Stripe's
|
|
3122
|
-
`Request-Id`.
|
|
3123
|
-
|
|
3205
|
+
`Request-Id`. The real HTTP hostile-response journey checks this refusal
|
|
3206
|
+
against an ambiguous committed write; there is no copied declaration list.
|
|
3207
|
+
Q8 is decided in one place, `settleWrite` in
|
|
3124
3208
|
`src/write-outcome.ts`, once per logical call and over every request it
|
|
3125
3209
|
recorded. The invocation calls it for every failure of a served write: a
|
|
3126
3210
|
thrown or mapped error, a custom connector's, a program's call, and its
|
|
@@ -3369,29 +3453,17 @@ compiling and configuring the real thing.
|
|
|
3369
3453
|
`write_outcome_unknown`. The caller's own abort reason still passes by
|
|
3370
3454
|
identity for a read and for a served call, whose timeout passes through
|
|
3371
3455
|
unchanged for the invocation to report.
|
|
3372
|
-
|
|
3373
|
-
|
|
3374
|
-
|
|
3375
|
-
|
|
3376
|
-
|
|
3377
|
-
|
|
3378
|
-
|
|
3379
|
-
|
|
3380
|
-
|
|
3381
|
-
|
|
3382
|
-
|
|
3383
|
-
composite success followed by refusal, GitHub preflight failures, typed
|
|
3384
|
-
handler errors after successful sends, Forms cursor conflicts after 200,
|
|
3385
|
-
generic-code vendor refusals, auxiliary failures after resource dispatch,
|
|
3386
|
-
redaction of refusal errors, and concurrent direct-call ledger isolation.
|
|
3387
|
-
The round-6 cases cover a composite write's early refusal while siblings
|
|
3388
|
-
await credentials or are in flight, requests started after the call ended,
|
|
3389
|
-
connect-phase errnos with each body kind (all unknown for a write, and a
|
|
3390
|
-
direct read stays retryable), a request aborted with a refusal-shaped
|
|
3391
|
-
reason, an errno outside fetch's network error, and
|
|
3392
|
-
undeclared handlers whose untracked send precedes a typed failure. Each
|
|
3393
|
-
catalog case also checks that the ledger recorded every resource request
|
|
3394
|
-
the network saw, and the inventory that every API connector declares it.
|
|
3456
|
+
Shared provider outcomes and the real HTTP hostile-response journey check
|
|
3457
|
+
returned data, failure/recovery, privacy and physical writes without a
|
|
3458
|
+
catalog-wide status matrix. `test/provider-failure-sweep.test.ts` retains
|
|
3459
|
+
fault probes for Docs creation with initial text, composite success followed
|
|
3460
|
+
by refusal, GitHub preflight failures, typed handler errors after successful
|
|
3461
|
+
sends, Forms cursor conflicts after 200, generic-code vendor refusals,
|
|
3462
|
+
auxiliary failures after resource dispatch and concurrent direct-call isolation.
|
|
3463
|
+
It also holds siblings awaiting credentials or already in flight when another
|
|
3464
|
+
write fails, refuses requests after call closure, and probes network errors,
|
|
3465
|
+
refusal-shaped abort reasons and untracked sends. Native transport and
|
|
3466
|
+
request-lifetime suites retain their platform-specific evidence.
|
|
3395
3467
|
`test/write-evidence.test.ts` uses real refused, reset, and held sockets on
|
|
3396
3468
|
both runtimes: a refused write is unknown and a refused read retryable,
|
|
3397
3469
|
including a write aborted with another fetch's real refusal as its reason
|