@kindgi/tools 0.0.0-bootstrap.0 → 0.1.1

package/src/http.ts

@@ -0,0 +1,268 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type ToolSpecSynthesizerOptions, registerToolSpecSynthesizer } from './spec-registry.js';
+import type { HttpAuthSpec, HttpRequestBodySpec, HttpToolSpec, ToolContext } from './types.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: HttpToolSpec,
+  toolId: string,
+  options: ToolSpecSynthesizerOptions = {},
+): (input: unknown, ctx: ToolContext) => Promise<unknown> {
+  const doFetch = options.fetch ?? fetch;
+  return async (input, ctx) => {
+    const inputObj = coerceInputToObject(input, toolId);
+    const { url, consumedKeys } = substituteUrl(spec.urlTemplate, inputObj, toolId);
+
+    const headers: Record<string, string> = {};
+    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 = (): void => 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: 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: unknown, toolId: string): Record<string, unknown> {
+  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 as Record<string, unknown>;
+}
+
+/**
+ * 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: string,
+  input: Record<string, unknown>,
+  toolId: string,
+): { readonly url: string; readonly consumedKeys: ReadonlySet<string> } {
+  const consumed = new Set<string>();
+  const url = template.replace(/\{(\w+)\}/g, (_, key: string) => {
+    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: string, input: Record<string, unknown>): string {
+  return template.replace(/\{(\w+)\}/g, (_, key: string) => {
+    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: HttpAuthSpec,
+  ctx: ToolContext,
+  toolId: string,
+): Promise<string> {
+  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: Record<string, string>,
+  auth: HttpAuthSpec,
+  _ctx: ToolContext,
+  _toolId: string,
+  resolvedSecret: string,
+): void {
+  switch (auth.kind) {
+    case 'bearer':
+      headers.Authorization = `Bearer ${resolvedSecret}`;
+      return;
+    case 'header':
+      headers[auth.headerName] = resolvedSecret;
+      return;
+  }
+}
+
+function buildBody(
+  spec: HttpToolSpec,
+  input: Record<string, unknown>,
+  consumedKeys: ReadonlySet<string>,
+): { body: string | undefined; contentType: string | undefined } {
+  // Methods that don't carry a body by convention.
+  if (spec.method === 'GET' && spec.requestBody === undefined) {
+    return { body: undefined, contentType: undefined };
+  }
+  const kind: HttpRequestBodySpec['kind'] = spec.requestBody?.kind ?? 'json-input';
+  if (kind === 'json-input') {
+    const remaining: Record<string, unknown> = {};
+    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 as { kind: 'text'; template: string }).template;
+  return { body: substituteTemplate(template, input), contentType: 'text/plain' };
+}
+
+async function safeText(response: Response): Promise<string> {
+  try {
+    return await response.text();
+  } catch {
+    return '<no body>';
+  }
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+// 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';
+export type {
+  DefineToolOptions,
+  DefineToolSpec,
+  DefinedTool,
+  InferInput,
+  InferOutput,
+} 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 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';

package/src/invoke.ts

@@ -0,0 +1,165 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ValidateFunction } from 'ajv';
+import * as addFormatsModule from 'ajv-formats';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+
+import { parseWithSchema } from '@kindgi/schema';
+import type { Result } from '@kindgi/types';
+
+import type {
+  HandlerError,
+  InputValidationError,
+  OutputValidationError,
+  PreconditionFailedError,
+  ToolError,
+} from './errors.js';
+import { isToolPreconditionError } from './precondition.js';
+import type { JsonSchema, Tool, ToolContext } from './types.js';
+
+type AddFormatsFn = (ajv: InstanceType<typeof Ajv2020>, opts?: unknown) => unknown;
+const addFormatsRaw = addFormatsModule as unknown;
+const addFormats: AddFormatsFn =
+  typeof addFormatsRaw === 'function'
+    ? (addFormatsRaw as AddFormatsFn)
+    : (addFormatsRaw as { default: AddFormatsFn }).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: WeakMap<JsonSchema, ValidateFunction> = new WeakMap();
+const outputCache: WeakMap<JsonSchema, ValidateFunction> = 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: JsonSchema, side: 'input' | 'output'): ValidateFunction {
+  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 as object);
+  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: Pick<Tool, 'id' | 'input' | 'inputZod'>,
+  input: unknown,
+): Promise<Result<unknown, InputValidationError>> {
+  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: Tool['id'], errors: readonly unknown[]): InputValidationError {
+  return {
+    code: 'input-validation-failed',
+    message: `Input for tool "${toolId}" failed validation`,
+    toolId,
+    errors,
+  };
+}
+
+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 async function invokeTool<TInput = unknown, TOutput = unknown>(
+  tool: Tool<TInput, TOutput>,
+  input: unknown,
+  ctx: ToolContext,
+  options: InvokeToolOptions = {},
+): Promise<Result<TOutput, ToolError>> {
+  const prepared = await prepareInput(tool, input);
+  if (prepared.kind === 'err') return prepared;
+
+  let output: TOutput;
+  try {
+    output = await tool.handler(prepared.value as TInput, ctx);
+  } catch (cause) {
+    if (isToolPreconditionError(cause)) {
+      const refused: PreconditionFailedError = {
+        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: HandlerError = {
+      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: OutputValidationError = {
+        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 };
+}

package/src/manifest.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+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 function toManifest(tool: AnyTool): ToolManifest {
+  // 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: AnyTool): McpToolManifest {
+  return {
+    name: tool.id,
+    description: tool.description,
+    inputSchema: tool.input,
+    outputSchema: tool.output,
+  };
+}

package/src/precondition.ts

@@ -0,0 +1,40 @@
+// 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 {
+  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(
+    readonly reason: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'ToolPreconditionError';
+  }
+}
+
+/** Is `value` a `ToolPreconditionError` (from any copy of this package)? */
+export function isToolPreconditionError(value: unknown): value is ToolPreconditionError {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { readonly [PRECONDITION_FAILED]?: unknown })[PRECONDITION_FAILED] === true
+  );
+}