kestrel.markets/dist/mcp/protocol.d.ts

A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.

/**
 * # mcp/protocol — the JSON-RPC 2.0 + MCP wire vocabulary the Kestrel MCP face speaks (kestrel-djm.7)
 *
 * The small, dependency-free wire surface the {@link ./server.ts KestrelMcpServer} dispatcher answers over:
 * the JSON-RPC 2.0 envelope (`resources/list` · `resources/read` · `tools/list` · `tools/call` · the
 * `initialize` handshake) plus the MCP resource / tool result shapes. This module holds NO Kestrel runtime
 * semantics and imports NOTHING — it is pure types + own constants (the same zero-dependency discipline the
 * djm.2 protocol modules keep). Every djm.2/djm.4 protocol OBJECT the face returns rides VERBATIM inside a
 * {@link ToolResult.structuredContent} or a {@link ResourceContents.text}; this module only frames it.
 *
 * ── DESIGN FORK LOGGED (hard rules forbid .beads writes — recorded here like djm.5's sdk/types.ts note) ──
 *  (1) TRANSPORT: hand-rolled JSON-RPC 2.0, NOT `@modelcontextprotocol/sdk` (absent from node_modules; a heavy
 *      dep on the package graph the 'mcp' keyword advertises but never installed). The MCP wire is a small
 *      JSON-RPC 2.0 surface a zero-dependency dispatcher serves — no new dep, no drag on the light/heavy seam.
 *  (2) RESOURCE URIs: `kestrel://catalog/<index>` (the static djm.8 CatalogEntry mirror the SDK's `catalog()`
 *      returns — the tail is the enumeration index; the catalog is compared order-independently) and
 *      `kestrel://artifact/<encodeURIComponent(ref)>` (the immutable, content-addressed finalized artifacts,
 *      addressed by the SDK's own artifact `ref`). A resource READ returns the djm.2 object VERBATIM as JSON.
 *  (3) TOOL NAMING: dot-namespaced under `kestrel.` — one tool per SDK verb ({@link TOOL}).
 *  (4) FAILURE TAXONOMY: a TRANSPORT failure (malformed frame / bad request) → a JSON-RPC ERROR
 *      ({@link PARSE_ERROR} / {@link INVALID_REQUEST}); a KESTREL REFUSAL (a typed SDK error) → a tool RESULT
 *      with `isError:true` + `structuredContent.refusal.code`; a STAND_DOWN → a normal tool RESULT. The three
 *      are distinct, caller-distinguishable shapes (see the server's dispatch).
 */
/** A JSON-RPC 2.0 request/response id — a number, a string, or `null` (the reserved id for a request that
 *  could not be correlated, e.g. a frame that failed to parse). */
export type JsonRpcId = number | string | null;
/** A parsed JSON-RPC 2.0 request the dispatcher answers. `params` is deliberately `unknown` — every method
 *  narrows it fail-closed (a missing/ill-typed field is a typed refusal or an invalid-params error). */
export interface JsonRpcRequest {
    readonly jsonrpc: "2.0";
    readonly id?: JsonRpcId;
    readonly method: string;
    readonly params?: unknown;
}
/** The JSON-RPC 2.0 error object (the TRANSPORT-layer failure signal). `code` is a JSON-RPC reserved code. */
export interface JsonRpcError {
    readonly code: number;
    readonly message: string;
    readonly data?: unknown;
}
/** The JSON-RPC 2.0 response envelope: success carries `result`, a transport failure carries `error`
 *  (never both). A domain (Kestrel) refusal is NOT an `error` — it rides as an `isError` {@link ToolResult}. */
export interface JsonRpcResponse {
    readonly jsonrpc: "2.0";
    readonly id: JsonRpcId;
    readonly result?: unknown;
    readonly error?: JsonRpcError;
}
/** Invalid JSON was received — the TRANSPORT signal for a malformed MCP frame (the broken-pipe class). */
export declare const PARSE_ERROR = -32700;
/** The JSON was not a valid JSON-RPC Request object. */
export declare const INVALID_REQUEST = -32600;
/** The method does not exist / is not available. */
export declare const METHOD_NOT_FOUND = -32601;
/** Invalid method parameter(s). */
export declare const INVALID_PARAMS = -32602;
/** Internal JSON-RPC error (an unexpected server fault — kept DISTINCT from a typed Kestrel refusal). */
export declare const INTERNAL_ERROR = -32603;
/** The resource URI schemes (see the fork note): the static djm.8 catalog listings, the immutable artifacts,
 *  and the SINGLE ex-ante catalog pricing block (kestrel-adge) when the catalog serves one. */
