@agentproto/tool 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy (agentik.net)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @agentproto/tool
+
+Reference implementation of
+[**AIP-14 TOOL.md**](https://agentik.net/docs/aip-14) `defineTool` contract.
+
+A vendor-neutral tool registration primitive: an author writes a single
+`defineTool({...})` module + an optional sidecar `TOOL.md` manifest, and any
+framework-specific adapter (`@agentproto/adapter-mastra`, `@agencies/tool-langchain`,
+`@agencies/tool-a2a`, …) can wrap the resulting `ToolHandle` into its native
+tool API.
+
+```ts
+import { defineTool, ToolError } from "@agentproto/tool"
+import { z } from "zod"
+
+export default defineTool({
+  id: "echo",
+  description: "Returns its input verbatim.",
+  inputSchema: z.object({ message: z.string() }),
+  outputSchema: z.object({ echo: z.string() }),
+  mutates: [],
+  approval: "auto",
+  execute: async ({ input }) => {
+    if (input.message.length > 10_000) {
+      throw new ToolError({
+        code: "input_invalid",
+        message: "message too long",
+      })
+    }
+    return { echo: input.message }
+  },
+})
+```
+
+The host calls `handle.execute({ input, context })`. The runtime validates
+`input` against `inputSchema` (rejects with
+`ToolError({ code: "input_invalid" })` on shape mismatch) before invoking the
+body, then validates the body's return against `outputSchema`. Errors travel
+out-of-band: success returns the value; failures throw a `ToolError` that
+adapters MUST wrap into the standard `ToolResult<T>` envelope.
+
+## Spec
+
+See [AIP-14](https://agentik.net/docs/aip-14) for the canonical `defineTool`
+contract and conformance rules. This package is the TypeScript reference
+implementation.
+
+## Adapter packages
+
+- `@agentproto/adapter-mastra` — `toMastraTool(handle, ctx)` (planned)
+- `@agencies/tool-langchain` — (planned)
+- `@agencies/tool-a2a` — (planned)

package/dist/chunk-ZFIMSZXN.mjs

@@ -0,0 +1,245 @@
+import matter from 'gray-matter';
+import { z } from 'zod';
+import { createDoctype } from '@agentproto/define-doctype';
+
+/**
+ * @agentproto/tool v0.1.0-alpha
+ * AIP-14 TOOL.md `defineTool` reference implementation.
+ */
+
+
+// src/errors.ts
+var ToolError = class extends Error {
+  code;
+  retryable;
+  cause;
+  constructor(payload) {
+    super(payload.message);
+    this.name = "ToolError";
+    this.code = payload.code;
+    this.retryable = payload.retryable ?? false;
+    this.cause = payload.cause;
+  }
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable,
+      ...this.cause !== void 0 ? { cause: this.cause } : {}
+    };
+  }
+};
+function toToolError(thrown) {
+  if (thrown instanceof ToolError) return thrown;
+  if (thrown instanceof Error) {
+    return new ToolError({
+      code: "internal",
+      message: thrown.message,
+      cause: thrown
+    });
+  }
+  return new ToolError({
+    code: "internal",
+    message: String(thrown),
+    cause: thrown
+  });
+}
+function toToolResult(value, thrown) {
+  if (thrown !== void 0) {
+    const err = toToolError(thrown);
+    return { ok: false, error: err.toJSON() };
+  }
+  return { ok: true, value };
+}
+
+// src/define-tool.ts
+var PROVIDER_KINDS = [
+  "cli",
+  "http",
+  "mcp",
+  "sdk",
+  "builtin"
+];
+var constructTool = createDoctype({
+  aip: 14,
+  name: "tool",
+  validate(def) {
+    if ("execute" in def) {
+      throw new Error(
+        `defineTool: id='${def.id}' carries an 'execute' property. Bodies live on AIP-30 PROVIDER manifests, not on the TOOL contract. See https://agentproto.sh/docs/aip-30 for migration.`
+      );
+    }
+  },
+  build(def) {
+    return {
+      id: def.id,
+      name: def.name ?? def.id,
+      description: def.description,
+      version: def.version,
+      inputSchema: def.inputSchema,
+      outputSchema: def.outputSchema,
+      contextSchema: def.contextSchema,
+      mutates: Object.freeze([...def.mutates ?? []]),
+      requires: freezeCapabilities(def.requires),
+      approval: defaultApproval(def.approval, def.mutates),
+      riskLevel: def.riskLevel ?? 0,
+      costClass: def.costClass ?? "trivial",
+      timeoutMs: def.timeoutMs ?? 3e4,
+      retry: def.retry,
+      tags: Object.freeze([...def.tags ?? []]),
+      metadata: Object.freeze({ ...def.metadata ?? {} }),
+      idempotent: def.idempotent ?? false,
+      defaultImplementation: def.defaultImplementation,
+      driverConstraints: freezeProviderConstraints(def.driverConstraints)
+    };
+  }
+});
+function defineTool(definition) {
+  return constructTool(
+    definition
+  );
+}
+function validateInput(handle, input) {
+  const result = handle.inputSchema.safeParse(input);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: {
+        code: "input_invalid",
+        message: `id='${handle.id}': ${formatZodIssues(result.error.issues)}`,
+        cause: result.error.issues
+      }
+    };
+  }
+  return { ok: true, value: result.data };
+}
+function validateContext(handle, context) {
+  if (!handle.contextSchema) {
+    return { ok: true, value: context };
+  }
+  const result = handle.contextSchema.safeParse(context);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: {
+        code: "input_invalid",
+        message: `id='${handle.id}': context does not match contextSchema \u2014 ${formatZodIssues(result.error.issues)}`,
+        field: "context",
+        cause: result.error.issues
+      }
+    };
+  }
+  return { ok: true, value: result.data };
+}
+function validateOutput(handle, output) {
+  const result = handle.outputSchema.safeParse(output);
+  if (!result.success) {
+    throw new ToolError({
+      code: "output_invalid",
+      message: `id='${handle.id}': provider produced output that does not match outputSchema \u2014 ${formatZodIssues(result.error.issues)}`,
+      cause: result.error.issues
+    });
+  }
+  return result.data;
+}
+function defaultApproval(declared, mutates) {
+  if (declared) return declared;
+  return mutates && mutates.length > 0 ? "on-mutate" : "auto";
+}
+function freezeCapabilities(caps) {
+  return Object.freeze({
+    network: Object.freeze([...caps?.network ?? []]),
+    secrets: Object.freeze([...caps?.secrets ?? []]),
+    tools: Object.freeze([...caps?.tools ?? []])
+  });
+}
+function freezeProviderConstraints(c) {
+  const forbid = (c?.forbid ?? []).filter(
+    (k) => PROVIDER_KINDS.includes(k)
+  );
+  const requireKind = (c?.requireKind ?? []).filter(
+    (k) => PROVIDER_KINDS.includes(k)
+  );
+  return Object.freeze({
+    forbid: Object.freeze(forbid),
+    requireKind: Object.freeze(requireKind)
+  });
+}
+function formatZodIssues(issues) {
+  return issues.map((i) => `${i.path.length > 0 ? i.path.join(".") + ": " : ""}${i.message}`).join("; ");
+}
+
+// src/manifest/index.ts
+var toolManifestFrontmatterSchema = z.object({
+  schema: z.literal("agentproto/tool/v1").optional(),
+  name: z.string().min(1).max(80),
+  id: z.string().regex(/^[a-z][a-z0-9._-]{1,63}$/),
+  description: z.string().min(1).max(2e3),
+  version: z.string().regex(/^\d+\.\d+\.\d+/),
+  // Optional metadata
+  mutates: z.array(z.string()).optional(),
+  requires: z.object({
+    network: z.array(z.string()).optional(),
+    secrets: z.array(z.string()).optional(),
+    tools: z.array(z.string()).optional()
+  }).optional(),
+  // `ApprovalClass` is `"auto" | "always" | "on-mutate" | \`policy:${string}\``.
+  // z.union widens the regex branch to plain `string` (zod can't express
+  // template literal types), so we use `z.custom` to keep the inferred
+  // type exact — matters because `defineTool` accepts `ApprovalClass`.
+  approval: z.custom(
+    (v) => typeof v === "string" && (v === "auto" || v === "always" || v === "on-mutate" || /^policy:/.test(v)),
+    { message: "expected 'auto' | 'always' | 'on-mutate' | 'policy:<name>'" }
+  ).optional(),
+  risk_level: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]).optional(),
+  cost_class: z.enum(["trivial", "metered", "expensive"]).optional(),
+  timeout_ms: z.number().int().positive().optional(),
+  idempotent: z.boolean().optional(),
+  tags: z.array(z.string()).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  // AIP-26 / AIP-17 / AIP-19 references — kept loose; validated by their
+  // respective AIPs' adapters when consumed.
+  code: z.unknown().optional(),
+  run: z.unknown().optional(),
+  runner: z.unknown().optional(),
+  secrets: z.unknown().optional(),
+  network: z.unknown().optional()
+});
+function parseToolManifest(source) {
+  const parsed = matter(source);
+  if (Object.keys(parsed.data).length === 0) {
+    throw new Error("parseToolManifest: missing or empty frontmatter");
+  }
+  const result = toolManifestFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    throw new Error(
+      `parseToolManifest: invalid frontmatter \u2014 ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return { frontmatter: result.data, body: parsed.content };
+}
+function toolFromManifest(args) {
+  const fm = args.manifest.frontmatter;
+  return defineTool({
+    id: fm.id,
+    name: fm.name,
+    description: fm.description,
+    version: fm.version,
+    inputSchema: args.inputSchema,
+    outputSchema: args.outputSchema,
+    contextSchema: args.contextSchema,
+    mutates: fm.mutates,
+    requires: fm.requires,
+    approval: fm.approval,
+    riskLevel: fm.risk_level,
+    costClass: fm.cost_class,
+    timeoutMs: fm.timeout_ms,
+    idempotent: fm.idempotent,
+    tags: fm.tags,
+    metadata: fm.metadata
+  });
+}
+
+export { ToolError, defineTool, parseToolManifest, toToolError, toToolResult, toolFromManifest, toolManifestFrontmatterSchema, validateContext, validateInput, validateOutput };
+//# sourceMappingURL=chunk-ZFIMSZXN.mjs.map
+//# sourceMappingURL=chunk-ZFIMSZXN.mjs.map

package/dist/chunk-ZFIMSZXN.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/define-tool.ts","../src/manifest/index.ts"],"names":[],"mappings":"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","file":"chunk-ZFIMSZXN.mjs","sourcesContent":["import type { ToolResult } from \"./types.js\"\n\n/**\n * AIP-14 conventional error codes. Tool-specific codes MAY use a domain\n * prefix (`\"stripe:card_declined\"`).\n */\nexport type ToolErrorCode =\n  | \"input_invalid\"\n  | \"output_invalid\"\n  | \"unauthorised\"\n  | \"not_found\"\n  | \"rate_limited\"\n  | \"timeout\"\n  | \"upstream_error\"\n  | \"internal\"\n  | (string & {})\n\nexport interface ToolErrorPayload {\n  code: ToolErrorCode\n  message: string\n  retryable?: boolean\n  cause?: unknown\n}\n\n/**\n * Structured error thrown by tool bodies. Adapters wrap this into the\n * standard {@link ToolResult} envelope; bodies MUST throw it (never\n * return error objects).\n */\nexport class ToolError extends Error {\n  readonly code: ToolErrorCode\n  readonly retryable: boolean\n  readonly cause: unknown\n\n  constructor(payload: ToolErrorPayload) {\n    super(payload.message)\n    this.name = \"ToolError\"\n    this.code = payload.code\n    this.retryable = payload.retryable ?? false\n    this.cause = payload.cause\n  }\n\n  toJSON(): ToolErrorPayload {\n    return {\n      code: this.code,\n      message: this.message,\n      retryable: this.retryable,\n      ...(this.cause !== undefined ? { cause: this.cause } : {}),\n    }\n  }\n}\n\n/**\n * Wrap an unknown thrown value into a {@link ToolError}. Used by adapters\n * to normalise non-ToolError throws into the standard envelope.\n */\nexport function toToolError(thrown: unknown): ToolError {\n  if (thrown instanceof ToolError) return thrown\n  if (thrown instanceof Error) {\n    return new ToolError({\n      code: \"internal\",\n      message: thrown.message,\n      cause: thrown,\n    })\n  }\n  return new ToolError({\n    code: \"internal\",\n    message: String(thrown),\n    cause: thrown,\n  })\n}\n\n/**\n * Adapter helper: project a thrown ToolError (or any throw) into the\n * standard {@link ToolResult} envelope. Adapters MUST do this; bodies MUST NOT.\n */\nexport function toToolResult<T>(\n  value: T | undefined,\n  thrown: unknown\n): ToolResult<T> {\n  if (thrown !== undefined) {\n    const err = toToolError(thrown)\n    return { ok: false, error: err.toJSON() }\n  }\n  return { ok: true, value: value as T }\n}\n","import { createDoctype } from \"@agentproto/define-doctype\"\nimport type { ZodType } from \"zod\"\nimport { ToolError } from \"./errors.js\"\nimport type {\n  ApprovalClass,\n  DriverConstraints,\n  DriverKind,\n  ToolCapabilities,\n  ToolContext,\n  ToolDefinition,\n  ToolHandle,\n  ValidationResult,\n} from \"./types.js\"\n\nconst PROVIDER_KINDS: readonly DriverKind[] = [\n  \"cli\",\n  \"http\",\n  \"mcp\",\n  \"sdk\",\n  \"builtin\",\n]\n\n/**\n * AIP-14 reference implementation of `defineTool`.\n *\n * Returns a {@link ToolHandle} with defaults applied. The handle is a\n * pure contract — schemas, governance metadata, provider routing\n * hints. Bodies live on AIP-30 PROVIDER manifests; invocation goes\n * through provider-runtime's resolver.\n *\n * Built on `createDoctype` from `@agentproto/define-doctype`: the\n * id-pattern + description-length validation and the top-level\n * `Object.freeze` are shared with every other AIP defineX. The\n * spec-14-specific parts (migration guard for `execute`, defaulting\n * `approval` from `mutates`, freezing nested arrays/objects) live in\n * `validate` and `build` below.\n *\n * Conformance highlights ([§ Conformance rules](https://agentproto.sh/docs/aip-14)):\n *  - No `execute` field on the contract — bodies are providers' job.\n *  - `defineTool` MUST refuse a definition carrying `execute` (migration error).\n *  - No I/O at module load — `defineTool(...)` is pure construction.\n */\nconst constructTool = createDoctype<\n  ToolDefinition<unknown, unknown, ToolContext>,\n  ToolHandle<unknown, unknown, ToolContext>\n>({\n  aip: 14,\n  name: \"tool\",\n  validate(def) {\n    // Migration guard: catch authors trying to ship a body on the contract.\n    // The body lives on a PROVIDER (per AIP-30); reject at construction.\n    if (\"execute\" in (def as unknown as Record<string, unknown>)) {\n      throw new Error(\n        `defineTool: id='${def.id}' carries an 'execute' property. ` +\n          `Bodies live on AIP-30 PROVIDER manifests, not on the TOOL contract. ` +\n          `See https://agentproto.sh/docs/aip-30 for migration.`,\n      )\n    }\n  },\n  build(def) {\n    return {\n      id: def.id,\n      name: def.name ?? def.id,\n      description: def.description,\n      version: def.version,\n      inputSchema: def.inputSchema,\n      outputSchema: def.outputSchema,\n      contextSchema: def.contextSchema,\n      mutates: Object.freeze([...(def.mutates ?? [])]),\n      requires: freezeCapabilities(def.requires),\n      approval: defaultApproval(def.approval, def.mutates),\n      riskLevel: def.riskLevel ?? 0,\n      costClass: def.costClass ?? \"trivial\",\n      timeoutMs: def.timeoutMs ?? 30_000,\n      retry: def.retry,\n      tags: Object.freeze([...(def.tags ?? [])]),\n      metadata: Object.freeze({ ...(def.metadata ?? {}) }),\n      idempotent: def.idempotent ?? false,\n      defaultImplementation: def.defaultImplementation,\n      driverConstraints: freezeProviderConstraints(def.driverConstraints),\n    }\n  },\n})\n\n/**\n * Public-facing `defineTool` — typed wrapper around `constructTool`\n * that preserves the per-call `<TInput, TOutput, TContext>` inference\n * so callers don't write any generics. The wrapper exists purely for\n * generic propagation; the runtime body is the meta-factory above.\n */\nexport function defineTool<\n  TInput,\n  TOutput,\n  TContext extends ToolContext = ToolContext,\n>(\n  definition: ToolDefinition<TInput, TOutput, TContext>,\n): ToolHandle<TInput, TOutput, TContext> {\n  return constructTool(\n    definition as ToolDefinition<unknown, unknown, ToolContext>,\n  ) as unknown as ToolHandle<TInput, TOutput, TContext>\n}\n\n/**\n * Validate input against a tool's `inputSchema`. Returns a typed\n * {@link ValidationResult}; provider runtimes MUST call this BEFORE\n * dispatching to the provider's body.\n */\nexport function validateInput<TInput>(\n  handle: Pick<ToolHandle<TInput>, \"id\" | \"inputSchema\">,\n  input: unknown,\n): ValidationResult<TInput> {\n  const result = handle.inputSchema.safeParse(input)\n  if (!result.success) {\n    return {\n      ok: false,\n      error: {\n        code: \"input_invalid\",\n        message: `id='${handle.id}': ${formatZodIssues(result.error.issues)}`,\n        cause: result.error.issues,\n      },\n    }\n  }\n  return { ok: true, value: result.data as TInput }\n}\n\n/**\n * Validate context against a tool's `contextSchema` (when declared).\n * Returns a typed {@link ValidationResult}; provider runtimes MUST\n * call this BEFORE dispatching when the contract has a contextSchema.\n *\n * Tools without a contextSchema accept any context shape; this helper\n * returns the input verbatim in that case.\n */\nexport function validateContext<TContext extends ToolContext = ToolContext>(\n  handle: Pick<ToolHandle<unknown, unknown, TContext>, \"id\" | \"contextSchema\">,\n  context: unknown,\n): ValidationResult<TContext> {\n  if (!handle.contextSchema) {\n    return { ok: true, value: context as TContext }\n  }\n  const result = handle.contextSchema.safeParse(context)\n  if (!result.success) {\n    return {\n      ok: false,\n      error: {\n        code: \"input_invalid\",\n        message: `id='${handle.id}': context does not match contextSchema — ${formatZodIssues(result.error.issues)}`,\n        field: \"context\",\n        cause: result.error.issues,\n      },\n    }\n  }\n  return { ok: true, value: result.data as TContext }\n}\n\n/**\n * Validate output against a tool's `outputSchema`. Returns the typed\n * {@link ValidationResult}; provider runtimes MUST call this AFTER\n * the body returns and BEFORE handing the value to the caller.\n *\n * On failure, hosts SHOULD throw {@link ToolError} with code\n * `\"output_invalid\"` — the tool produced a contract violation.\n */\nexport function validateOutput<TOutput>(\n  handle: Pick<ToolHandle<unknown, TOutput>, \"id\" | \"outputSchema\">,\n  output: unknown,\n): TOutput {\n  const result = handle.outputSchema.safeParse(output)\n  if (!result.success) {\n    throw new ToolError({\n      code: \"output_invalid\",\n      message: `id='${handle.id}': provider produced output that does not match outputSchema — ${formatZodIssues(result.error.issues)}`,\n      cause: result.error.issues,\n    })\n  }\n  return result.data as TOutput\n}\n\nfunction defaultApproval(\n  declared: ApprovalClass | undefined,\n  mutates: readonly string[] | undefined,\n): ApprovalClass {\n  if (declared) return declared\n  return mutates && mutates.length > 0 ? \"on-mutate\" : \"auto\"\n}\n\nfunction freezeCapabilities(\n  caps: ToolCapabilities | undefined,\n): Readonly<ToolCapabilities> {\n  return Object.freeze({\n    network: Object.freeze([...(caps?.network ?? [])]),\n    secrets: Object.freeze([...(caps?.secrets ?? [])]),\n    tools: Object.freeze([...(caps?.tools ?? [])]),\n  })\n}\n\nfunction freezeProviderConstraints(\n  c: DriverConstraints | undefined,\n): Required<DriverConstraints> {\n  const forbid = (c?.forbid ?? []).filter((k): k is DriverKind =>\n    PROVIDER_KINDS.includes(k as DriverKind),\n  )\n  const requireKind = (c?.requireKind ?? []).filter((k): k is DriverKind =>\n    PROVIDER_KINDS.includes(k as DriverKind),\n  )\n  return Object.freeze({\n    forbid: Object.freeze(forbid) as readonly DriverKind[],\n    requireKind: Object.freeze(requireKind) as readonly DriverKind[],\n  })\n}\n\nfunction formatZodIssues(\n  issues: ReadonlyArray<{ path: ReadonlyArray<PropertyKey>; message: string }>,\n): string {\n  return issues\n    .map((i) => `${i.path.length > 0 ? i.path.join(\".\") + \": \" : \"\"}${i.message}`)\n    .join(\"; \")\n}\n\nexport type { ZodType }\n","import matter from \"gray-matter\"\nimport { z, type ZodType } from \"zod\"\nimport { defineTool } from \"../define-tool.js\"\nimport type { ApprovalClass, ToolContext, ToolHandle } from \"../types.js\"\n\n/**\n * AIP-14 TOOL.md sidecar parser.\n *\n * Reads frontmatter (host-relevant metadata) + body (long-form\n * description / examples / errors). The TS module's `defineTool(...)`\n * supplies the schemas and execute body; this manifest supplies the\n * runtime metadata that overrides or augments the in-code defaults.\n *\n * Field set covers AIP-14 §\"Frontmatter\" — required and optional fields\n * normalised to snake_case → camelCase.\n */\n\nexport const toolManifestFrontmatterSchema = z.object({\n  schema: z.literal(\"agentproto/tool/v1\").optional(),\n  name: z.string().min(1).max(80),\n  id: z.string().regex(/^[a-z][a-z0-9._-]{1,63}$/),\n  description: z.string().min(1).max(2000),\n  version: z.string().regex(/^\\d+\\.\\d+\\.\\d+/),\n\n  // Optional metadata\n  mutates: z.array(z.string()).optional(),\n  requires: z\n    .object({\n      network: z.array(z.string()).optional(),\n      secrets: z.array(z.string()).optional(),\n      tools: z.array(z.string()).optional(),\n    })\n    .optional(),\n  // `ApprovalClass` is `\"auto\" | \"always\" | \"on-mutate\" | \\`policy:${string}\\``.\n  // z.union widens the regex branch to plain `string` (zod can't express\n  // template literal types), so we use `z.custom` to keep the inferred\n  // type exact — matters because `defineTool` accepts `ApprovalClass`.\n  approval: z\n    .custom<ApprovalClass>(\n      (v): v is ApprovalClass =>\n        typeof v === \"string\" &&\n        (v === \"auto\" ||\n          v === \"always\" ||\n          v === \"on-mutate\" ||\n          /^policy:/.test(v)),\n      { message: \"expected 'auto' | 'always' | 'on-mutate' | 'policy:<name>'\" },\n    )\n    .optional(),\n  risk_level: z\n    .union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)])\n    .optional(),\n  cost_class: z.enum([\"trivial\", \"metered\", \"expensive\"]).optional(),\n  timeout_ms: z.number().int().positive().optional(),\n  idempotent: z.boolean().optional(),\n  tags: z.array(z.string()).optional(),\n  metadata: z.record(z.string(), z.unknown()).optional(),\n\n  // AIP-26 / AIP-17 / AIP-19 references — kept loose; validated by their\n  // respective AIPs' adapters when consumed.\n  code: z.unknown().optional(),\n  run: z.unknown().optional(),\n  runner: z.unknown().optional(),\n  secrets: z.unknown().optional(),\n  network: z.unknown().optional(),\n})\n\nexport type ToolManifestFrontmatter = z.infer<\n  typeof toolManifestFrontmatterSchema\n>\n\nexport interface ToolManifest {\n  frontmatter: ToolManifestFrontmatter\n  body: string\n}\n\n/**\n * Parse a TOOL.md source string into structured frontmatter + body.\n * Throws on missing frontmatter or schema-invalid frontmatter.\n */\nexport function parseToolManifest(source: string): ToolManifest {\n  const parsed = matter(source)\n  if (Object.keys(parsed.data).length === 0) {\n    throw new Error(\"parseToolManifest: missing or empty frontmatter\")\n  }\n  const result = toolManifestFrontmatterSchema.safeParse(parsed.data)\n  if (!result.success) {\n    throw new Error(\n      `parseToolManifest: invalid frontmatter — ${result.error.issues\n        .map(i => `${i.path.join(\".\")}: ${i.message}`)\n        .join(\"; \")}`\n    )\n  }\n  return { frontmatter: result.data, body: parsed.content }\n}\n\n/**\n * Build a fully-typed {@link ToolHandle} from a parsed `TOOL.md` manifest\n * + caller-supplied schemas. The .md is the single source of truth for\n * metadata (id, name, description, version, mutates, approval, …); the\n * schemas live in the TS module that ships alongside the .md.\n *\n * Both inputs are revalidated by `defineTool`'s shared invariants\n * (id pattern, description length, top-level freeze) — `parseToolManifest`\n * already enforces a stricter id pattern + version semver, so a\n * well-formed manifest passes through cleanly. Mismatches between the\n * manifest's id-shape and `defineTool`'s pattern surface a\n * descriptive error from the same validation pipeline as the TS path.\n *\n * @example\n *   const manifest = parseToolManifest(readFileSync(\"./echo/TOOL.md\", \"utf8\"))\n *   const echo = toolFromManifest({\n *     manifest,\n *     inputSchema: z.object({ msg: z.string() }),\n *     outputSchema: z.object({ msg: z.string() }),\n *   })\n */\nexport function toolFromManifest<\n  TInput,\n  TOutput,\n  TContext extends ToolContext = ToolContext,\n>(args: {\n  manifest: ToolManifest\n  inputSchema: ZodType<TInput>\n  outputSchema: ZodType<TOutput>\n  contextSchema?: ZodType<TContext>\n}): ToolHandle<TInput, TOutput, TContext> {\n  const fm = args.manifest.frontmatter\n  return defineTool<TInput, TOutput, TContext>({\n    id: fm.id,\n    name: fm.name,\n    description: fm.description,\n    version: fm.version,\n    inputSchema: args.inputSchema,\n    outputSchema: args.outputSchema,\n    contextSchema: args.contextSchema,\n    mutates: fm.mutates,\n    requires: fm.requires,\n    approval: fm.approval,\n    riskLevel: fm.risk_level,\n    costClass: fm.cost_class,\n    timeoutMs: fm.timeout_ms,\n    idempotent: fm.idempotent,\n    tags: fm.tags,\n    metadata: fm.metadata,\n  })\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+import { T as ToolContext, a as ToolDefinition, b as ToolHandle, V as ValidationResult, c as ToolResult } from './types-Ce8BEvMm.js';
+export { A as ApprovalClass, D as DriverConstraints, d as DriverKind, R as RetryPolicy, e as ToolCapabilities, f as ValidationFailure, g as ValidationSuccess } from './types-Ce8BEvMm.js';
+import * as _agentproto_manifest from '@agentproto/manifest';
+import { DoctypeSpec } from '@agentproto/manifest';
+import 'zod';
+
+/**
+ * Public-facing `defineTool` — typed wrapper around `constructTool`
+ * that preserves the per-call `<TInput, TOutput, TContext>` inference
+ * so callers don't write any generics. The wrapper exists purely for
+ * generic propagation; the runtime body is the meta-factory above.
+ */
+declare function defineTool<TInput, TOutput, TContext extends ToolContext = ToolContext>(definition: ToolDefinition<TInput, TOutput, TContext>): ToolHandle<TInput, TOutput, TContext>;
+/**
+ * Validate input against a tool's `inputSchema`. Returns a typed
+ * {@link ValidationResult}; provider runtimes MUST call this BEFORE
+ * dispatching to the provider's body.
+ */
+declare function validateInput<TInput>(handle: Pick<ToolHandle<TInput>, "id" | "inputSchema">, input: unknown): ValidationResult<TInput>;
+/**
+ * Validate context against a tool's `contextSchema` (when declared).
+ * Returns a typed {@link ValidationResult}; provider runtimes MUST
+ * call this BEFORE dispatching when the contract has a contextSchema.
+ *
+ * Tools without a contextSchema accept any context shape; this helper
+ * returns the input verbatim in that case.
+ */
+declare function validateContext<TContext extends ToolContext = ToolContext>(handle: Pick<ToolHandle<unknown, unknown, TContext>, "id" | "contextSchema">, context: unknown): ValidationResult<TContext>;
+/**
+ * Validate output against a tool's `outputSchema`. Returns the typed
+ * {@link ValidationResult}; provider runtimes MUST call this AFTER
+ * the body returns and BEFORE handing the value to the caller.
+ *
+ * On failure, hosts SHOULD throw {@link ToolError} with code
+ * `"output_invalid"` — the tool produced a contract violation.
+ */
+declare function validateOutput<TOutput>(handle: Pick<ToolHandle<unknown, TOutput>, "id" | "outputSchema">, output: unknown): TOutput;
+
+/**
+ * `createTool(params, opts)` — write a TOOL.md to disk.
+ *
+ * Symmetric to `parseToolManifest` (.md → handle) and `defineTool`
+ * (params → handle): this takes params, validates via defineTool
+ * (single source of truth — same zod schema, same cross-AIP
+ * invariants), then serialises the validated frontmatter to YAML
+ * and writes it under `<dir>/<id>/TOOL.md`.
+ *
+ * The author's body markdown is preserved verbatim in `opts.body`.
+ * Pass `dryRun: true` to get the rendered string without touching
+ * disk — useful for tests, the MCP server's preview, and CI lints.
+ *
+ * Non-frontmatter values that can't appear in YAML (zod schemas,
+ * function bodies) are filtered out by `filterSerializable` from
+ * `@agentproto/define-doctype`; the resulting frontmatter matches
+ * what `parseToolManifest` would consume on the way back in.
+ */
+
+interface CreateToolOptions {
+    /** Workspace-relative or absolute directory under which to write `<id>/TOOL.md`. */
+    dir: string;
+    /** Body markdown after the frontmatter. Defaults to a one-line stub. */
+    body?: string;
+    /** Render only — don't write. Returns the rendered string. */
+    dryRun?: boolean;
+}
+interface CreateToolResult<TInput, TOutput, TContext extends ToolContext> {
+    /** The path where the file was (or would be) written. */
+    path: string;
+    /** The validated handle returned by defineTool. */
+    handle: ToolHandle<TInput, TOutput, TContext>;
+    /** The full rendered file contents (frontmatter + body). */
+    rendered: string;
+}
+declare function createTool<TInput, TOutput, TContext extends ToolContext = ToolContext>(params: ToolDefinition<TInput, TOutput, TContext>, opts: CreateToolOptions): Promise<CreateToolResult<TInput, TOutput, TContext>>;
+
+declare const toolSpec: DoctypeSpec<ToolDefinition<unknown, unknown>, ToolHandle<unknown, unknown>>;
+declare const toolVerbs: _agentproto_manifest.Verbs<ToolDefinition<unknown, unknown, ToolContext>, ToolHandle<unknown, unknown, ToolContext>>;
+
+/**
+ * AIP-14 conventional error codes. Tool-specific codes MAY use a domain
+ * prefix (`"stripe:card_declined"`).
+ */
+type ToolErrorCode = "input_invalid" | "output_invalid" | "unauthorised" | "not_found" | "rate_limited" | "timeout" | "upstream_error" | "internal" | (string & {});
+interface ToolErrorPayload {
+    code: ToolErrorCode;
+    message: string;
+    retryable?: boolean;
+    cause?: unknown;
+}
+/**
+ * Structured error thrown by tool bodies. Adapters wrap this into the
+ * standard {@link ToolResult} envelope; bodies MUST throw it (never
+ * return error objects).
+ */
+declare class ToolError extends Error {
+    readonly code: ToolErrorCode;
+    readonly retryable: boolean;
+    readonly cause: unknown;
+    constructor(payload: ToolErrorPayload);
+    toJSON(): ToolErrorPayload;
+}
+/**
+ * Wrap an unknown thrown value into a {@link ToolError}. Used by adapters
+ * to normalise non-ToolError throws into the standard envelope.
+ */
+declare function toToolError(thrown: unknown): ToolError;
+/**
+ * Adapter helper: project a thrown ToolError (or any throw) into the
+ * standard {@link ToolResult} envelope. Adapters MUST do this; bodies MUST NOT.
+ */
+declare function toToolResult<T>(value: T | undefined, thrown: unknown): ToolResult<T>;
+
+/**
+ * @agentproto/tool — AIP-14 TOOL.md `defineTool` reference impl.
+ *
+ * Vendor-neutral tool **contract** registration: an author writes
+ * `defineTool({...})` and the runtime returns a `ToolHandle` carrying
+ * identity, schemas, side-effect profile, approval class, and
+ * provider routing hints. Bodies live on AIP-30 PROVIDER manifests;
+ * invocation goes through `@agentproto/driver`.
+ *
+ * Spec: https://agentproto.sh/docs/aip-14
+ */
+declare const SPEC_NAME: "agenttool/v1";
+declare const SPEC_VERSION: "1.0.0-alpha";
+
+export { type CreateToolOptions, type CreateToolResult, SPEC_NAME, SPEC_VERSION, ToolContext, ToolDefinition, ToolError, type ToolErrorCode, type ToolErrorPayload, ToolHandle, ToolResult, ValidationResult, createTool, defineTool, toToolError, toToolResult, toolSpec, toolVerbs, validateContext, validateInput, validateOutput };

package/dist/index.mjs

@@ -0,0 +1,55 @@
+import { parseToolManifest, defineTool } from './chunk-ZFIMSZXN.mjs';
+export { ToolError, defineTool, toToolError, toToolResult, validateContext, validateInput, validateOutput } from './chunk-ZFIMSZXN.mjs';
+import { filterSerializable } from '@agentproto/define-doctype';
+import matter from 'gray-matter';
+import { mkdir, writeFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { createVerbs } from '@agentproto/manifest';
+
+/**
+ * @agentproto/tool v0.1.0-alpha
+ * AIP-14 TOOL.md `defineTool` reference implementation.
+ */
+async function createTool(params, opts) {
+  const handle = defineTool(params);
+  const path = join(opts.dir, handle.id, "TOOL.md");
+  const frontmatter = filterSerializable({
+    schema: "agentproto/tool/v1",
+    ...params
+  });
+  const rendered = matter.stringify(
+    opts.body ?? `# ${handle.name}
+
+${handle.description}
+`,
+    frontmatter
+  );
+  if (!opts.dryRun) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, rendered, "utf8");
+  }
+  return { path, handle, rendered };
+}
+var toolSpec = {
+  name: "tool",
+  aip: 14,
+  schemaLiteral: "agentproto/tool/v1",
+  pathOf: (h) => `${h.id}/TOOL.md`,
+  define: (params) => defineTool(params),
+  parse: (source) => {
+    const m = parseToolManifest(source);
+    return {
+      frontmatter: m.frontmatter,
+      body: m.body
+    };
+  }
+};
+var toolVerbs = createVerbs(toolSpec);
+
+// src/index.ts
+var SPEC_NAME = "agenttool/v1";
+var SPEC_VERSION = "1.0.0-alpha";
+
+export { SPEC_NAME, SPEC_VERSION, createTool, toolSpec, toolVerbs };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/create-tool.ts","../src/spec.ts","../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAgDA,eAAsB,UAAA,CAKpB,QACA,IAAA,EACsD;AACtD,EAAA,MAAM,MAAA,GAAS,WAAsC,MAAM,CAAA;AAC3D,EAAA,MAAM,OAAO,IAAA,CAAK,IAAA,CAAK,GAAA,EAAK,MAAA,CAAO,IAAI,SAAS,CAAA;AAChD,EAAA,MAAM,cAAc,kBAAA,CAAmB;AAAA,IACrC,MAAA,EAAQ,oBAAA;AAAA,IACR,GAAG;AAAA,GACJ,CAAA;AACD,EAAA,MAAM,WAAW,MAAA,CAAO,SAAA;AAAA,IACtB,IAAA,CAAK,IAAA,IAAQ,CAAA,EAAA,EAAK,MAAA,CAAO,IAAI;;AAAA,EAAO,OAAO,WAAW;AAAA,CAAA;AAAA,IACtD;AAAA,GACF;AACA,EAAA,IAAI,CAAC,KAAK,MAAA,EAAQ;AAChB,IAAA,MAAM,MAAM,OAAA,CAAQ,IAAI,GAAG,EAAE,SAAA,EAAW,MAAM,CAAA;AAC9C,IAAA,MAAM,SAAA,CAAU,IAAA,EAAM,QAAA,EAAU,MAAM,CAAA;AAAA,EACxC;AACA,EAAA,OAAO,EAAE,IAAA,EAAM,MAAA,EAAQ,QAAA,EAAS;AAClC;AC1DO,IAAM,QAAA,GAGT;AAAA,EACF,IAAA,EAAM,MAAA;AAAA,EACN,GAAA,EAAK,EAAA;AAAA,EACL,aAAA,EAAe,oBAAA;AAAA,EACf,MAAA,EAAQ,CAAC,CAAA,KAAM,CAAA,EAAG,EAAE,EAAE,CAAA,QAAA,CAAA;AAAA,EACtB,MAAA,EAAQ,CAAC,MAAA,KACP,UAAA,CAAW,MAAM,CAAA;AAAA,EACnB,KAAA,EAAO,CAAC,MAAA,KAAW;AACjB,IAAA,MAAM,CAAA,GAAI,kBAAkB,MAAM,CAAA;AAClC,IAAA,OAAO;AAAA,MACL,aAAa,CAAA,CAAE,WAAA;AAAA,MACf,MAAM,CAAA,CAAE;AAAA,KACV;AAAA,EACF;AACF;AAEO,IAAM,SAAA,GAAY,YAAY,QAAQ;;;ACpBtC,IAAM,SAAA,GAAY;AAClB,IAAM,YAAA,GAAe","file":"index.mjs","sourcesContent":["/**\n * `createTool(params, opts)` — write a TOOL.md to disk.\n *\n * Symmetric to `parseToolManifest` (.md → handle) and `defineTool`\n * (params → handle): this takes params, validates via defineTool\n * (single source of truth — same zod schema, same cross-AIP\n * invariants), then serialises the validated frontmatter to YAML\n * and writes it under `<dir>/<id>/TOOL.md`.\n *\n * The author's body markdown is preserved verbatim in `opts.body`.\n * Pass `dryRun: true` to get the rendered string without touching\n * disk — useful for tests, the MCP server's preview, and CI lints.\n *\n * Non-frontmatter values that can't appear in YAML (zod schemas,\n * function bodies) are filtered out by `filterSerializable` from\n * `@agentproto/define-doctype`; the resulting frontmatter matches\n * what `parseToolManifest` would consume on the way back in.\n */\n\nimport { filterSerializable } from \"@agentproto/define-doctype\"\nimport matter from \"gray-matter\"\nimport { mkdir, writeFile } from \"node:fs/promises\"\nimport { dirname, join } from \"node:path\"\nimport { defineTool } from \"./define-tool.js\"\nimport type { ToolContext, ToolDefinition, ToolHandle } from \"./types.js\"\n\nexport interface CreateToolOptions {\n  /** Workspace-relative or absolute directory under which to write `<id>/TOOL.md`. */\n  dir: string\n  /** Body markdown after the frontmatter. Defaults to a one-line stub. */\n  body?: string\n  /** Render only — don't write. Returns the rendered string. */\n  dryRun?: boolean\n}\n\nexport interface CreateToolResult<\n  TInput,\n  TOutput,\n  TContext extends ToolContext,\n> {\n  /** The path where the file was (or would be) written. */\n  path: string\n  /** The validated handle returned by defineTool. */\n  handle: ToolHandle<TInput, TOutput, TContext>\n  /** The full rendered file contents (frontmatter + body). */\n  rendered: string\n}\n\nexport async function createTool<\n  TInput,\n  TOutput,\n  TContext extends ToolContext = ToolContext,\n>(\n  params: ToolDefinition<TInput, TOutput, TContext>,\n  opts: CreateToolOptions,\n): Promise<CreateToolResult<TInput, TOutput, TContext>> {\n  const handle = defineTool<TInput, TOutput, TContext>(params)\n  const path = join(opts.dir, handle.id, \"TOOL.md\")\n  const frontmatter = filterSerializable({\n    schema: \"agentproto/tool/v1\",\n    ...params,\n  }) as Record<string, unknown>\n  const rendered = matter.stringify(\n    opts.body ?? `# ${handle.name}\\n\\n${handle.description}\\n`,\n    frontmatter,\n  )\n  if (!opts.dryRun) {\n    await mkdir(dirname(path), { recursive: true })\n    await writeFile(path, rendered, \"utf8\")\n  }\n  return { path, handle, rendered }\n}\n","/**\n * AIP-14 doctype spec — fed to `@agentproto/manifest.createVerbs`\n * to derive create / load / list / update / resolve / delete in one\n * place. Keeping the spec separate from `define-tool.ts` lets the\n * manifest layer (and the future MCP server) iterate over a uniform\n * descriptor without each package re-implementing the wiring.\n */\n\nimport { createVerbs, type DoctypeSpec } from \"@agentproto/manifest\"\nimport { defineTool } from \"./define-tool.js\"\nimport { parseToolManifest } from \"./manifest/index.js\"\nimport type { ToolDefinition, ToolHandle } from \"./types.js\"\n\nexport const toolSpec: DoctypeSpec<\n  ToolDefinition<unknown, unknown>,\n  ToolHandle<unknown, unknown>\n> = {\n  name: \"tool\",\n  aip: 14,\n  schemaLiteral: \"agentproto/tool/v1\",\n  pathOf: (h) => `${h.id}/TOOL.md`,\n  define: (params) =>\n    defineTool(params) as ToolHandle<unknown, unknown>,\n  parse: (source) => {\n    const m = parseToolManifest(source)\n    return {\n      frontmatter: m.frontmatter as unknown as Record<string, unknown>,\n      body: m.body,\n    }\n  },\n}\n\nexport const toolVerbs = createVerbs(toolSpec)\n","/**\n * @agentproto/tool — AIP-14 TOOL.md `defineTool` reference impl.\n *\n * Vendor-neutral tool **contract** registration: an author writes\n * `defineTool({...})` and the runtime returns a `ToolHandle` carrying\n * identity, schemas, side-effect profile, approval class, and\n * provider routing hints. Bodies live on AIP-30 PROVIDER manifests;\n * invocation goes through `@agentproto/driver`.\n *\n * Spec: https://agentproto.sh/docs/aip-14\n */\n\nexport const SPEC_NAME = \"agenttool/v1\" as const\nexport const SPEC_VERSION = \"1.0.0-alpha\" as const\n\nexport {\n  defineTool,\n  validateInput,\n  validateContext,\n  validateOutput,\n} from \"./define-tool.js\"\n// Standalone create-tool kept for back-compat; new code should import\n// the unified verb surface (`toolVerbs.create`, `.load`, `.list`,\n// `.update`, `.resolve`, `.delete`) from `./spec.js`.\nexport {\n  createTool,\n  type CreateToolOptions,\n  type CreateToolResult,\n} from \"./create-tool.js\"\nexport { toolSpec, toolVerbs } from \"./spec.js\"\nexport {\n  ToolError,\n  toToolError,\n  toToolResult,\n  type ToolErrorCode,\n  type ToolErrorPayload,\n} from \"./errors.js\"\nexport type {\n  ToolDefinition,\n  ToolHandle,\n  ToolContext,\n  ToolCapabilities,\n  ApprovalClass,\n  DriverConstraints,\n  DriverKind,\n  RetryPolicy,\n  ToolResult,\n  ValidationResult,\n  ValidationFailure,\n  ValidationSuccess,\n} from \"./types.js\"\n"]}

