@zackbart/connecta 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,258 @@
 
 All notable changes to this package are documented here.
 
+## 0.5.0 — 2026-07-26
+
+A feature release. Toolkits, per-connector usage guides, and per-connector
+result caps are the substance; a paging fix, a docs coherence pass, and a
+cleared audit advisory round it out. Nothing here is breaking, and a deployment
+that declares none of the new options keeps its 0.4.1 *runtime* behavior on
+every path that matters: an unscoped connection still sees the whole registry,
+a zero-guide catalog gains no discovery text, and an unset cap truncates where
+it always did. One narrow exception — a request carrying `?toolkit=` against a
+deployment that configures no toolkits is now a 404, where 0.4.1 never read the
+parameter and served the request; no 0.4.1 client had reason to send it. Three
+textual changes are unconditional and reach every deployment, so anything that
+snapshots them will diff: the `get_result` tool description now documents the
+accepted `maxBytes` range, its `maxBytes` JSON Schema tightens from
+`exclusiveMinimum: 0` to `minimum: 1`, and the matching validation error
+message is reworded. The next intentional breaking release stays reserved for
+issue #28.
+
+### Added
+
+- **Toolkits — named scoped views over one deployment's registry.** A connecta
+  deployment belongs to an org; a toolkit is the slice one team group sees.
+  Operators declare them in the new `ConnectaConfig.toolkits` (`{ support: {
+  connectors: [...], includeTools?, excludeTools? } }`, with per-tool address
+  grain; `ToolkitConfig` and `ToolkitDefinition` are exported), and a client
+  selects one with `?toolkit=<name>` on the MCP URL. The boundary is a single
+  enforcement point: a `ScopedRegistry` built once per HTTP request — the
+  transport is stateless, so there is no longer-lived connection to hang it on
+  — with every meta-tool and the `execute_code` sandbox bridge typed against a
+  narrow `RegistryView` rather than the full `Registry`, so reaching for an
+  unfiltered method is a compile error instead of a silent leak. All nine
+  meta-tools are scoped; an out-of-scope address fails byte-identically to a
+  nonexistent one; `get_result` stashes are namespaced per toolkit so a scoped
+  session cannot page out a sibling's results; and health observations are
+  per-toolkit so one scope's `lastError` never names another's tools. A
+  monotonic has-ever-succeeded flag is the one deployment-wide *observation* a
+  scoped view can read back, so scoped sessions don't misreport live remote
+  connectors as `unknown`. Plenty of other state is shared by design and is not
+  scoped at all — the tool-catalog cache, and, worth saying out loud, the
+  `conn:<id>:` storage namespace and the credential vault: **a downstream OAuth
+  token obtained under one toolkit is usable from another.** `/ui`, `/health`,
+  and the OAuth pages stay unscoped operator surfaces. **Selection is
+  self-service: any caller who can reach the endpoint may name any toolkit, or
+  omit the parameter and see the whole registry.** A toolkit scopes visibility,
+  not identity — binding a team member to a toolkit belongs in `auth`, and
+  enforcing that binding is a deliberate follow-up (issue #37). Until it lands,
+  treat toolkits as an ergonomics and context-budget feature rather than access
+  control; connecta warns at startup when toolkits are configured without
+  inbound `auth`. `InboundAuth.authorize` already receives the full request, so
+  an adapter can refuse a mismatched `?toolkit=` today.
+- **Per-connector usage guides, served by the existing `skills` meta-tool.** A
+  connector declaration can carry `usageGuide` — agent-facing markdown,
+  config-as-code, and a new pass-through option on both `ApiOptions` and
+  `RemoteMcpOptions`. `skills({})` then lists the built-in `usage` guide
+  alongside one summarized entry per guided connector, with `skills({ name:
+  "connector:<id>" })` returning the guide verbatim. Collision with a built-in
+  skill name is structurally impossible because the built-in names are bare
+  identifiers that never contain `:`, so no `connector:<id>` can ever match one
+  — not even when a connector's id is literally `usage`. The prefixed form is
+  also the only way to reach a guide: a bare connector id is never resolved,
+  and errors with a pointer to the prefixed name rather than shadowing
+  anything. Discovery is conditional: the extra `usage` section and the `guide`
+  hints on `search_tools`/`describe_tools`/`skills` appear only once some
+  connector declares a guide, so a zero-guide deployment's catalog is
+  byte-identical to before — with one exception: the `skills({ name })` error
+  wording for connector-shaped names. Those branches are gated on the name
+  matching a connector id, not on any guide existing, so asking for a bare
+  connector id now reports that the connector has no usage guide where 0.4.1
+  said `Unknown skill`, and `connector:<unknown>` reports an unknown connector.
+  Guides follow the connection's toolkit scope — a scoped session sees only
+  in-scope guides.
+- **Per-connector `maxResultBytes` override.** The inline-result byte cap now
+  resolves per call as connector value → global `ConnectaConfig.maxResultBytes`
+  → the built-in 50 000 default, so a connector that habitually returns large
+  payloads can be capped without shrinking everything else. It is a new
+  `maxResultBytes` field on the `Connector` interface with pass-through options
+  on both `ApiOptions` and `RemoteMcpOptions`. Resolution happens after address
+  resolution inside the call path, so `call_tool`, `call_destructive_tool`, and
+  each leg of a `batch_call` use their own connector's cap. `get_result`'s
+  default page size deliberately stays on the global cap — a stashed result
+  carries no connector identity — and `execute_code` host-call results never
+  flowed through this truncation path at all (they have a separate guard on the
+  final sandbox return), so they're unaffected. A toolkit can neither raise nor
+  lower a cap.
+- **`ToolCallActivityEvent.toolkitId`** — an optional field on the exported
+  activity event, set to the toolkit a call arrived through and absent on
+  unscoped calls. Every custom `ActivityStore` now receives it, so a sink that
+  persists into a typed or column-bound schema needs a migration to keep the
+  value rather than drop it on the floor; sinks that pass the event through
+  untouched need no change.
+
+### Fixed
+
+- **`maxResultBytes` is validated at all three intake points, and `get_result`
+  paging can never fail to advance** (issue #32). The cap is now a whole number
+  of bytes >= 1, enforced from one shared definition. An unusable operator
+  value (zero, negative, `NaN`, non-integer, `Infinity`) emits a startup
+  warning through the existing insensible-config channel — naming the connector
+  for a per-connector override, and quoting the exact value the runtime falls
+  back to — instead of silently misbehaving: previously `0`/`NaN` served a
+  0-byte head, and a *negative* cap served a **larger** head than the default
+  (`Uint8Array.slice` counts from the end) while still claiming truncation. A
+  bad `get_result` `maxBytes` argument is now an ordinary input-validation
+  error. On top of intake validation, `alignEndToCharBoundary` widens any
+  window that would yield no bytes, so a page inside the payload always
+  advances; the end of the payload is handled separately, by only reporting a
+  `nextOffset` while the window stops short of the total. Between them, paging
+  terminates whatever effective page size reaches it. Worth recording so the
+  issue isn't closed on a false premise: the *client*-triggerable hang the
+  issue suspected was confirmed never reachable — the wire schema already
+  rejected non-positive `maxBytes` before dispatch, verified empirically
+  against the previous release. The hang was real but operator-triggered only;
+  the in-handler check is defense in depth for in-process callers. Valid values
+  behave byte-identically to 0.4.1.
+- **Documentation coherence pass across README, `docs/`, and `examples/`.** The
+  changes above each documented themselves; nobody had reconciled the set.
+  Fixed: a TOC link to an anchor that never existed, a toolkits section that
+  opened by calling a toolkit "an access boundary" in direct contradiction of
+  the "what toolkits are *not*" text below it, a `ConnectaConfig` table missing
+  `toolkits` and `probeTimeoutMs`, design.md's silence on guides and toolkits,
+  and a `serveMcp` misattribution of where the scope is actually built.
+  **Operators running the worker example should note a schema migration**: its
+  `ActivityStore` dropped `toolkitId`, the field that shows which team's view a
+  call came through. The example now binds and reads back a `toolkit_id`
+  column, and its README carries an `ALTER TABLE` note for pre-existing D1
+  tables — without it, every insert fails with `no such column`, and because
+  activity writes are best-effort the failure is invisible to the caller (it
+  surfaces only as a warning per write in the operator log) while the activity
+  table stops filling.
+
+### Security
+
+- **`branding.favicon.href` is now scheme-gated**, completing the branding-URL
+  invariant begun in 0.4.1 (issue #29). All three branding URLs are validated
+  in one resolver shared by both HTML surfaces (`/ui` and the OAuth result
+  pages). A favicon href must be an absolute http(s) URL or a genuinely
+  root-relative path — enforced structurally, after stripping the tab/LF/CR
+  characters URL parsers ignore, with an origin comparison kept as defense in
+  depth. Root-relative only, because `/ui` and `/oauth/callback/<id>` sit at
+  different depths and a document-relative path would resolve differently on
+  each. A rejected value falls back silently to the default `/favicon.svg` and
+  is named in a startup warning — which also names a dropped `productUrl` or
+  `ownerUrl`, so a deployment that has been quietly carrying one of those since
+  0.4.1 will start seeing a warning line it did not see before.
+  `resolveBranding` also reads every field through a string guard, so malformed
+  branding from an untyped JavaScript caller degrades to defaults instead of
+  throwing at construction.
+- **GHSA-frvp-7c67-39w9 cleared, and `check:security` tightened from `high` to
+  `moderate`.** The advisory (a Windows-only path traversal in
+  `@hono/node-server`'s `serve-static`) is resolved by a root `overrides` entry
+  pinning `@hono/node-server@^2.0.12`. No *declared* dependency version changes
+  — the MCP SDK stays where it was — though the override does of course move
+  the resolved transitive package across a major, 1.19.14 to 2.0.12. The
+  planned SDK bump could not work: every SDK release from 1.25.0 onward pins a
+  `@hono/node-server@^1.19.x` range that can never resolve to the patched 2.x
+  line, and it is those same releases that pull the package in at all. This is
+  audit-noise remediation rather than live vulnerability remediation — a
+  module-graph trace from every SDK entrypoint connecta uses found no reachable
+  `@hono/node-server` import, and the vulnerable `serve-static` subpath is
+  imported by nothing in the tree — which is what makes the forced major safe.
+  The old `high` gate caught high and critical findings correctly, but by
+  construction could never surface this moderate one; `SECURITY.md` is updated
+  to match, having still recorded the advisory as an accepted open finding
+  under the old threshold. **Residual, stated plainly:** npm applies
+  `overrides` only at the root project, so consumers who install this package
+  still resolve the `1.19.x` range and will keep seeing the advisory in their
+  own audits until the SDK moves to `@hono/node-server@^2`. Tracked as issue
+  #40, which also retires the override.
+
+## 0.4.1 — 2026-07-25
+
+A security-hardening release from a full audit of the codebase. Every change is
+backward-compatible: new safety that could alter behavior is opt-in or a
+generous default, and existing well-behaved deployments are unaffected. No
+sandbox-escape, RCE, or XSS was found; the items below are the real gaps.
+
+### Security
+
+- **QuickJS sandbox log memory is now bounded.** `execute_code`'s `console.log`
+  capped only the *number* of retained entries (200), not their size, so
+  untrusted guest code — the sandbox's explicit threat model — could
+  `console.log("x".repeat(25_000_000))` two hundred times and retain multiple
+  GB of host memory, OOMing the Node process. Each entry is now truncated to 8k
+  chars and the cumulative buffer to 256k, both at capture time. Small logs are
+  byte-for-byte unchanged.
+
+- **The `fileStorage` state file is now owner-only.** It holds downstream OAuth
+  access/refresh tokens in cleartext on the Node backend and was written with
+  no mode (world-readable `0644`), so any local user could read long-lived
+  tokens. The directory is now `0700`, the temp file `0600` (the atomic rename
+  preserves it), and an existing loose-mode file is repaired to `0600` on load.
+  Repair is best-effort so a non-POSIX filesystem can't block startup.
+
+- **Cleartext-credential and destination guard on `remoteMcp`.** Static
+  `headers` credentials were attached with no scheme check, so an `http://`
+  `url` sent bearer tokens / API keys in cleartext. `remoteMcp` now warns at
+  construction when headers-auth targets a non-https, non-loopback URL, and a
+  new opt-in `requireHttps` makes that a hard error. A `NOTE` documents the
+  residual redirect-following SSRF in the SDK's fetch transport (a malicious
+  downstream could 3xx-redirect to an internal address); a full guard needs
+  manual redirect handling in the SDK and is deferred to a non-patch release.
+
+- **Construction-time warnings for insecure deployment shapes.**
+  `createConnecta` now emits a one-time `logger.warn` when: no inbound `auth`
+  is configured while credential/OAuth connectors are present (any caller
+  reaches the credential vault — connecta's trust model is single-domain, so an
+  open or open-signup deployment grants every caller full access); `publicUrl`
+  is unset while OAuth connectors exist (the downstream `redirect_uri` is
+  derived from the attacker-influenced inbound `Host` header — set `publicUrl`
+  to a fixed https origin); or a connector exposes `finishAuth` but not
+  `verifyState` (its `/oauth/callback` would exchange any delivered `code`).
+  The shipped `remoteMcp` implements `verifyState`, so the last fires only for
+  hand-rolled connectors. Full per-actor authorization remains an architectural
+  change for a future release.
+
+- **The discovery meta-tools no longer hang on a stuck downstream.**
+  `list_connectors`, `search_tools`, and `describe_tools` fanned out live
+  probes to every connector with no deadline, so one hung downstream stalled
+  the whole call. Bounded by the new `probeTimeoutMs` (below); a timed-out
+  connector degrades to an unavailable/errored entry. The bound is
+  caller-facing — the registry takes no `AbortSignal` yet, so the underlying
+  fetch is not cancelled; real cancellation is a documented follow-up.
+
+- **`/ui` now ships a nonce-based script CSP.** The operator page carried no
+  script-restricting CSP, so any future escaping regression would be directly
+  exploitable. It now sends a per-request `script-src 'nonce-…' 'strict-dynamic'
+  https: 'unsafe-inline'; object-src 'none'; base-uri 'none'; frame-ancestors
+  'none'`. `'strict-dynamic'` keeps Clerk's runtime-injected scripts working;
+  the `https:`/`'unsafe-inline'` fallbacks are ignored by modern browsers and
+  only cover legacy ones; and no `default-src` is set so Clerk's network/fonts
+  and the inline styles stay unrestricted. Operator `branding` `productUrl`/
+  `ownerUrl` values are now scheme-gated (a `javascript:` URL is dropped rather
+  than rendered as a link), and credential metadata omits `lastFour` for values
+  shorter than 12 chars so a short secret doesn't leak half of itself.
+
+### Added
+
+- `RemoteMcpOptions.requireHttps` (default `false`) — reject a non-`https://`
+  (non-loopback) `url` at construction, and `RemoteMcpOptions.logger` for the
+  cleartext-credential warning.
+- `ApiOptions.strictValidation` (default `false`) and
+  `ValidateToolInputOptions.failClosed` (default `false`) — reject a call whose
+  `inputSchema` the validator cannot evaluate instead of passing the raw
+  arguments through. The default remains fail-open (a broken schema does not
+  break an otherwise working tool); `api()` also now eagerly compiles each tool
+  schema at construction so a bad one warns once at startup rather than
+  silently on first use.
+- `ConnectaConfig.probeTimeoutMs` (default `30_000`) — per-connector deadline
+  for the `list_connectors`/`search_tools`/`describe_tools` fan-out. Generous
+  by default so it trips only on a pathological hang; does not apply to
+  `call_tool`/`batch_call`, which carry `defaultToolTimeoutMs`.
+
 ## 0.4.0 — 2026-07-25
 
 ### Added

package/README.md

@@ -44,13 +44,13 @@ A tool **address** is `<connectorId>.<toolName>` (e.g. `notion.search`).
 | Tool | Input | Returns |
 | --- | --- | --- |
 | `list_connectors` | `{ probe? }` | live (`probe: true`, default) or cached health, tool count, and recent real-call observations |
-| `skills` | `{ name? }` | lists or fetches the concise `usage` guide for choosing among the meta-tools |
+| `skills` | `{ name? }` | lists or fetches the concise `usage` guide for choosing among the meta-tools, plus any operator-authored per-connector guide (`connector:<connectorId>`) |
 | `search_tools` | `{ query?, connector?, limit?, offset?, fullDescriptions?, includeSchemas? }` | ranked, paginated matches; optionally includes compact/raw schemas to remove a round trip |
 | `describe_tools` | `{ addresses[], format?, fullDescriptions? }` | names, descriptions, input/output schemas, and behavior annotations |
 | `call_tool` | `{ address, args?, fields?, resultMode?, timeoutMs?, maxRetries?, diagnostics? }` | invokes only tools explicitly annotated `readOnlyHint: true` |
 | `call_destructive_tool` | same as `call_tool` | invokes unannotated, write-capable, or destructive tools through a host-visible approval boundary |
 | `authorize_connector` | `{ connector, force? }` | starts (or with `force`, restarts) the downstream OAuth flow; returns the `authorizationUrl` to open |
-| `get_result` | `{ id, offset?, maxBytes? }` | a byte-slice page of a truncated result — `{ text, offset, nextOffset?, totalBytes }` |
+| `get_result` | `{ id, offset?, maxBytes? }` | a byte-slice page of a truncated result — `{ text, offset, nextOffset?, totalBytes }`; `maxBytes` is a whole number of bytes >= 1 |
 | `batch_call` | `{ calls, resultMode?, timeoutMs?, maxRetries? }` | 1–10 parallel calls sharing request-scoped clients, with attempts/timing/errors |
 | `execute_code` *(optional)* | `{ code }` | result + logs of bounded async JS orchestration over explicitly read-only tools; registered only when an `executor` is configured |
 
@@ -65,9 +65,7 @@ connector configuration, auth policy, domain, bindings, migrations, and secrets.
 
 ```ts
 import { DynamicWorkerExecutor } from "@cloudflare/codemode";
-import {
-  api, bearerToken, createConnecta, remoteMcp,
-} from "@zackbart/connecta";
+import { bearerToken, createConnecta, remoteMcp } from "@zackbart/connecta";
 import { clerkAuth } from "@zackbart/connecta/auth/clerk";
 import { cloudflareKvStorage } from "./cloudflare-kv.js";
 
@@ -143,6 +141,41 @@ listen(connecta, 8787); // http://localhost:8787/mcp
 Example: [`examples/node/`](./examples/node/). Docker (single-service compose
 stack): [`examples/docker/`](./examples/docker/).
 
+## Toolkits — one deployment, many teams
+
+A deployment belongs to an org. Optional **toolkits** give each group of team
+members its own scoped view of the same registry, so different teams no longer
+need separate deployments:
+
+```ts
+createConnecta({
+  connectors: [zendesk, notion, gmail],
+  auth: bearerToken(env.CONNECTA_TOKEN),
+  toolkits: {
+    support: { connectors: ["zendesk", "notion"] },
+    exec: {
+      connectors: ["zendesk", "notion", "gmail"],
+      excludeTools: ["gmail.send_message"], // finer grain than a connector id
+    },
+  },
+});
+```
+
+A client picks one at connect time: `https://…/mcp?toolkit=support`. Inside a
+scoped session **every** meta-tool — search, describe, call, batch, skills,
+authorize, `get_result`, and `execute_code` host calls — behaves as if
+out-of-scope connectors and tools do not exist, and an out-of-scope address
+fails identically to a nonexistent one. No `?toolkit=` ⇒ the full registry, as
+before; an unknown name is an error, never a silent fallback.
+
+A toolkit scopes **visibility, not identity**: any authenticated client may
+select any toolkit, or omit the parameter and see everything, so a credential
+shared by two teams gives both teams every view. Binding a member to a toolkit
+belongs in `auth`, which stays the access check; enforcing that binding is a
+deliberate follow-up
+([issue #37](https://github.com/zackbart/connecta/issues/37)). Details:
+[docs §16](./docs/documentation.md#16-toolkits-scoped-views).
+
 ## Code mode
 
 With an `executor` configured, the model can write an async function instead of
@@ -202,9 +235,11 @@ api("example", {
 ```
 
 Set `credentialEncryptionKey` on `createConnecta` to a base64-encoded 32-byte
-key held in the runtime's secret store (`openssl rand -base64 32`). Credential
-mutation routes require the configured Clerk provider and a same-origin browser
-request; the static inbound bearer cannot administer the vault.
+key held in the runtime's secret store (`openssl rand -base64 32`) — a connector
+that declares a credential without one fails at construction rather than booting
+with an unusable vault. Credential mutation routes require the configured Clerk
+provider and a same-origin browser request; the static inbound bearer cannot
+administer the vault.
 
 Connecta does not bundle service-specific HTTP API connectors. Package consumers
 define them with `api()` (or implement `Connector` directly), keeping endpoint,
@@ -233,17 +268,37 @@ const connecta = createConnecta({
 ```
 
 One final event is emitted for each resolved connector call made through
-`call_tool`, `batch_call`, or `execute_code`; retries remain one event with an
-`attempts` count. Implementing `list` enables the authenticated Activity tab in
-`/ui`; `activityReadGate` can narrow reads further. Writes are best-effort and
-never change a tool result. Clerk calls carry the Clerk user ID; shared bearer
-calls are honestly labeled as bearer unless
-`bearerToken(secret, { subjectId })` assigns that credential a stable subject.
+`call_tool`, `call_destructive_tool`, `batch_call`, or `execute_code`; retries
+remain one event with an `attempts` count. Implementing `list` enables the
+authenticated Activity tab in `/ui`; `activityReadGate` can narrow reads
+further. Writes are best-effort and never change a tool result. Clerk calls
+carry the Clerk user ID; shared bearer calls are honestly labeled as bearer
+unless `bearerToken(secret, { subjectId })` assigns that credential a stable
+subject. On Workers, pass `ctx` through to `connecta.fetch(request, env, ctx)`
+so async writes settle on `waitUntil`.
+[`examples/worker/src/d1-activity.ts`](./examples/worker/src/d1-activity.ts) is
+a complete D1 implementation with keyset paging and a retention pass.
+
+## Operator dashboard
+
+`GET /ui` is a read-only dashboard with no build step: connector health, tool
+counts and descriptions with a client-side filter, downstream authorization
+links, the credential controls above, and an Activity tab when an activity store
+is configured. The shell is open because it carries no data; everything it shows
+comes from `/ui/data`, behind the same auth gate as `/mcp`. With Clerk
+configured it signs operators in through Clerk's hosted portal; a bearer-only
+deployment falls back to a pasted token.
+
+Every deployment-facing label and mark on `/ui` and the OAuth result pages comes
+from `ConnectaConfig.branding` — `productName`, `ownerName`, their URLs,
+`description`, `pageTitle`, `themeColor`, and `favicon` — each falling back to a
+neutral Connecta default. Nothing about the operator is baked into the package.
 
 ## Learn more
 
 - **[`docs/documentation.md`](./docs/documentation.md)** — how everything works: architecture,
-  the meta-tools, connectors, inbound auth, downstream OAuth, storage, running it
-  (Node / Workers / Docker), Clerk setup, testing, troubleshooting.
+  the meta-tools, connectors and their usage guides, inbound auth, downstream
+  OAuth, storage, running it (Node / Workers / Docker), Clerk setup, testing,
+  troubleshooting, code mode, the status UI, activity history, and toolkits.
 - **[`docs/design.md`](./docs/design.md)** — why it's built this way, and the non-goals.
-- **Status UI** — a read-only operator dashboard at `GET /ui` (open shell; data from the bearer/Clerk-gated `/ui/data`). See [§14](./docs/documentation.md#14-status-ui).
+- **[`CHANGELOG.md`](./CHANGELOG.md)** — what changed in each release.

package/SECURITY.md

@@ -12,14 +12,18 @@ sensitive payloads in a public issue.
 
 ## Dependency policy
 
-CI blocks high and critical production dependency advisories. Moderate findings
-are reviewed for reachability and recorded when an upstream package has not yet
-released a compatible fix.
+CI blocks moderate, high, and critical production dependency advisories. Lower
+findings are reviewed for reachability and recorded when an upstream package has
+not yet released a compatible fix.
 
-The initial release has one such upstream finding:
 `@modelcontextprotocol/sdk@1.29.0` declares `@hono/node-server` 1.x, which is
 covered by `GHSA-frvp-7c67-39w9`. The advisory affects Hono's Windows
 `serve-static` implementation. Connecta does not import that adapter or serve
 static files through Hono. npm's suggested fix downgrades the MCP SDK below
-security behavior Connecta relies on, so the package retains SDK 1.29.0 while
-tracking an upstream compatible release.
+security behavior Connecta relies on, so the package instead pins
+`@hono/node-server` to 2.x through an `overrides` entry and keeps SDK 1.29.0.
+
+Because npm only applies `overrides` to the root project, that pin governs this
+repository's own installs rather than trees built by consumers of the published
+package. The override is removed once the SDK declares `@hono/node-server` ^2
+upstream.

package/dist/activity.d.ts

@@ -34,6 +34,12 @@ export interface ToolCallActivityEvent {
     serverName: string;
     serverVersion: string;
     deploymentId?: string;
+    /**
+     * Name of the toolkit this connection selected with `?toolkit=`, when it
+     * selected one. Calls are recorded the same way with or without it; this only
+     * says which scoped view the call came through.
+     */
+    toolkitId?: string;
 }
 export interface ActivityPage {
     events: ToolCallActivityEvent[];
@@ -69,6 +75,8 @@ export interface ActivityRequestContext {
         version: string;
     };
     deploymentId?: string;
+    /** Toolkit this connection is scoped to, when `?toolkit=` selected one. */
+    toolkitId?: string;
     defer?: (promise: Promise<unknown>) => void;
     logger: Logger;
 }

package/dist/activity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,uBAAuB,GACvB,YAAY,GACZ,cAAc,CAAC;AAEnB,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,CAAC,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,eAAe,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED,iFAAiF;AACjF,qBAAa,0BAA2B,SAAQ,KAAK;IAC1C,IAAI,SAAgC;;CAK9C;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC7B,KAAK,EAAE,aAAa,KACjB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,qBAAqB,EACnB,aAAa,GACb,UAAU,GACV,SAAS,GACT,QAAQ,GACR,SAAS,GACT,YAAY,GACZ,UAAU,GACV,WAAW,CACd,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,sBAAsB,GAAG,SAAS,EAC3C,KAAK,EAAE,kBAAkB,GACxB,IAAI,CAkCN"}
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,uBAAuB,GACvB,YAAY,GACZ,cAAc,CAAC;AAEnB,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,CAAC,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,eAAe,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED,iFAAiF;AACjF,qBAAa,0BAA2B,SAAQ,KAAK;IAC1C,IAAI,SAAgC;;CAK9C;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC7B,KAAK,EAAE,aAAa,KACjB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,qBAAqB,EACnB,aAAa,GACb,UAAU,GACV,SAAS,GACT,QAAQ,GACR,SAAS,GACT,YAAY,GACZ,UAAU,GACV,WAAW,CACd,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,sBAAsB,GAAG,SAAS,EAC3C,KAAK,EAAE,kBAAkB,GACxB,IAAI,CAmCN"}

package/dist/activity.js

@@ -32,6 +32,7 @@ export function recordToolActivity(context, input) {
         ...(context.deploymentId
             ? { deploymentId: context.deploymentId }
             : {}),
+        ...(context.toolkitId ? { toolkitId: context.toolkitId } : {}),
     };
     try {
         const result = context.sink.record(event);

package/dist/activity.js.map

@@ -1 +1 @@
-{"version":3,"file":"activity.js","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAiEA,iFAAiF;AACjF,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,IAAI,GAAG,4BAA4B,CAAC;IAE7C;QACE,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACnC,CAAC;CACF;AA6BD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA2C,EAC3C,KAAyB;IAEzB,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,MAAM,KAAK,GAA0B;QACnC,aAAa,EAAE,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;QACvB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACrD,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACjD,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI;QACnC,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO;QACzC,GAAG,CAAC,OAAO,CAAC,YAAY;YACtB,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE;YACxC,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;IACF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,IAAI,OAAQ,MAA2B,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACvE,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACtD,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,mCAAmC,EAAE,KAAK,CAAC,CAAC;QAClE,CAAC,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,KAAK;YAAE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,mCAAmC,EAAE,KAAK,CAAC,CAAC;IAClE,CAAC;AACH,CAAC"}
+{"version":3,"file":"activity.js","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAuEA,iFAAiF;AACjF,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,IAAI,GAAG,4BAA4B,CAAC;IAE7C;QACE,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACnC,CAAC;CACF;AA+BD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA2C,EAC3C,KAAyB;IAEzB,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,MAAM,KAAK,GAA0B;QACnC,aAAa,EAAE,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;QACvB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACrD,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACjD,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI;QACnC,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO;QACzC,GAAG,CAAC,OAAO,CAAC,YAAY;YACtB,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE;YACxC,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/D,CAAC;IACF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,IAAI,OAAQ,MAA2B,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACvE,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACtD,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,mCAAmC,EAAE,KAAK,CAAC,CAAC;QAClE,CAAC,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,KAAK;YAAE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,mCAAmC,EAAE,KAAK,CAAC,CAAC;IAClE,CAAC;AACH,CAAC"}

package/dist/connectors/api.d.ts

@@ -17,6 +17,19 @@ export interface ApiOptions {
     /** Human-readable display name; the connector id remains the address prefix. */
     title?: string;
     description?: string;
+    /**
+     * Max inline result size (bytes) for this connector's tools before
+     * call_tool/batch_call truncate and stash the full text for get_result
+     * paging. Overrides the deployment's `maxResultBytes`; omit to inherit it.
+     * Must be a whole number of bytes >= 1; anything else warns at startup and
+     * is ignored.
+     */
+    maxResultBytes?: number;
+    /**
+     * Optional agent-facing usage guide (markdown) served by the `skills`
+     * meta-tool as `connector:<id>`. See `Connector.usageGuide`.
+     */
+    usageGuide?: string;
     /** Optional operator-managed credential exposed through ctx.credential and /ui. */
     credential?: ConnectorCredentialConfig;
     /** Optional validation behind /ui's Test action. */
@@ -31,6 +44,16 @@ export interface ApiOptions {
      * on loose coercion.
      */
     validateArgs?: boolean;
+    /**
+     * Fail-closed on a tool whose `inputSchema` the validator cannot evaluate
+     * (default false). The default surfaces such a schema as a one-time warning
+     * and then passes the raw arguments through, so a broken schema never breaks
+     * an otherwise working tool. Set true to instead reject those calls with a
+     * non-retryable `invalid_args` ConnectorCallError, so a schema that cannot be
+     * enforced never silently admits unvalidated input. Only consulted when
+     * `validateArgs` is not false.
+     */
+    strictValidation?: boolean;
     tools: ApiTool[];
 }
 /**

package/dist/connectors/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/connectors/api.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,SAAS,EACT,yBAAyB,EACzB,yBAAyB,EACzB,gBAAgB,EAChB,oBAAoB,EACpB,UAAU,EACV,eAAe,EAEhB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B;;;OAGG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAC3E;AAED,MAAM,WAAW,UAAU;IACzB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,UAAU,CAAC,EAAE,yBAAyB,CAAC;IACvC,oDAAoD;IACpD,cAAc,CAAC,EAAE,CACf,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,gBAAgB,KAClB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACnC,6DAA6D;IAC7D,eAAe,CAAC,EAAE,CAChB,MAAM,EAAE,yBAAyB,EACjC,GAAG,EAAE,gBAAgB,KAClB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,CAsC3D"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/connectors/api.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,SAAS,EACT,yBAAyB,EACzB,yBAAyB,EACzB,gBAAgB,EAChB,oBAAoB,EACpB,UAAU,EACV,eAAe,EAEhB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B;;;OAGG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAC3E;AAED,MAAM,WAAW,UAAU;IACzB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,UAAU,CAAC,EAAE,yBAAyB,CAAC;IACvC,oDAAoD;IACpD,cAAc,CAAC,EAAE,CACf,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,gBAAgB,KAClB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACnC,6DAA6D;IAC7D,eAAe,CAAC,EAAE,CAChB,MAAM,EAAE,yBAAyB,EACjC,GAAG,EAAE,gBAAgB,KAClB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,CAkD3D"}

package/dist/connectors/api.js

@@ -1,4 +1,4 @@
-import { validateToolInput } from "../validate.js";
+import { precompileValidator, validateToolInput } from "../validate.js";
 /**
  * A connector defined entirely in code: static tool defs + fetch handlers.
  * Tool inputs are plain JSON Schema objects (bring your own zod-to-json-schema
@@ -20,11 +20,22 @@ export function api(id, opts) {
     }));
     const byName = new Map(opts.tools.map((t) => [t.name, t]));
     const validateArgs = opts.validateArgs ?? true;
+    const strictValidation = opts.strictValidation ?? false;
+    if (validateArgs) {
+        // Compile each schema now so a validator-hostile inputSchema surfaces once
+        // here rather than silently on its first call. Warning-only; never throws.
+        for (const t of opts.tools) {
+            if (t.inputSchema)
+                precompileValidator(t.inputSchema, { address: `${id}.${t.name}` });
+        }
+    }
     return {
         id,
         title: opts.title,
         kind: "api",
         description: opts.description,
+        maxResultBytes: opts.maxResultBytes,
+        usageGuide: opts.usageGuide,
         credential: opts.credential,
         testCredential: opts.testCredential,
         testCredentials: opts.testCredentials,
@@ -42,6 +53,7 @@ export function api(id, opts) {
                 const invalid = validateToolInput(tool.inputSchema, input, {
                     address: `${id}.${name}`,
                     logger: ctx.logger,
+                    failClosed: strictValidation,
                 });
                 if (invalid)
                     throw invalid;

package/dist/connectors/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/connectors/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAsDnD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,GAAG,CAAC,EAAU,EAAE,IAAgB;IAC9C,MAAM,IAAI,GAAc,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7C,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,YAAY,EAAE,CAAC,CAAC,YAAY;QAC5B,WAAW,EAAE,CAAC,CAAC,WAAW;KAC3B,CAAC,CAAC,CAAC;IACJ,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC;IAC/C,OAAO;QACL,EAAE;QACF,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI,EAAE,KAAK;QACX,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,WAAW,EAAE,IAAI;QACjB,KAAK,CAAC,SAAS;YACb,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG;YAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,mBAAmB,EAAE,GAAG,CAAC,CAAC;YACjE,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC;YACzB,IAAI,YAAY,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBACrC,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE;oBACzD,OAAO,EAAE,GAAG,EAAE,IAAI,IAAI,EAAE;oBACxB,MAAM,EAAE,GAAG,CAAC,MAAM;iBACnB,CAAC,CAAC;gBACH,IAAI,OAAO;oBAAE,MAAM,OAAO,CAAC;YAC7B,CAAC;YACD,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAClC,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/connectors/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AA6ExE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,GAAG,CAAC,EAAU,EAAE,IAAgB;IAC9C,MAAM,IAAI,GAAc,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7C,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,YAAY,EAAE,CAAC,CAAC,YAAY;QAC5B,WAAW,EAAE,CAAC,CAAC,WAAW;KAC3B,CAAC,CAAC,CAAC;IACJ,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC;IAC/C,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,IAAI,KAAK,CAAC;IACxD,IAAI,YAAY,EAAE,CAAC;QACjB,2EAA2E;QAC3E,2EAA2E;QAC3E,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC3B,IAAI,CAAC,CAAC,WAAW;gBACf,mBAAmB,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;IACD,OAAO;QACL,EAAE;QACF,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI,EAAE,KAAK;QACX,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,WAAW,EAAE,IAAI;QACjB,KAAK,CAAC,SAAS;YACb,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG;YAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,mBAAmB,EAAE,GAAG,CAAC,CAAC;YACjE,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC;YACzB,IAAI,YAAY,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBACrC,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE;oBACzD,OAAO,EAAE,GAAG,EAAE,IAAI,IAAI,EAAE;oBACxB,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,UAAU,EAAE,gBAAgB;iBAC7B,CAAC,CAAC;gBACH,IAAI,OAAO;oBAAE,MAAM,OAAO,CAAC;YAC7B,CAAC;YACD,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAClC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/connectors/remote-mcp.d.ts

@@ -1,5 +1,5 @@
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import type { Connector, ConnectorContext } from "../types.js";
+import type { Connector, ConnectorContext, Logger } from "../types.js";
 export type RemoteMcpAuth = {
     type: "headers";
     headers: Record<string, string>;
@@ -11,7 +11,33 @@ export interface RemoteMcpOptions {
     /** Human-readable display name; the connector id remains the address prefix. */
     title?: string;
     description?: string;
+    /**
+     * Max inline result size (bytes) for this connector's tools before
+     * call_tool/batch_call truncate and stash the full text for get_result
+     * paging. Overrides the deployment's `maxResultBytes`; omit to inherit it.
+     * Must be a whole number of bytes >= 1; anything else warns at startup and
+     * is ignored.
+     */
+    maxResultBytes?: number;
+    /**
+     * Optional agent-facing usage guide (markdown) served by the `skills`
+     * meta-tool as `connector:<id>`. See `Connector.usageGuide`.
+     */
+    usageGuide?: string;
     auth?: RemoteMcpAuth;
+    /**
+     * Refuse to connect to a non-`https://` `url` at construction (default
+     * false). Loopback hosts (`localhost`, `127.0.0.1`, `[::1]`) are always
+     * allowed for local development. Off by default, static `headers` credentials
+     * over a cleartext connection are warned about but permitted; set this true
+     * to make that misconfiguration a hard error instead.
+     */
+    requireHttps?: boolean;
+    /**
+     * Destination for the cleartext-credential warning emitted at construction.
+     * Default console.
+     */
+    logger?: Logger;
     /**
      * @internal Testing seam. When set, this transport is used instead of the
      * HTTP transport, letting tests point the connector at an in-process MCP

package/dist/connectors/remote-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-mcp.d.ts","sourceRoot":"","sources":["../../src/connectors/remote-mcp.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAK/E,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAGjB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,SAAS,CAAC;CAC1D;AAeD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,SAAS,CA+RvE"}
+{"version":3,"file":"remote-mcp.d.ts","sourceRoot":"","sources":["../../src/connectors/remote-mcp.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAK/E,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAEhB,MAAM,EAEP,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,SAAS,CAAC;CAC1D;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,SAAS,CA8TvE"}