@kindgi/tools 0.0.0-bootstrap.0 → 0.1.0

package/dist/http.js

@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { registerToolSpecSynthesizer } from './spec-registry.js';
+/**
+ * First-party synthesizer for `HttpToolSpec` (kind: 'http').
+ *
+ * `defineTool({spec: {kind: 'http', ...}})` produces a runtime
+ * `Tool` whose handler is auto-generated to perform the outbound
+ * HTTP call. The registered tool dispatches, validates, and travels
+ * identically to a hand-written in-process tool — kernel, invoke
+ * pipeline, and MCP discovery treat it as a normal `Tool`. The
+ * declarative `spec` field on the manifest is preserved for
+ * middleware and for JSON export / cross-process registration.
+ *
+ * Behavior at invoke time:
+ *
+ *   1. Input JSON-Schema validation runs (via the standard invoke
+ *      pipeline); handler receives a validated input.
+ *   2. `urlTemplate` placeholders are substituted from input keys.
+ *      Missing key → throw. Substituted keys are still available in
+ *      the request body (unless `requestBody.kind === 'input-passthrough'`
+ *      with different semantics documented below).
+ *   3. `authorization` is resolved via `ctx.resolveSecret(secretRef)`.
+ *      If the tool declares authorization but `ctx.resolveSecret` is
+ *      undefined, the handler throws a clear error rather than
+ *      silently dropping the credential.
+ *   4. Static headers are added as-is.
+ *   5. Request body is built per `requestBody.kind`:
+ *        - `'json-input'` (default when `requestBody` absent for
+ *          POST/PUT/PATCH): JSON-serialize the tool's input MINUS
+ *          keys already consumed by `urlTemplate`.
+ *        - `'input-passthrough'`: JSON-serialize the entire input
+ *          without removing URL-consumed keys.
+ *        - `'text'`: substitute `{param}` placeholders in `template`
+ *          from input; send as `Content-Type: text/plain`.
+ *   6. `fetch()` with an AbortController that inherits from
+ *      `ctx.abortSignal` and adds a `timeoutMs` deadline (default
+ *      30_000). Aborts propagate as `handler-error`.
+ *   7. Status is checked against `successStatus` (default 200-299).
+ *      Failures throw with the response body as the message.
+ *   8. Response body is parsed as JSON (default) or returned as
+ *      text. Output JSON-Schema validation runs in the invoke
+ *      pipeline; handler doesn't validate.
+ */
+function buildHttpHandler(spec, toolId, options = {}) {
+    const doFetch = options.fetch ?? fetch;
+    return async (input, ctx) => {
+        const inputObj = coerceInputToObject(input, toolId);
+        const { url, consumedKeys } = substituteUrl(spec.urlTemplate, inputObj, toolId);
+        const headers = {};
+        for (const h of spec.headers ?? []) {
+            headers[h.name] = substituteTemplate(h.value, inputObj);
+        }
+        if (spec.authorization !== undefined) {
+            applyAuth(headers, spec.authorization, ctx, toolId, await resolveAuthSecret(spec.authorization, ctx, toolId));
+        }
+        const { body, contentType } = buildBody(spec, inputObj, consumedKeys);
+        if (body !== undefined && contentType !== undefined && headers['Content-Type'] === undefined) {
+            headers['Content-Type'] = contentType;
+        }
+        const timeoutMs = spec.timeoutMs ?? 30_000;
+        const controller = new AbortController();
+        const timeoutHandle = setTimeout(() => controller.abort(new Error(`http-tool "${toolId}" timed out after ${timeoutMs}ms`)), timeoutMs);
+        // Chain the caller's abort signal into ours — if the run is
+        // cancelled mid-flight, the outbound request cancels too.
+        const upstreamAbort = () => controller.abort(ctx.abortSignal.reason);
+        if (ctx.abortSignal.aborted) {
+            clearTimeout(timeoutHandle);
+            throw ctx.abortSignal.reason ?? new Error('aborted');
+        }
+        ctx.abortSignal.addEventListener('abort', upstreamAbort, { once: true });
+        let response;
+        try {
+            response = await doFetch(url, {
+                method: spec.method,
+                headers,
+                ...(body !== undefined && { body }),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timeoutHandle);
+            ctx.abortSignal.removeEventListener('abort', upstreamAbort);
+        }
+        const successMin = spec.successStatus?.min ?? 200;
+        const successMax = spec.successStatus?.max ?? 299;
+        if (response.status < successMin || response.status > successMax) {
+            const text = await safeText(response);
+            throw new Error(`http-tool "${toolId}" got status ${response.status} ${response.statusText || ''} — ${text.slice(0, 512)}`);
+        }
+        const parseJson = spec.parseJson ?? true;
+        if (!parseJson) {
+            return await response.text();
+        }
+        const rawText = await response.text();
+        if (rawText.length === 0)
+            return null;
+        try {
+            return JSON.parse(rawText);
+        }
+        catch (cause) {
+            throw new Error(`http-tool "${toolId}" response was not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+    };
+}
+// Register at module load. Framework barrel imports this module
+// (`packages/tools/src/index.ts`) so any consumer that pulls in
+// `@kindgi/tools` gets the 'http' kind registered automatically.
+registerToolSpecSynthesizer('http', buildHttpHandler);
+function coerceInputToObject(input, toolId) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new Error(`http-tool "${toolId}" requires an object input for URL substitution; got ${typeof input}`);
+    }
+    return input;
+}
+/**
+ * Substitute `{name}` placeholders in `template` with values from
+ * `input`. Returns the substituted URL plus the set of keys that
+ * were consumed (used by `buildBody` to strip them from a
+ * `json-input` body).
+ *
+ * URL-safe encoding: values are `encodeURIComponent`'d. Numeric,
+ * boolean, and string primitives are coerced via `String()`; nested
+ * objects or arrays throw.
+ */
+function substituteUrl(template, input, toolId) {
+    const consumed = new Set();
+    const url = template.replace(/\{(\w+)\}/g, (_, key) => {
+        if (!(key in input)) {
+            throw new Error(`http-tool "${toolId}" urlTemplate references "{${key}}" but input has no such key`);
+        }
+        const value = input[key];
+        if (value === null ||
+            value === undefined ||
+            typeof value === 'object' ||
+            typeof value === 'function' ||
+            typeof value === 'symbol') {
+            throw new Error(`http-tool "${toolId}" urlTemplate key "{${key}}" must be a primitive; got ${typeof value}`);
+        }
+        consumed.add(key);
+        return encodeURIComponent(String(value));
+    });
+    return { url, consumedKeys: consumed };
+}
+/**
+ * Substitute `{name}` placeholders in a plain string (used for
+ * header values + `text` body templates). Unlike `substituteUrl`,
+ * this does NOT URL-encode values — headers/text bodies want raw
+ * strings. Missing keys throw.
+ */
+function substituteTemplate(template, input) {
+    return template.replace(/\{(\w+)\}/g, (_, key) => {
+        if (!(key in input))
+            return `{${key}}`; // preserve if not in input (may be literal braces)
+        const value = input[key];
+        if (value === null || value === undefined)
+            return '';
+        return String(value);
+    });
+}
+async function resolveAuthSecret(auth, ctx, toolId) {
+    if (ctx.resolveSecret === undefined) {
+        throw new Error(`http-tool "${toolId}" declares authorization but ToolContext.resolveSecret is not wired. The dispatch site must populate resolveSecret from the deployment's SecretBinding.`);
+    }
+    return ctx.resolveSecret(auth.secretRef);
+}
+function applyAuth(headers, auth, _ctx, _toolId, resolvedSecret) {
+    switch (auth.kind) {
+        case 'bearer':
+            headers.Authorization = `Bearer ${resolvedSecret}`;
+            return;
+        case 'header':
+            headers[auth.headerName] = resolvedSecret;
+            return;
+    }
+}
+function buildBody(spec, input, consumedKeys) {
+    // Methods that don't carry a body by convention.
+    if (spec.method === 'GET' && spec.requestBody === undefined) {
+        return { body: undefined, contentType: undefined };
+    }
+    const kind = spec.requestBody?.kind ?? 'json-input';
+    if (kind === 'json-input') {
+        const remaining = {};
+        for (const [k, v] of Object.entries(input)) {
+            if (!consumedKeys.has(k))
+                remaining[k] = v;
+        }
+        // Empty remaining input → still send an empty body so servers
+        // can distinguish "no body" from "empty body". For POST-with-only-
+        // URL-params the caller can explicitly configure `input-passthrough`
+        // or a `text` body if the server expects that shape.
+        if (Object.keys(remaining).length === 0) {
+            return { body: '', contentType: undefined };
+        }
+        return { body: JSON.stringify(remaining), contentType: 'application/json' };
+    }
+    if (kind === 'input-passthrough') {
+        return { body: JSON.stringify(input), contentType: 'application/json' };
+    }
+    // kind === 'text'
+    const template = spec.requestBody.template;
+    return { body: substituteTemplate(template, input), contentType: 'text/plain' };
+}
+async function safeText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '<no body>';
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { defineTool, defineToolAsync, validateToolManifest, TOOL_SCHEMA_URI_EXPORTED as TOOL_SCHEMA_URI, } from './define.js';
+export type { DefineToolOptions, DefineToolSpec, DefinedTool, InferInput, InferOutput, } from './define.js';
+import './http.js';
+export { registerToolSpecSynthesizer, getToolSpecSynthesizer } from './spec-registry.js';
+export type { ToolSpecSynthesizer, ToolSpecSynthesizerOptions } from './spec-registry.js';
+export { invokeTool } from './invoke.js';
+export { ToolPreconditionError, isToolPreconditionError } from './precondition.js';
+export type { InvokeToolOptions } from './invoke.js';
+export { createToolRegistry } from './registry.js';
+export type { ToolRegistry, ToolResolution } from './registry.js';
+export { toManifest, toMcpManifest } from './manifest.js';
+export { EFFECT_KINDS } from './types.js';
+export type { AnyTool, CodeArtifactRef, Effect, EffectKind, HttpAuthSpec, HttpHeaderSpec, HttpMethod, HttpRequestBodySpec, HttpToolSpec, JsonSchema, McpToolManifest, Need, NetworkPolicy, RuntimeLimits, SandboxMode, Tool, ToolContext, ToolManifest, ToolSecretRef, ToolSpec, TypedNeeds, } from './types.js';
+export type { DuplicateToolError, DuplicateToolVersionError, HandlerError, InputValidationError, InvalidSchemaError, InvalidToolDefinitionError, InvalidVersionRangeError, OutputValidationError, PreconditionFailedError, ToolError, ToolNotFoundError, ToolVersionNotFoundError, ToolVersionUnresolvableError, UnknownEffectError, } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,UAAU,EACV,eAAe,EACf,oBAAoB,EACpB,wBAAwB,IAAI,eAAe,GAC5C,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,UAAU,EACV,WAAW,GACZ,MAAM,aAAa,CAAC;AAIrB,OAAO,WAAW,CAAC;AACnB,OAAO,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACzF,YAAY,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACnF,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EACV,OAAO,EACP,eAAe,EACf,MAAM,EACN,UAAU,EACV,YAAY,EACZ,cAAc,EACd,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,eAAe,EACf,IAAI,EACJ,aAAa,EACb,aAAa,EACb,WAAW,EACX,IAAI,EACJ,WAAW,EACX,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,kBAAkB,EAClB,yBAAyB,EACzB,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,SAAS,EACT,iBAAiB,EACjB,wBAAwB,EACxB,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export { defineTool, defineToolAsync, validateToolManifest, TOOL_SCHEMA_URI_EXPORTED as TOOL_SCHEMA_URI, } from './define.js';
+// Side-effect import — registers the 'http' spec synthesizer at
+// package load so `defineTool({spec: {kind: 'http', ...}})` works
+// out of the box for any consumer that imports @kindgi/tools.
+import './http.js';
+export { registerToolSpecSynthesizer, getToolSpecSynthesizer } from './spec-registry.js';
+export { invokeTool } from './invoke.js';
+export { ToolPreconditionError, isToolPreconditionError } from './precondition.js';
+export { createToolRegistry } from './registry.js';
+export { toManifest, toMcpManifest } from './manifest.js';
+export { EFFECT_KINDS } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,EACL,UAAU,EACV,eAAe,EACf,oBAAoB,EACpB,wBAAwB,IAAI,eAAe,GAC5C,MAAM,aAAa,CAAC;AAQrB,gEAAgE;AAChE,kEAAkE;AAClE,8DAA8D;AAC9D,OAAO,WAAW,CAAC;AACnB,OAAO,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEzF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/invoke.d.ts

@@ -0,0 +1,27 @@
+import type { Result } from '@kindgi/types';
+import type { ToolError } from './errors.js';
+import type { Tool, ToolContext } from './types.js';
+export interface InvokeToolOptions {
+    /**
+     * Skip validation of the handler's return value against `tool.output`.
+     * Trade-off: faster, but a broken handler can produce data that violates
+     * the declared contract without the runtime noticing. Default: false.
+     */
+    readonly skipOutputValidation?: boolean;
+}
+/**
+ * Invoke a tool with a caller-supplied input and context. The path is:
+ *   1. Validate a copy of `input` against `tool.input`, filling in its
+ *      defaults, and — for a Zod-authored tool — parse it with
+ *      `tool.inputZod` (defaults, transforms, refinements). Reject on
+ *      failure.
+ *   2. Call `tool.handler(prepared, ctx)`. Catch any throw and return
+ *      `handler-error` — invocation is total, throws don't escape.
+ *   3. Validate the return value against `tool.output` schema (unless the
+ *      caller opts out).
+ *
+ * Validation cost is amortised via a schema-object-keyed cache — the second
+ * invocation of the same tool reuses the compiled Ajv validator.
+ */
+export declare function invokeTool<TInput = unknown, TOutput = unknown>(tool: Tool<TInput, TOutput>, input: unknown, ctx: ToolContext, options?: InvokeToolOptions): Promise<Result<TOutput, ToolError>>;
+//# sourceMappingURL=invoke.d.ts.map

package/dist/invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../src/invoke.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,KAAK,EAKV,SAAS,EACV,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAc,IAAI,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA6EhE,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAClE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3B,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAyCrC"}

package/dist/invoke.js

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import * as addFormatsModule from 'ajv-formats';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { parseWithSchema } from '@kindgi/schema';
+import { isToolPreconditionError } from './precondition.js';
+const addFormatsRaw = addFormatsModule;
+const addFormats = typeof addFormatsRaw === 'function'
+    ? addFormatsRaw
+    : addFormatsRaw.default;
+/**
+ * Cache compiled validators keyed by the schema *object reference*. Tools
+ * are defined once and reused, so schema identity is stable — the WeakMap
+ * releases entries when the tool is dropped.
+ */
+const inputCache = new WeakMap();
+const outputCache = new WeakMap();
+/**
+ * A compiled validator. Input validators fill in each property's JSON
+ * Schema `default` (`useDefaults`) — the data they check is a copy of the
+ * caller's.
+ */
+function compile(schema, side) {
+    const cache = side === 'input' ? inputCache : outputCache;
+    const cached = cache.get(schema);
+    if (cached !== undefined)
+        return cached;
+    const ajv = new Ajv2020({
+        strict: true,
+        allErrors: true,
+        allowUnionTypes: false,
+        ...(side === 'input' && { useDefaults: true }),
+    });
+    addFormats(ajv);
+    const validator = ajv.compile(schema);
+    cache.set(schema, validator);
+    return validator;
+}
+/**
+ * The input a handler receives: validated against `tool.input` with its
+ * defaults filled in, then — for a Zod-authored tool — parsed by its Zod
+ * schema, so defaults, transforms and refinements apply and the handler
+ * gets what its `z.infer` type says.
+ */
+async function prepareInput(tool, input) {
+    const candidate = structuredClone(input);
+    const validator = compile(tool.input, 'input');
+    if (!validator(candidate)) {
+        return { kind: 'err', error: inputError(tool.id, validator.errors ?? []) };
+    }
+    if (tool.inputZod === undefined)
+        return { kind: 'ok', value: candidate };
+    const parsed = await parseWithSchema(tool.inputZod, candidate);
+    if (parsed.kind === 'ok')
+        return parsed;
+    return {
+        kind: 'err',
+        error: inputError(tool.id, parsed.issues.map((i) => ({
+            instancePath: (i.path ?? []).map((p) => `/${String(p)}`).join(''),
+            message: i.message,
+        }))),
+    };
+}
+function inputError(toolId, errors) {
+    return {
+        code: 'input-validation-failed',
+        message: `Input for tool "${toolId}" failed validation`,
+        toolId,
+        errors,
+    };
+}
+/**
+ * Invoke a tool with a caller-supplied input and context. The path is:
+ *   1. Validate a copy of `input` against `tool.input`, filling in its
+ *      defaults, and — for a Zod-authored tool — parse it with
+ *      `tool.inputZod` (defaults, transforms, refinements). Reject on
+ *      failure.
+ *   2. Call `tool.handler(prepared, ctx)`. Catch any throw and return
+ *      `handler-error` — invocation is total, throws don't escape.
+ *   3. Validate the return value against `tool.output` schema (unless the
+ *      caller opts out).
+ *
+ * Validation cost is amortised via a schema-object-keyed cache — the second
+ * invocation of the same tool reuses the compiled Ajv validator.
+ */
+export async function invokeTool(tool, input, ctx, options = {}) {
+    const prepared = await prepareInput(tool, input);
+    if (prepared.kind === 'err')
+        return prepared;
+    let output;
+    try {
+        output = await tool.handler(prepared.value, ctx);
+    }
+    catch (cause) {
+        if (isToolPreconditionError(cause)) {
+            const refused = {
+                code: 'precondition-failed',
+                message: `Tool "${tool.id}" was not run: ${cause.reason}: ${cause.message}`,
+                toolId: tool.id,
+                reason: cause.reason,
+                cause,
+            };
+            return { kind: 'err', error: refused };
+        }
+        const err = {
+            code: 'handler-error',
+            message: `Tool "${tool.id}" handler threw: ${cause instanceof Error ? cause.message : String(cause)}`,
+            toolId: tool.id,
+            cause,
+        };
+        return { kind: 'err', error: err };
+    }
+    if (!options.skipOutputValidation) {
+        const outputValidator = compile(tool.output, 'output');
+        if (!outputValidator(output)) {
+            const err = {
+                code: 'output-validation-failed',
+                message: `Tool "${tool.id}" handler produced output that failed validation`,
+                toolId: tool.id,
+                errors: outputValidator.errors ?? [],
+            };
+            return { kind: 'err', error: err };
+        }
+    }
+    return { kind: 'ok', value: output };
+}
+//# sourceMappingURL=invoke.js.map

package/dist/invoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.js","sourceRoot":"","sources":["../src/invoke.ts"],"names":[],"mappings":"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"}

package/dist/manifest.d.ts

@@ -0,0 +1,23 @@
+import type { AnyTool, McpToolManifest, ToolManifest } from './types.js';
+/**
+ * Project a runtime `Tool` to its serialisable manifest — everything
+ * declared in `@kindgi/specs/tool.schema.json` minus the `handler` binding.
+ *
+ * Use for wire transport, MCP exposure (via `toMcpManifest`), and
+ * discovery endpoints. The result round-trips through JSON.
+ */
+export declare function toManifest(tool: AnyTool): ToolManifest;
+/**
+ * Project a `Tool` to the MCP `tools/list` shape:
+ * `{ name, description, inputSchema, outputSchema? }`.
+ *
+ * MCP's tool discovery format is narrower than our own — no needs, no
+ * effects, no transport hint. Those stay on the Kindgi side (used by
+ * policy, capabilities, scheduling); the MCP client sees only what the
+ * spec exposes.
+ *
+ * `outputSchema` is optional in MCP; we always emit it so clients that
+ * read it get typed returns.
+ */
+export declare function toMcpManifest(tool: AnyTool): McpToolManifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CAMtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,CAO5D"}

package/dist/manifest.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Project a runtime `Tool` to its serialisable manifest — everything
+ * declared in `@kindgi/specs/tool.schema.json` minus the `handler` binding.
+ *
+ * Use for wire transport, MCP exposure (via `toMcpManifest`), and
+ * discovery endpoints. The result round-trips through JSON.
+ */
+export function toManifest(tool) {
+    // Strip runtime-only bindings that never cross the wire: the handler
+    // function itself, and the optional Zod authoring schemas preserved
+    // for TS type inference on the runtime object.
+    const { handler: _handler, inputZod: _inputZod, outputZod: _outputZod, ...manifest } = tool;
+    return manifest;
+}
+/**
+ * Project a `Tool` to the MCP `tools/list` shape:
+ * `{ name, description, inputSchema, outputSchema? }`.
+ *
+ * MCP's tool discovery format is narrower than our own — no needs, no
+ * effects, no transport hint. Those stay on the Kindgi side (used by
+ * policy, capabilities, scheduling); the MCP client sees only what the
+ * spec exposes.
+ *
+ * `outputSchema` is optional in MCP; we always emit it so clients that
+ * read it get typed returns.
+ */
+export function toMcpManifest(tool) {
+    return {
+        name: tool.id,
+        description: tool.description,
+        inputSchema: tool.input,
+        outputSchema: tool.output,
+    };
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAIjC;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,qEAAqE;IACrE,oEAAoE;IACpE,+CAA+C;IAC/C,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC;IAC5F,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,EAAE;QACb,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,KAAK;QACvB,YAAY,EAAE,IAAI,CAAC,MAAM;KAC1B,CAAC;AACJ,CAAC"}

package/dist/precondition.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A runtime's refusal to run a tool: something the tool declares wasn't
+ * there — a secret it declares couldn't be resolved, say. A runtime that
+ * wraps a tool's handler throws it before calling the tool's own code;
+ * `invokeTool` reports it as `precondition-failed` (not `handler-error`:
+ * the handler never ran), with the runtime's `reason` code.
+ *
+ * Recognized by a registered symbol, not `instanceof`, so a runtime and
+ * a tool that load different copies of this package still agree.
+ */
+declare const PRECONDITION_FAILED: unique symbol;
+export declare class ToolPreconditionError extends Error {
+    readonly reason: string;
+    readonly [PRECONDITION_FAILED] = true;
+    /**
+     * @param reason The runtime's code for what was missing
+     *   (`secret-unavailable`, `env-not-configured`, …).
+     * @param message What was missing, by name; never a secret's value.
+     */
+    constructor(reason: string, message: string);
+}
+/** Is `value` a `ToolPreconditionError` (from any copy of this package)? */
+export declare function isToolPreconditionError(value: unknown): value is ToolPreconditionError;
+export {};
+//# sourceMappingURL=precondition.d.ts.map

package/dist/precondition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"precondition.d.ts","sourceRoot":"","sources":["../src/precondition.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,QAAA,MAAM,mBAAmB,eAAiD,CAAC;AAE3E,qBAAa,qBAAsB,SAAQ,KAAK;IAS5C,QAAQ,CAAC,MAAM,EAAE,MAAM;IARzB,QAAQ,CAAC,CAAC,mBAAmB,CAAC,QAAQ;IAEtC;;;;OAIG;gBAEQ,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM;CAKlB;AAED,4EAA4E;AAC5E,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAMtF"}

package/dist/precondition.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * A runtime's refusal to run a tool: something the tool declares wasn't
+ * there — a secret it declares couldn't be resolved, say. A runtime that
+ * wraps a tool's handler throws it before calling the tool's own code;
+ * `invokeTool` reports it as `precondition-failed` (not `handler-error`:
+ * the handler never ran), with the runtime's `reason` code.
+ *
+ * Recognized by a registered symbol, not `instanceof`, so a runtime and
+ * a tool that load different copies of this package still agree.
+ */
+const PRECONDITION_FAILED = Symbol.for('kindgi.tools.precondition-failed');
+export class ToolPreconditionError extends Error {
+    reason;
+    [PRECONDITION_FAILED] = true;
+    /**
+     * @param reason The runtime's code for what was missing
+     *   (`secret-unavailable`, `env-not-configured`, …).
+     * @param message What was missing, by name; never a secret's value.
+     */
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'ToolPreconditionError';
+    }
+}
+/** Is `value` a `ToolPreconditionError` (from any copy of this package)? */
+export function isToolPreconditionError(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[PRECONDITION_FAILED] === true);
+}
+//# sourceMappingURL=precondition.js.map

package/dist/precondition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"precondition.js","sourceRoot":"","sources":["../src/precondition.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;;;;;;GASG;AACH,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;AAE3E,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IASnC;IARF,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC;IAEtC;;;;OAIG;IACH,YACW,MAAc,EACvB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,WAAM,GAAN,MAAM,CAAQ;QAIvB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAsD,CAAC,mBAAmB,CAAC,KAAK,IAAI,CACtF,CAAC;AACJ,CAAC"}