export declare const CATALOG_URI_PREFIX = "kestrel://catalog/";
export declare const ARTIFACT_URI_PREFIX = "kestrel://artifact/";
/** The one ex-ante pricing resource URI (kestrel-adge) — advertised only when `sdk.catalog()` carries a
 *  `pricing` block; reading it returns the {@link import("../protocol/catalog.ts").CatalogPricing} verbatim. */
export declare const PRICING_URI = "kestrel://catalog-pricing";
/** Build the immutable-artifact URI for a content-addressed artifact `ref` (the SDK's own artifact handle). */
export declare const artifactUri: (ref: string) => string;
/** A resource advertised by `resources/list`. */
export interface Resource {
    readonly uri: string;
    readonly name: string;
    readonly description?: string;
    readonly mimeType?: string;
}
/** The lossless payload a `resources/read` returns — the djm.2 protocol object serialized VERBATIM as JSON
 *  text (`application/json`). The caller `JSON.parse`s `text` back to the exact protocol object. */
export interface ResourceContents {
    readonly uri: string;
    readonly mimeType?: string;
    readonly text: string;
}
/** The tool names — one tool per SDK verb, dot-namespaced under `kestrel.`. Nothing the SDK can do is
 *  missing from the MCP face (the complete trial + incremental Session lifecycle + Grade + continuation). */
export declare const TOOL: {
    readonly validate: "kestrel.validate";
    readonly open: "kestrel.session.open";
    readonly start: "kestrel.session.start";
    readonly advance: "kestrel.session.advance";
    readonly revise: "kestrel.session.revise";
    readonly submit: "kestrel.session.submit";
    readonly resume: "kestrel.session.resume";
    readonly finalize: "kestrel.session.finalize";
    readonly grade: "kestrel.grade";
    readonly operationResume: "kestrel.operation.resume";
    readonly secretsSet: "kestrel.secrets.set";
    readonly secretsUnset: "kestrel.secrets.unset";
    readonly secretsList: "kestrel.secrets.list";
};
/** The frozen tool-name space. */
export type ToolName = (typeof TOOL)[keyof typeof TOOL];
/** A single content block on a tool result (the human-readable rendering; the machine-readable truth is
 *  {@link ToolResult.structuredContent}). */
export interface ContentBlock {
    readonly type: "text";
    readonly text: string;
}
/**
 * A `tools/call` RESULT. `structuredContent` carries the lossless djm.2 protocol object VERBATIM (the
 * canonical identities / diagnostics / receipts / roots — never a reshaped summary). `isError:true` marks a
 * TYPED KESTREL REFUSAL (its `structuredContent.refusal.code` is the typed code the caller matches on) — a
 * domain outcome delivered IN-BAND, never conflated with a JSON-RPC transport `error`.
 */
export interface ToolResult {
    readonly content: readonly ContentBlock[];
    readonly structuredContent?: unknown;
    readonly isError?: boolean;
}
/** A tool advertised by `tools/list`: its name, a description, and its JSON-Schema input shape. */
export interface ToolDescriptor {
    readonly name: string;
    readonly description: string;
    readonly inputSchema: Record<string, unknown>;
}
/**
 * A TRANSPORT-layer protocol error the dispatcher raises for a malformed frame / bad request / invalid
 * params — carried out of a handler and mapped to a JSON-RPC `error` with {@link jsonRpcCode}. Deliberately
 * carries NO `code: string` field, so it is NEVER mistaken for a typed Kestrel refusal (which the tool path
 * detects by a string `code`): the two failure classes stay distinct and caller-distinguishable (fail-closed).
 */
export declare class McpProtocolError extends Error {
    readonly name = "McpProtocolError";
    readonly jsonRpcCode: number;
    constructor(jsonRpcCode: number, message: string);
}
//# sourceMappingURL=protocol.d.ts.map