@cyanheads/mcp-ts-core 0.8.3 → 0.8.5
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/CLAUDE.md +26 -8
- package/README.md +2 -2
- package/changelog/0.8.x/0.8.4.md +60 -0
- package/changelog/0.8.x/0.8.5.md +42 -0
- package/dist/core/context.d.ts +79 -8
- package/dist/core/context.d.ts.map +1 -1
- package/dist/core/context.js +46 -9
- package/dist/core/context.js.map +1 -1
- package/dist/core/index.d.ts +2 -2
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/index.js +1 -1
- package/dist/core/index.js.map +1 -1
- package/dist/linter/rules/error-contract-rules.d.ts +3 -1
- package/dist/linter/rules/error-contract-rules.d.ts.map +1 -1
- package/dist/linter/rules/error-contract-rules.js +40 -2
- package/dist/linter/rules/error-contract-rules.js.map +1 -1
- package/dist/logs/combined.log +4 -12
- package/dist/logs/error.log +4 -12
- package/dist/mcp-server/tools/utils/toolDefinition.d.ts +5 -2
- package/dist/mcp-server/tools/utils/toolDefinition.d.ts.map +1 -1
- package/dist/mcp-server/tools/utils/toolDefinition.js +5 -2
- package/dist/mcp-server/tools/utils/toolDefinition.js.map +1 -1
- package/dist/testing/index.d.ts.map +1 -1
- package/dist/testing/index.js +5 -1
- package/dist/testing/index.js.map +1 -1
- package/dist/types-global/errors.d.ts +24 -3
- package/dist/types-global/errors.d.ts.map +1 -1
- package/package.json +11 -11
- package/skills/add-service/SKILL.md +13 -2
- package/skills/add-tool/SKILL.md +68 -23
- package/skills/api-auth/SKILL.md +6 -5
- package/skills/api-context/SKILL.md +55 -6
- package/skills/api-errors/SKILL.md +79 -7
- package/skills/design-mcp-server/SKILL.md +10 -3
- package/templates/AGENTS.md +4 -2
- package/templates/CLAUDE.md +4 -2
- package/templates/src/mcp-server/tools/definitions/echo.tool.ts +1 -0
package/CLAUDE.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Protocol
|
|
2
2
|
|
|
3
|
-
**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.8.
|
|
3
|
+
**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.8.5
|
|
4
4
|
**npm:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) · **Docker:** [ghcr.io/cyanheads/mcp-ts-core](https://ghcr.io/cyanheads/mcp-ts-core)
|
|
5
5
|
|
|
6
6
|
> **Developer note:** Never assume. Read related files and docs before making changes. Read full file content for context. Never edit a file before reading it.
|
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
|
|
24
24
|
| Subpath | Key Exports | Purpose |
|
|
25
25
|
|:--------|:------------|:--------|
|
|
26
|
-
| `@cyanheads/mcp-ts-core` | `createApp`, `tool`, `resource`, `prompt`, `appTool`, `appResource`, `APP_RESOURCE_MIME_TYPE`, `Context`, `createFail`, `TypedFail`, `ReasonOf`, `HandlerContext`, `z` | Main entry point |
|
|
26
|
+
| `@cyanheads/mcp-ts-core` | `createApp`, `tool`, `resource`, `prompt`, `appTool`, `appResource`, `APP_RESOURCE_MIME_TYPE`, `Context`, `createFail`, `createRecoveryFor`, `TypedFail`, `TypedRecoveryFor`, `ReasonOf`, `HandlerContext`, `z` | Main entry point |
|
|
27
27
|
| `/worker` | `createWorkerHandler`, `CloudflareBindings` | Cloudflare Workers entry |
|
|
28
28
|
| `/tools` | `ToolDefinition`, `AnyToolDefinition`, `ToolAnnotations` | Tool definition types |
|
|
29
29
|
| `/resources` | `ResourceDefinition`, `AnyResourceDefinition` | Resource definition types |
|
|
@@ -299,6 +299,7 @@ interface Context {
|
|
|
299
299
|
readonly signal: AbortSignal; // cancellation
|
|
300
300
|
readonly progress?: ContextProgress; // present when task: true
|
|
301
301
|
readonly uri?: URL; // present for resource handlers
|
|
302
|
+
recoveryFor(reason: string): { recovery: { hint: string } } | {}; // opt-in contract resolver
|
|
302
303
|
}
|
|
303
304
|
```
|
|
304
305
|
|
|
@@ -320,7 +321,13 @@ const values = await ctx.state.getMany<Item>(['item:1', 'item:2']); // Map<strin
|
|
|
320
321
|
const page = await ctx.state.list('item:', { cursor, limit: 20 }); // { items, cursor? }
|
|
321
322
|
```
|
|
322
323
|
|
|
323
|
-
Throws `McpError(InvalidRequest)` if `tenantId` missing. Tenant ID
|
|
324
|
+
Throws `McpError(InvalidRequest)` if `tenantId` missing. Tenant ID resolution:
|
|
325
|
+
|
|
326
|
+
| Mode | `tenantId` source |
|
|
327
|
+
|:-----|:------------------|
|
|
328
|
+
| stdio (any auth) | `'default'` |
|
|
329
|
+
| HTTP + `MCP_AUTH_MODE=none` | `'default'` (single-tenant by design) |
|
|
330
|
+
| HTTP + `MCP_AUTH_MODE=jwt`/`oauth` | JWT `'tid'` claim — fail-closed if absent |
|
|
324
331
|
|
|
325
332
|
### `ctx.elicit` / `ctx.sample`
|
|
326
333
|
|
|
@@ -345,19 +352,30 @@ See `api-context` skill for full details.
|
|
|
345
352
|
|
|
346
353
|
## Error Handling
|
|
347
354
|
|
|
348
|
-
**Recommended path: declare a typed error contract.** Add `errors: [{ reason, code, when, retryable? }]` to `tool()` / `resource()`. The handler then receives `ctx.fail(reason, msg?, data?)` typed against the reason union — `ctx.fail('typo')` is a TypeScript error. The runtime auto-populates `data.reason` for observability and the linter enforces conformance against the handler body.
|
|
355
|
+
**Recommended path: declare a typed error contract.** Add `errors: [{ reason, code, when, recovery, retryable? }]` to `tool()` / `resource()`. The handler then receives `ctx.fail(reason, msg?, data?)` typed against the reason union — `ctx.fail('typo')` is a TypeScript error. The runtime auto-populates `data.reason` for observability and the linter enforces conformance against the handler body. The `recovery` field is required (≥5 words, lint-validated) — it's the single source of truth for the recovery hint that flows to the wire. Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire (the framework mirrors `data.recovery.hint` into `content[]` text). Override with explicit `{ recovery: { hint: '...' } }` when runtime context matters.
|
|
349
356
|
|
|
350
357
|
```ts
|
|
351
358
|
errors: [
|
|
352
|
-
{ reason: 'no_match', code: JsonRpcErrorCode.NotFound,
|
|
353
|
-
|
|
359
|
+
{ reason: 'no_match', code: JsonRpcErrorCode.NotFound,
|
|
360
|
+
when: 'No PMID returned data',
|
|
361
|
+
recovery: 'Try pubmed_search_articles to discover valid PMIDs first.' },
|
|
362
|
+
{ reason: 'queue_full', code: JsonRpcErrorCode.RateLimited,
|
|
363
|
+
when: 'Queue at capacity', retryable: true,
|
|
364
|
+
recovery: 'Wait 30 seconds before retrying or reduce batch size.' },
|
|
354
365
|
],
|
|
355
366
|
async handler(input, ctx) {
|
|
356
|
-
|
|
357
|
-
|
|
367
|
+
// Static recovery — pulled from the contract via ctx.recoveryFor.
|
|
368
|
+
if (queue.full()) throw ctx.fail('queue_full', undefined, { ...ctx.recoveryFor('queue_full') });
|
|
369
|
+
// Dynamic recovery — interpolate runtime context, override the contract default.
|
|
370
|
+
if (!matched) throw ctx.fail('no_match', `No data for ${input.pmids.length} PMIDs`, {
|
|
371
|
+
pmids: input.pmids,
|
|
372
|
+
recovery: { hint: `Use pubmed_search_articles to discover valid PMIDs.` },
|
|
373
|
+
});
|
|
358
374
|
}
|
|
359
375
|
```
|
|
360
376
|
|
|
377
|
+
**`ctx.recoveryFor(reason)`** is the first member of a planned family of opt-in resolution helpers (future: `troubleshootingFor`, `userMessageFor`, …). Always present on `Context` (returns `{}` when no contract is attached or the reason is unknown — spread-safe), strictly typed on `HandlerContext<R>` against the declared reason union. The same resolver works in services that accept `ctx`: `throw validationError(msg, { reason: 'X', ...ctx.recoveryFor('X') })`. No auto-population — author opts in by typing the helper.
|
|
378
|
+
|
|
361
379
|
The contract describes the **public failure surface** — declare domain-specific failures only. **Baseline codes** (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble from anywhere and are auto-allowed by the conformance lint, so you don't need to enumerate them per-tool. The conformance lint scans handler source text only — failures thrown from called services aren't visible to it (still reach the client correctly via the auto-classifier, just without lint enforcement).
|
|
362
380
|
|
|
363
381
|
**Fallback for ad-hoc throws** (no contract entry fits, prototype tools, service-layer code): use error factories.
|
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
|
|
6
6
|
<div align="center">
|
|
7
7
|
|
|
8
|
-
[](./CHANGELOG.md) [](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [](https://modelcontextprotocol.io/) [](./LICENSE)
|
|
9
9
|
|
|
10
10
|
[](https://www.typescriptlang.org/) [](https://bun.sh/)
|
|
11
11
|
|
|
@@ -182,7 +182,7 @@ Handlers receive a unified `Context` object:
|
|
|
182
182
|
| `ctx.notifyResourceListChanged` | `Function?` | Notify clients the resource list changed |
|
|
183
183
|
| `ctx.progress` | `ContextProgress?` | Task progress reporting (when `task: true`) |
|
|
184
184
|
| `ctx.requestId` | `string` | Unique request ID |
|
|
185
|
-
| `ctx.tenantId` | `string?` | Tenant ID (
|
|
185
|
+
| `ctx.tenantId` | `string?` | Tenant ID (JWT `tid` claim, or `'default'` for stdio and HTTP+`MCP_AUTH_MODE=none`) |
|
|
186
186
|
|
|
187
187
|
### Subpath exports
|
|
188
188
|
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "ErrorContract.recovery is now required (≥ 5 words, lint-validated). Decoupled from runtime data.recovery.hint — no auto-population, just a forcing function for thoughtful authoring."
|
|
3
|
+
breaking: true
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 0.8.4 — 2026-04-29
|
|
7
|
+
|
|
8
|
+
`recovery: string` joins `code`, `reason`, and `when` as a required field on every `ErrorContract` entry. Closes [#85](https://github.com/cyanheads/mcp-ts-core/issues/85).
|
|
9
|
+
|
|
10
|
+
The contract `recovery` and the throw-site `data.recovery.hint` are **decoupled by design**. The contract field is descriptive metadata read by the linter and scaffolding skills (a forcing function for thoughtful authoring). The wire payload's `data.recovery.hint` — which 0.8.3's error-path parity invariant mirrors into `content[]` text — is populated separately at the throw site by the author when dynamic context matters. No magic, no hidden transformation.
|
|
11
|
+
|
|
12
|
+
## Changed
|
|
13
|
+
|
|
14
|
+
- **`ErrorContract.recovery: string`** (`src/types-global/errors.ts`) — required at the TypeScript type level. Existing tools that declare `errors[]` won't compile without a `recovery` string per entry.
|
|
15
|
+
|
|
16
|
+
## Added
|
|
17
|
+
|
|
18
|
+
- **Three lint rules** (`src/linter/rules/error-contract-rules.ts`):
|
|
19
|
+
- `error-contract-recovery-required` — error when `recovery` is missing or non-string
|
|
20
|
+
- `error-contract-recovery-empty` — error when `recovery` is empty or whitespace-only
|
|
21
|
+
- `error-contract-recovery-min-words` — warning when `recovery` has fewer than 5 words (forcing function against placeholders like "Try again.")
|
|
22
|
+
|
|
23
|
+
## Docs
|
|
24
|
+
|
|
25
|
+
- `CLAUDE.md` / `AGENTS.md` (root + `templates/`) — Error Handling sections updated with the required `recovery` field and the decoupling principle for `data.recovery.hint`.
|
|
26
|
+
- `skills/add-tool/SKILL.md` v2.1 → v2.2 — template scaffolds `recovery` in `errors[]`.
|
|
27
|
+
- `skills/api-errors/SKILL.md` v1.1 → v1.2 — documents the field, lint rules, and decoupling principle.
|
|
28
|
+
- `skills/design-mcp-server/SKILL.md` v2.7 → v2.8 — recovery-hint shape corrected to canonical nested `recovery: { hint: ... }`. Closes [#82](https://github.com/cyanheads/mcp-ts-core/issues/82).
|
|
29
|
+
- `templates/src/mcp-server/tools/definitions/echo.tool.ts` — `empty_message` entry gains a `recovery` string.
|
|
30
|
+
|
|
31
|
+
## Migration
|
|
32
|
+
|
|
33
|
+
Every existing `errors[]` entry needs a `recovery` string. TypeScript will flag missing entries on upgrade — fix in place.
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
// Before
|
|
37
|
+
errors: [
|
|
38
|
+
{ reason: 'no_match', code: JsonRpcErrorCode.NotFound,
|
|
39
|
+
when: 'No item matched.' },
|
|
40
|
+
],
|
|
41
|
+
|
|
42
|
+
// After
|
|
43
|
+
errors: [
|
|
44
|
+
{ reason: 'no_match', code: JsonRpcErrorCode.NotFound,
|
|
45
|
+
when: 'No item matched.',
|
|
46
|
+
recovery: 'Broaden the query or check the spelling and try again.' },
|
|
47
|
+
],
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The `recovery` string is contract metadata, not the wire-payload hint. To surface dynamic recovery guidance at the call site (mirrored into `content[]` text by 0.8.3's parity invariant), pass it explicitly:
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
throw ctx.fail('no_match', `No item ${id}`, {
|
|
54
|
+
recovery: { hint: `No item ${id}; try a different ID.` },
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Maintenance
|
|
59
|
+
|
|
60
|
+
- Dependencies refreshed via `bun update --latest`. All minor/patch — `@opentelemetry/*` (0.215.0 → 0.216.0, 2.7.0 → 2.7.1), `@cloudflare/workers-types` (4.20260426.1 → 4.20260429.1), `unpdf` (1.6.1 → 1.6.2), and others.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "HTTP+MCP_AUTH_MODE=none defaults tenantId to 'default' so ctx.state works without minting JWTs. New ctx.recoveryFor opt-in contract resolver carries the contract recovery onto the wire — single source of truth for handler and service throws."
|
|
3
|
+
breaking: false
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 0.8.5 — 2026-04-29
|
|
7
|
+
|
|
8
|
+
Two changes shipped together. `MCP_AUTH_MODE=none` over HTTP now behaves as the documented "single-tenant, no auth" mode (closes [#87](https://github.com/cyanheads/mcp-ts-core/issues/87)). And the contract `recovery` field gets a typed runtime resolver — `ctx.recoveryFor(reason)` — that carries the lint-validated string onto the wire without authoring duplication, while preserving the "no auto-population, no hidden transformation" stance from [#85](https://github.com/cyanheads/mcp-ts-core/issues/85) (closes [#89](https://github.com/cyanheads/mcp-ts-core/issues/89), supersedes [#88](https://github.com/cyanheads/mcp-ts-core/issues/88)).
|
|
9
|
+
|
|
10
|
+
## Added
|
|
11
|
+
|
|
12
|
+
- **`ctx.recoveryFor(reason)`** (`src/core/context.ts`) — opt-in contract resolver. Returns the canonical wire shape `{ recovery: { hint } }` for declared reasons; returns `{}` when no contract is attached or the reason is unknown. Always present on `Context` (spread-safe with no optional chaining); strictly typed on `HandlerContext<R>` against the declared reason union. Same resolver works in services that accept `ctx`.
|
|
13
|
+
- **`createRecoveryFor(errors)`** (`src/core/context.ts`) — internal builder, mirrors `createFail`. Public re-export from `@cyanheads/mcp-ts-core` for advanced use.
|
|
14
|
+
- **`TypedRecoveryFor<R>`** type alias for the strict signature, exported alongside `TypedFail<R>`.
|
|
15
|
+
- **First member of a planned family of opt-in resolution helpers.** Future contract-bound fields (`troubleshootingFor`, `userMessageFor`, …) follow the same shape: single-purpose method, spreadable wire-shape return, `{}` fallback, strict variant on `HandlerContext<R>`.
|
|
16
|
+
|
|
17
|
+
## Fixed
|
|
18
|
+
|
|
19
|
+
- **`createContext`** (`src/core/context.ts`) — `tenantId` defaults to `'default'` when `MCP_AUTH_MODE=none`, regardless of transport. Stdio behavior unchanged. HTTP+`jwt`/`oauth` without `tid` still fails closed (security invariant: distinct authenticated callers must not silently share state).
|
|
20
|
+
- **`ctx.state` error message** — references `MCP_AUTH_MODE` semantics instead of stale "via createApp()" wording.
|
|
21
|
+
|
|
22
|
+
## Changed
|
|
23
|
+
|
|
24
|
+
- **`HandlerContext<R>`** — when `R` is a literal union, the type now uses `Omit<Context, 'recoveryFor'> & { fail: TypedFail<R>; recoveryFor: TypedRecoveryFor<R> }` (intersecting the loose `Context.recoveryFor` would widen `parameter(0)` back to `string` and lose typo-catching). Behavior unchanged for callers; type is strictly narrower for declared reasons.
|
|
25
|
+
- **`attachTypedFail`** (`src/core/context.ts`) — wires both `fail` and `recoveryFor` when the definition declares an `errors[]` contract. Bare `Context` carries a no-op `recoveryFor` so service-side spreads are always safe.
|
|
26
|
+
|
|
27
|
+
## Docs
|
|
28
|
+
|
|
29
|
+
- `AGENTS.md` / `CLAUDE.md` / `README.md` — `tenantId` resolution table covers all three modes; error handling section and Context interface documents `ctx.recoveryFor`; exports table includes `createRecoveryFor`, `TypedRecoveryFor`.
|
|
30
|
+
- `skills/api-context/SKILL.md` v1.1 → v1.2 — new `ctx.recoveryFor` section with signature, behavior table, and family-pattern note; identity field table and `ctx.state` notes carry the auth-none default.
|
|
31
|
+
- `skills/api-errors/SKILL.md` v1.3 → v1.4 — opt-in resolution subsection replaces the const-pattern guidance; gap callout removed; service-layer pattern updated.
|
|
32
|
+
- `skills/api-auth/SKILL.md` — `tenantId` sources table covers HTTP+`none`.
|
|
33
|
+
- `skills/add-tool/SKILL.md` v2.3 → v2.4 — template demonstrates static (`...ctx.recoveryFor('reason')`) and dynamic (inline `{ recovery: { hint } }`) recovery side by side; service-layer subsection now passes `ctx` and uses the resolver.
|
|
34
|
+
- `skills/add-service/SKILL.md` v1.4 → v1.5 — service-side spread pattern with `...ctx.recoveryFor('reason')`.
|
|
35
|
+
|
|
36
|
+
## Security note
|
|
37
|
+
|
|
38
|
+
HTTP+`MCP_AUTH_MODE=none` is **single-tenant by design** — all unauthenticated callers share the `'default'` tenant. Servers requiring per-caller isolation must use `MCP_AUTH_MODE=jwt` or `oauth` with tokens that carry a `tid` claim.
|
|
39
|
+
|
|
40
|
+
## Design principle (#85 / #88 / #89)
|
|
41
|
+
|
|
42
|
+
`ctx.recoveryFor` is **opt-in resolution**, not auto-population. The framework never attaches `data.recovery.hint` without an explicit signal at the throw site — authors opt in by typing the helper, the same way `ctx.fail('reason')` opts into resolving the contract `code`. The contract is the single source of truth for the recovery hint; the resolver is a typed lookup keyed by the same reason the author already typed. No magic, no hidden transformation. The `≥5 words` lint rule on contract `recovery` becomes load-bearing — every `ctx.recoveryFor` call site benefits from the thoughtfulness the contract enforced.
|
package/dist/core/context.d.ts
CHANGED
|
@@ -96,6 +96,31 @@ export interface Context {
|
|
|
96
96
|
readonly notifyResourceUpdated?: ((uri: string) => void) | undefined;
|
|
97
97
|
/** Progress reporting for background tasks. Undefined for non-task tools. */
|
|
98
98
|
readonly progress?: ContextProgress | undefined;
|
|
99
|
+
/**
|
|
100
|
+
* Resolves a contract-bound recovery hint by reason and returns it in the
|
|
101
|
+
* canonical wire shape `{ recovery: { hint } }` — safe to spread directly into
|
|
102
|
+
* factory `data` or `ctx.fail`'s data argument:
|
|
103
|
+
*
|
|
104
|
+
* ```ts
|
|
105
|
+
* throw ctx.fail('parse_failed', `Parse error: ${err.message}`, ctx.recoveryFor('parse_failed'));
|
|
106
|
+
* throw validationError('Parse failed', { reason: 'parse_failed', ...ctx.recoveryFor('parse_failed') });
|
|
107
|
+
* ```
|
|
108
|
+
*
|
|
109
|
+
* Returns `{}` when the calling definition has no `errors[]` contract, or the
|
|
110
|
+
* reason isn't declared in it. Always safe to spread — no optional chaining
|
|
111
|
+
* needed at call sites. The strict, typed variant (which guarantees the
|
|
112
|
+
* non-empty return) lives on `HandlerContext<R>` when a contract is declared.
|
|
113
|
+
*
|
|
114
|
+
* Single source of truth pattern: write the recovery once in the contract entry
|
|
115
|
+
* (lint-validated for ≥5 words), reference it everywhere via this resolver.
|
|
116
|
+
* Authors who want runtime-context recovery (interpolating input values, IDs,
|
|
117
|
+
* queue state) override at the throw site as today.
|
|
118
|
+
*/
|
|
119
|
+
recoveryFor(reason: string): {
|
|
120
|
+
recovery: {
|
|
121
|
+
hint: string;
|
|
122
|
+
};
|
|
123
|
+
} | Record<string, never>;
|
|
99
124
|
/** Unique request ID for log correlation. */
|
|
100
125
|
readonly requestId: string;
|
|
101
126
|
/** Request LLM completion from the client. Present when client supports sampling. */
|
|
@@ -106,7 +131,13 @@ export interface Context {
|
|
|
106
131
|
readonly spanId?: string | undefined;
|
|
107
132
|
/** Key-value state scoped to the current tenant. Throws if tenantId is missing. */
|
|
108
133
|
readonly state: ContextState;
|
|
109
|
-
/**
|
|
134
|
+
/**
|
|
135
|
+
* Tenant ID. Sources, in order:
|
|
136
|
+
* - JWT `tid` claim — HTTP with `MCP_AUTH_MODE=jwt`/`oauth`
|
|
137
|
+
* - `'default'` — stdio (any auth mode) or HTTP with `MCP_AUTH_MODE=none`
|
|
138
|
+
* - `undefined` — HTTP with `jwt`/`oauth` when the token lacks `tid`
|
|
139
|
+
* (fail-closed: `ctx.state` will throw rather than silently share state)
|
|
140
|
+
*/
|
|
110
141
|
readonly tenantId?: string | undefined;
|
|
111
142
|
/** ISO 8601 creation time. */
|
|
112
143
|
readonly timestamp: string;
|
|
@@ -145,17 +176,39 @@ export type TypedFail<R extends string> = (reason: R, message?: string, data?: R
|
|
|
145
176
|
export type ReasonOf<E> = E extends readonly {
|
|
146
177
|
reason: infer R extends string;
|
|
147
178
|
}[] ? string extends R ? never : R : never;
|
|
179
|
+
/**
|
|
180
|
+
* Strict, typed contract-resolver signature attached to `HandlerContext<R>`
|
|
181
|
+
* when a definition declares `errors[]`. Tightens the loose `Context.recoveryFor`
|
|
182
|
+
* to:
|
|
183
|
+
* - `reason` is constrained to the declared union (TS catches typos)
|
|
184
|
+
* - return is the non-empty wire shape (no fallback `{}` branch)
|
|
185
|
+
*
|
|
186
|
+
* Family of opt-in resolution helpers — future contract-bound fields
|
|
187
|
+
* (`troubleshootingFor`, `userMessageFor`, …) follow the same shape.
|
|
188
|
+
*/
|
|
189
|
+
export type TypedRecoveryFor<R extends string> = (reason: R) => {
|
|
190
|
+
recovery: {
|
|
191
|
+
hint: string;
|
|
192
|
+
};
|
|
193
|
+
};
|
|
148
194
|
/**
|
|
149
195
|
* Handler context. When a definition declares `errors[]`, the handler receives
|
|
150
|
-
* `Context & { fail: TypedFail<R> }` where
|
|
151
|
-
* When no contract is declared, the handler
|
|
152
|
-
*
|
|
196
|
+
* `Context & { fail: TypedFail<R>; recoveryFor: TypedRecoveryFor<R> }` where
|
|
197
|
+
* `R` is the declared reason union. When no contract is declared, the handler
|
|
198
|
+
* receives plain `Context` (its loose `recoveryFor` is still callable but
|
|
199
|
+
* always returns `{}`) and must throw `McpError` directly.
|
|
153
200
|
*
|
|
154
201
|
* The conditional `[R] extends [never]` distinguishes "no contract declared"
|
|
155
202
|
* (R = never) from "contract declared with reasons" (R = literal union).
|
|
203
|
+
*
|
|
204
|
+
* The contract branch uses `Omit<Context, 'recoveryFor'>` because intersecting
|
|
205
|
+
* the loose `Context.recoveryFor(string)` with the strict `TypedRecoveryFor<R>`
|
|
206
|
+
* would create an overload that widens `parameter(0)` back to `string` — losing
|
|
207
|
+
* the typo-catching benefit. Omit-and-replace narrows cleanly.
|
|
156
208
|
*/
|
|
157
|
-
export type HandlerContext<R extends string = never> = [R] extends [never] ? Context : Context & {
|
|
209
|
+
export type HandlerContext<R extends string = never> = [R] extends [never] ? Context : Omit<Context, 'recoveryFor'> & {
|
|
158
210
|
fail: TypedFail<R>;
|
|
211
|
+
recoveryFor: TypedRecoveryFor<R>;
|
|
159
212
|
};
|
|
160
213
|
/**
|
|
161
214
|
* @internal
|
|
@@ -174,9 +227,27 @@ export type HandlerContext<R extends string = never> = [R] extends [never] ? Con
|
|
|
174
227
|
*/
|
|
175
228
|
export declare function createFail(errors: readonly ErrorContract[]): TypedFail<string>;
|
|
176
229
|
/**
|
|
177
|
-
*
|
|
178
|
-
*
|
|
179
|
-
*
|
|
230
|
+
* Builds a runtime `recoveryFor` resolver for a given contract. Looks up the
|
|
231
|
+
* entry by `reason` and returns the canonical wire shape `{ recovery: { hint } }`,
|
|
232
|
+
* safe to spread into factory `data` or `ctx.fail`'s data argument.
|
|
233
|
+
*
|
|
234
|
+
* Returns `{}` when the reason isn't declared — at runtime this protects JS
|
|
235
|
+
* callers and stale contracts; at compile time `TypedRecoveryFor<R>` constrains
|
|
236
|
+
* the reason to declared values. The `{}` fallback also keeps the bare-Context
|
|
237
|
+
* resolver (no contract attached) safe to spread without optional chaining.
|
|
238
|
+
*
|
|
239
|
+
* @internal
|
|
240
|
+
*/
|
|
241
|
+
export declare function createRecoveryFor(errors: readonly ErrorContract[]): (reason: string) => {
|
|
242
|
+
recovery: {
|
|
243
|
+
hint: string;
|
|
244
|
+
};
|
|
245
|
+
} | Record<string, never>;
|
|
246
|
+
/**
|
|
247
|
+
* Attaches a typed `fail` and `recoveryFor` helper to `ctx` when the definition
|
|
248
|
+
* declares an error contract. The bare `Context.recoveryFor` (always present
|
|
249
|
+
* via `createContext`) is overwritten with a contract-aware resolver. Used by
|
|
250
|
+
* the tool and resource handler factories so all call sites stay identical.
|
|
180
251
|
*
|
|
181
252
|
* @internal
|
|
182
253
|
*/
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"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"}
|
package/dist/core/context.js
CHANGED
|
@@ -40,16 +40,43 @@ export function createFail(errors) {
|
|
|
40
40
|
};
|
|
41
41
|
}
|
|
42
42
|
/**
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
43
|
+
* Builds a runtime `recoveryFor` resolver for a given contract. Looks up the
|
|
44
|
+
* entry by `reason` and returns the canonical wire shape `{ recovery: { hint } }`,
|
|
45
|
+
* safe to spread into factory `data` or `ctx.fail`'s data argument.
|
|
46
|
+
*
|
|
47
|
+
* Returns `{}` when the reason isn't declared — at runtime this protects JS
|
|
48
|
+
* callers and stale contracts; at compile time `TypedRecoveryFor<R>` constrains
|
|
49
|
+
* the reason to declared values. The `{}` fallback also keeps the bare-Context
|
|
50
|
+
* resolver (no contract attached) safe to spread without optional chaining.
|
|
51
|
+
*
|
|
52
|
+
* @internal
|
|
53
|
+
*/
|
|
54
|
+
export function createRecoveryFor(errors) {
|
|
55
|
+
const byReason = new Map();
|
|
56
|
+
for (const entry of errors)
|
|
57
|
+
byReason.set(entry.reason, entry);
|
|
58
|
+
return (reason) => {
|
|
59
|
+
const entry = byReason.get(reason);
|
|
60
|
+
if (!entry)
|
|
61
|
+
return {};
|
|
62
|
+
return { recovery: { hint: entry.recovery } };
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Attaches a typed `fail` and `recoveryFor` helper to `ctx` when the definition
|
|
67
|
+
* declares an error contract. The bare `Context.recoveryFor` (always present
|
|
68
|
+
* via `createContext`) is overwritten with a contract-aware resolver. Used by
|
|
69
|
+
* the tool and resource handler factories so all call sites stay identical.
|
|
46
70
|
*
|
|
47
71
|
* @internal
|
|
48
72
|
*/
|
|
49
73
|
export function attachTypedFail(ctx, errors) {
|
|
50
74
|
if (!errors || errors.length === 0)
|
|
51
75
|
return ctx;
|
|
52
|
-
return Object.assign(ctx, {
|
|
76
|
+
return Object.assign(ctx, {
|
|
77
|
+
fail: createFail(errors),
|
|
78
|
+
recoveryFor: createRecoveryFor(errors),
|
|
79
|
+
});
|
|
53
80
|
}
|
|
54
81
|
/**
|
|
55
82
|
* Constructs a Context from internal dependencies.
|
|
@@ -58,13 +85,17 @@ export function attachTypedFail(ctx, errors) {
|
|
|
58
85
|
*/
|
|
59
86
|
export function createContext(deps) {
|
|
60
87
|
const { appContext, logger: pinoLogger, storage, signal } = deps;
|
|
61
|
-
// Default tenantId to 'default'
|
|
62
|
-
//
|
|
63
|
-
//
|
|
88
|
+
// Default tenantId to 'default' when no auth pipeline is expected to populate it:
|
|
89
|
+
// - stdio: single-client by nature, no auth middleware runs
|
|
90
|
+
// - HTTP + MCP_AUTH_MODE=none: single-tenant by design (auth=none means
|
|
91
|
+
// "no identity check, sharing is intentional")
|
|
92
|
+
// Preserves fail-closed for HTTP + jwt/oauth: a token missing the `tid` claim
|
|
93
|
+
// must NOT silently share state across distinct authenticated callers.
|
|
64
94
|
const isStdio = process.env.MCP_TRANSPORT_TYPE?.toLowerCase() !== 'http';
|
|
95
|
+
const isAuthDisabled = (process.env.MCP_AUTH_MODE ?? 'none').toLowerCase() === 'none';
|
|
65
96
|
const effectiveContext = appContext.tenantId
|
|
66
97
|
? appContext
|
|
67
|
-
: isStdio
|
|
98
|
+
: isStdio || isAuthDisabled
|
|
68
99
|
? { ...appContext, tenantId: 'default' }
|
|
69
100
|
: appContext;
|
|
70
101
|
const log = createContextLogger(pinoLogger, effectiveContext);
|
|
@@ -88,6 +119,12 @@ export function createContext(deps) {
|
|
|
88
119
|
notifyResourceUpdated: deps.notifyResourceUpdated,
|
|
89
120
|
progress,
|
|
90
121
|
uri: deps.uri,
|
|
122
|
+
// No-op resolver for definitions without a contract. `attachTypedFail`
|
|
123
|
+
// overwrites with a contract-aware resolver when `errors[]` is declared.
|
|
124
|
+
// Always-present so service code can spread `...ctx.recoveryFor('x')`
|
|
125
|
+
// without optional chaining, regardless of whether the calling tool
|
|
126
|
+
// declared a contract.
|
|
127
|
+
recoveryFor: () => ({}),
|
|
91
128
|
};
|
|
92
129
|
}
|
|
93
130
|
// ---------------------------------------------------------------------------
|
|
@@ -127,7 +164,7 @@ function createContextLogger(appLogger, appContext) {
|
|
|
127
164
|
function createContextState(storage, appContext, signal) {
|
|
128
165
|
const requireContext = () => {
|
|
129
166
|
if (!appContext.tenantId) {
|
|
130
|
-
throw invalidRequest('tenantId required for state operations.
|
|
167
|
+
throw invalidRequest('tenantId required for state operations. With MCP_AUTH_MODE=jwt|oauth, the token must include a "tid" claim. Stdio and HTTP+MCP_AUTH_MODE=none default tenantId to "default" automatically.');
|
|
131
168
|
}
|
|
132
169
|
return appContext;
|
|
133
170
|
};
|
package/dist/core/context.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,EAEL,cAAc,EACd,gBAAgB,EAChB,QAAQ,GACT,MAAM,0BAA0B,CAAC;
|
|
1
|
+
{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"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"}
|
package/dist/core/index.d.ts
CHANGED
|
@@ -9,8 +9,8 @@ export type { CoreServices, CreateAppOptions, ServerHandle } from '../core/app.j
|
|
|
9
9
|
export { createApp } from '../core/app.js';
|
|
10
10
|
export type { LandingConfig, LandingLink } from '../core/serverManifest.js';
|
|
11
11
|
export { z } from 'zod';
|
|
12
|
-
export type { AuthContext, Context, ContextLogger, ContextProgress, ContextState, HandlerContext, ReasonOf, SamplingOpts, TypedFail, } from '../core/context.js';
|
|
13
|
-
export { createFail } from '../core/context.js';
|
|
12
|
+
export type { AuthContext, Context, ContextLogger, ContextProgress, ContextState, HandlerContext, ReasonOf, SamplingOpts, TypedFail, TypedRecoveryFor, } from '../core/context.js';
|
|
13
|
+
export { createFail, createRecoveryFor } from '../core/context.js';
|
|
14
14
|
export { APP_RESOURCE_MIME_TYPE, appResource, appTool } from '../mcp-server/apps/appBuilders.js';
|
|
15
15
|
export type { AnyPromptDefinition, PromptDefinition, } from '../mcp-server/prompts/utils/promptDefinition.js';
|
|
16
16
|
export { prompt } from '../mcp-server/prompts/utils/promptDefinition.js';
|
package/dist/core/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAM1C,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAM3E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,YAAY,EACV,WAAW,EACX,OAAO,EACP,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,SAAS,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAM1C,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAM3E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,YAAY,EACV,WAAW,EACX,OAAO,EACP,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAMlE,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAChG,YAAY,EACV,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,gDAAgD,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,gDAAgD,CAAC;AACxE,YAAY,EACV,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,oDAAoD,CAAC;AAC9E,sEAAsE;AACtE,YAAY,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAC1E,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,GACf,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,4CAA4C,CAAC;AAMlE,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,SAAS,EACT,UAAU,EACV,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAM3D,YAAY,EACV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,eAAe,GAChB,MAAM,oCAAoC,CAAC"}
|
package/dist/core/index.js
CHANGED
|
@@ -10,7 +10,7 @@ export { createApp } from '../core/app.js';
|
|
|
10
10
|
// Zod re-export (consumers use the framework's copy, no separate zod dep)
|
|
11
11
|
// ---------------------------------------------------------------------------
|
|
12
12
|
export { z } from 'zod';
|
|
13
|
-
export { createFail } from '../core/context.js';
|
|
13
|
+
export { createFail, createRecoveryFor } from '../core/context.js';
|
|
14
14
|
// ---------------------------------------------------------------------------
|
|
15
15
|
// Definition builders & types
|
|
16
16
|
// ---------------------------------------------------------------------------
|
package/dist/core/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAQ1C,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAE9E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAQ1C,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAE9E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkBxB,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAElE,8EAA8E;AAC9E,8BAA8B;AAC9B,8EAA8E;AAE9E,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAKhG,OAAO,EAAE,MAAM,EAAE,MAAM,gDAAgD,CAAC;AAKxE,OAAO,EAAE,QAAQ,EAAE,MAAM,oDAAoD,CAAC;AAQ9E,OAAO,EAAE,IAAI,EAAE,MAAM,4CAA4C,CAAC;AAalE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC"}
|
|
@@ -10,9 +10,11 @@ import type { LintDefinitionType, LintDiagnostic } from '../types.js';
|
|
|
10
10
|
* Validates the `errors[]` contract on a tool/resource definition.
|
|
11
11
|
* Checks:
|
|
12
12
|
* - `errors` is an array
|
|
13
|
-
* - each entry is an object with required `code`, `reason`, `when`
|
|
13
|
+
* - each entry is an object with required `code`, `reason`, `when`, `recovery`
|
|
14
14
|
* - `code` is a real `JsonRpcErrorCode` value
|
|
15
15
|
* - `reason` is snake_case and unique within the contract
|
|
16
|
+
* - `recovery` is non-empty and ≥ 5 words (forcing function for thoughtful
|
|
17
|
+
* agent guidance — placeholders like "Try again." get flagged)
|
|
16
18
|
* - `retryable` (when present) is a boolean
|
|
17
19
|
*/
|
|
18
20
|
export declare function lintErrorContract(errors: unknown, definitionType: LintDefinitionType, definitionName: string): LintDiagnostic[];
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"error-contract-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/error-contract-rules.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"error-contract-rules.d.ts","sourceRoot":"","sources":["../../../src/linter/rules/error-contract-rules.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAetE;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,OAAO,EACf,cAAc,EAAE,kBAAkB,EAClC,cAAc,EAAE,MAAM,GACrB,cAAc,EAAE,CAmLlB;AAuDD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,EAC5C,cAAc,EAAE,kBAAkB,EAClC,cAAc,EAAE,MAAM,GACrB,cAAc,EAAE,CA4FlB"}
|
|
@@ -13,13 +13,16 @@ import { stripCommentsAndStrings } from './source-text.js';
|
|
|
13
13
|
*/
|
|
14
14
|
const VALID_CODES = new Set(Object.values(JsonRpcErrorCode).filter((v) => typeof v === 'number'));
|
|
15
15
|
const REASON_RE = /^[a-z][a-z0-9_]*$/;
|
|
16
|
+
const RECOVERY_MIN_WORDS = 5;
|
|
16
17
|
/**
|
|
17
18
|
* Validates the `errors[]` contract on a tool/resource definition.
|
|
18
19
|
* Checks:
|
|
19
20
|
* - `errors` is an array
|
|
20
|
-
* - each entry is an object with required `code`, `reason`, `when`
|
|
21
|
+
* - each entry is an object with required `code`, `reason`, `when`, `recovery`
|
|
21
22
|
* - `code` is a real `JsonRpcErrorCode` value
|
|
22
23
|
* - `reason` is snake_case and unique within the contract
|
|
24
|
+
* - `recovery` is non-empty and ≥ 5 words (forcing function for thoughtful
|
|
25
|
+
* agent guidance — placeholders like "Try again." get flagged)
|
|
23
26
|
* - `retryable` (when present) is a boolean
|
|
24
27
|
*/
|
|
25
28
|
export function lintErrorContract(errors, definitionType, definitionName) {
|
|
@@ -56,7 +59,7 @@ export function lintErrorContract(errors, definitionType, definitionName) {
|
|
|
56
59
|
diagnostics.push({
|
|
57
60
|
rule: 'error-contract-entry-type',
|
|
58
61
|
severity: 'error',
|
|
59
|
-
message: `${definitionType} '${definitionName}' ${path} must be an object with { code, reason, when }.`,
|
|
62
|
+
message: `${definitionType} '${definitionName}' ${path} must be an object with { code, reason, when, recovery }.`,
|
|
60
63
|
definitionType,
|
|
61
64
|
definitionName,
|
|
62
65
|
});
|
|
@@ -140,6 +143,41 @@ export function lintErrorContract(errors, definitionType, definitionName) {
|
|
|
140
143
|
definitionName,
|
|
141
144
|
});
|
|
142
145
|
}
|
|
146
|
+
// recovery
|
|
147
|
+
if (typeof e.recovery !== 'string') {
|
|
148
|
+
diagnostics.push({
|
|
149
|
+
rule: 'error-contract-recovery-required',
|
|
150
|
+
severity: 'error',
|
|
151
|
+
message: `${definitionType} '${definitionName}' ${path}.recovery must be a non-empty string ` +
|
|
152
|
+
'describing what the agent should do when this failure occurs.',
|
|
153
|
+
definitionType,
|
|
154
|
+
definitionName,
|
|
155
|
+
});
|
|
156
|
+
}
|
|
157
|
+
else if (e.recovery.trim().length === 0) {
|
|
158
|
+
diagnostics.push({
|
|
159
|
+
rule: 'error-contract-recovery-empty',
|
|
160
|
+
severity: 'error',
|
|
161
|
+
message: `${definitionType} '${definitionName}' ${path}.recovery is empty. ` +
|
|
162
|
+
'Provide actionable guidance for the agent.',
|
|
163
|
+
definitionType,
|
|
164
|
+
definitionName,
|
|
165
|
+
});
|
|
166
|
+
}
|
|
167
|
+
else {
|
|
168
|
+
const wordCount = e.recovery.trim().split(/\s+/).filter(Boolean).length;
|
|
169
|
+
if (wordCount < RECOVERY_MIN_WORDS) {
|
|
170
|
+
diagnostics.push({
|
|
171
|
+
rule: 'error-contract-recovery-min-words',
|
|
172
|
+
severity: 'warning',
|
|
173
|
+
message: `${definitionType} '${definitionName}' ${path}.recovery has ${wordCount} word(s); ` +
|
|
174
|
+
`minimum is ${RECOVERY_MIN_WORDS}. Specific guidance ("Try X with Y") beats ` +
|
|
175
|
+
'placeholders ("Try again.", "Check input.").',
|
|
176
|
+
definitionType,
|
|
177
|
+
definitionName,
|
|
178
|
+
});
|
|
179
|
+
}
|
|
180
|
+
}
|
|
143
181
|
// retryable (optional)
|
|
144
182
|
if (e.retryable !== undefined && typeof e.retryable !== 'boolean') {
|
|
145
183
|
diagnostics.push({
|