package/dist/manifest/index.d.ts

@@ -0,0 +1,82 @@
+import { z, ZodType } from 'zod';
+import { A as ApprovalClass, T as ToolContext, b as ToolHandle } from '../types-Ce8BEvMm.js';
+
+/**
+ * AIP-14 TOOL.md sidecar parser.
+ *
+ * Reads frontmatter (host-relevant metadata) + body (long-form
+ * description / examples / errors). The TS module's `defineTool(...)`
+ * supplies the schemas and execute body; this manifest supplies the
+ * runtime metadata that overrides or augments the in-code defaults.
+ *
+ * Field set covers AIP-14 §"Frontmatter" — required and optional fields
+ * normalised to snake_case → camelCase.
+ */
+declare const toolManifestFrontmatterSchema: z.ZodObject<{
+    schema: z.ZodOptional<z.ZodLiteral<"agentproto/tool/v1">>;
+    name: z.ZodString;
+    id: z.ZodString;
+    description: z.ZodString;
+    version: z.ZodString;
+    mutates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requires: z.ZodOptional<z.ZodObject<{
+        network: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    approval: z.ZodOptional<z.ZodCustom<ApprovalClass, ApprovalClass>>;
+    risk_level: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>>;
+    cost_class: z.ZodOptional<z.ZodEnum<{
+        trivial: "trivial";
+        metered: "metered";
+        expensive: "expensive";
+    }>>;
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    idempotent: z.ZodOptional<z.ZodBoolean>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    code: z.ZodOptional<z.ZodUnknown>;
+    run: z.ZodOptional<z.ZodUnknown>;
+    runner: z.ZodOptional<z.ZodUnknown>;
+    secrets: z.ZodOptional<z.ZodUnknown>;
+    network: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type ToolManifestFrontmatter = z.infer<typeof toolManifestFrontmatterSchema>;
+interface ToolManifest {
+    frontmatter: ToolManifestFrontmatter;
+    body: string;
+}
+/**
+ * Parse a TOOL.md source string into structured frontmatter + body.
+ * Throws on missing frontmatter or schema-invalid frontmatter.
+ */
+declare function parseToolManifest(source: string): ToolManifest;
+/**
+ * Build a fully-typed {@link ToolHandle} from a parsed `TOOL.md` manifest
+ * + caller-supplied schemas. The .md is the single source of truth for
+ * metadata (id, name, description, version, mutates, approval, …); the
+ * schemas live in the TS module that ships alongside the .md.
+ *
+ * Both inputs are revalidated by `defineTool`'s shared invariants
+ * (id pattern, description length, top-level freeze) — `parseToolManifest`
+ * already enforces a stricter id pattern + version semver, so a
+ * well-formed manifest passes through cleanly. Mismatches between the
+ * manifest's id-shape and `defineTool`'s pattern surface a
+ * descriptive error from the same validation pipeline as the TS path.
+ *
+ * @example
+ *   const manifest = parseToolManifest(readFileSync("./echo/TOOL.md", "utf8"))
+ *   const echo = toolFromManifest({
+ *     manifest,
+ *     inputSchema: z.object({ msg: z.string() }),
+ *     outputSchema: z.object({ msg: z.string() }),
+ *   })
+ */
+declare function toolFromManifest<TInput, TOutput, TContext extends ToolContext = ToolContext>(args: {
+    manifest: ToolManifest;
+    inputSchema: ZodType<TInput>;
+    outputSchema: ZodType<TOutput>;
+    contextSchema?: ZodType<TContext>;
+}): ToolHandle<TInput, TOutput, TContext>;
+
+export { type ToolManifest, type ToolManifestFrontmatter, parseToolManifest, toolFromManifest, toolManifestFrontmatterSchema };

package/dist/manifest/index.mjs

@@ -0,0 +1,3 @@
+export { parseToolManifest, toolFromManifest, toolManifestFrontmatterSchema } from '../chunk-ZFIMSZXN.mjs';
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/manifest/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/dist/types-Ce8BEvMm.d.ts

@@ -0,0 +1,161 @@
+import { ZodType } from 'zod';
+
+/**
+ * AIP-14 ToolDefinition — the abstract agent contract.
+ *
+ * Field set mirrors `TOOL.md` frontmatter so a manifest and a TS
+ * module are interchangeable inputs to the runtime. The contract
+ * carries identity, schemas, side-effect profile, approval class,
+ * and resource budget — but **not** the body. Bodies live on
+ * AIP-30 PROVIDER manifests + their `execute[<toolId>]` entries.
+ *
+ * Generic over context: tools that depend on host-injected state
+ * (database connections, governance config, …) declare a
+ * `contextSchema` — analogous to `inputSchema` but for the per-call
+ * context object — and the host validates context against it before
+ * dispatching to the resolved provider's body.
+ */
+interface ToolDefinition<TInput = unknown, TOutput = unknown, TContext extends ToolContext = ToolContext> {
+    /** Machine identifier. Lowercase, digits, dashes, dots. 2–80 chars. */
+    id: string;
+    /** Human-readable display name. Optional; falls back to `id`. */
+    name?: string;
+    /** One-paragraph purpose, written for the LLM caller. */
+    description: string;
+    /** Spec version of THIS tool (semver). */
+    version?: string;
+    /**
+     * Input shape — zod schema in v0.1. Hosts validate args.input against
+     * it before dispatching to the resolved provider; bodies MUST NOT
+     * re-validate.
+     *
+     * v0.2 will also accept JSON Schema directly.
+     */
+    inputSchema: ZodType<TInput>;
+    outputSchema: ZodType<TOutput>;
+    /**
+     * Optional context schema. When provided, the host validates
+     * `args.context` against it before dispatching to the provider,
+     * rejecting with `input_invalid` (field=`context`) on mismatch.
+     * Providers receive the narrowed, typed context.
+     */
+    contextSchema?: ZodType<TContext>;
+    /** Resources the tool may modify. Format: `<class>:<scope>`. */
+    mutates?: readonly string[];
+    /** Capability requirements (governance/gating per AIP-7). */
+    requires?: ToolCapabilities;
+    approval?: ApprovalClass;
+    riskLevel?: 0 | 1 | 2 | 3;
+    costClass?: "trivial" | "metered" | "expensive";
+    /** Hard wall-clock contract ceiling. Providers MAY narrow; never widen. */
+    timeoutMs?: number;
+    retry?: RetryPolicy;
+    /** Free-form discovery tags. */
+    tags?: readonly string[];
+    /** Free-form metadata under namespaced keys (`mastra.…`, `langchain.…`). */
+    metadata?: Record<string, unknown>;
+    /** Whether retries are observably free of extra effect. Defaults to `false`. */
+    idempotent?: boolean;
+    /**
+     * Optional pin for the canonical provider. The AIP-30 resolver uses
+     * this in Phase 5 (cost ranking) when no other signal differentiates
+     * candidates. Null/undefined = pick by resolver policy.
+     */
+    defaultImplementation?: string;
+    /**
+     * Author-side allowlist/denylist on which provider kinds the contract
+     * permits. Use to express "this tool MUST NOT be served via untrusted
+     * HTTP" (`forbid: ["http"]`) for self-hosted-only contracts.
+     */
+    driverConstraints?: DriverConstraints;
+}
+type DriverKind = "cli" | "http" | "mcp" | "sdk" | "builtin";
+interface DriverConstraints {
+    /** Provider kinds the contract refuses. */
+    forbid?: readonly DriverKind[];
+    /** Whitelist of allowed provider kinds. Empty/missing = all permitted. */
+    requireKind?: readonly DriverKind[];
+}
+type ToolContext = Record<string, unknown> & {
+    signal?: AbortSignal;
+};
+type ApprovalClass = "auto" | "always" | "on-mutate" | `policy:${string}`;
+interface ToolCapabilities {
+    network?: readonly string[];
+    secrets?: readonly string[];
+    tools?: readonly string[];
+}
+interface RetryPolicy {
+    maxAttempts: number;
+    backoff: "fixed" | "exponential";
+    initialMs: number;
+}
+/**
+ * The host-registrable contract handle returned by `defineTool`.
+ *
+ * Adapters (`toMastraTool`, …) AND provider runtimes (`http-runtime`,
+ * `cli-runtime`, …) consume this shape. The handle does **not** carry
+ * an invoke method — invocation goes through provider-runtime, which
+ * resolves a provider per call and dispatches to its `execute[id]`.
+ */
+interface ToolHandle<TInput = unknown, TOutput = unknown, TContext extends ToolContext = ToolContext> {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly version?: string;
+    readonly inputSchema: ZodType<TInput>;
+    readonly outputSchema: ZodType<TOutput>;
+    readonly contextSchema?: ZodType<TContext>;
+    readonly mutates: readonly string[];
+    readonly requires: ToolCapabilities;
+    readonly approval: ApprovalClass;
+    readonly riskLevel: 0 | 1 | 2 | 3;
+    readonly costClass: "trivial" | "metered" | "expensive";
+    readonly timeoutMs: number;
+    readonly retry?: RetryPolicy;
+    readonly tags: readonly string[];
+    readonly metadata: Record<string, unknown>;
+    readonly idempotent: boolean;
+    readonly defaultImplementation?: string;
+    readonly driverConstraints: Required<DriverConstraints>;
+}
+/**
+ * Standard out-of-band result envelope. Provider runtimes wrap thrown
+ * errors into this shape; consumers consume `ToolResult<T>` rather than
+ * `Promise<T>`.
+ */
+type ToolResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        retryable?: boolean;
+        cause?: unknown;
+    };
+};
+/**
+ * Validation helpers exposed for provider-runtime to reuse the same
+ * input/output/context validation logic AIP-14 prescribes. Provider
+ * runtimes MUST validate args.input against `tool.inputSchema` and
+ * (when declared) args.context against `tool.contextSchema` BEFORE
+ * dispatching to a provider's body.
+ */
+interface ValidationFailure {
+    ok: false;
+    error: {
+        code: "input_invalid";
+        message: string;
+        field?: string;
+        cause?: unknown;
+    };
+}
+interface ValidationSuccess<T> {
+    ok: true;
+    value: T;
+}
+type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;
+
+export type { ApprovalClass as A, DriverConstraints as D, RetryPolicy as R, ToolContext as T, ValidationResult as V, ToolDefinition as a, ToolHandle as b, ToolResult as c, DriverKind as d, ToolCapabilities as e, ValidationFailure as f, ValidationSuccess as g };

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@agentproto/tool",
+  "version": "0.1.1",
+  "description": "agentproto/tool-runtime — reference implementation of AIP-14 TOOL.md `defineTool` contract. Vendor-neutral tool registration with validated input/output schemas, structured error envelopes, and side-effect declarations. Per-framework adapters (Mastra, LangChain, A2A) consume the produced ToolHandle.",
+  "keywords": [
+    "agentproto",
+    "aip-14",
+    "tool",
+    "tool-runtime",
+    "defineTool",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentik.net/docs/aip-14",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./manifest": {
+      "types": "./dist/manifest/index.d.ts",
+      "import": "./dist/manifest/index.mjs",
+      "default": "./dist/manifest/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "gray-matter": "^4.0.3",
+    "zod": "^4.4.3",
+    "@agentproto/define-doctype": "0.1.0",
+    "@agentproto/manifest": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}