@zackbart/connecta 0.12.2 → 0.14.0
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 +324 -0
- package/README.md +4 -1
- package/dist/catalog-service.d.ts +41 -0
- package/dist/catalog-service.d.ts.map +1 -1
- package/dist/catalog-service.js +127 -11
- package/dist/catalog-service.js.map +1 -1
- package/dist/connectors/api.d.ts +5 -4
- package/dist/connectors/api.d.ts.map +1 -1
- package/dist/connectors/api.js +5 -1
- package/dist/connectors/api.js.map +1 -1
- package/dist/connectors/remote-mcp.d.ts +5 -4
- package/dist/connectors/remote-mcp.d.ts.map +1 -1
- package/dist/connectors/remote-mcp.js.map +1 -1
- package/dist/execute.d.ts.map +1 -1
- package/dist/execute.js +12 -10
- package/dist/execute.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/meta-tools.d.ts.map +1 -1
- package/dist/meta-tools.js +5 -4
- package/dist/meta-tools.js.map +1 -1
- package/dist/providers/cloudflare.d.ts +53 -0
- package/dist/providers/cloudflare.d.ts.map +1 -0
- package/dist/providers/cloudflare.js +1385 -0
- package/dist/providers/cloudflare.js.map +1 -0
- package/dist/providers/linear.d.ts +44 -0
- package/dist/providers/linear.d.ts.map +1 -0
- package/dist/providers/linear.js +243 -0
- package/dist/providers/linear.js.map +1 -0
- package/dist/providers/mixpanel.d.ts +21 -0
- package/dist/providers/mixpanel.d.ts.map +1 -0
- package/dist/providers/mixpanel.js +191 -0
- package/dist/providers/mixpanel.js.map +1 -0
- package/dist/providers/notion.d.ts +39 -0
- package/dist/providers/notion.d.ts.map +1 -0
- package/dist/providers/notion.js +1625 -0
- package/dist/providers/notion.js.map +1 -0
- package/dist/providers/stripe.d.ts +37 -0
- package/dist/providers/stripe.d.ts.map +1 -0
- package/dist/providers/stripe.js +232 -0
- package/dist/providers/stripe.js.map +1 -0
- package/dist/skills.d.ts +7 -9
- package/dist/skills.d.ts.map +1 -1
- package/dist/skills.js +58 -24
- package/dist/skills.js.map +1 -1
- package/dist/types.d.ts +26 -6
- package/dist/types.d.ts.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/documentation/cloudflare.md +268 -0
- package/documentation/code-mode.md +6 -6
- package/documentation/connectors.md +122 -4
- package/documentation/linear.md +144 -0
- package/documentation/meta-tools.md +91 -8
- package/documentation/mixpanel.md +77 -0
- package/documentation/notion.md +233 -0
- package/documentation/stripe.md +202 -0
- package/ethos.md +8 -3
- package/package.json +21 -1
- package/src/catalog-service.ts +174 -10
- package/src/connectors/api.ts +10 -4
- package/src/connectors/remote-mcp.ts +5 -3
- package/src/execute.ts +18 -10
- package/src/index.ts +1 -0
- package/src/meta-tools.ts +10 -4
- package/src/providers/cloudflare.ts +1696 -0
- package/src/providers/linear.ts +301 -0
- package/src/providers/mixpanel.ts +228 -0
- package/src/providers/notion.ts +1879 -0
- package/src/providers/stripe.ts +306 -0
- package/src/skills.ts +64 -23
- package/src/types.ts +27 -6
- package/src/version.ts +1 -1
- package/templates/node/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,330 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this package are documented here.
|
|
4
4
|
|
|
5
|
+
## 0.14.0 — 2026-08-03
|
|
6
|
+
|
|
7
|
+
Connecta went from one maintained prebuilt connection to five. Stripe, Linear,
|
|
8
|
+
Notion, and Cloudflare join Mixpanel behind `./providers/<name>`, and together
|
|
9
|
+
they answer the question the Mixpanel connection left open: whether a
|
|
10
|
+
maintained connection means anything more specific than a wrapper. Stripe and
|
|
11
|
+
Linear proxy hosted MCP servers and spend their effort on what a transport
|
|
12
|
+
cannot say — Stripe makes production-versus-sandbox a required declaration with
|
|
13
|
+
no default and refuses a deployment whose API key contradicts it; Linear
|
|
14
|
+
selects a read-only *endpoint* whose token cannot reach a write API, which is a
|
|
15
|
+
stronger guarantee than any annotation. Notion and Cloudflare are hand-written
|
|
16
|
+
`api()` surfaces, and they exist because shape is the problem rather than
|
|
17
|
+
transport: a Notion page is tens of kilobytes of discriminated wrappers and
|
|
18
|
+
rich-text runs around a few hundred bytes of meaning, and a generated
|
|
19
|
+
Cloudflare wrapper exposed `arguments?: {}[]` in its compact schema and pushed
|
|
20
|
+
the real parameter list into a documentation page an agent had to read before
|
|
21
|
+
it could call anything. Fifteen and fourteen deliberate tools respectively,
|
|
22
|
+
projected down to ids and plain values, with `raw: true` wherever the dropped
|
|
23
|
+
detail can matter. None of the four adds a dependency — not to core, not as an
|
|
24
|
+
optional peer, not in `devDependencies`. The whole set installs with nothing
|
|
25
|
+
extra and none of it is reachable from the root entry.
|
|
26
|
+
|
|
27
|
+
Nothing breaks. Every export is additive and lives behind its own subpath, no
|
|
28
|
+
existing signature moved, and a deployment that configures none of the new
|
|
29
|
+
providers can upgrade with a version bump and read no further. Two changes are
|
|
30
|
+
worth knowing about anyway. Vetted annotations on a prebuilt connection no
|
|
31
|
+
longer argue with an explicit downstream annotation in *either* direction: a
|
|
32
|
+
name the downstream explicitly marks `readOnlyHint: true` that no release has
|
|
33
|
+
classified now stays callable from `execute_code` instead of failing closed
|
|
34
|
+
onto the approval path. Silence on an unclassified name still means not
|
|
35
|
+
read-only, so catalog drift is unaffected — this only moves names the
|
|
36
|
+
downstream actually spoke about. The one branch that still outranks the
|
|
37
|
+
downstream is a name a release reviewed and filed destructive: a
|
|
38
|
+
`Delete-Dashboard` arriving with `readOnlyHint: true` is a downstream bug
|
|
39
|
+
rather than news, and stays behind `call_destructive_tool`. That asymmetry is
|
|
40
|
+
deliberate for now and tracked as an open question (#315). The other change is
|
|
41
|
+
text: the `execute_code` code-parameter description gained a sentence about not
|
|
42
|
+
aborting on a missing tool match or result key. Everything in `eval/` is
|
|
43
|
+
internal and ships in no package (#295, #297, #303, #306, #310, PRs #305–#317).
|
|
44
|
+
|
|
45
|
+
### Added
|
|
46
|
+
|
|
47
|
+
- **A maintained Stripe connection at `./providers/stripe`.** `stripe(id, {
|
|
48
|
+
mode, purpose, title?, auth?, connectedAccount?, instructions?,
|
|
49
|
+
maxResultBytes? })` proxies Stripe's hosted MCP server at
|
|
50
|
+
`https://mcp.stripe.com/` over HTTPS, OAuth by default and static headers for
|
|
51
|
+
restricted API keys. `mode` is `"production" | "sandbox"` with **no default**,
|
|
52
|
+
because there is no safe guess between an account that moves real money and
|
|
53
|
+
one that does not. Stripe publishes one endpoint and selects the environment
|
|
54
|
+
by credential, so the mode cannot be routed — instead it is made impossible to
|
|
55
|
+
miss, appearing in the default title, in the description `search_tools` ranks,
|
|
56
|
+
in the first two lines of the guide, and in the admission policy (production
|
|
57
|
+
100 calls/second at concurrency 8; sandbox 25 at 4). A `headers` credential
|
|
58
|
+
carrying a recognizable key prefix (`sk_`, `rk_`, or `pk_` with `_live_` or
|
|
59
|
+
`_test_`) that contradicts the declared mode throws at construction; an OAuth
|
|
60
|
+
connector or an unrecognized credential shape is left alone rather than
|
|
61
|
+
guessed at, and the error names only the two modes, never the key.
|
|
62
|
+
`connectedAccount` requires an `acct_` id and headers auth. Seven reads and
|
|
63
|
+
four writes are vetted fill-in-only.
|
|
64
|
+
- **A maintained Linear connection at `./providers/linear`.** `linear(id, {
|
|
65
|
+
purpose, access?, title?, auth?, instructions?, maxResultBytes?,
|
|
66
|
+
callAdmission? })` proxies Linear's hosted MCP server, with `access` selecting
|
|
67
|
+
the endpoint: `"read-write"` (default) at `https://mcp.linear.app/mcp` with
|
|
68
|
+
the `read` and `write` scopes, `"read-only"` at
|
|
69
|
+
`https://mcp.linear.app/mcp/readonly` with `read` alone. Read-only is not a
|
|
70
|
+
client-side filter — the token minted for that endpoint cannot reach Linear's
|
|
71
|
+
write APIs at all. The mode is legible at browse time rather than only after
|
|
72
|
+
the guide is fetched: a read-only connection titles itself `Linear
|
|
73
|
+
(read-only)` and its guide opens with the access note, which is what discovery
|
|
74
|
+
summarizes. The deprecated `/sse` transport is deliberately unreachable. No
|
|
75
|
+
admission policy is imposed by default, because Linear's published limit is
|
|
76
|
+
per user per hour and varies by credential type while Connecta's counter is
|
|
77
|
+
per runtime; a deployment that knows its own ceiling can pass `callAdmission`.
|
|
78
|
+
The read allowlist is a deliberate superset of any one workspace, since
|
|
79
|
+
several tools are plan-gated. Every `save_*` is filed destructive — they are
|
|
80
|
+
upserts.
|
|
81
|
+
- **A maintained Notion connection at `./providers/notion`.** `notion(id, {
|
|
82
|
+
purpose, title?, instructions?, credentialLabel?, defaultPageSize?,
|
|
83
|
+
maxResultBytes? })` is the first prebuilt connection built on `api()` rather
|
|
84
|
+
than `remoteMcp()`: fifteen hand-written tools over `api.notion.com` pinned to
|
|
85
|
+
`Notion-Version: 2026-03-11` with no override, because that is the version in
|
|
86
|
+
which databases split into data sources, `archived` became `in_trash`, and
|
|
87
|
+
block append took a `position` object — an older pin would return quietly
|
|
88
|
+
wrong results rather than fail loudly. Ten reads carry `readOnlyHint: true`;
|
|
89
|
+
five writes route through `call_destructive_tool`, with `destructiveHint`
|
|
90
|
+
reserved for the two that replace or remove existing state.
|
|
91
|
+
`update_page_properties` has no `in_trash` argument, so an update can never
|
|
92
|
+
trash a page; `trash_page` is its own named and reversible tool. Lean
|
|
93
|
+
projections are the headline — properties flattened, rich text reduced to
|
|
94
|
+
plain strings, `search` dropping properties entirely, `get_page` reporting
|
|
95
|
+
what Notion truncated at 25 references — and seven reads take `raw: true` to
|
|
96
|
+
return the untouched payload where the dropped detail matters. Errors map to
|
|
97
|
+
what the caller should do next: 403 is deliberately not `auth_required`,
|
|
98
|
+
because re-authorizing cannot grant a capability or share a page, and 404 says
|
|
99
|
+
out loud that Notion returns it both for a missing object and an unshared one.
|
|
100
|
+
Admission pairs a 180-per-minute rolling budget with `maxConcurrency: 3`,
|
|
101
|
+
because a budget alone is an average and an average cannot stop a program
|
|
102
|
+
firing forty calls in one tick. Its guide is the only one of the four marked
|
|
103
|
+
`required`.
|
|
104
|
+
- **A maintained Cloudflare connection at `./providers/cloudflare`.**
|
|
105
|
+
`cloudflare(id, { purpose, title?, accountId?, zoneId?, baseUrl?,
|
|
106
|
+
credential?, instructions?, maxResultBytes?, maxConcurrency? })` is fourteen
|
|
107
|
+
hand-written tools over the v4 REST API, fetch-native and dependency-free:
|
|
108
|
+
Cloudflare publishes an official SDK and this connection does not use it,
|
|
109
|
+
because the SDK's typed wrappers and pagination helpers are exactly what a
|
|
110
|
+
projected result and a `page.hasMore` boolean replace. `test/package-surface.test.ts`
|
|
111
|
+
pins the claim — the `cloudflare` package must appear in no dependency list at
|
|
112
|
+
all, and every import in the provider must be relative. Every tool carries a
|
|
113
|
+
complete closed schema: `additionalProperties: false`, an accurate `required`
|
|
114
|
+
list, an `enum` on every constrained field, a description on every property
|
|
115
|
+
(asserted, not claimed), and per-endpoint `perPage` bounds. Because
|
|
116
|
+
`strictValidation` refuses an out-of-range page size locally, the schemas
|
|
117
|
+
record *whose* bound is being enforced and the descriptions say so out loud:
|
|
118
|
+
Cloudflare's own where documented, this connection's cap where Cloudflare's
|
|
119
|
+
nominal ceiling is unusable (`list_dns_records` caps at 1,000 against a
|
|
120
|
+
documented 5,000,000), and this connection's entirely where Cloudflare
|
|
121
|
+
documents none (`list_pages_projects`). Twenty-one DNS record types are
|
|
122
|
+
exported as `CLOUDFLARE_DNS_RECORD_TYPES`. Admission mirrors the documented
|
|
123
|
+
1,200-per-five-minutes with a default concurrency of 6.
|
|
124
|
+
|
|
125
|
+
### Changed
|
|
126
|
+
|
|
127
|
+
- **Explicit downstream annotations win in both directions.** A prebuilt
|
|
128
|
+
connection's vetted classification was already fill-in only against a
|
|
129
|
+
downstream saying a name is *less* safe than the allowlist claims. It now also
|
|
130
|
+
yields to a downstream saying a name is safe when no release has classified
|
|
131
|
+
that name at all: an explicit `readOnlyHint: true` on an unreviewed tool is
|
|
132
|
+
kept, and the tool stays callable from `execute_code`. On a name no release
|
|
133
|
+
has reviewed, the downstream's word is the only evidence there is. Silence
|
|
134
|
+
still means not read-only, so catalog drift fails closed exactly as before,
|
|
135
|
+
and a name a release reviewed and filed destructive still outranks a
|
|
136
|
+
downstream `readOnlyHint: true` — an open question rather than a settled
|
|
137
|
+
invariant (#315). Mixpanel deployments are the ones that can observe this
|
|
138
|
+
today: a tool Mixpanel explicitly annotates read-only that this release's
|
|
139
|
+
allowlist has never seen moves off the approval path.
|
|
140
|
+
- **`execute_code` tells a program not to abort on a missing key.** The code
|
|
141
|
+
parameter's description gained: "So does aborting on a missing tool match or
|
|
142
|
+
result key — re-search, describe, or read the result's actual keys here
|
|
143
|
+
instead." The eval lane that motivated it measures whether a program shapes
|
|
144
|
+
its result in the run that produced it rather than returning catalog data for
|
|
145
|
+
a later call.
|
|
146
|
+
- **`documentation/` gained a guide per maintained connection** — `stripe.md`,
|
|
147
|
+
`linear.md`, `notion.md`, `cloudflare.md` — and `connectors.md` now lists all
|
|
148
|
+
five. Its custom-`remoteMcp()` example moved off Linear to an in-house deploy
|
|
149
|
+
server, as did the Docker example's OAuth demo, since Linear is now a prebuilt
|
|
150
|
+
connection rather than an illustration of hand-writing one.
|
|
151
|
+
|
|
152
|
+
### Fixed
|
|
153
|
+
|
|
154
|
+
- **`api()` connectors await their handlers.** `callTool` returned the handler's
|
|
155
|
+
promise without awaiting it, so a handler that threw before its first `await`
|
|
156
|
+
sat handler-less through the thenable-adoption microtask and was reported as
|
|
157
|
+
an unhandled rejection by workerd and vitest even though the caller caught the
|
|
158
|
+
typed failure. It is now a caught typed failure and nothing else. Affects
|
|
159
|
+
every `api()` connector, hand-written or prebuilt.
|
|
160
|
+
- **An empty-query browse of an unavailable catalog says so.** A browse has no
|
|
161
|
+
terms to analyze and so reported nothing at all, which was indistinguishable
|
|
162
|
+
from a connector that simply exposes no tools — while the guidance on a scoped
|
|
163
|
+
miss recommends exactly that browse. A browse scoped to an unavailable
|
|
164
|
+
connector now carries `unavailableConnectorCount`, the typed `catalogError`,
|
|
165
|
+
and guidance naming it; an unscoped browse carries the count and a
|
|
166
|
+
scope-by-connector pointer but no `catalogError`, because one connector's
|
|
167
|
+
failure is not another browse's context. A configured connector that
|
|
168
|
+
correctly exposes no tools still reports no analysis, so empty, unavailable,
|
|
169
|
+
and unknown do not serialize alike.
|
|
170
|
+
- **An empty-query browse of an unknown connector reports the unknown
|
|
171
|
+
connector.** A browse scoped to an id that is not configured now returns
|
|
172
|
+
`connectorScope`, `unknownConnector`, and the same omit-the-connector guidance
|
|
173
|
+
the term-bearing path already gave. Nothing was attempted, so there is no
|
|
174
|
+
count and no `catalogError`, and the response names no connector but the one
|
|
175
|
+
the caller supplied — listing what else is configured would answer a question
|
|
176
|
+
they did not ask, past a filter they may not pass.
|
|
177
|
+
|
|
178
|
+
### Internal
|
|
179
|
+
|
|
180
|
+
- **A reference-connection lane in `eval/`.** Six cases — discovery, a simple
|
|
181
|
+
read, a dependent reduction, invalid arguments, an unavailable credential, and
|
|
182
|
+
write routing — run a cold agent against a second isolated deployment whose
|
|
183
|
+
`cloudflare()` connector is the real constructor with only the network
|
|
184
|
+
doubled, reached through the already-documented `baseUrl`. Schemas,
|
|
185
|
+
`strictValidation`, annotations, projections, admission, guide, and error
|
|
186
|
+
mapping are the shipped ones, and credentials go through the real vault; no
|
|
187
|
+
product surface was added for the benchmark. Write routing is the only case
|
|
188
|
+
permitted across the destructive boundary, and the fixture exposes a
|
|
189
|
+
downstream-effects endpoint as independent evidence. `eval/` is not in the
|
|
190
|
+
published `files` allowlist; deployments never see it.
|
|
191
|
+
|
|
192
|
+
## 0.13.0 — 2026-08-03
|
|
193
|
+
|
|
194
|
+
Everything an agent reads before it calls anything got more selective. Connecta
|
|
195
|
+
ships its first maintained prebuilt connection — `mixpanel()` behind
|
|
196
|
+
`./providers/mixpanel`, one import returning one ordinary `Connector` with the
|
|
197
|
+
provider's endpoint, region, auth, and rate-limit defaults already right — and
|
|
198
|
+
the ethos now names a maintained prebuilt connection the preferred authoring
|
|
199
|
+
path, with `remoteMcp()` and `api()` staying equal first-class primitives for
|
|
200
|
+
everything nobody maintains. Connector guides became structured: a guide can
|
|
201
|
+
declare a bounded `summary` and mark itself `required`, and discovery carries
|
|
202
|
+
`guideSummary` with `guideRequired`/`guideRequiredReasons`, so an agent fetches
|
|
203
|
+
a guide when it changes the call and skips it when a complete read-only schema
|
|
204
|
+
already says everything. A connector-scoped search whose catalog is down now
|
|
205
|
+
returns a typed `catalogError` instead of advice to retry later. And the tool
|
|
206
|
+
descriptions stopped inviting the two failures the new cold-agent benchmark
|
|
207
|
+
kept catching: a top-level search that duplicates the one the program was about
|
|
208
|
+
to run, and a program guessing at a result shape it never read.
|
|
209
|
+
|
|
210
|
+
No API breaks. `usageGuide` still accepts a plain markdown string and means
|
|
211
|
+
exactly what it did; every new discovery field is additive and absent unless
|
|
212
|
+
earned. What changed under existing deployments is text, and it is worth
|
|
213
|
+
knowing about: the served tool descriptions and the MCP `instructions` string
|
|
214
|
+
are rewritten, and `skills({})` now summarizes a connector guide from its first
|
|
215
|
+
body line rather than its heading — a guide opening `# Acme` that used to list
|
|
216
|
+
as "Acme" now lists as the sentence beneath it. The built-in usage skill also
|
|
217
|
+
grew, because the per-connector guides section is now appended unconditionally
|
|
218
|
+
rather than only where a guide exists; that keeps the shared guide
|
|
219
|
+
byte-identical across every deployment, so an agent that read it once in a task
|
|
220
|
+
never needs a second local copy, at the cost of one paragraph in deployments
|
|
221
|
+
with no guides. Upgrading is a version bump and nothing else — there is no new
|
|
222
|
+
configuration, no new dependency, and no behavior a deployment must opt into
|
|
223
|
+
(#294, #295, #296, #297, PRs #298–#302).
|
|
224
|
+
|
|
225
|
+
### Added
|
|
226
|
+
|
|
227
|
+
- **A maintained Mixpanel connection at `./providers/mixpanel`.**
|
|
228
|
+
`mixpanel(id, { purpose, region?, auth?, instructions?, title?,
|
|
229
|
+
maxResultBytes? })` proxies Mixpanel's hosted MCP server with the endpoint
|
|
230
|
+
chosen by data residency (`us`, `eu`, `in`, default `us`), OAuth by default
|
|
231
|
+
and static headers for service accounts, HTTPS required, and a rolling
|
|
232
|
+
600-calls-per-hour admission budget matching the provider's published limit.
|
|
233
|
+
It carries a maintained usage guide — start at `Get-Projects`, then
|
|
234
|
+
`Get-Business-Context`; discover names instead of guessing spellings; fetch
|
|
235
|
+
`Get-Query-Schema` before `Run-Query` — to which a deployment may append its
|
|
236
|
+
own account instructions. The subpath is an optional import, not a
|
|
237
|
+
dependency: nothing new installs with core.
|
|
238
|
+
- **Fill-in-only vetted safety annotations.** The connection classifies 63
|
|
239
|
+
Mixpanel tools — 35 read-only, 28 writes split into additive creates and
|
|
240
|
+
destructive edits — but only where the downstream is silent. An explicit
|
|
241
|
+
`destructiveHint: true` or `readOnlyHint: false` from Mixpanel on an
|
|
242
|
+
allowlisted read name wins, because that is the downstream saying this
|
|
243
|
+
release's allowlist is wrong. Tools this release has never seen fail closed
|
|
244
|
+
to approval-visible rather than being assumed safe.
|
|
245
|
+
- **`ConnectorUsageGuide`.** A connector may now declare
|
|
246
|
+
`usageGuide: { content, summary?, required? }` instead of a bare string.
|
|
247
|
+
`summary` is the bounded line discovery shows; `required: true` says correct
|
|
248
|
+
use always depends on conventions no tool schema can carry. Mutations and
|
|
249
|
+
truncated schemas already require review and do not need the flag.
|
|
250
|
+
- **`guideSummary`, `guideRequired`, and `guideRequiredReasons` on discovery.**
|
|
251
|
+
`search_tools`, `connecta.search`, and `connecta.describe` now say what a
|
|
252
|
+
guide covers and whether it must be read first, with the reason named:
|
|
253
|
+
`connector_required` and `approval_required` stand however far a schema is
|
|
254
|
+
expanded, while `schema_truncated` clears once describe returns the exact
|
|
255
|
+
shape. A connector-scoped search that matches nothing still surfaces the
|
|
256
|
+
connector's guide, so an agent that searched the wrong terms learns the
|
|
257
|
+
vocabulary instead of concluding the connector is empty.
|
|
258
|
+
- **A scoped `catalogError`.** A search explicitly scoped to one connector
|
|
259
|
+
whose catalog is unavailable now returns the classified failure — `code`,
|
|
260
|
+
bounded `message`, `retryable`, and `retryAfterMs` when known — so an agent
|
|
261
|
+
can tell a transient outage from one an operator has to clear. Exactly four
|
|
262
|
+
fields, pinned by a test: an unscoped search still gets only
|
|
263
|
+
`unavailableConnectorCount`, because one connector's failure is not another
|
|
264
|
+
search's context.
|
|
265
|
+
|
|
266
|
+
### Changed
|
|
267
|
+
|
|
268
|
+
- **Routing guidance no longer invites redundant discovery.** Top-level
|
|
269
|
+
`search_tools` is now reserved for a single unreduced read or for
|
|
270
|
+
write-capable work; anything involving reduction, dependent steps, loops, or
|
|
271
|
+
joins is one `execute_code` program that searches and calls inside the run.
|
|
272
|
+
Search guidance also tells an agent to scope to an obvious connector id and
|
|
273
|
+
to require purpose, input, truncation, safety, and output fit rather than
|
|
274
|
+
taking the first lexical match. Measured against the shipped text over five
|
|
275
|
+
repetitions, route compliance went from 9/30 to 25/30.
|
|
276
|
+
- **`call_destructive_tool` carries the guide note.** Destructive multi-step
|
|
277
|
+
work keeps its route through top-level discovery — `execute_code` admits only
|
|
278
|
+
read-only tools — and its description now says to inspect the address and
|
|
279
|
+
fetch any guide it names before a consequential call.
|
|
280
|
+
- **The ethos prefers prebuilt connections, and refuses a registry.** The
|
|
281
|
+
decisions table accepts prebuilt connections as the preferred authoring path
|
|
282
|
+
*when connecta maintains one*, fenced: exactly one ordinary `Connector` with
|
|
283
|
+
no extra privileges, never a bundle or preset, tools hand-written or proxied
|
|
284
|
+
rather than generated from a schema document, and vetted annotations that
|
|
285
|
+
only fill in downstream silence. A provider registry or integration
|
|
286
|
+
marketplace is refused outright — prebuilt connections are imports, not
|
|
287
|
+
listings, and discovery happens in documentation, never at runtime.
|
|
288
|
+
- **The usage skill is byte-identical everywhere.** The per-connector guides
|
|
289
|
+
section is appended unconditionally and rewritten to route on
|
|
290
|
+
`guideRequired`/`guideSummary` rather than telling agents to read every
|
|
291
|
+
guide before first use. Guide-free deployments still pay no fixed
|
|
292
|
+
tool-description cost — the conditional notes in the meta-tool descriptions
|
|
293
|
+
remain absent.
|
|
294
|
+
- **Guide summaries prefer substance over headings.** `skills({})` reads a
|
|
295
|
+
guide's first meaningful body line, falling back to the heading and then to
|
|
296
|
+
the connector description, so a listing describes what a guide says rather
|
|
297
|
+
than what it is titled.
|
|
298
|
+
|
|
299
|
+
### Fixed
|
|
300
|
+
|
|
301
|
+
- **The Mixpanel connection could not have booted.** Its call-admission rule
|
|
302
|
+
paired a budget with `retryAfterMs` — a queue setting without a queue, which
|
|
303
|
+
the admission controller refuses at construction. No suite caught it because
|
|
304
|
+
every suite stubbed remote-MCP before the registry saw the connector; a new
|
|
305
|
+
suite now boots two accounts through the real `createConnecta` with `fetch`
|
|
306
|
+
rigged to throw, proving the boot and the per-account address, catalog,
|
|
307
|
+
storage, credential, and budget namespaces.
|
|
308
|
+
- **Tool descriptions claimed a waiver describe already performs.** Three
|
|
309
|
+
descriptions said schema expansion never clears a guide requirement while
|
|
310
|
+
`describe` cleared `schema_truncated` on every call. The text moved to the
|
|
311
|
+
behavior rather than the reverse.
|
|
312
|
+
- **Package-surface guards derive from `src/providers/`** instead of naming
|
|
313
|
+
`mixpanel.ts`, so the next provider fails them only for a real reason.
|
|
314
|
+
|
|
315
|
+
### Internal
|
|
316
|
+
|
|
317
|
+
- **A cold-agent benchmark lane in `eval/`.** Fourteen cases across two lanes —
|
|
318
|
+
eight measuring whether an agent meeting a connector cold discovers, routes,
|
|
319
|
+
and recovers, six measuring route compliance for the description rewrite —
|
|
320
|
+
with a comparator that refuses to compare runs whose harness, scoring, or
|
|
321
|
+
sandbox fingerprints differ, and reports a `productSha256` over `src/**`. A
|
|
322
|
+
baseline and a candidate cut from one working tree record the same commit and
|
|
323
|
+
the same dirty flag, and only the fingerprint says whether the candidate
|
|
324
|
+
measured changed code. It also reports host-routing probes separately from
|
|
325
|
+
foreign calls, so a contaminated run announces itself instead of reading as a
|
|
326
|
+
product regression. `eval/` is not in the published `files` list; deployments
|
|
327
|
+
never see it.
|
|
328
|
+
|
|
5
329
|
## 0.12.2 — 2026-08-02
|
|
6
330
|
|
|
7
331
|
Rendered programs can now bind a small, explicit set of read-only connector
|
package/README.md
CHANGED
|
@@ -72,7 +72,10 @@ For an agent setting this up, the contract is:
|
|
|
72
72
|
2. Keep the required `executor: quickJsExecutor()` configuration; without an
|
|
73
73
|
executor the deployment refuses to boot.
|
|
74
74
|
3. Keep secrets in environment variables or a secret store, never source.
|
|
75
|
-
4. Add
|
|
75
|
+
4. Add connectors explicitly: import a maintained prebuilt provider
|
|
76
|
+
constructor when one exists, otherwise write a deliberate `remoteMcp()` or
|
|
77
|
+
`api()` connector. There is no registry to browse and nothing registers
|
|
78
|
+
itself.
|
|
76
79
|
5. Run `npm run typecheck`, start the server, and run
|
|
77
80
|
`CONNECTA_TOKEN=... npm run doctor`. Doctor checks health, the executor, and
|
|
78
81
|
the exact seven-tool model-facing surface, then executes a harmless sandbox
|
|
@@ -41,6 +41,7 @@ export interface CatalogDescribeArgs {
|
|
|
41
41
|
interface CatalogSearchEntry {
|
|
42
42
|
connector: Connector;
|
|
43
43
|
guide?: string;
|
|
44
|
+
guideSummary?: string;
|
|
44
45
|
tool: {
|
|
45
46
|
name: string;
|
|
46
47
|
address: string;
|
|
@@ -53,8 +54,23 @@ interface CatalogSearchEntry {
|
|
|
53
54
|
requiredInputKeys?: string[];
|
|
54
55
|
outputKeys?: string[];
|
|
55
56
|
annotations?: ToolDef["annotations"];
|
|
57
|
+
guideRequired?: true;
|
|
58
|
+
guideRequiredReasons?: GuideRequiredReason[];
|
|
56
59
|
};
|
|
57
60
|
}
|
|
61
|
+
type GuideRequiredReason = "connector_required" | "approval_required" | "schema_truncated";
|
|
62
|
+
/**
|
|
63
|
+
* The classified-failure subset a scoped search may echo: enough to tell a
|
|
64
|
+
* transient outage from one an operator must clear, and nothing more. Kept as
|
|
65
|
+
* its own type rather than `CallErrorDetails` so widening the call-path
|
|
66
|
+
* classifier cannot widen this discovery-surface field by accident.
|
|
67
|
+
*/
|
|
68
|
+
interface CatalogFailureDetail {
|
|
69
|
+
code: string;
|
|
70
|
+
message: string;
|
|
71
|
+
retryable: boolean;
|
|
72
|
+
retryAfterMs?: number;
|
|
73
|
+
}
|
|
58
74
|
export interface CatalogSearchPage {
|
|
59
75
|
entries: CatalogSearchEntry[];
|
|
60
76
|
total: number;
|
|
@@ -71,6 +87,12 @@ export interface CatalogSearchPage {
|
|
|
71
87
|
connectorScope?: string;
|
|
72
88
|
unknownConnector?: true;
|
|
73
89
|
unavailableConnectorCount?: number;
|
|
90
|
+
/** Bounded typed failure for an explicitly scoped unavailable catalog. */
|
|
91
|
+
catalogError?: CatalogFailureDetail;
|
|
92
|
+
guide?: string;
|
|
93
|
+
guideSummary?: string;
|
|
94
|
+
guideRequired?: true;
|
|
95
|
+
guideRequiredReasons?: GuideRequiredReason[];
|
|
74
96
|
guidance?: string;
|
|
75
97
|
};
|
|
76
98
|
}
|
|
@@ -79,6 +101,9 @@ export interface CatalogDescription {
|
|
|
79
101
|
name?: string;
|
|
80
102
|
description?: string;
|
|
81
103
|
guide?: string;
|
|
104
|
+
guideSummary?: string;
|
|
105
|
+
guideRequired?: true;
|
|
106
|
+
guideRequiredReasons?: GuideRequiredReason[];
|
|
82
107
|
inputSchema?: unknown;
|
|
83
108
|
outputSchema?: unknown;
|
|
84
109
|
annotations?: ToolDef["annotations"];
|
|
@@ -158,6 +183,12 @@ export declare function groupedSearchResult(page: CatalogSearchPage): {
|
|
|
158
183
|
connectorScope?: string;
|
|
159
184
|
unknownConnector?: true;
|
|
160
185
|
unavailableConnectorCount?: number;
|
|
186
|
+
/** Bounded typed failure for an explicitly scoped unavailable catalog. */
|
|
187
|
+
catalogError?: CatalogFailureDetail;
|
|
188
|
+
guide?: string;
|
|
189
|
+
guideSummary?: string;
|
|
190
|
+
guideRequired?: true;
|
|
191
|
+
guideRequiredReasons?: GuideRequiredReason[];
|
|
161
192
|
guidance?: string;
|
|
162
193
|
};
|
|
163
194
|
matchMode?: "partial";
|
|
@@ -166,6 +197,7 @@ export declare function groupedSearchResult(page: CatalogSearchPage): {
|
|
|
166
197
|
id: string;
|
|
167
198
|
title?: string;
|
|
168
199
|
guide?: string;
|
|
200
|
+
guideSummary?: string;
|
|
169
201
|
tools: CatalogSearchEntry["tool"][];
|
|
170
202
|
}[];
|
|
171
203
|
total: number;
|
|
@@ -182,11 +214,18 @@ export declare function flatSearchResult(page: CatalogSearchPage): {
|
|
|
182
214
|
connectorScope?: string;
|
|
183
215
|
unknownConnector?: true;
|
|
184
216
|
unavailableConnectorCount?: number;
|
|
217
|
+
/** Bounded typed failure for an explicitly scoped unavailable catalog. */
|
|
218
|
+
catalogError?: CatalogFailureDetail;
|
|
219
|
+
guide?: string;
|
|
220
|
+
guideSummary?: string;
|
|
221
|
+
guideRequired?: true;
|
|
222
|
+
guideRequiredReasons?: GuideRequiredReason[];
|
|
185
223
|
guidance?: string;
|
|
186
224
|
};
|
|
187
225
|
matchMode?: "partial";
|
|
188
226
|
nextOffset?: number;
|
|
189
227
|
tools: {
|
|
228
|
+
guideSummary?: string;
|
|
190
229
|
guide?: string;
|
|
191
230
|
name: string;
|
|
192
231
|
address: string;
|
|
@@ -199,6 +238,8 @@ export declare function flatSearchResult(page: CatalogSearchPage): {
|
|
|
199
238
|
requiredInputKeys?: string[];
|
|
200
239
|
outputKeys?: string[];
|
|
201
240
|
annotations?: ToolDef["annotations"];
|
|
241
|
+
guideRequired?: true;
|
|
242
|
+
guideRequiredReasons?: GuideRequiredReason[];
|
|
202
243
|
}[];
|
|
203
244
|
total: number;
|
|
204
245
|
offset: number;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"catalog-service.d.ts","sourceRoot":"","sources":["../src/catalog-service.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EACV,yBAAyB,EACzB,YAAY,EACb,MAAM,eAAe,CAAC;
|
|
1
|
+
{"version":3,"file":"catalog-service.d.ts","sourceRoot":"","sources":["../src/catalog-service.ts"],"names":[],"mappings":"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"}
|