@convilyn/sdk-author 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,1158 @@
+import { ZodTypeAny, TypeOf } from 'zod';
+import { Server } from 'node:http';
+
+/** The SDK release version (independent of the manifest schema version). */
+declare const VERSION = "0.7.0";
+/**
+ * The schema version stamped into a compiled manifest's `sdk_version` field —
+ * kept in lockstep with the Python / Go author SDKs' manifest format.
+ */
+declare const MANIFEST_SDK_VERSION = "1.0.0";
+
+/**
+ * Typed errors raised by the Author SDK — a faithful port of the Python / Go
+ * author SDKs.
+ *
+ *     ConvilynAuthorError          base; everything the SDK throws
+ *     ├── InvalidSignatureError    inbound HMAC verification failed
+ *     ├── ConvilynStartupError     server cannot safely start (fail-closed gate)
+ *     └── ConfirmationInvalidError confirmation-handshake token rejected
+ */
+/** Base class for every error the Author SDK throws. */
+declare class ConvilynAuthorError extends Error {
+    constructor(message: string);
+}
+/** Stable machine-readable reason for an {@link InvalidSignatureError}. */
+type InvalidSignatureReason = 'missing_secret' | 'missing_header' | 'invalid_timestamp' | 'timestamp_out_of_range' | 'signature_mismatch';
+/**
+ * Raised when an inbound HMAC signature fails verification. `reason` is a stable
+ * machine-readable code; `message` is human-readable and safe to log. Reasons
+ * are intentionally coarse to avoid leaking signing details to attackers.
+ */
+declare class InvalidSignatureError extends ConvilynAuthorError {
+    readonly reason: InvalidSignatureReason;
+    constructor(reason: InvalidSignatureReason, message: string);
+}
+/**
+ * Raised when the server cannot safely start — e.g. `serve()` without
+ * `CONVILYN_HMAC_SECRET` and without the explicit insecure-local-dev opt-in.
+ * Port of the Python / Go `ConvilynStartupError` (fail-closed startup
+ * contract).
+ */
+declare class ConvilynStartupError extends ConvilynAuthorError {
+    constructor(message: string);
+}
+/**
+ * Raised when a platform API call (via {@link ConvilynClient}) returns a non-2xx
+ * response. `status` is the HTTP status; `body` is the parsed JSON (or text) the
+ * server returned.
+ */
+declare class ConvilynApiError extends ConvilynAuthorError {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body: unknown);
+}
+/** Stable machine-readable reason for a {@link ConfirmationInvalidError}. */
+type ConfirmationInvalidReason = 'malformed' | 'expired' | 'digest_mismatch' | 'signature_mismatch';
+/**
+ * Raised when a confirmation-handshake token fails verification. `reason` is a
+ * stable machine-readable code (maps to the framework's `CONFIRMATION_INVALID`).
+ */
+declare class ConfirmationInvalidError extends ConvilynAuthorError {
+    readonly reason: ConfirmationInvalidReason;
+    constructor(reason: ConfirmationInvalidReason, message: string);
+}
+
+/**
+ * Inbound HMAC verification for calls from the Convilyn gateway, plus the
+ * matching signer. Mirrors the gateway's `mcp_gateway/hmac_signer.py` and the
+ * Python / Go author SDKs **byte-for-byte**, so a TS-authored server is
+ * interchangeable behind the same gateway.
+ *
+ * Wire format:
+ * - `x-convilyn-signature` — HMAC-SHA256 hex digest
+ * - `x-convilyn-timestamp` — Unix seconds (integer string)
+ * - `x-convilyn-server-id` — server name, audit-only (NOT in the signed payload)
+ *
+ * Signed payload = `<timestamp>` bytes + `.` + raw body bytes. Comparison is
+ * constant-time; a timestamp tolerance window defends against replay.
+ *
+ * This is a public author capability: a server using its own HTTP framework
+ * (instead of the SDK's runtime) calls {@link verifySignature} to reject forged
+ * requests.
+ */
+/** HMAC header names (lowercase; match the gateway's signer). */
+declare const SIGNATURE_HEADER = "x-convilyn-signature";
+declare const TIMESTAMP_HEADER = "x-convilyn-timestamp";
+declare const SERVER_ID_HEADER = "x-convilyn-server-id";
+/** Default replay window (seconds) vs the gateway clock. */
+declare const DEFAULT_HMAC_TOLERANCE_SECONDS = 300;
+/**
+ * Body accepted by the signer / verifier. The gateway signs the **raw body
+ * bytes**, so a binary or non-UTF-8 body MUST be passed as `Uint8Array` — a
+ * lossy-decoded `string` re-encodes as UTF-8 and will not reproduce the digest
+ * (the request is rejected, never falsely accepted).
+ */
+type RequestBody = string | Uint8Array;
+/**
+ * Produce the `{ signature, timestamp }` pair for an outbound request, mirroring
+ * the gateway's signer. Useful for tests and for clients calling a
+ * developer-hosted server directly. `unixSeconds` is truncated to an integer.
+ */
+declare function signRequest(secret: string, body: RequestBody, unixSeconds: number): {
+    signature: string;
+    timestamp: string;
+};
+/** Tunables for {@link verifySignature}. */
+interface VerifyOptions {
+    /** Max clock skew (seconds) vs the gateway; `<= 0` uses the default 300. */
+    toleranceSeconds?: number;
+    /** Override "now" (Unix seconds) for tests; defaults to the real clock. */
+    now?: () => number;
+}
+/**
+ * Verify an inbound HMAC signature; throw {@link InvalidSignatureError} on any
+ * failure (missing secret/headers, malformed or out-of-tolerance timestamp, or
+ * digest mismatch). Header keys must be lowercased.
+ */
+declare function verifySignature(secret: string, body: RequestBody, headers: Record<string, string | undefined>, options?: VerifyOptions): void;
+
+/**
+ * Core value types shared across the Author SDK — tool results, error details,
+ * data references, and the manifest schema rows. Mirrors the Go SDK's `types.go`
+ * and the Python `types.py`. Domain fields are camelCase; the snake_case wire
+ * mapping lives in `manifest.ts` (and, later, the JSON-RPC runtime).
+ */
+/** Reference to data stored in the ToolDataStore (the LLM sees only the summary). */
+interface ToolDataRef {
+    refId: string;
+    summary: string;
+}
+/** Structured error detail for a failed tool execution. */
+interface ToolError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/** Result returned from a tool execution. Build via {@link ToolResult.ok} / `.fail`. */
+interface ToolResult {
+    success: boolean;
+    data?: Record<string, unknown>;
+    error?: ToolError;
+    executionTimeMs?: number;
+    /**
+     * Optional LLM-facing one-line summary. When set it becomes the wire
+     * envelope's required `summary`; otherwise the JSON-RPC runtime derives one.
+     * (Added in A3; omitting it preserves the A1 `ok` / `fail` shapes exactly.)
+     */
+    summary?: string;
+}
+/** Constructors for {@link ToolResult} (mirrors Python `ToolResult.ok` / `.fail`). */
+declare const ToolResult: {
+    ok(data: Record<string, unknown>, summary?: string): ToolResult;
+    fail(code: string, message: string, details?: Record<string, unknown>, summary?: string): ToolResult;
+};
+/** Manifest schema for a single tool. */
+interface ToolSpec {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    idempotent: boolean;
+    outputSchema?: Record<string, unknown>;
+}
+/** Manifest schema for the server section. */
+interface ServerSpec {
+    name: string;
+    version: string;
+    description: string;
+    mcpServerName?: string;
+}
+/** One line of a compliance report. */
+interface ComplianceResult {
+    passed: boolean;
+    checkName: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/** Full report from a local compliance run. */
+interface ComplianceReport {
+    results: ComplianceResult[];
+}
+/** True when every check in the report passed. */
+declare function allChecksPassed(report: ComplianceReport): boolean;
+/** Just the failing checks of a report. */
+declare function failedChecks(report: ComplianceReport): ComplianceResult[];
+
+/**
+ * The compiled blueprint of a ToolServer — its tools and capabilities described
+ * without running any code. The gateway consumes this to configure routing and
+ * agent tool binding. Port of the Python / Go `ConvilynManifest`.
+ *
+ * Serialisation maps the camelCase domain to the snake_case wire shape and keeps
+ * empty lists as `[]` (never omitted), matching the Python/Go output byte-exactly.
+ */
+
+/** Options for constructing a {@link ConvilynManifest}. */
+interface ConvilynManifestOptions {
+    tools?: ToolSpec[];
+    capabilities?: string[];
+    sdkVersion?: string;
+}
+/** The compiled blueprint of a ToolServer. */
+declare class ConvilynManifest {
+    readonly sdkVersion: string;
+    readonly server: ServerSpec;
+    readonly tools: ToolSpec[];
+    readonly capabilities: string[];
+    constructor(server: ServerSpec, options?: ConvilynManifestOptions);
+    /** The platform wire object (snake_case; empty lists kept as `[]`). */
+    toWire(): Record<string, unknown>;
+    /** The manifest serialised as 2-space-indented JSON. */
+    toJson(): string;
+    /** Write the manifest to a JSON file (default `convilyn.manifest.json`). */
+    save(path?: string): Promise<string>;
+    /** Parse a manifest from its wire object. */
+    static fromWire(wire: Record<string, unknown>): ConvilynManifest;
+    /** Parse a manifest from a JSON string. */
+    static fromJson(data: string): ConvilynManifest;
+    /** Read a manifest from a JSON file (default `convilyn.manifest.json`). */
+    static load(path?: string): Promise<ConvilynManifest>;
+}
+
+/**
+ * Environment-driven SDK configuration for a tool server. Port of the Go
+ * `SDKConfig` / Python frozen `SDKConfig`. Read it with {@link SDKConfig.fromEnv};
+ * construct directly (with explicit options) in tests.
+ */
+/** Construction options for {@link SDKConfig}; each falls back to a default. */
+interface SDKConfigOptions {
+    serverHost?: string;
+    serverPort?: number;
+    logLevel?: string;
+    awsRegion?: string;
+    dynamodbEndpoint?: string;
+    toolDataTable?: string;
+    environment?: string;
+    apiKey?: string;
+    platformUrl?: string;
+    hmacSecret?: string;
+    hmacToleranceSeconds?: number;
+    /** Secret for minting / verifying confirmation-handshake tokens. */
+    toolConfirmationSecret?: string;
+    /** Whether the process runs in AWS Lambda (set by {@link SDKConfig.fromEnv}). */
+    lambda?: boolean;
+}
+type EnvLike = Record<string, string | undefined>;
+/** Immutable SDK configuration. */
+declare class SDKConfig {
+    #private;
+    readonly serverHost: string;
+    readonly serverPort: number;
+    readonly logLevel: string;
+    readonly awsRegion: string;
+    readonly dynamodbEndpoint: string;
+    readonly toolDataTable: string;
+    readonly environment: string;
+    readonly apiKey: string;
+    readonly platformUrl: string;
+    readonly hmacSecret: string;
+    readonly hmacToleranceSeconds: number;
+    readonly toolConfirmationSecret: string;
+    constructor(options?: SDKConfigOptions);
+    /** True when running in AWS Lambda. */
+    get isLambda(): boolean;
+    /** True for a local/dev environment (relaxes HMAC). */
+    get isLocal(): boolean;
+    /** Load configuration from environment variables, falling back to defaults. */
+    static fromEnv(env?: EnvLike): SDKConfig;
+}
+
+/**
+ * Pluggable store for large tool outputs — tools return `{ ref_id, summary }` so
+ * the LLM context stays small, then the agent retrieves the full data later by
+ * `ref_id`. Port of the Python `DataStoreProtocol` / Go `DataStore`.
+ */
+
+/**
+ * Stores and retrieves large tool outputs by `ref_id`. `get` resolves to `null`
+ * for an unknown id — a miss is not an error.
+ */
+interface DataStore {
+    store(data: Record<string, unknown>): Promise<string>;
+    get(refId: string): Promise<Record<string, unknown> | null>;
+}
+/** Generate a `ref_id` in the mcp-shared format `td_<12-hex>`. */
+declare function generateRefId(): string;
+/**
+ * Zero-dependency {@link DataStore} for local development and testing. Data is
+ * lost when the process exits.
+ */
+declare class InMemoryDataStore implements DataStore {
+    #private;
+    store(data: Record<string, unknown>): Promise<string>;
+    get(refId: string): Promise<Record<string, unknown> | null>;
+    /** Number of stored entries. */
+    get size(): number;
+}
+/**
+ * Build the appropriate {@link DataStore} for the config. A1 ships the in-memory
+ * store; the DynamoDB-backed production store lands in a later increment, keyed
+ * off `config.isLambda`.
+ */
+declare function createDataStore(_config?: SDKConfig): DataStore;
+
+/**
+ * Execution context injected into tools that opt in (by accepting it). Exposes
+ * the request id, the shared {@link DataStore}, and a progress channel. Port of
+ * the Python / Go `ToolContext`.
+ */
+
+/** Receives progress reports emitted via {@link ToolContext.reportProgress}. */
+interface ProgressBackend {
+    report(requestId: string, percent: number, message: string): void;
+}
+/**
+ * Dev-mode {@link ProgressBackend} that writes each report to a sink (defaults
+ * to `process.stderr`). Inject `write` for tests or to silence it.
+ */
+declare class ConsoleProgressBackend implements ProgressBackend {
+    #private;
+    constructor(write?: (line: string) => void);
+    report(requestId: string, percent: number, message: string): void;
+}
+/**
+ * Execution context passed to a tool. Holds the request id, the shared
+ * {@link DataStore}, and an optional {@link ProgressBackend}.
+ */
+declare class ToolContext {
+    #private;
+    readonly requestId: string;
+    readonly dataStore: DataStore;
+    constructor(requestId: string, dataStore: DataStore, progress?: ProgressBackend | null);
+    /**
+     * Emit a progress update (0–100). Throws {@link RangeError} when `percent` is
+     * out of range; a no-op when no {@link ProgressBackend} is wired.
+     */
+    reportProgress(percent: number, message: string): void;
+}
+/**
+ * Build a {@link ToolContext} from a request payload, reading `request_id`
+ * (defaulting to `"unknown"`).
+ */
+declare function createToolContext(dataStore: DataStore, payload: Record<string, unknown>): ToolContext;
+
+/**
+ * `WorkflowSpec` — an immutable fluent builder for the portable workflow
+ * authoring artifact the platform consumes.
+ *
+ * Two wire shapes, one method each (single responsibility per contract):
+ *
+ * - `compile()` emits the snake_case {@link WorkflowBlueprint} — the PUBLIC
+ *   publish artifact the Developer Portal's `submit_workflow` accepts, in
+ *   cross-SDK parity with the Python author SDK's `compile()`.
+ * - `toExportPayload()` emits the camelCase {@link ExportPayload} — the
+ *   user_workflows authoring/canvas contract
+ *   (`docs/contracts/user_workflows/user_workflows_openapi.yaml`), which
+ *   carries UI-only metadata (positions, notes, canvasLayout) the blueprint
+ *   deliberately omits.
+ *
+ * Every `with*` / `add*` / `use*` method returns a NEW `WorkflowSpec` (the
+ * receiver is never mutated), matching the project's immutability rule. Contract
+ * constraints are enforced client-side so a bad spec fails fast with a clear
+ * {@link ConvilynAuthorError} instead of a server 422.
+ */
+/** Lifecycle visibility of a persisted workflow (set via the platform, not here). */
+type Visibility = 'private' | 'public' | 'archived';
+/** Provenance of a workflow's fork source. */
+type SourceType = 'curated' | 'user' | 'blank';
+/** 2D position on the Builder canvas — pure UI metadata, ignored by the agent. */
+interface Position {
+    x: number;
+    y: number;
+}
+/**
+ * One tool the agent may call. `toolName` is the
+ * `"server-name:tool_name"` form (e.g. `"doc-parser-mcp:extract_text"`).
+ * `position` is UI-only and does not affect execution order.
+ */
+interface ToolPaletteItem {
+    toolName: string;
+    position: Position;
+    note?: string;
+}
+/** Optional Builder-only canvas state. Ignored by the compiler and the agent. */
+interface CanvasLayout {
+    edges?: Array<{
+        from: string;
+        to: string;
+    }>;
+    viewport?: {
+        zoom?: number;
+        pan?: Position;
+    };
+}
+/** The camelCase user_workflows authoring/canvas artifact (`ExportPayload`). */
+interface ExportPayload {
+    schemaVersion: string;
+    name: string;
+    description?: string;
+    systemPrompt: string;
+    toolPalette: ToolPaletteItem[];
+    canvasLayout?: CanvasLayout;
+    tags: string[];
+}
+/**
+ * Public blueprint schema version. The platform's translator is keyed on
+ * this so its internal workflow contract can evolve without breaking an
+ * already-published author SDK. Mirrors the Python SDK's `PUBLIC_SCHEMA_VERSION`.
+ */
+declare const PUBLIC_SCHEMA_VERSION = "1";
+/** Public agent-mode knobs an author may set on a blueprint. */
+interface BlueprintAgentConfig {
+    system_prompt?: string;
+    max_iterations?: number;
+    temperature?: number;
+}
+/** MCP server and tool configuration ("server:tool" refs). */
+interface BlueprintMcpConfig {
+    mcp_servers: string[];
+    tools: string[];
+}
+/**
+ * The compiled PUBLIC publish artifact — snake_case, in cross-SDK parity with
+ * the Python author SDK's `WorkflowBlueprint`. This is what the Developer
+ * Portal's `submit_workflow` accepts; platform-internal fields (category,
+ * platform, prompt-template ids) are injected by the server-side translator.
+ */
+interface WorkflowBlueprint {
+    public_schema_version: string;
+    spec_id: string;
+    version: string;
+    name: string;
+    description?: string;
+    keywords?: string[];
+    agent_config?: BlueprintAgentConfig;
+    mcp_config?: BlueprintMcpConfig;
+}
+/** Cross-SDK alias — the Python SDK names its `compile()` output the same way. */
+type CompiledWorkflowSpec = WorkflowBlueprint;
+/** Immutable builder for a portable workflow spec. */
+declare class WorkflowSpec {
+    #private;
+    constructor(name: string, options?: {
+        specId?: string;
+        version?: string;
+    });
+    get name(): string;
+    get description(): string | undefined;
+    get systemPrompt(): string;
+    get schemaVersion(): string;
+    get specId(): string | undefined;
+    get version(): string;
+    get tags(): readonly string[];
+    get toolPalette(): readonly ToolPaletteItem[];
+    get canvasLayout(): CanvasLayout | undefined;
+    withName(name: string): WorkflowSpec;
+    withDescription(description: string): WorkflowSpec;
+    withSystemPrompt(systemPrompt: string): WorkflowSpec;
+    withSchemaVersion(schemaVersion: string): WorkflowSpec;
+    /** Set the portal spec id (`dev_<developer-id>.<name>` namespace). */
+    withSpecId(specId: string): WorkflowSpec;
+    /** Set the blueprint semver version (default `1.0.0`). */
+    withVersion(version: string): WorkflowSpec;
+    /** Replace the tag set. */
+    withTags(tags: string[]): WorkflowSpec;
+    /** Append a tag (no-op if already present). */
+    addTag(tag: string): WorkflowSpec;
+    /**
+     * Add (or replace, by `toolName`) one tool on the palette. Rejects the
+     * `request_user_input` tool (invariant I3) and palettes larger than
+     * {@link MAX_TOOLS}.
+     */
+    addTool(toolName: string, options?: {
+        position?: Position;
+        note?: string;
+    }): WorkflowSpec;
+    /** Add several tools by name (default canvas position), de-duplicated. */
+    useTools(...toolNames: string[]): WorkflowSpec;
+    withCanvasLayout(canvasLayout: CanvasLayout): WorkflowSpec;
+    /**
+     * The PUBLIC publish blueprint (snake_case; Python-SDK parity). This is the
+     * shape `submitWorkflow` / `convilyn-author push` send to the Developer
+     * Portal. Requires a `specId` (constructor option or {@link withSpecId}).
+     *
+     * Mirrors the Python SDK's `exclude_none` semantics: `agent_config` is
+     * emitted only when a systemPrompt is set, `mcp_config` only when the
+     * palette is non-empty. UI-only metadata (positions, notes, canvasLayout)
+     * is deliberately NOT emitted — the portal's blueprint schema rejects
+     * unknown fields; that data belongs to {@link toExportPayload}.
+     */
+    compile(): WorkflowBlueprint;
+    /** The compiled blueprint serialised as 2-space-indented JSON. */
+    compileJson(): string;
+    /** Write the compiled blueprint to a JSON file (default `workflow.spec.json`). */
+    save(path?: string): Promise<string>;
+    /**
+     * The camelCase user_workflows `ExportPayload` (canvas/authoring contract).
+     * Carries the UI-only metadata (positions, notes, canvasLayout) that the
+     * publish blueprint omits.
+     */
+    toExportPayload(): ExportPayload;
+    /** Rebuild a {@link WorkflowSpec} from a user_workflows `ExportPayload`. */
+    static fromExportPayload(payload: ExportPayload): WorkflowSpec;
+    /**
+     * Rebuild a {@link WorkflowSpec} from a publish blueprint. Lossy for canvas
+     * metadata by design — that data lives in the `ExportPayload` contract.
+     */
+    static fromBlueprint(blueprint: WorkflowBlueprint): WorkflowSpec;
+    /**
+     * Parse a spec from a JSON string. Shape-sniffs: objects carrying `spec_id`
+     * or `public_schema_version` parse as a blueprint; anything else as an
+     * `ExportPayload` — so `push --workflow-file` accepts both file formats.
+     */
+    static fromJson(data: string): WorkflowSpec;
+    /** Read a saved spec from a JSON file (default `workflow.spec.json`). */
+    static load(path?: string): Promise<WorkflowSpec>;
+}
+
+/**
+ * The five high-level workflow policies an author may attach to a published
+ * workflow. Grounded in `docs/contracts/sdk_public_openapi.yaml`
+ * (§WorkflowPolicies) — camelCase wire, every field optional. These attach to a
+ * community-workflow patch (the platform client, a later increment), so they are
+ * standalone here and are NOT folded into {@link WorkflowSpec.compile}.
+ */
+/** Failure categories that trigger a retry. */
+type RetryCategory = 'transient' | 'rate_limited' | 'tool_error';
+/** When and how a failed step is retried. */
+interface RetryPolicy {
+    /** 1–10. */
+    maxAttempts?: number;
+    /** ≥ 0. */
+    backoffMs?: number;
+    retryOn?: RetryCategory[];
+}
+/** Per-workflow wall-clock + step-count bound. */
+interface TimeoutPolicy {
+    /** ≥ 1. */
+    maxStepCount?: number;
+    /** ≥ 1. */
+    maxWallClockSeconds?: number;
+}
+/** Structural + quality checks the final artefact must pass. */
+interface OutputValidationPolicy {
+    requiredSections?: string[];
+    /** ≥ 0. */
+    minLengthChars?: number;
+    qualityRubric?: string;
+}
+/** Situations in which the workflow must pause for a human answer. */
+type PauseTrigger = 'ambiguity' | 'high_cost' | 'low_confidence';
+/** When the workflow must pause for a human. */
+interface HumanReviewPolicy {
+    pauseFor?: PauseTrigger[];
+    slotPromptStyle?: 'terse' | 'verbose';
+}
+/** What to do when retries are exhausted or output validation fails. */
+type FallbackAction = 'abort' | 'return_partial' | 'escalate';
+/** Behaviour after retries are exhausted / validation fails. */
+interface FallbackPolicy {
+    action?: FallbackAction;
+    escalationContact?: string;
+}
+/** The five policies; declare only those you want to constrain. */
+interface WorkflowPolicies {
+    retry?: RetryPolicy;
+    timeout?: TimeoutPolicy;
+    outputValidation?: OutputValidationPolicy;
+    humanReview?: HumanReviewPolicy;
+    fallback?: FallbackPolicy;
+}
+/**
+ * Validate + normalise a {@link WorkflowPolicies} object: range-checks the
+ * numeric bounds from the contract and returns a fresh object containing only
+ * the sub-policies that were supplied. Throws {@link ConvilynAuthorError} on an
+ * out-of-range value.
+ */
+declare function buildWorkflowPolicies(input: WorkflowPolicies): WorkflowPolicies;
+
+/**
+ * `defineTool` — declare a tool for a {@link ToolServer}. The author supplies a
+ * Zod schema for the input; the SDK derives the manifest `input_schema`
+ * (JSON Schema) from it via `zod-to-json-schema`, statically types the handler
+ * args via `z.infer`, and validates inbound `/mcp` arguments against it at
+ * runtime. (Design decision: TS has no type-hint reflection, so the
+ * schema is author-supplied — Zod is the single source for schema + types +
+ * validation. `zod` is a peerDependency and is **not** re-exported.)
+ */
+
+/** A handler's return — sync or async {@link ToolResult}. */
+type ToolHandlerResult = ToolResult | Promise<ToolResult>;
+/** A compiled tool: its manifest spec, its input validator, and its handler. */
+interface ToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly idempotent: boolean;
+    /** The Zod schema; used to validate inbound `/mcp` arguments. */
+    readonly inputSchema: ZodTypeAny;
+    /** The JSON Schema derived from `inputSchema` (manifest `input_schema`). */
+    readonly jsonSchema: Record<string, unknown>;
+    /** Optional manifest `output_schema` (a JSON Schema object). */
+    readonly outputSchema?: Record<string, unknown>;
+    /** Runs the tool with already-validated arguments. */
+    readonly handler: (args: unknown, ctx: ToolContext) => ToolHandlerResult;
+    /** The manifest row for this tool. */
+    toSpec(): ToolSpec;
+}
+/** Definition object accepted by {@link defineTool}. */
+interface ToolDefinitionInput<S extends ZodTypeAny> {
+    name: string;
+    description: string;
+    /** A Zod object schema describing the tool's arguments. */
+    input: S;
+    idempotent: boolean;
+    /** Receives arguments typed by `input` (via `z.infer`) and the execution context. */
+    handler: (args: TypeOf<S>, ctx: ToolContext) => ToolHandlerResult;
+    /** Optional JSON Schema for the tool's output (manifest only; not validated). */
+    outputSchema?: Record<string, unknown>;
+}
+/**
+ * Declare a tool. Returns a {@link ToolDefinition} ready to register on a
+ * {@link ToolServer}. The `input` Zod schema is the single source of truth for
+ * the manifest schema, the handler's argument types, and runtime validation.
+ */
+declare function defineTool<S extends ZodTypeAny>(def: ToolDefinitionInput<S>): ToolDefinition;
+
+/**
+ * JSON-RPC 2.0 envelope types + constructors for the `/mcp` runtime. The wire
+ * shape matches the `mcp-shared` framework and the Python / Go author SDKs so a
+ * TS-authored server is interchangeable behind the same gateway:
+ *
+ *     request  { jsonrpc:"2.0", method:"tools/call", params:{ name, arguments, context? }, id }
+ *     response { jsonrpc:"2.0", result?, error?:{ code, message, data? }, id }
+ *
+ * Tool-level outcomes (validation failures, tool errors) ride inside `result`
+ * as a ToolResult envelope — only protocol-level faults use the `error` member.
+ */
+/** JSON-RPC protocol version string. */
+declare const JSONRPC_VERSION = "2.0";
+/** The single method the runtime dispatches. */
+declare const TOOLS_CALL = "tools/call";
+/** An inbound JSON-RPC request. */
+interface JSONRPCRequest {
+    jsonrpc: string;
+    method: string;
+    params?: Record<string, unknown>;
+    id?: string | number | null;
+}
+/** The `error` member of a JSON-RPC response. */
+interface JSONRPCErrorObject {
+    code: number;
+    message: string;
+    data?: Record<string, unknown>;
+}
+/** An outbound JSON-RPC response (exactly one of `result` / `error`). */
+interface JSONRPCResponse {
+    jsonrpc: typeof JSONRPC_VERSION;
+    result?: unknown;
+    error?: JSONRPCErrorObject;
+    id: string | number | null;
+}
+
+/**
+ * `ToolServer` — the registry of an author's tools and the transport-free
+ * JSON-RPC dispatcher behind the `/mcp` endpoint. {@link ToolServer.dispatch} is
+ * pure (request in, response out), so it is unit-testable without sockets; the
+ * Node `http` wiring lives in `http-runtime.ts`.
+ *
+ * Dispatch contract (matches the `mcp-shared` framework):
+ * - only `tools/call` is supported; any other method → `-32601`.
+ * - missing `params.name` → `-32602`; unknown tool → `-32601`.
+ * - input that fails the tool's Zod schema → a `validation_error` ToolResult
+ *   envelope inside `result` (NOT a JSON-RPC error).
+ * - a handler that throws → `-32603`.
+ * - the built-in `get_tool_data` resolves a `ref_id` from the DataStore; it is
+ *   not listed in the manifest (the platform injects it globally).
+ */
+
+/** The built-in tool that resolves an offloaded `ref_id` to its full payload. */
+declare const GET_TOOL_DATA = "get_tool_data";
+/** Options for constructing a {@link ToolServer}. */
+interface ToolServerOptions {
+    tools?: ToolDefinition[];
+    capabilities?: string[];
+    /** Backing store for `ref_id` offload + retrieval; defaults to in-memory. */
+    dataStore?: DataStore;
+    sdkVersion?: string;
+}
+/** The registry of an author's tools plus the JSON-RPC dispatcher. */
+declare class ToolServer {
+    #private;
+    readonly server: ServerSpec;
+    readonly dataStore: DataStore;
+    constructor(server: ServerSpec, options?: ToolServerOptions);
+    /** Register a tool. Throws on a duplicate name. Chainable. */
+    register(tool: ToolDefinition): this;
+    /** Names of the registered (author) tools. */
+    get toolNames(): string[];
+    /** Number of registered (author) tools — the `/health` `tool_count`. */
+    get toolCount(): number;
+    /** The compiled manifest blueprint for this server. */
+    manifest(): ConvilynManifest;
+    /**
+     * Dispatch one JSON-RPC request. Pure and transport-free: never throws for a
+     * tool fault — protocol faults become a JSON-RPC `error`, tool/validation
+     * faults become a ToolResult envelope inside `result`.
+     */
+    dispatch(request: JSONRPCRequest): Promise<JSONRPCResponse>;
+}
+
+/**
+ * Node `http` runtime for a {@link ToolServer}. Exposes the three endpoints the
+ * gateway expects:
+ *
+ *   GET  /health    → { status, server, version, tool_count }
+ *   GET  /manifest  → the server manifest (snake_case wire object)
+ *   POST /mcp       → HMAC-verified JSON-RPC `tools/call` dispatch
+ *
+ * The HMAC signature covers the **raw request body bytes**, so the body buffer is
+ * captured before any `JSON.parse`. Verification reuses {@link verifySignature}
+ * (byte-for-byte parity with the gateway signer). No external dependencies.
+ */
+
+/** Options for {@link serve}; unset fields fall back to {@link SDKConfig}. */
+interface ServeOptions {
+    port?: number;
+    host?: string;
+    /** HMAC secret for `/mcp` verification. Required to accept signed requests. */
+    hmacSecret?: string;
+    toleranceSeconds?: number;
+    /**
+     * Explicit INSECURE local-development opt-in: with no secret configured,
+     * `serve` refuses to start unless this is `true` (set by `convilyn-author
+     * dev`) or `CONVILYN_DEV_INSECURE=1` is in the environment. A configured
+     * secret always wins — the opt-in never bypasses verification.
+     */
+    allowInsecure?: boolean;
+    /** Pre-built config; defaults to {@link SDKConfig.fromEnv}. */
+    config?: SDKConfig;
+}
+/**
+ * Environment variable that explicitly opts a bare `serve()` process into
+ * INSECURE local development (no inbound signature verification). Port of the
+ * Python `ENV_DEV_INSECURE` / Go `EnvDevInsecure`.
+ */
+declare const ENV_DEV_INSECURE = "CONVILYN_DEV_INSECURE";
+/**
+ * True iff the operator explicitly opted into insecure local dev. Any other
+ * value (including unset) is "not opted in" — the secure default is
+ * fail-closed.
+ */
+declare function devInsecureRequested(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Build and start an HTTP server for `toolServer`. Returns the listening
+ * {@link Server}; await its `listening` event (and read `.address()`) for the
+ * bound port when `port` is `0`.
+ *
+ * **Fail-closed:** unless an HMAC secret is configured, `serve` throws
+ * {@link ConvilynStartupError} — independent of `CONVILYN_ENVIRONMENT` or the
+ * bind host. Insecure local development must be opted into explicitly, either
+ * via `allowInsecure: true` (passed by `convilyn-author dev`) or by setting
+ * `CONVILYN_DEV_INSECURE=1`. Port of the Python `start_server`.
+ */
+declare function serve(toolServer: ToolServer, options?: ServeOptions): Server;
+
+/**
+ * Serialises an author-facing {@link ToolResult} into the snake_case ToolResult
+ * **wire envelope** the gateway expects. The author SDK keeps the result ergonomic
+ * (`ToolResult.ok` / `.fail`); this module bridges it to the richer wire shape:
+ *
+ *     { summary, status, data?, ref_id?, validation_errors?, error?,
+ *       success, error_code, error_message }
+ *
+ * `summary` is required on the wire (1–2000 chars); it is taken from
+ * {@link ToolResult.summary} when the author set one, otherwise derived here.
+ *
+ * Scope: statuses `ok` / `tool_error` / `validation_error`. The
+ * `needs_confirmation` handshake and `cost_micro_u` / `cost_breakdown` land in a
+ * follow-up.
+ */
+
+/** Tool execution status carried on the wire (A3 subset). */
+type ToolStatus = 'ok' | 'tool_error' | 'validation_error';
+/** One field-level validation failure (status `validation_error`). */
+interface ValidationIssueWire {
+    field: string;
+    issue: string;
+    expected?: string;
+}
+/** The snake_case ToolResult envelope as published on the wire. */
+interface ToolResultWire {
+    summary: string;
+    status: ToolStatus;
+    data?: Record<string, unknown>;
+    ref_id?: string;
+    validation_errors?: ValidationIssueWire[];
+    error?: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+    success: boolean;
+    error_code: string | null;
+    error_message: string | null;
+}
+/** Inline payloads larger than this (bytes, UTF-8) are offloaded to the DataStore. */
+declare const OUTPUT_INLINE_THRESHOLD_BYTES = 16384;
+
+/**
+ * Local, offline compliance checks for a {@link ToolServer} — the producer of
+ * the {@link ComplianceReport} the `convilyn-author test` command (and the A5
+ * local harness) report. No platform calls; nothing leaves the process.
+ *
+ * Checks are deliberately non-invasive: schemas and the runtime plumbing are
+ * exercised, but author tool handlers are NOT blindly invoked (they may have
+ * real side effects / external calls). `get_tool_data` is exercised against a
+ * value the harness stores itself.
+ */
+
+/**
+ * Run the local compliance suite against a server, returning a
+ * {@link ComplianceReport}. Use {@link allChecksPassed} / {@link failedChecks}
+ * (from `./types`) to interpret it.
+ */
+declare function runComplianceChecks(server: ToolServer): Promise<ComplianceReport>;
+
+/**
+ * Confirmation-handshake token signing — byte-for-byte compatible with the
+ * `mcp-shared` framework and the Python / Go author SDKs, so a token minted by a
+ * TS-authored server verifies against the gateway (and vice versa).
+ *
+ * Token wire format: `base64url("<expires>:<digest>:<sig>")` (RFC 4648 url-safe,
+ * **padding kept**), where
+ *   digest = sha256hex(canonicalJson(normalizeForDigest(arguments)))
+ *   sig    = hmacSha256hex(secret, "<toolName>|<expires>|<digest>")
+ *
+ * This is a **distinct** scheme from the inbound request HMAC in `./auth` (which
+ * signs `<timestamp>.<body>`); the two are not interchangeable.
+ *
+ * Byte-exactness notes:
+ * - `canonicalJson` matches Python `json.dumps(sort_keys=True, separators=(",",":"))`
+ *   with the default `ensure_ascii=True` — every code point ≥ 0x80 is emitted as
+ *   `\uXXXX` (surrogate pairs for non-BMP), keys sorted by UTF-16 code unit.
+ * - `normalizeForDigest` strips volatile presigned-URL query params before hashing
+ *   (re-encoding kept params with Python `quote_plus` semantics) so a re-presigned
+ *   URL still matches the confirmed arguments.
+ */
+/** Confirmation token lifetime (seconds); matches the framework constant. */
+declare const CONFIRMATION_TTL_SECONDS = 300;
+/** Recursively drop volatile presign params from any URL strings within `value`. */
+declare function normalizeForDigest(value: unknown): unknown;
+/** Arguments passed to {@link mintConfirmationToken} / {@link verifyConfirmationToken}. */
+interface ConfirmationTokenInput {
+    toolName: string;
+    arguments: Record<string, unknown>;
+    /** Unix seconds at which the token expires. */
+    expiresAtUnix: number;
+    secret: string;
+}
+/**
+ * Mint a confirmation token for a tool call, byte-for-byte compatible with the
+ * gateway / Python / Go signer.
+ */
+declare function mintConfirmationToken(input: ConfirmationTokenInput): string;
+/** Verification input (`expiresAtUnix` is ignored — it is read from the token). */
+interface VerifyConfirmationInput {
+    toolName: string;
+    arguments: Record<string, unknown>;
+    token: string;
+    secret: string;
+    /** Override "now" (Unix seconds) for tests; defaults to the real clock. */
+    now?: () => number;
+}
+/**
+ * Verify a confirmation token against the (re-)supplied arguments. Throws
+ * {@link ConfirmationInvalidError} on a malformed / expired / mismatched token.
+ * The `confirmation_token` argument (present on the confirming re-call) is
+ * stripped before re-computing the digest.
+ */
+declare function verifyConfirmationToken(input: VerifyConfirmationInput): void;
+
+/**
+ * Wire types for the Developer Portal (`/api/v1/developers/*`) consumed by
+ * {@link ConvilynClient}. Keys are snake_case, matching the platform's
+ * Developer Portal API. These mirror the platform response models, not any
+ * Python/Go SDK internal structure.
+ */
+
+/** Server verification-pipeline status (`ServerVerificationStatus`). */
+type ServerVerificationStatus = 'submitted' | 'validating' | 'sandbox_testing' | 'verified' | 'active' | 'rejected' | 'test_failed' | 'suspended';
+/** Workflow verification-pipeline status (`WorkflowVerificationStatus`). */
+type WorkflowVerificationStatus = 'submitted' | 'validating' | 'sandbox_testing' | 'active' | 'rejected' | 'suspended';
+/** Body for `POST /developers/register`. */
+interface DeveloperRegisterRequest {
+    email: string;
+    name: string;
+    company?: string;
+}
+/** Response of `POST /developers/register`. The `api_key` is shown only once. */
+interface DeveloperRegisterResponse {
+    developer_id: string;
+    api_key: string;
+    status: string;
+}
+/** Body for `POST /developers/servers`. `endpoint_url` must be https + public. */
+interface ServerSubmitRequest {
+    manifest: Record<string, unknown>;
+    endpoint_url: string;
+}
+/** Response of `POST /developers/servers`. */
+interface ServerSubmitResponse {
+    server_id: string;
+    server_name: string;
+    status: ServerVerificationStatus;
+}
+/** A registered server (item in `GET /developers/servers`). */
+interface DeveloperServer {
+    server_id: string;
+    server_name: string;
+    endpoint_url: string;
+    status: ServerVerificationStatus;
+    tools: string[];
+    created_at?: string | null;
+}
+/** Response of `GET /developers/servers/{id}/status`. */
+interface ServerStatusResponse {
+    server_id: string;
+    status: ServerVerificationStatus;
+    message?: string | null;
+}
+/** Response of a sandbox test run (`POST /developers/servers/{id}/test`). */
+interface TestRunResponse {
+    run_id: string;
+    status: string;
+    results: Record<string, unknown>;
+    tool_call_log: Array<Record<string, unknown>>;
+}
+/** Body for `POST /developers/workflows`. */
+interface WorkflowSubmitRequest {
+    /** Compiled workflow spec — the `WorkflowSpec.compile()` blueprint (a plain
+     * object is also accepted for hand-built specs). */
+    workflow_spec: WorkflowBlueprint | Record<string, unknown>;
+    /** Server ids whose tools this workflow uses (1–20). */
+    server_ids: string[];
+}
+/** Response of `POST /developers/workflows`. */
+interface WorkflowSubmitResponse {
+    workflow_id: string;
+    spec_id: string;
+    status: WorkflowVerificationStatus;
+}
+/** Response of `GET /developers/workflows/{id}/status`. */
+interface WorkflowStatusResponse {
+    workflow_id: string;
+    spec_id: string;
+    status: WorkflowVerificationStatus;
+    validation_errors: string[];
+}
+/** A submitted workflow in list view (`GET /developers/workflows`). */
+interface WorkflowListItem {
+    workflow_id: string;
+    spec_id: string;
+    name: string;
+    version: string;
+    status: WorkflowVerificationStatus;
+    server_ids: string[];
+    created_at?: string | null;
+}
+/** Per-server health check captured during a workflow test run. */
+interface WorkflowServerCheck {
+    server_id: string;
+    server_name: string;
+    passed: boolean;
+    checks: Array<Record<string, unknown>>;
+}
+/** Response of `POST /developers/workflows/{id}/test`. */
+interface WorkflowTestResponse {
+    workflow_id: string;
+    status: string;
+    validation: Record<string, unknown>;
+    server_checks: WorkflowServerCheck[];
+    all_passed: boolean;
+}
+/** Lifecycle status of a hosted author runtime. */
+type RuntimeStatus = 'provisioning' | 'active' | 'rolling_back' | 'inactive' | 'failed';
+/** Request body of `POST /developers/runtimes/hosted`. */
+interface DeployHostedRequest {
+    manifest: Record<string, unknown>;
+    region: string;
+    workflow_spec?: Record<string, unknown>;
+}
+/** Response of `POST /developers/runtimes/hosted` (202). */
+interface DeployHostedResponse {
+    runtime_id: string;
+    status: RuntimeStatus;
+    endpoint_url?: string | null;
+    region: string;
+    version: number;
+    workflow_id?: string | null;
+}
+/** Response of `POST /developers/runtimes/{id}/rollback`. */
+interface RollbackResponse {
+    runtime_id: string;
+    version: number;
+    status: RuntimeStatus;
+}
+/** One log line from `GET /developers/runtimes/{id}/logs`. */
+interface RuntimeLogEntry {
+    timestamp: string;
+    level: string;
+    message: string;
+}
+
+/**
+ * `ConvilynClient` — a fetch-based client for the **Developer Portal**
+ * (`/api/v1/developers/*`), the platform's third-party author/publish surface.
+ *
+ * This is the TypeScript counterpart of the Python `convilyn_sdk.ConvilynClient`
+ * (`sdk/author-python/src/convilyn_sdk/client.py`): the author BUILDS a tool
+ * server + workflow spec locally (`ToolServer`, `WorkflowSpec`,
+ * `runComplianceChecks`), then INTEGRATES its own artifacts by registering them
+ * through the portal:
+ *
+ *   POST   /developers/register            — mint a `cvl_` developer key (no auth)
+ *   POST   /developers/servers             — submit a tool-server manifest
+ *   GET    /developers/servers             — list
+ *   GET    /developers/servers/{id}/status — verification status
+ *   POST   /developers/servers/{id}/test   — sandbox test
+ *   DELETE /developers/servers/{id}        — deactivate
+ *   POST   /developers/workflows           — submit a compiled workflow spec
+ *   GET    /developers/workflows           — list
+ *   GET    /developers/workflows/{id}/status — status
+ *   POST   /developers/workflows/{id}/test — sandbox test
+ *   DELETE /developers/workflows/{id}      — deactivate
+ *   POST   /developers/runtimes/hosted     — deploy to the hosted author runtime
+ *   POST   /developers/runtimes/{id}/rollback — flip to the previous version
+ *   GET    /developers/runtimes/{id}/logs  — recent runtime log lines
+ *
+ * Auth: `Authorization: Bearer <cvl_ developer key>`, read from
+ * `CONVILYN_API_KEY` (`config.ts`). This SDK deliberately does NOT call the
+ * first-party console surfaces (`/user_workflows/*`, `/mcp/tools/catalog`) — those
+ * are JWT/session endpoints owned by the web UI, not an author-publishing API.
+ * Response bodies are snake_case, matching the platform's Developer Portal
+ * API.
+ */
+
+/** The subset of `fetch` the client uses (so a fake can be injected in tests). */
+type FetchLike = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+/** Options for {@link ConvilynClient}; unset fields fall back to {@link SDKConfig}. */
+interface ConvilynClientOptions {
+    /** Full API base incl. `/api/v1`; defaults to `${platformUrl}/api/v1`. */
+    baseUrl?: string;
+    /** `cvl_` developer key; defaults to `CONVILYN_API_KEY`. */
+    apiKey?: string;
+    /** Injected `fetch` (defaults to the global). */
+    fetch?: FetchLike;
+    config?: SDKConfig;
+}
+/** Fetch-based client for the Developer Portal author/publish endpoints. */
+declare class ConvilynClient {
+    #private;
+    readonly baseUrl: string;
+    constructor(options?: ConvilynClientOptions);
+    /** The `cvl_` developer key currently in use (empty until set or registered). */
+    get apiKey(): string;
+    /**
+     * `POST /developers/register` — create a developer account and mint a `cvl_`
+     * key. No auth required. The returned key is captured on this client for
+     * subsequent calls (and returned so the caller can persist it — it is shown
+     * only once).
+     */
+    register(request: DeveloperRegisterRequest): Promise<DeveloperRegisterResponse>;
+    /** `POST /developers/servers` — submit a tool-server manifest for verification. */
+    submitServer(request: ServerSubmitRequest): Promise<ServerSubmitResponse>;
+    /** `GET /developers/servers` — list this developer's servers. */
+    listServers(): Promise<DeveloperServer[]>;
+    /** `GET /developers/servers/{id}/status` — verification status of a server. */
+    serverStatus(serverId: string): Promise<ServerStatusResponse>;
+    /** `POST /developers/servers/{id}/test` — trigger a sandbox test run. */
+    testServer(serverId: string, slots?: Record<string, unknown>): Promise<TestRunResponse>;
+    /** `DELETE /developers/servers/{id}` — deactivate a server. */
+    deactivateServer(serverId: string): Promise<void>;
+    /** `POST /developers/workflows` — submit a compiled workflow spec + its server ids. */
+    submitWorkflow(request: WorkflowSubmitRequest): Promise<WorkflowSubmitResponse>;
+    /** `GET /developers/workflows` — list this developer's workflows. */
+    listWorkflows(): Promise<WorkflowListItem[]>;
+    /** `GET /developers/workflows/{id}/status` — verification status of a workflow. */
+    workflowStatus(workflowId: string): Promise<WorkflowStatusResponse>;
+    /** `POST /developers/workflows/{id}/test` — sandbox-test a submitted workflow. */
+    testWorkflow(workflowId: string, testInput?: Record<string, unknown>): Promise<WorkflowTestResponse>;
+    /** `DELETE /developers/workflows/{id}` — deactivate a workflow. */
+    deactivateWorkflow(workflowId: string): Promise<void>;
+    /**
+     * `POST /developers/runtimes/hosted` — deploy a tool server into the
+     * Convilyn-Hosted Author Runtime. Counterpart to {@link submitServer}:
+     * instead of registering a caller-deployed endpoint, the platform
+     * provisions a sandboxed Lambda and returns its public endpoint URL.
+     *
+     * Backends without the hosted stack answer 503 `HOSTED_NOT_AVAILABLE`
+     * (older builds: 501); environments with the router unmounted answer 404.
+     * All surface as {@link ConvilynApiError} — catch and fall back to
+     * `push --endpoint-url` (BYO) when a hard guarantee is needed.
+     */
+    deployHostedRuntime(manifest: Record<string, unknown>, options: {
+        region: string;
+        workflowSpec?: Record<string, unknown>;
+    }): Promise<DeployHostedResponse>;
+    /**
+     * `POST /developers/runtimes/{id}/rollback` — atomically flip the runtime
+     * back to its previous active version.
+     */
+    rollbackHostedRuntime(runtimeId: string): Promise<RollbackResponse>;
+    /**
+     * `GET /developers/runtimes/{id}/logs` — recent runtime log lines.
+     * `since` is an ISO-8601 timestamp or relative shorthand (`"5m"`, `"1h"`)
+     * interpreted server-side; `limit` defaults to 100 (server caps ~1000).
+     * Accepts either a bare list or an `{entries: [...]}` envelope (mirror of
+     * the Python client) so the SDK survives the wire shape stabilising.
+     */
+    getHostedRuntimeLogs(runtimeId: string, options?: {
+        since?: string;
+        limit?: number;
+    }): Promise<RuntimeLogEntry[]>;
+}
+
+/**
+ * Local testing harness — invoke a registered tool in-process and get its wire
+ * envelope back, without standing up an HTTP server. Lets authors unit-test
+ * their tools (and the platform's confirmation / validation behaviour) directly
+ * against a {@link ToolServer}.
+ *
+ * It drives the same transport-free `ToolServer.dispatch` the `/mcp` runtime
+ * uses, so what you assert in a test is exactly what the gateway would receive.
+ */
+
+/** Options for {@link invokeTool}. */
+interface InvokeToolOptions {
+    /** `request_id` surfaced to the tool's {@link ToolContext}. */
+    requestId?: string;
+}
+/**
+ * Invoke `toolName` on `server` with `args` and return the ToolResult wire
+ * envelope. Throws {@link ConvilynAuthorError} if the dispatch returns a
+ * JSON-RPC protocol error (unknown tool / method / bad params) — tool-level
+ * outcomes (`tool_error` / `validation_error`) come back as an envelope, not a
+ * throw, so they can be asserted on.
+ */
+declare function invokeTool(server: ToolServer, toolName: string, args?: Record<string, unknown>, options?: InvokeToolOptions): Promise<ToolResultWire>;
+
+export { type BlueprintAgentConfig, type BlueprintMcpConfig, CONFIRMATION_TTL_SECONDS, type CanvasLayout, type CompiledWorkflowSpec, type ComplianceReport, type ComplianceResult, ConfirmationInvalidError, type ConfirmationInvalidReason, type ConfirmationTokenInput, ConsoleProgressBackend, ConvilynApiError, ConvilynAuthorError, ConvilynClient, type ConvilynClientOptions, ConvilynManifest, type ConvilynManifestOptions, ConvilynStartupError, DEFAULT_HMAC_TOLERANCE_SECONDS, type DataStore, type DeployHostedRequest, type DeployHostedResponse, type DeveloperRegisterRequest, type DeveloperRegisterResponse, type DeveloperServer, ENV_DEV_INSECURE, type ExportPayload, type FallbackAction, type FallbackPolicy, type FetchLike, GET_TOOL_DATA, type HumanReviewPolicy, InMemoryDataStore, InvalidSignatureError, type InvalidSignatureReason, type InvokeToolOptions, type JSONRPCErrorObject, type JSONRPCRequest, type JSONRPCResponse, JSONRPC_VERSION, MANIFEST_SDK_VERSION, OUTPUT_INLINE_THRESHOLD_BYTES, type OutputValidationPolicy, PUBLIC_SCHEMA_VERSION, type PauseTrigger, type Position, type ProgressBackend, type RequestBody, type RetryCategory, type RetryPolicy, type RollbackResponse, type RuntimeLogEntry, type RuntimeStatus, SDKConfig, type SDKConfigOptions, SERVER_ID_HEADER, SIGNATURE_HEADER, type ServeOptions, type ServerSpec, type ServerStatusResponse, type ServerSubmitRequest, type ServerSubmitResponse, type ServerVerificationStatus, type SourceType, TIMESTAMP_HEADER, TOOLS_CALL, type TestRunResponse, type TimeoutPolicy, ToolContext, type ToolDataRef, type ToolDefinition, type ToolDefinitionInput, type ToolError, type ToolHandlerResult, type ToolPaletteItem, ToolResult, type ToolResultWire, ToolServer, type ToolServerOptions, type ToolSpec, type ToolStatus, VERSION, type ValidationIssueWire, type VerifyConfirmationInput, type VerifyOptions, type Visibility, type WorkflowBlueprint, type WorkflowListItem, type WorkflowPolicies, type WorkflowServerCheck, WorkflowSpec, type WorkflowStatusResponse, type WorkflowSubmitRequest, type WorkflowSubmitResponse, type WorkflowTestResponse, type WorkflowVerificationStatus, allChecksPassed, buildWorkflowPolicies, createDataStore, createToolContext, defineTool, devInsecureRequested, failedChecks, generateRefId, invokeTool, mintConfirmationToken, normalizeForDigest, runComplianceChecks, serve, signRequest, verifyConfirmationToken, verifySignature };