run402-mcp 4.154.1 → 4.155.1
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/README.md +1 -1
- package/dist/docs/llms-sdk.txt +25 -7
- package/package.json +3 -3
- package/schemas/release-spec.v1.json +71 -0
- package/sdk/README.md +13 -1
- package/sdk/dist/function-tools.d.ts +119 -0
- package/sdk/dist/function-tools.d.ts.map +1 -0
- package/sdk/dist/function-tools.js +280 -0
- package/sdk/dist/function-tools.js.map +1 -0
- package/sdk/dist/index.d.ts +3 -1
- package/sdk/dist/index.d.ts.map +1 -1
- package/sdk/dist/index.js +2 -1
- package/sdk/dist/index.js.map +1 -1
- package/sdk/dist/namespaces/auth.d.ts +16 -1
- package/sdk/dist/namespaces/auth.d.ts.map +1 -1
- package/sdk/dist/namespaces/auth.js.map +1 -1
- package/sdk/dist/namespaces/buzz.d.ts +4 -2
- package/sdk/dist/namespaces/buzz.d.ts.map +1 -1
- package/sdk/dist/namespaces/buzz.js +4 -2
- package/sdk/dist/namespaces/buzz.js.map +1 -1
- package/sdk/dist/namespaces/deploy.d.ts.map +1 -1
- package/sdk/dist/namespaces/deploy.js +127 -5
- package/sdk/dist/namespaces/deploy.js.map +1 -1
- package/sdk/dist/namespaces/deploy.types.d.ts +80 -22
- package/sdk/dist/namespaces/deploy.types.d.ts.map +1 -1
- package/sdk/dist/namespaces/deploy.types.js +2 -0
- package/sdk/dist/namespaces/deploy.types.js.map +1 -1
- package/sdk/dist/namespaces/functions.d.ts.map +1 -1
- package/sdk/dist/namespaces/functions.js +4 -0
- package/sdk/dist/namespaces/functions.js.map +1 -1
- package/sdk/dist/namespaces/functions.types.d.ts +8 -1
- package/sdk/dist/namespaces/functions.types.d.ts.map +1 -1
- package/sdk/dist/namespaces/org.d.ts +1 -1
- package/sdk/dist/namespaces/org.js +1 -1
- package/sdk/dist/namespaces/org.types.d.ts +1 -1
- package/sdk/dist/namespaces/repos.d.ts +12 -12
- package/sdk/dist/namespaces/repos.d.ts.map +1 -1
- package/sdk/dist/namespaces/repos.js +9 -9
- package/sdk/dist/namespaces/repos.js.map +1 -1
- package/sdk/dist/namespaces/vault.crypto.js +2 -2
- package/sdk/dist/namespaces/vault.crypto.js.map +1 -1
- package/sdk/dist/node/deploy-manifest.d.ts.map +1 -1
- package/sdk/dist/node/deploy-manifest.js +9 -0
- package/sdk/dist/node/deploy-manifest.js.map +1 -1
- package/sdk/dist/node/index.d.ts +4 -2
- package/sdk/dist/node/index.d.ts.map +1 -1
- package/sdk/dist/node/index.js +13 -2
- package/sdk/dist/node/index.js.map +1 -1
- package/sdk/dist/node/tool-declarations.d.ts +88 -0
- package/sdk/dist/node/tool-declarations.d.ts.map +1 -0
- package/sdk/dist/node/tool-declarations.js +587 -0
- package/sdk/dist/node/tool-declarations.js.map +1 -0
- package/sdk/dist/node/vault-address.d.ts +2 -2
- package/sdk/dist/node/vault-address.js +2 -2
- package/sdk/dist/node/vault-address.js.map +1 -1
- package/sdk/dist/node/vault-keystore.d.ts +6 -6
- package/sdk/dist/node/vault-keystore.d.ts.map +1 -1
- package/sdk/dist/node/vault-keystore.js +5 -5
- package/sdk/dist/node/vault-keystore.js.map +1 -1
- package/sdk/dist/node/vault-member-bundle.js +1 -1
- package/sdk/dist/node/vault-member-bundle.js.map +1 -1
- package/sdk/dist/node/vault-prewarm.d.ts +23 -2
- package/sdk/dist/node/vault-prewarm.d.ts.map +1 -1
- package/sdk/dist/node/vault-prewarm.js +34 -2
- package/sdk/dist/node/vault-prewarm.js.map +1 -1
- package/sdk/dist/node/vault-publication.d.ts +13 -13
- package/sdk/dist/node/vault-publication.d.ts.map +1 -1
- package/sdk/dist/node/vault-publication.js +19 -20
- package/sdk/dist/node/vault-publication.js.map +1 -1
- package/sdk/dist/secret-gate.js +1 -1
- package/sdk/dist/secret-gate.js.map +1 -1
- package/sdk/dist/type-contract.d.ts.map +1 -1
- package/sdk/dist/type-contract.js +6 -0
- package/sdk/dist/type-contract.js.map +1 -1
package/README.md
CHANGED
|
@@ -443,7 +443,7 @@ const result = await r.up({ name: "my-app", manifest: "run402.json" }, { approva
|
|
|
443
443
|
console.log(result);
|
|
444
444
|
```
|
|
445
445
|
|
|
446
|
-
The SDK is organised into focused namespaces: `actions` (Node recursive action runner), `pay` (bounded arbitrary-URL x402 buyer), `projects`, `snapshots`, `branches`, `archives`, `assets`, `cache`, `ci`, `sites`, `functions`, `jobs`, `secrets`, `subdomains`, `domains`, `projects.stripe` (the organization's own Stripe account: `account`, `onboardingLinks`, `checkoutSessions`, `portalSessions`), `push` (web push notification status and per-message deliveries: `status`, `getMessage`), `appRepos` (plain git repositories the app owns: `list`, `create`, `get`, `delete`, `log`, `readFile`, `tree`, `diff`, `commit`, `revert`; not the encrypted `repos` vaults), `email` (+ `webhooks`), `auth`, `apps`, `tier`, `billing`, `contracts`, `ai`, `wallets` (the local wallet: `status`, `create`, `export`, `faucet`; plus the server label), `service`, `admin`, `session` (a person's sign-in session: `run402 login` loopback and `--device` seams plus the browser surface), `writeApproval` (the passkey write approval behind `run402 approve`), `me` (account overview and status), `wallets` (signed server-side wallet label), `orgs` (org-owned control plane + `r.org(id)` sub-client), `grants` (per-project capability grants), and `identityLinks` (public, protocol-discriminated human/agent Nostr attribution), plus `const project = await r.project(id); await project.apply(spec)` for staged multi-resource writes (release slices + assets slice via `/apply/v1/*`). Every operation throws a typed `Run402Error` subclass on failure: `PaymentRequired`, `PaymentBuyerError`, `ProjectNotFound`, `Unauthorized`, `ApiError`, `NetworkError`, `LocalError`, `Run402DeployError`. `apply()` automatically re-plans safe current-base `BASE_RELEASE_CONFLICT` races and emits `apply.retry` progress events. See [`sdk/README.md`](./sdk/README.md).
|
|
446
|
+
The SDK is organised into focused namespaces: `actions` (Node recursive action runner), `pay` (bounded arbitrary-URL x402 buyer), `projects`, `snapshots`, `branches`, `archives`, `assets`, `cache`, `ci`, `sites`, `functions`, `jobs`, `secrets`, `subdomains`, `domains`, `projects.stripe` (the organization's own Stripe account: `account`, `onboardingLinks`, `checkoutSessions`, `portalSessions`), `push` (web push notification status and per-message deliveries: `status`, `getMessage`), `appRepos` (plain git repositories the app owns: `list`, `create`, `get`, `delete`, `log`, `readFile`, `tree`, `diff`, `commit`, `revert`; not the encrypted `repos` vaults), `email` (+ `webhooks`), `auth`, `apps`, `tier`, `billing`, `contracts`, `ai`, `wallets` (the local wallet: `status`, `create`, `import` (a key, or an AWS KMS key by reference with `{ kms }`), `send` (USDC, from the wallet or a smart wallet it owns), `export`, `faucet`; plus the server label), `service`, `admin`, `session` (a person's sign-in session: `run402 login` loopback and `--device` seams plus the browser surface), `writeApproval` (the passkey write approval behind `run402 approve`), `me` (account overview and status), `wallets` (signed server-side wallet label), `orgs` (org-owned control plane + `r.org(id)` sub-client), `grants` (per-project capability grants), and `identityLinks` (public, protocol-discriminated human/agent Nostr attribution), plus `const project = await r.project(id); await project.apply(spec)` for staged multi-resource writes (release slices + assets slice via `/apply/v1/*`). Every operation throws a typed `Run402Error` subclass on failure: `PaymentRequired`, `PaymentBuyerError`, `ProjectNotFound`, `Unauthorized`, `ApiError`, `NetworkError`, `LocalError`, `Run402DeployError`. `apply()` automatically re-plans safe current-base `BASE_RELEASE_CONFLICT` races and emits `apply.retry` progress events. See [`sdk/README.md`](./sdk/README.md).
|
|
447
447
|
|
|
448
448
|
## Buzz/Nostr identity links
|
|
449
449
|
|
package/dist/docs/llms-sdk.txt
CHANGED
|
@@ -1039,7 +1039,7 @@ const active = await p.apply.getActiveRelease();
|
|
|
1039
1039
|
const diff = await p.apply.diff({ from: "empty", to: "active", limit: 1000 });
|
|
1040
1040
|
```
|
|
1041
1041
|
|
|
1042
|
-
`getRelease` / `getActiveRelease` return `ReleaseInventory` (`kind: "release_inventory"`, `state_kind: "current_live" | "effective" | "desired_manifest"`, site paths, `static_public_paths`, functions, secret keys, subdomains, materialized routes, applied migrations, `release_generation`, `static_manifest_sha256`, nullable `static_manifest_metadata`, `embedding` (the release's framing opt-in as catalog keys, or `null`; absent on an older gateway), `sign_in_path` (the app's own sign-in page for MCP authorization, or `null` for the hosted page; absent on an older gateway), `noindex` (`true` when every response of the host carries `X-Robots-Tag: noindex, nofollow, nosnippet`; absent on an older gateway), and inventory warnings when returned). `site.paths` is the release static asset inventory; `static_public_paths[]` is the browser reachability inventory with `public_path`, `asset_path`, `reachability_authority`, `direct`, `cache_class`, `content_type`, and optional route metadata. `reachability_authority` explains whether reachability came from implicit file-path mode, explicit `site.public_paths`, or a route-only static alias. `static_manifest_metadata: null` means unavailable, not zero; when present it includes `file_count`, `total_bytes`, `cache_classes`, `cache_class_sources`, and `spa_fallback`. `diff` returns `ReleaseToReleaseDiff` (`kind: "release_diff"`) with `migrations.applied_between_releases`; secret and subdomain diffs have only `added` / `removed`, never `changed`; route diffs expose `routes.added` / `removed` / `changed`; `static_assets` exposes unchanged/changed/added/removed files, `newly_uploaded_cas_bytes`, `reused_cas_bytes`, `deployment_copy_bytes_eliminated`, `legacy_immutable_warnings`, `previous_immutable_failures`, and `cas_authorization_failures`.
|
|
1042
|
+
`getRelease` / `getActiveRelease` return `ReleaseInventory` (`kind: "release_inventory"`, `state_kind: "current_live" | "effective" | "desired_manifest"`, site paths, `static_public_paths`, functions (each with the `tools` the app serves at `/_run402/mcp`: `{ name, title?, description, input, annotations?, method, path }[]`, present when it has any; the single-tool field is gone), secret keys, subdomains, materialized routes, applied migrations, `release_generation`, `static_manifest_sha256`, nullable `static_manifest_metadata`, `embedding` (the release's framing opt-in as catalog keys, or `null`; absent on an older gateway), `sign_in_path` (the app's own sign-in page for MCP authorization, or `null` for the hosted page; absent on an older gateway), `noindex` (`true` when every response of the host carries `X-Robots-Tag: noindex, nofollow, nosnippet`; absent on an older gateway), and inventory warnings when returned). `site.paths` is the release static asset inventory; `static_public_paths[]` is the browser reachability inventory with `public_path`, `asset_path`, `reachability_authority`, `direct`, `cache_class`, `content_type`, and optional route metadata. `reachability_authority` explains whether reachability came from implicit file-path mode, explicit `site.public_paths`, or a route-only static alias. `static_manifest_metadata: null` means unavailable, not zero; when present it includes `file_count`, `total_bytes`, `cache_classes`, `cache_class_sources`, and `spa_fallback`. `diff` returns `ReleaseToReleaseDiff` (`kind: "release_diff"`) with `migrations.applied_between_releases`; secret and subdomain diffs have only `added` / `removed`, never `changed`; route diffs expose `routes.added` / `removed` / `changed`; `tools` lists the app's tool names under `added` / `removed` / `changed` (a plan's `diff.tools` has the same shape, and a changed function names `tools` in `fields_changed`); `static_assets` exposes unchanged/changed/added/removed files, `newly_uploaded_cas_bytes`, `reused_cas_bytes`, `deployment_copy_bytes_eliminated`, `legacy_immutable_warnings`, `previous_immutable_failures`, and `cas_authorization_failures`.
|
|
1043
1043
|
|
|
1044
1044
|
#### `ReleaseSpec` shape
|
|
1045
1045
|
|
|
@@ -1065,7 +1065,23 @@ The full type is exported as `ReleaseSpec` from `@run402/sdk` and `@run402/sdk/n
|
|
|
1065
1065
|
```
|
|
1066
1066
|
|
|
1067
1067
|
- Replace vs patch semantics per resource. `site.replace` = "this is the whole site" (files absent are removed). `site.patch.put` / `patch.delete` = surgical updates. `site.public_paths` is the browser reachability table and is separate from release asset paths: `{ mode: "explicit", replace: { "/events": { asset: "events.html", cache_class: "html" } } }` serves public `/events` from release asset `events.html`; in explicit mode `/events.html` is not public unless separately declared. `{ mode: "implicit" }` restores filename-derived public reachability and can widen access. Public-path-only site specs are deployable. Known static `cache_class` inputs are `html`, `immutable_versioned`, and `revalidating_asset`; preserve unknown strings returned by observability APIs. `functions` has the same replace/patch split. Secrets are declaration-only: use `r.project(id).secrets.set(key, { value })` for values, then `secrets.require[]` to assert keys exist and `secrets.delete[]` to remove keys at activation. `subdomains` supports exactly one mode per spec: `set` replaces the release's managed subdomain list, `add` appends without removing existing entries, and `remove` deletes named entries. Today `subdomains.set` accepts at most one subdomain per project; multi-subdomain `set` is rejected locally with `SUBDOMAIN_MULTI_NOT_SUPPORTED`. Top-level absence = leave untouched.
|
|
1068
|
-
- FunctionSpec. `functions.replace` is the complete desired function map; `functions.patch.set` updates only listed functions, and `functions.patch.delete` removes listed names. Each function accepts `runtime?: "node22"`, exactly one code source (`source` for a single bundled module, or `files` plus `entrypoint` for multi-file functions), optional `config.timeoutSeconds`, optional `config.memoryMb`, optional `triggers[]`, and the auth-gate fields `requireAuth` and `requireRole`. A schedule is a schedule trigger, and `{ type: "schedule", cron: "0 9 * * *" }` is a complete one: the gateway derives its `id` from the cron and timezone (`sched_` + 12 hex; name it with `id` to keep its identity across cron edits), defaults `timezone` to `UTC`, and defaults `run` to `{ event_type: "<function_name>.schedule", payload: {} }` (`run` may also carry `retry` and `expires_after_seconds`); the plan's `schedule_triggers` shows every default. Each scheduled tick creates a durable function run. A `functions.patch.set` entry without `source` keeps the deployed function and replaces only the fields it names, which is how `r.functions.schedule(projectId, name, cron, { timezone?, id? })` and `r.functions.unschedule(projectId, name, { id? })` change a schedule without code. Email and app-repo triggers need an `id`. Email triggers use `{ id, type: "email", mailbox, events, run }`, where `mailbox` is a mailbox slug/id and `events` is any of `reply_received`, `delivery`, `bounced`, `complained`, `mailbox_suspended`, `sender_suspended`; each matching email event creates a durable function run with the canonical event payload under `payload.event`. A `mailbox_suspended` trigger fires when the mailbox is abuse-suspended (payload event carries `suspended_reason`, `suspended_at`, `evidence`, `recovery_actions`) and executes independently of the suspended mailbox's send capability — the app observes its own outage without polling or a public webhook URL. A `sender_suspended` trigger fires when one sending address of a catch-all mailbox is suspended (payload event carries `address`, `suspended_reason`, `suspended_at`, `evidence`, `recovery_actions`). A `reply_received` payload carries `delivered_to`. In typed deploy configs, prefer `scheduleTrigger(...)` and `emailTrigger(...)`. `FunctionSpec` also accepts `deps?: string[]` (npm specs) under capability `apply-v1-function-deps`; the gateway installs and bundles them. `r.functions.deploy(..., { deps })` builds a one-function `functions.patch.set` and rides this same unified-apply path.
|
|
1068
|
+
- FunctionSpec. `functions.replace` is the complete desired function map; `functions.patch.set` updates only listed functions, and `functions.patch.delete` removes listed names. Each function accepts `runtime?: "node22"`, exactly one code source (`source` for a single bundled module, or `files` plus `entrypoint` for multi-file functions), optional `config.timeoutSeconds`, optional `config.memoryMb`, optional `triggers[]`, optional `tools[]` (the function's MCP tools; see "MCP tools" below), and the auth-gate fields `requireAuth` and `requireRole`. A schedule is a schedule trigger, and `{ type: "schedule", cron: "0 9 * * *" }` is a complete one: the gateway derives its `id` from the cron and timezone (`sched_` + 12 hex; name it with `id` to keep its identity across cron edits), defaults `timezone` to `UTC`, and defaults `run` to `{ event_type: "<function_name>.schedule", payload: {} }` (`run` may also carry `retry` and `expires_after_seconds`); the plan's `schedule_triggers` shows every default. Each scheduled tick creates a durable function run. A `functions.patch.set` entry without `source` keeps the deployed function and replaces only the fields it names, which is how `r.functions.schedule(projectId, name, cron, { timezone?, id? })` and `r.functions.unschedule(projectId, name, { id? })` change a schedule without code. Email and app-repo triggers need an `id`. Email triggers use `{ id, type: "email", mailbox, events, run }`, where `mailbox` is a mailbox slug/id and `events` is any of `reply_received`, `delivery`, `bounced`, `complained`, `mailbox_suspended`, `sender_suspended`; each matching email event creates a durable function run with the canonical event payload under `payload.event`. A `mailbox_suspended` trigger fires when the mailbox is abuse-suspended (payload event carries `suspended_reason`, `suspended_at`, `evidence`, `recovery_actions`) and executes independently of the suspended mailbox's send capability — the app observes its own outage without polling or a public webhook URL. A `sender_suspended` trigger fires when one sending address of a catch-all mailbox is suspended (payload event carries `address`, `suspended_reason`, `suspended_at`, `evidence`, `recovery_actions`). A `reply_received` payload carries `delivered_to`. In typed deploy configs, prefer `scheduleTrigger(...)` and `emailTrigger(...)`. `FunctionSpec` also accepts `deps?: string[]` (npm specs) under capability `apply-v1-function-deps`; the gateway installs and bundles them. `r.functions.deploy(..., { deps })` builds a one-function `functions.patch.set` and rides this same unified-apply path.
|
|
1069
|
+
- MCP tools (`FunctionSpec.tools`). Every app is an MCP server at `https://<host>/_run402/mcp`, and a function's tools ride its release entry: `tools?: FunctionToolSpec[]`, each `{ name?, title?, description, input, annotations?, method?, path? }`. A tool names one request its function answers (`method`, default `POST`, and `path`, which may hold `{param}` segments; with no `path`, the function's one exact `POST` route), and calling the tool is that request: path parameters fill the path, the other arguments are the query string on `GET` / `DELETE` and the JSON body on `POST` / `PATCH` / `PUT`. A `GET` tool is listed read-only unless `annotations.readOnlyHint` is `false`. The release entry is the only carrier, exactly like `triggers`: the gateway never reads function source for tools, an entry sent with no `tools` has none, and a function the spec does not name keeps the ones it has.
|
|
1070
|
+
- **You normally never write the field.** A function file declares its tools beside the handler, as static literals: `export const tool = { description, input }` (one tool, named after the function unless it states `name`) or `export const tools = { list_events: { … }, create_event: { … } }` (several, the key as the name; never both exports). `@run402/sdk/node` reads that export from the entry source of every function a deploy reads (`apply`, `r.up`, `r.functions.deploy` and a spec from the manifest adapter all pass through it), by parsing and never by running it, and sends `tools`: one entry as written for `tool`, one per key for `tools`, `[]` when the source declares none. A stated `tools`, even `[]`, is sent as written and the source is not read for it; `@run402/astro` relies on that to carry the tools of a project's endpoint files on the `ssr` function. A `patch.set` entry with no `source` sends no `tools` and keeps the function's tools (a schedule or config edit). A source the SDK does not read (a pre-resolved `ContentRef`, or a `files` entrypoint given as a `ReadableStream`, which can be read only once) gets no `tools` from it, and the function deploys with none unless you state `tools`; the plan's `diff.tools.removed` shows it.
|
|
1071
|
+
- **The isomorphic entry carries `tools` as data.** `@run402/sdk` has no parser, so it forwards `tools` when you pass it and reads no source. Over raw HTTP it is the same: send `functions.<name>.tools` yourself; an export in the source means nothing to the gateway.
|
|
1072
|
+
- **Refusals come before any request,** as `Run402DeployError` with the gateway's code for the same condition, `resource` `functions.<function>.tools[.<tool>]`, `details: { function, tool?, file, line?, field_path }` (`line` only when it is exact) and an `edit_request` next action: `MCP_TOOL_NOT_STATIC` (a variable, call, spread, computed key or `${…}` template; a reassigned or re-exported binding; an unparseable file), `MCP_TOOL_SCHEMA_INVALID` (shape), `MCP_TOOL_NAME_INVALID`, `MCP_TOOL_NAME_DUPLICATE` (two tools of one spec), `MCP_TOOL_PATH_UNSUPPORTED` (a wildcard or rest segment). The gateway raises the same codes at the plan (HTTP 422), plus `MCP_TOOL_ROUTE_MISSING`, `MCP_TOOL_ROUTE_AMBIGUOUS` and `MCP_TOOL_ROUTE_ELSEWHERE` for the binding. The plan's `diff.tools` (`{ added, removed, changed }`, tool names) shows what a deploy would do before anything is uploaded.
|
|
1073
|
+
- **The reader is exported.** `extractToolDeclarations(source, { file?, endpoint? })` from `@run402/sdk/node` returns `{ ok: true, tools }` or `{ ok: false, problem: { code, message, file, line?, field_path, tool? } }`. It tries the source as JavaScript, then erases types with Node's `module.stripTypeScriptTypes` (lines stay exact), then transforms syntax that cannot be erased, such as an `enum` (no line is reported); it follows a local binding through an `export { }` clause, so it reads an esbuild bundle, minified or not. With `endpoint: { route, base?, trailingSlash?, prerendered? }` it reads an Astro endpoint file: every tool carries `name`, `method` (the one handler the file exports unless stated) and `path` (the route, `[param]` as `{param}`).
|
|
1074
|
+
|
|
1075
|
+
```ts
|
|
1076
|
+
import { extractToolDeclarations } from "@run402/sdk/node";
|
|
1077
|
+
|
|
1078
|
+
const read = extractToolDeclarations(
|
|
1079
|
+
`export const tools = { list_events: { method: "GET", path: "/api/events", description: "List events.", input: { type: "object" } } };`,
|
|
1080
|
+
{ file: "functions/portal.ts" },
|
|
1081
|
+
);
|
|
1082
|
+
if (read.ok) console.log(read.tools); // [{ name: "list_events", description: "List events.", input: { type: "object" }, method: "GET", path: "/api/events" }]
|
|
1083
|
+
else console.error(read.problem.code, read.problem.file, read.problem.line, read.problem.field_path);
|
|
1084
|
+
```
|
|
1069
1085
|
- Function-level auth gates. Each `FunctionSpec` carries two optional declarative fields enforced by the gateway before invocation:
|
|
1070
1086
|
- `requireAuth?: boolean` — when `true`, gateway rejects callers without a valid project user JWT with `Run402DeployError`-shaped envelope or `401` at request time. No DB lookup. Independent from `requireRole`.
|
|
1071
1087
|
- `requireRole?: RequireRoleSpec | null` — gateway resolves the caller's role from the project-schema table and rejects callers whose role is not in `allowed` with `403`. Implies authentication (no JWT → 401). Pass `null` in patch mode to remove an existing gate. `RequireRoleSpec` is `{ table: string; idColumn: string; roleColumn: string; allowed: string[]; cacheTtl?: number }`. All identifiers are unqualified; `cacheTtl` is seconds (default 60, max 600, 0 disables caching for instant-revocation paths).
|
|
@@ -2070,9 +2086,11 @@ r.archives.importToCore(opts: {
|
|
|
2070
2086
|
```
|
|
2071
2087
|
deploy(projectId, opts: {
|
|
2072
2088
|
name: string, code: string, config?: { timeout?, memory? },
|
|
2073
|
-
deps?: string[], schedule?: string | null, timezone?: string,
|
|
2089
|
+
deps?: string[], schedule?: string | null, timezone?: string, tools?: FunctionToolSpec[],
|
|
2074
2090
|
}): Promise<FunctionDeployResult> // routes through unified apply (functions.patch.set). schedule is declared as a schedule trigger beside the
|
|
2075
|
-
// function's other triggers (null removes it; omitted keeps the triggers it has).
|
|
2091
|
+
// function's other triggers (null removes it; omitted keeps the triggers it has). tools: leave out with @run402/sdk/node, which reads
|
|
2092
|
+
// `export const tool` / `export const tools` from code and sends them ([] for none); pass it to carry MCP tools as data. A deploy
|
|
2093
|
+
// replaces the function, so with neither it has no tools afterwards. result: { name, url, status, runtime, triggers, warnings },
|
|
2076
2094
|
// triggers as stored; runtime_version & deps_resolved are null via this path - read r.functions.list() for resolved versions
|
|
2077
2095
|
invoke(projectId, name, opts?: { method?, body?, headers?, idempotencyKey?, wait? }): Promise<FunctionInvokeResult> // paid calls require a stable idempotencyKey; wait polls a 202 run handle and replays the same key for the retained result
|
|
2078
2096
|
logs(projectId, name, opts?: { tail?, since?, until?, requestId?, origin? }): Promise<FunctionLogsResult>
|
|
@@ -2489,7 +2507,7 @@ testAndWait(routeId, { pollMs?, timeoutMs?, onPoll? })
|
|
|
2489
2507
|
// cadence, not failure (the shared waitFor contract).
|
|
2490
2508
|
```
|
|
2491
2509
|
|
|
2492
|
-
Only
|
|
2510
|
+
Only seven reviewed event types are routable (`agent_claim_created`, `agent_claim_released`, `agent_message_sent`, `deploy_activated`, `error_fingerprints_observed`, `platform_incident`, `platform_payment_received`); the classes `security` / `billing_critical` / `destructive_lifecycle` / `verification` / `recovery` may never be routed. Filters: omitted/`null` = everything registered; an explicit `[]` is a 422, never a wildcard. Routes deliver NEW events only (`start_after_event_id` floor); delivery is at-least-once with byte-identical republish, backing off 1m/5m/30m/2h/12h to 8 attempts or 48h, then `dead_letter` — visible in `deliveries()`. Ten consecutive hard failures auto-pause the route (`pause_reason: "delivery_failures"`) and fire the mandatory `buzz_route_auto_paused` owner notification. No response ever contains the signing secret — `notification_pubkey` + `signing_generation` are the only credential material on the wire. Every mutation carries an `Idempotency-Key` (auto-generated when omitted) and requires fresh `buzz.event_route` step-up server-side (a SIWX wallet is inherently fresh).
|
|
2493
2511
|
|
|
2494
2512
|
### `r.repos`
|
|
2495
2513
|
|
|
@@ -2810,7 +2828,7 @@ verifyEmailCode(projectId, { challengeId, code }): Promise<MagicLinkVerifyResult
|
|
|
2810
2828
|
createUser(projectId, opts: { email, isAdmin?, sendInvite?, redirectUrl?, clientState? }): Promise<AuthUserAdminResult>
|
|
2811
2829
|
inviteUser(projectId, opts: { email, isAdmin?, redirectUrl, clientState? }): Promise<AuthUserAdminResult>
|
|
2812
2830
|
getUser(projectId, opts: { email }): Promise<AuthUserRecord> // { id, email, is_admin, is_test, email_verified_at, created_at }; read-only
|
|
2813
|
-
createTestSession(projectId, opts: { label, isAdmin? }): Promise<TestSessionResult> // { user, session, access_token, expires_in, ... }
|
|
2831
|
+
createTestSession(projectId, opts: { label, isAdmin? }): Promise<TestSessionResult> // { user, session, access_token, expires_in, app_origins, mcp?, examples, ... }
|
|
2814
2832
|
setUserPassword(projectId, opts: { accessToken, newPassword, currentPassword? }): Promise<void>
|
|
2815
2833
|
settings(projectId, opts: {
|
|
2816
2834
|
allow_password_set?,
|
|
@@ -2850,7 +2868,7 @@ Native Sign in with Apple (an iPhone app's own sheet) needs the app's bundle ID
|
|
|
2850
2868
|
|
|
2851
2869
|
`getUser` looks one project user up by email (case-insensitive) with the service key and changes nothing: a member or a test user (`is_test: true`), so a role table keyed by user id can be seeded. No match throws the gateway's 404 `AUTH_USER_NOT_FOUND`, whose `next_actions` name the create route.
|
|
2852
2870
|
|
|
2853
|
-
`createTestSession` mints a 2-hour session (cookie value and bearer token) for the test user `<label>@<project_id>.test.invalid`, created on first use and reused by label; a test user is never a real member and carries `is_test: true` everywhere. It needs the service key and the project's test mode (on by default for prototype; otherwise `403 TEST_MODE_DISABLED`; `r.auth.settings(projectId, { test_mode: true })` enables it). Because it returns
|
|
2871
|
+
`createTestSession` mints a 2-hour session (cookie value and bearer token) for the test user `<label>@<project_id>.test.invalid`, created on first use and reused by label; a test user is never a real member and carries `is_test: true` everywhere. It needs the service key and the project's test mode (on by default for prototype; otherwise `403 TEST_MODE_DISABLED`; `r.auth.settings(projectId, { test_mode: true })` enables it). When the project has a host that serves its routes, the bundle also carries `mcp: { url, access_token, expires_at }`: `url` is the app's `/_run402/mcp` on `app_origins[0]` and `access_token` is an MCP access token for the test user, valid only there and for no longer than the test session, so a script can `POST` `tools/list` or `tools/call` to `mcp.url` with `Authorization: Bearer <mcp.access_token>` and run the app's tools as that user, through the app's own middleware, with no browser and no consent screen. `examples.mcp` is a ready-to-run `tools/list` call (`null` when there is no origin), beside `examples.ssr` and `examples.rest`. Because it returns credentials it refuses on the MCP `run` sandbox (`SECRET_REQUIRES_CLI`). `run402 dev --as <label>` hands the cookie and bearer to the local dev server without printing them, and does not use the MCP token; to call the app's tools as the test user, mint the session from an `@run402/sdk/node` script, or `POST /auth/v1/test-sessions` with the service key and run its `examples.mcp`.
|
|
2854
2872
|
|
|
2855
2873
|
### `r.apps`
|
|
2856
2874
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "run402-mcp",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.155.1",
|
|
4
4
|
"packageManager": "npm@11.19.0",
|
|
5
5
|
"mcpName": "com.run402/mcp",
|
|
6
6
|
"description": "MCP server for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.",
|
|
@@ -34,8 +34,8 @@
|
|
|
34
34
|
"test:buzz-installer": "node buzz/install-smoke.mjs",
|
|
35
35
|
"test:sync": "node --test --import tsx sync.test.ts scripts/types-node-engines.test.mjs examples/tenant-x402-wallet-stats/example.test.mjs examples/static-config-js/example.test.mjs",
|
|
36
36
|
"test:docs": "node scripts/check-typed-config-docs.mjs && npm run check:docs --workspace=@run402/sdk -- --skip-build && npm run test:docs:quality",
|
|
37
|
-
"test": "npm run build && node scripts/build-agent-skills-index.mjs --check && node scripts/build-vault-surface.mjs --check && node --experimental-test-module-mocks --test --import tsx SKILL.test.ts sync.test.ts buzz/setup.test.mjs buzz/helper.test.mjs buzz/package.test.mjs scripts/build-agent-skills-index.test.mjs scripts/build-agent-flat-docs.test.mjs scripts/build-vault-surface.test.mjs scripts/types-node-engines.test.mjs examples/tenant-x402-wallet-stats/example.test.mjs examples/static-config-js/example.test.mjs 'core/src/**/*.test.ts' 'sdk/src/**/*.test.ts' 'src/**/*.test.ts' mcp-integration.test.ts && node --test cli-core-target.test.mjs mcp-vendored-sdk-imports.test.mjs scripts/publish-idempotent.test.mjs && node --experimental-test-module-mocks --test cli-up-argv.test.mjs cli-up-repo-compose.test.mjs cli-repos-surface.test.mjs cli-repos-naming.test.mjs cli-projects-vault-scaffold.test.mjs cli-identity-link.test.mjs cli-identity-link-matrix.test.mjs cli-redeem.test.mjs cli-rooms-context-session-key.test.mjs cli-messages-wait.test.mjs cli-rooms-invite-key-leak.test.mjs cli-rooms-join-arrival.test.mjs cli/lib/buzz.test.mjs cli/lib/qr-png.test.mjs && node --test cli-help-listing.test.mjs cli-module-references.test.mjs cli-output-contract.test.mjs cli-json-noop-contract.test.mjs cli-e2e.test.mjs cli-help.test.mjs cli-subscriptions-help.test.mjs cli-provision-active.test.mjs cli-typed-config-modes.test.mjs cli-argv.test.mjs cli-repos-naming.test.mjs cli-conventions-gate.test.mjs cli-doctor.test.mjs cli-rest-diagnostics.test.mjs cli-credentials.test.mjs paid-stack-deps.test.mjs published-dependencies.test.mjs settlement-disclosure.test.mjs cli-suggestions-gate.test.mjs sdk-boundary-gate.test.mjs cli-env.test.mjs cli-wallets.test.mjs cli-org.test.mjs cli-org-context.test.mjs cli-image-org.test.mjs cli-harness-context.test.mjs cli-ci.test.mjs cli-snapshots.test.mjs cli-stripe.test.mjs cli-push.test.mjs cli-app-repos.test.mjs cli-deploy-ci.test.mjs cli-login-loopback.test.mjs cli-vault-remote-helper.test.mjs cli-vault-daemon.test.mjs cli-deploy-vault-lane.test.mjs cli/lib/buzz-doctor.test.mjs cli/lib/diagnostic-telemetry.test.mjs cli/lib/doctor-source-scan.test.mjs cli/lib/errors.test.mjs cli/lib/argparse.test.mjs cli/lib/manifest.test.mjs cli/lib/wallet-context.test.mjs cli-project-env-fallback.test.mjs cli/lib/path-lookup.test.mjs cli/lib/pay.test.mjs cli/lib/up.test.mjs cli/lib/deploy-rehearse-discovery.test.mjs cli/lib/update-check.test.mjs cli-bootstrap-next-actions.test.mjs cli-sdk-errors-room-invite-hint.test.mjs cli-dev-as.test.mjs && npm run test:docs",
|
|
38
|
-
"test:e2e": "npm run build && node --test cli-core-target.test.mjs && node --experimental-test-module-mocks --test cli-repos-surface.test.mjs cli-repos-naming.test.mjs cli-up-repo-compose.test.mjs cli-projects-vault-scaffold.test.mjs cli-identity-link.test.mjs cli-identity-link-matrix.test.mjs cli-redeem.test.mjs cli-rooms-context-session-key.test.mjs cli-messages-wait.test.mjs cli-rooms-invite-key-leak.test.mjs cli-rooms-join-arrival.test.mjs && node --test cli-help-listing.test.mjs cli-module-references.test.mjs cli-output-contract.test.mjs cli-json-noop-contract.test.mjs cli-e2e.test.mjs cli-help.test.mjs cli-subscriptions-help.test.mjs cli-provision-active.test.mjs cli-typed-config-modes.test.mjs cli-argv.test.mjs cli-repos-naming.test.mjs cli-conventions-gate.test.mjs cli-doctor.test.mjs cli-rest-diagnostics.test.mjs cli-credentials.test.mjs paid-stack-deps.test.mjs published-dependencies.test.mjs settlement-disclosure.test.mjs cli-suggestions-gate.test.mjs sdk-boundary-gate.test.mjs cli-env.test.mjs cli-wallets.test.mjs cli-org.test.mjs cli-org-context.test.mjs cli-image-org.test.mjs cli-harness-context.test.mjs cli-ci.test.mjs cli-snapshots.test.mjs cli-stripe.test.mjs cli-push.test.mjs cli-app-repos.test.mjs cli-deploy-ci.test.mjs cli-login-loopback.test.mjs cli-vault-remote-helper.test.mjs cli-vault-daemon.test.mjs cli-deploy-vault-lane.test.mjs cli/lib/buzz-doctor.test.mjs cli/lib/diagnostic-telemetry.test.mjs cli/lib/doctor-source-scan.test.mjs cli/lib/errors.test.mjs cli/lib/path-lookup.test.mjs cli/lib/up.test.mjs cli/lib/update-check.test.mjs cli-bootstrap-next-actions.test.mjs cli-sdk-errors-room-invite-hint.test.mjs",
|
|
37
|
+
"test": "npm run build && node scripts/build-agent-skills-index.mjs --check && node scripts/build-vault-surface.mjs --check && node --experimental-test-module-mocks --test --import tsx SKILL.test.ts sync.test.ts buzz/setup.test.mjs buzz/helper.test.mjs buzz/package.test.mjs scripts/build-agent-skills-index.test.mjs scripts/build-agent-flat-docs.test.mjs scripts/build-vault-surface.test.mjs scripts/types-node-engines.test.mjs examples/tenant-x402-wallet-stats/example.test.mjs examples/static-config-js/example.test.mjs 'core/src/**/*.test.ts' 'sdk/src/**/*.test.ts' 'src/**/*.test.ts' mcp-integration.test.ts && node --test cli-core-target.test.mjs mcp-vendored-sdk-imports.test.mjs scripts/publish-idempotent.test.mjs && node --experimental-test-module-mocks --test cli-up-argv.test.mjs cli-up-repo-compose.test.mjs cli-repos-surface.test.mjs cli-repos-naming.test.mjs cli-projects-vault-scaffold.test.mjs cli-identity-link.test.mjs cli-identity-link-matrix.test.mjs cli-redeem.test.mjs cli-rooms-context-session-key.test.mjs cli-messages-wait.test.mjs cli-rooms-invite-key-leak.test.mjs cli-rooms-join-arrival.test.mjs cli/lib/buzz.test.mjs cli/lib/qr-png.test.mjs && node --test cli-help-listing.test.mjs cli-module-references.test.mjs cli-output-contract.test.mjs cli-json-noop-contract.test.mjs cli-e2e.test.mjs cli-help.test.mjs cli-subscriptions-help.test.mjs cli-provision-active.test.mjs cli-typed-config-modes.test.mjs cli-argv.test.mjs cli-repos-naming.test.mjs cli-conventions-gate.test.mjs cli-doctor.test.mjs cli-rest-diagnostics.test.mjs cli-credentials.test.mjs paid-stack-deps.test.mjs published-dependencies.test.mjs settlement-disclosure.test.mjs cli-suggestions-gate.test.mjs sdk-boundary-gate.test.mjs cli-env.test.mjs cli-wallets.test.mjs cli-org.test.mjs cli-org-context.test.mjs cli-image-org.test.mjs cli-harness-context.test.mjs cli-ci.test.mjs cli-snapshots.test.mjs cli-stripe.test.mjs cli-push.test.mjs cli-app-repos.test.mjs cli-deploy-ci.test.mjs cli-deploy-tools.test.mjs cli-login-loopback.test.mjs cli-vault-remote-helper.test.mjs cli-vault-daemon.test.mjs cli-deploy-vault-lane.test.mjs cli/lib/buzz-doctor.test.mjs cli/lib/diagnostic-telemetry.test.mjs cli/lib/doctor-source-scan.test.mjs cli/lib/errors.test.mjs cli/lib/argparse.test.mjs cli/lib/manifest.test.mjs cli/lib/wallet-context.test.mjs cli-project-env-fallback.test.mjs cli/lib/path-lookup.test.mjs cli/lib/pay.test.mjs cli/lib/up.test.mjs cli/lib/deploy-rehearse-discovery.test.mjs cli/lib/update-check.test.mjs cli-bootstrap-next-actions.test.mjs cli-sdk-errors-room-invite-hint.test.mjs cli-dev-as.test.mjs && npm run test:docs",
|
|
38
|
+
"test:e2e": "npm run build && node --test cli-core-target.test.mjs && node --experimental-test-module-mocks --test cli-repos-surface.test.mjs cli-repos-naming.test.mjs cli-up-repo-compose.test.mjs cli-projects-vault-scaffold.test.mjs cli-identity-link.test.mjs cli-identity-link-matrix.test.mjs cli-redeem.test.mjs cli-rooms-context-session-key.test.mjs cli-messages-wait.test.mjs cli-rooms-invite-key-leak.test.mjs cli-rooms-join-arrival.test.mjs && node --test cli-help-listing.test.mjs cli-module-references.test.mjs cli-output-contract.test.mjs cli-json-noop-contract.test.mjs cli-e2e.test.mjs cli-help.test.mjs cli-subscriptions-help.test.mjs cli-provision-active.test.mjs cli-typed-config-modes.test.mjs cli-argv.test.mjs cli-repos-naming.test.mjs cli-conventions-gate.test.mjs cli-doctor.test.mjs cli-rest-diagnostics.test.mjs cli-credentials.test.mjs paid-stack-deps.test.mjs published-dependencies.test.mjs settlement-disclosure.test.mjs cli-suggestions-gate.test.mjs sdk-boundary-gate.test.mjs cli-env.test.mjs cli-wallets.test.mjs cli-org.test.mjs cli-org-context.test.mjs cli-image-org.test.mjs cli-harness-context.test.mjs cli-ci.test.mjs cli-snapshots.test.mjs cli-stripe.test.mjs cli-push.test.mjs cli-app-repos.test.mjs cli-deploy-ci.test.mjs cli-deploy-tools.test.mjs cli-login-loopback.test.mjs cli-vault-remote-helper.test.mjs cli-vault-daemon.test.mjs cli-deploy-vault-lane.test.mjs cli/lib/buzz-doctor.test.mjs cli/lib/diagnostic-telemetry.test.mjs cli/lib/doctor-source-scan.test.mjs cli/lib/errors.test.mjs cli/lib/path-lookup.test.mjs cli/lib/up.test.mjs cli/lib/update-check.test.mjs cli-bootstrap-next-actions.test.mjs cli-sdk-errors-room-invite-hint.test.mjs",
|
|
39
39
|
"test:help": "npm run build && node --test cli-help.test.mjs",
|
|
40
40
|
"test:integration": "node --test --import tsx core/src/siwx-integration.integ.ts",
|
|
41
41
|
"test:integration:full": "node --test --import tsx cli-integration.test.ts",
|
|
@@ -279,6 +279,13 @@
|
|
|
279
279
|
"$ref": "#/$defs/functionTrigger"
|
|
280
280
|
}
|
|
281
281
|
},
|
|
282
|
+
"tools": {
|
|
283
|
+
"type": "array",
|
|
284
|
+
"description": "The MCP tools this function answers at /_run402/mcp. Usually left out: run402 deploy and run402 up read `export const tool = { ... }` or `export const tools = { name: { ... } }` from the function's source (static literals, parsed and never run) and fill this in, [] when the source declares none. Written here, it is sent as written and the source is not read. The release entry is the only carrier: a function sent with no tools has none.",
|
|
285
|
+
"items": {
|
|
286
|
+
"$ref": "#/$defs/functionTool"
|
|
287
|
+
}
|
|
288
|
+
},
|
|
282
289
|
"requireAuth": {
|
|
283
290
|
"type": "boolean"
|
|
284
291
|
},
|
|
@@ -315,6 +322,70 @@
|
|
|
315
322
|
}
|
|
316
323
|
}
|
|
317
324
|
},
|
|
325
|
+
"functionTool": {
|
|
326
|
+
"type": "object",
|
|
327
|
+
"additionalProperties": false,
|
|
328
|
+
"description": "One MCP tool. A tool names one request its function answers: calling it sends `method` to `path`, each {param} filled from the arguments, the rest as the query string (GET, DELETE) or the JSON body (POST, PATCH, PUT). A GET tool is listed read-only unless annotations.readOnlyHint is false.",
|
|
329
|
+
"required": [
|
|
330
|
+
"description",
|
|
331
|
+
"input"
|
|
332
|
+
],
|
|
333
|
+
"properties": {
|
|
334
|
+
"name": {
|
|
335
|
+
"type": "string",
|
|
336
|
+
"pattern": "^[A-Za-z0-9_.-]{1,128}$",
|
|
337
|
+
"description": "A valid MCP tool name, unique in the release. Omitted, the function name."
|
|
338
|
+
},
|
|
339
|
+
"title": {
|
|
340
|
+
"type": "string",
|
|
341
|
+
"minLength": 1,
|
|
342
|
+
"maxLength": 128
|
|
343
|
+
},
|
|
344
|
+
"description": {
|
|
345
|
+
"type": "string",
|
|
346
|
+
"minLength": 1,
|
|
347
|
+
"maxLength": 1024,
|
|
348
|
+
"description": "What tells an assistant when to call the tool."
|
|
349
|
+
},
|
|
350
|
+
"input": {
|
|
351
|
+
"type": "object",
|
|
352
|
+
"description": "JSON Schema for the arguments; its root type is \"object\". Every {param} of path is a required string or integer property."
|
|
353
|
+
},
|
|
354
|
+
"annotations": {
|
|
355
|
+
"type": "object",
|
|
356
|
+
"additionalProperties": false,
|
|
357
|
+
"properties": {
|
|
358
|
+
"readOnlyHint": {
|
|
359
|
+
"type": "boolean"
|
|
360
|
+
},
|
|
361
|
+
"destructiveHint": {
|
|
362
|
+
"type": "boolean"
|
|
363
|
+
},
|
|
364
|
+
"idempotentHint": {
|
|
365
|
+
"type": "boolean"
|
|
366
|
+
},
|
|
367
|
+
"openWorldHint": {
|
|
368
|
+
"type": "boolean"
|
|
369
|
+
}
|
|
370
|
+
}
|
|
371
|
+
},
|
|
372
|
+
"method": {
|
|
373
|
+
"enum": [
|
|
374
|
+
"GET",
|
|
375
|
+
"POST",
|
|
376
|
+
"PATCH",
|
|
377
|
+
"PUT",
|
|
378
|
+
"DELETE"
|
|
379
|
+
],
|
|
380
|
+
"description": "Default POST."
|
|
381
|
+
},
|
|
382
|
+
"path": {
|
|
383
|
+
"type": "string",
|
|
384
|
+
"pattern": "^/",
|
|
385
|
+
"description": "The request path, with {param} for a segment filled from the arguments. Omitted, the function's one exact POST route."
|
|
386
|
+
}
|
|
387
|
+
}
|
|
388
|
+
},
|
|
318
389
|
"functionTrigger": {
|
|
319
390
|
"type": "object",
|
|
320
391
|
"additionalProperties": true,
|
package/sdk/README.md
CHANGED
|
@@ -57,7 +57,7 @@ The SDK locally rejects secret-shaped inputs and verifies the exact seven-field
|
|
|
57
57
|
|
|
58
58
|
`r.buzz.status()` capability-detects the community control plane and the additive human-adoption offer flow. `r.buzz.offerAdoption(...)` and typed `humanAdoptionOffers.create/get/cancel/createAttempt` expose the durable HTTPS handoff without treating offer creation as consent or authority; the attempt method is for an explicitly authenticated human client. Polling a completed offer returns three distinct effects: the terminal consent receipt, public human identity attribution, and ordinary owner membership. The membership is the only organization-authority source; link and membership revocation are independent and neither rewrites the receipt. Existing `humanAdoptions` direct methods remain advanced compatibility. `communityInstallations` and `enrollments` expose their independent lifecycles; `install(...)` and `enroll(...)` are goal aliases. The SDK generates idempotency keys when omitted, rejects nested secret-shaped fields before network access, never signs Buzz events, and represents enrollment authority only as expiring grants to named existing projects. MCP intentionally omits offer/attempt mutations and renders the exact handoff. Buzz itself remains unchanged. Gateway failures retain their stable code, exact repair `field`, complete `nextActions`, and `safeToRetry`. See the [Fizz/Honey lifecycle](../buzz/references/community-control-plane.md).
|
|
59
59
|
|
|
60
|
-
`r.buzz.notifications` routes selected project events (`deploy_activated`, `error_fingerprints_observed`, `platform_incident` — the
|
|
60
|
+
`r.buzz.notifications` routes selected project events (`agent_claim_created`, `agent_claim_released`, `agent_message_sent`, `deploy_activated`, `error_fingerprints_observed`, `platform_incident`, `platform_payment_received` — the seven reviewed projectors; `security`/`billing_critical`/`destructive_lifecycle`/`verification`/`recovery` classes may never be routed) into a Buzz community channel as signed NIP-29 messages. The workflow is configure → authorize → test → live: `createRoute` returns an `authorization` block whose `pending_buzz_authorization` state carries the one exact non-secret handoff (a Buzz community owner adds the `notification_pubkey` as a relay member), and `testAndWait` queues a signed probe and polls it to a terminal state — on timeout it RETURNS the still-queued delivery rather than throwing (the tick publishes ~every 60s; silence is cadence, not failure). `list`/`get`/`deliveries` are reads (`get` reports honest `health` derived from route + credential state, never queue emptiness); `update` is revision-guarded (`409 BUZZ_ROUTE_REVISION_STALE` without mutation); `pause`/`resume`/`rotate`/`revoke` are the lifecycle. No response carries the signing secret, an empty filter array is rejected rather than treated as a wildcard, routes deliver NEW events only, and Buzz is never a deadman channel — mandatory notification classes keep their human paths regardless of route state.
|
|
61
61
|
|
|
62
62
|
Before creating an x402 payment payload, the Node entry confirms USDC with
|
|
63
63
|
bounded retry/backoff and independent RPC failover on Base and Base Sepolia.
|
|
@@ -601,6 +601,18 @@ const resumed = await (await r.project(projectId)).apply.resume("op_...");
|
|
|
601
601
|
|
|
602
602
|
Plan responses may advertise `rehearsal: { available, rehearse_url, reason }` where `reason` is `null` when available, else `no_migrations`, `no_live_release`, or `migrations_unchanged`; commit results may carry `restore_point` or `snapshot_skipped_reason`. The automatic rehearsal inside `apply()` / `r.up()` reports `rehearsal: { status: "passed", … }` or `{ status: "skipped", reason: "no_live_release" | "no_migrations" | "migrations_unchanged" | "disabled" | "reviewed_plan" | "unsupported" }`; `migrations_unchanged` (gateway-supplied, or derived from the plan's `{ new, noop }` migration buckets when `new` is empty) means every migration is already applied with an identical checksum, so a page-only redeploy that still carries its migrations ships without a branch.
|
|
603
603
|
- **Release observability is typed.** Use `r.project(id).apply.getRelease(releaseId, { siteLimit? })`, `r.project(id).apply.getActiveRelease({ siteLimit? })`, and `r.project(id).apply.diff({ from, to, limit? })` to inspect release inventory and release-to-release diffs (there is no bare `r.deploy` surface). Inventories include `release_generation`, `static_manifest_sha256`, nullable `static_manifest_metadata` (`file_count`, `total_bytes`, `cache_classes`, `cache_class_sources`, `spa_fallback`), and `static_public_paths[]` when returned. `site.paths` lists release static assets; `static_public_paths[]` lists browser reachability with `public_path`, `asset_path`, `reachability_authority`, `direct`, cache class, and content type. `diff` returns `ReleaseToReleaseDiff` with `migrations.applied_between_releases`; secret diffs expose keys only; `static_assets` exposes unchanged/changed/added/removed files, CAS byte reuse, eliminated deployment-copy bytes, and immutable/CAS warning counts.
|
|
604
|
+
- **Your app's MCP tools ride each function's release entry.** Every app is an MCP server at `https://<host>/_run402/mcp`, and `FunctionSpec.tools` (`{ name?, title?, description, input, annotations?, method?, path? }[]`) is the only carrier of its tools: the gateway never reads function source for them, and a function sent with no `tools` has none. With `@run402/sdk/node` you normally leave the field out. A function file declares its tools beside the handler as static literals, `export const tool = { description, input }` or `export const tools = { list_events: { … }, create_event: { … } }`, and the deploy reads that export from every function source it reads, by parsing and never by running it, and sends `tools` (`[]` when the source declares none). A declaration it cannot carry throws `Run402DeployError` before any request, with the gateway's `MCP_TOOL_*` code, `details: { function, tool?, file, line?, field_path }` and an `edit_request` next action. The isomorphic `@run402/sdk` has no parser: it forwards `tools` when you pass it. Release reads list `functions[].tools` (`name`, `description`, `input`, `annotations`, `method`, `path`), and plan and release diffs carry `tools: { added, removed, changed }` by name.
|
|
605
|
+
|
|
606
|
+
```ts
|
|
607
|
+
import { extractToolDeclarations } from "@run402/sdk/node";
|
|
608
|
+
|
|
609
|
+
const read = extractToolDeclarations(
|
|
610
|
+
`export const tool = { description: "Cancel one of the caller's bookings.", input: { type: "object", properties: { booking_id: { type: "string" } }, required: ["booking_id"] } };`,
|
|
611
|
+
{ file: "functions/cancel.ts" },
|
|
612
|
+
);
|
|
613
|
+
if (!read.ok) throw new Error(`${read.problem.code} at ${read.problem.file}:${read.problem.line ?? "?"} (${read.problem.field_path})`);
|
|
614
|
+
console.log(read.tools); // one entry, as written; the gateway names it after the function
|
|
615
|
+
```
|
|
604
616
|
- **Server-authoritative manifest digest** — no byte-for-byte canonicalize requirement on the client.
|
|
605
617
|
- The Node entry adds `fileSetFromDir(path)` for filesystem byte sources:
|
|
606
618
|
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* MCP tools on a function's release entry (`functions.<name>.tools`).
|
|
3
|
+
*
|
|
4
|
+
* A function file or an Astro endpoint file declares its tools beside the
|
|
5
|
+
* handler, as static literals:
|
|
6
|
+
*
|
|
7
|
+
* export const tool = { description: "…", input: { type: "object", … } };
|
|
8
|
+
* export const tools = { list_notes: { … }, add_note: { … } };
|
|
9
|
+
*
|
|
10
|
+
* Deploy tooling reads the export by parsing, never by running it (the Node
|
|
11
|
+
* extractor, `node/tool-declarations.ts`), and carries it in the release. The
|
|
12
|
+
* gateway takes a function's tools only from its release entry: an omitted
|
|
13
|
+
* `tools` means none, as with `triggers`.
|
|
14
|
+
*
|
|
15
|
+
* This module is the isomorphic half: the rules one entry obeys (shared by
|
|
16
|
+
* the extractor and by the spec check for `tools` passed as data), the
|
|
17
|
+
* refusal's shape, the error a deploy throws for it, and the slot the Node
|
|
18
|
+
* entry point installs its source reader into.
|
|
19
|
+
*/
|
|
20
|
+
import { Run402DeployError } from "./errors.js";
|
|
21
|
+
import type { FunctionToolSpec } from "./namespaces/deploy.types.js";
|
|
22
|
+
/** Codes a tool declaration is refused with before any request, and by the gateway at plan with HTTP 422. */
|
|
23
|
+
export type McpToolErrorCode = "MCP_TOOL_NOT_STATIC" | "MCP_TOOL_SCHEMA_INVALID" | "MCP_TOOL_NAME_INVALID" | "MCP_TOOL_NAME_DUPLICATE" | "MCP_TOOL_ROUTE_ELSEWHERE" | "MCP_TOOL_PATH_UNSUPPORTED";
|
|
24
|
+
/** Why a tool declaration is refused, as data. */
|
|
25
|
+
export interface ToolDeclarationProblem {
|
|
26
|
+
code: McpToolErrorCode;
|
|
27
|
+
message: string;
|
|
28
|
+
/** The source file as the caller named it; null for an inline source or for `tools` passed as data. */
|
|
29
|
+
file: string | null;
|
|
30
|
+
/** 1-based line in `file`. Present only when it is exact. */
|
|
31
|
+
line?: number;
|
|
32
|
+
/** Where in the export or the spec, e.g. `tools.add_note.input.type`. */
|
|
33
|
+
field_path: string;
|
|
34
|
+
/** The tool's name, when the declaration got far enough to have one. */
|
|
35
|
+
tool?: string;
|
|
36
|
+
}
|
|
37
|
+
export declare const MCP_TOOL_DESCRIPTION_MAX = 1024;
|
|
38
|
+
export declare const MCP_TOOL_TITLE_MAX = 128;
|
|
39
|
+
/** Serialized size ceiling for one declaration (description plus schema). */
|
|
40
|
+
export declare const MCP_TOOL_DECLARATION_MAX_BYTES: number;
|
|
41
|
+
/** MCP tool names: 1 to 128 of `A-Z a-z 0-9 _ - .`. */
|
|
42
|
+
export declare function isValidMcpToolName(name: string): boolean;
|
|
43
|
+
type EntryProblem = Pick<ToolDeclarationProblem, "code" | "message" | "field_path">;
|
|
44
|
+
export type FunctionToolEntryCheck = {
|
|
45
|
+
ok: true;
|
|
46
|
+
tool: FunctionToolSpec;
|
|
47
|
+
} | {
|
|
48
|
+
ok: false;
|
|
49
|
+
problem: EntryProblem;
|
|
50
|
+
};
|
|
51
|
+
/**
|
|
52
|
+
* Split a tool path into its `{param}` names. A `{param}` stands for one whole
|
|
53
|
+
* path segment; a wildcard, a rest segment, or a parameter that is only part
|
|
54
|
+
* of a segment has no tool binding.
|
|
55
|
+
*/
|
|
56
|
+
export declare function toolPathParams(path: string): {
|
|
57
|
+
ok: true;
|
|
58
|
+
params: string[];
|
|
59
|
+
} | {
|
|
60
|
+
ok: false;
|
|
61
|
+
code: "MCP_TOOL_SCHEMA_INVALID" | "MCP_TOOL_PATH_UNSUPPORTED";
|
|
62
|
+
message: string;
|
|
63
|
+
};
|
|
64
|
+
/**
|
|
65
|
+
* Check one tool entry, already a plain value, against the rules every
|
|
66
|
+
* carrier shares, and return it with its fields in a fixed order.
|
|
67
|
+
* `pathParams` overrides the parameters read from `path` (an Astro endpoint's
|
|
68
|
+
* path is its route, never a field of the declaration).
|
|
69
|
+
*/
|
|
70
|
+
export declare function checkFunctionToolEntry(value: unknown, fieldPath: string, opts?: {
|
|
71
|
+
pathParams?: readonly string[];
|
|
72
|
+
}): FunctionToolEntryCheck;
|
|
73
|
+
/** One group of tools and where it came from: a function of a spec, or a source file of a build. */
|
|
74
|
+
export interface ToolNameGroup {
|
|
75
|
+
/** The function name or the file, as the refusal should name it. */
|
|
76
|
+
owner: string;
|
|
77
|
+
tools: ReadonlyArray<Pick<FunctionToolSpec, "name">>;
|
|
78
|
+
/** The name a tool with no `name` takes (a function file's single `tool`: the function name). */
|
|
79
|
+
defaultName?: string;
|
|
80
|
+
}
|
|
81
|
+
/** The first tool name two tools of one build share, with the two owners in the order given. */
|
|
82
|
+
export declare function findDuplicateToolName(groups: readonly ToolNameGroup[]): {
|
|
83
|
+
name: string;
|
|
84
|
+
owners: [string, string];
|
|
85
|
+
} | null;
|
|
86
|
+
/** `src/pages/api/notes.ts:12`, `functions.replace.api.source:12`, or just the name when there is no exact line. */
|
|
87
|
+
export declare function toolProblemLocation(problem: Pick<ToolDeclarationProblem, "file" | "line">, fallback?: string): string | null;
|
|
88
|
+
/**
|
|
89
|
+
* The error a deploy throws for a refused tool declaration, before any
|
|
90
|
+
* request: the gateway's code for the same condition, `resource`
|
|
91
|
+
* `functions.<function>.tools[.<tool>]`, the file, line and field path under
|
|
92
|
+
* `details`, and an `edit_request` next action.
|
|
93
|
+
*/
|
|
94
|
+
export declare function toolDeclarationError(problem: ToolDeclarationProblem, where: {
|
|
95
|
+
functionName: string;
|
|
96
|
+
sourceField?: string;
|
|
97
|
+
functions?: string[];
|
|
98
|
+
}): Run402DeployError;
|
|
99
|
+
/** What the installed reader is given: one function's entry source, as text. */
|
|
100
|
+
export interface FunctionToolLiftInput {
|
|
101
|
+
functionName: string;
|
|
102
|
+
source: string;
|
|
103
|
+
/** The source's path on disk, when it has one. */
|
|
104
|
+
file: string | null;
|
|
105
|
+
/** The spec field the source came from, e.g. `functions.replace.api.source`. */
|
|
106
|
+
sourceField: string;
|
|
107
|
+
}
|
|
108
|
+
/** Reads the tools a function's entry source declares; throws {@link Run402DeployError} on a refused declaration. */
|
|
109
|
+
export type FunctionToolLifter = (input: FunctionToolLiftInput) => FunctionToolSpec[];
|
|
110
|
+
/**
|
|
111
|
+
* Install the reader `apply` calls for every function source it reads when
|
|
112
|
+
* the entry names no `tools`. Reading a declaration means parsing JavaScript,
|
|
113
|
+
* which is Node-only, so `@run402/sdk/node` installs it when it loads; with
|
|
114
|
+
* none installed, `tools` is forwarded only when the caller passes it.
|
|
115
|
+
*/
|
|
116
|
+
export declare function installFunctionToolLifter(lifter: FunctionToolLifter | null): void;
|
|
117
|
+
export declare function installedFunctionToolLifter(): FunctionToolLifter | null;
|
|
118
|
+
export {};
|
|
119
|
+
//# sourceMappingURL=function-tools.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"function-tools.d.ts","sourceRoot":"","sources":["../src/function-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAA+C,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAElH,6GAA6G;AAC7G,MAAM,MAAM,gBAAgB,GACxB,qBAAqB,GACrB,yBAAyB,GACzB,uBAAuB,GACvB,yBAAyB,GACzB,0BAA0B,GAC1B,2BAA2B,CAAC;AAEhC,kDAAkD;AAClD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,uGAAuG;IACvG,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,6EAA6E;AAC7E,eAAO,MAAM,8BAA8B,QAAY,CAAC;AAWxD,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,KAAK,YAAY,GAAG,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC,CAAC;AAEpF,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC;AAUzC;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,yBAAyB,GAAG,2BAA2B,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAwB3K;AAkCD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GAC5C,sBAAsB,CA6ExB;AAED,oGAAoG;AACpG,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,iGAAiG;IACjG,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,gGAAgG;AAChG,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAYzH;AAED,oHAAoH;AACpH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI5H;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAC1E,iBAAiB,CA+CnB;AAED,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qHAAqH;AACrH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,qBAAqB,KAAK,gBAAgB,EAAE,CAAC;AAItF;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,GAAG,IAAI,CAEjF;AAED,wBAAgB,2BAA2B,IAAI,kBAAkB,GAAG,IAAI,CAEvE"}
|