@agentproto/adapter-mastra 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,45 @@
+# @agentproto/adapter-mastra
+
+Generic Mastra adapter for [AIP-14](https://agentik.net/docs/aip-14)
+`ToolHandle`s. Wraps any tool authored via
+[`@agentproto/tool`](../tool-runtime) into a Mastra `createTool({...})`
+handle.
+
+```ts
+import { defineTool } from "@agentproto/tool"
+import { toMastraTool } from "@agentproto/adapter-mastra"
+import { z } from "zod"
+
+const echo = defineTool({
+  id: "echo",
+  description: "Returns its input.",
+  inputSchema: z.object({ message: z.string() }),
+  outputSchema: z.object({ echo: z.string() }),
+  execute: ({ input }) => ({ echo: input.message }),
+})
+
+const mastraEcho = toMastraTool(echo, {
+  // Optional: static context fields merged into every invocation.
+  contextProvider: () => ({ governanceConfig: getGovernanceConfig() }),
+})
+```
+
+`toMastraTool` produces a Mastra-native handle whose `execute` calls
+`handle.invoke(...)` from the runtime — so input/output validation,
+schema-defined errors, and AIP-14 conformance happen once, regardless of which
+framework consumes the tool.
+
+## Mapping
+
+| AIP-14 ToolHandle                  | Mastra createTool                                        |
+| ---------------------------------- | -------------------------------------------------------- |
+| `id`                               | `id`                                                     |
+| `description`                      | `description`                                            |
+| `inputSchema` (zod)                | `inputSchema`                                            |
+| `outputSchema` (zod)               | `outputSchema`                                           |
+| `invoke({input, context})`         | `execute(inputData, mastraContext) → handle.invoke(...)` |
+| `mutates`, `approval`, `riskLevel` | `metadata` (Mastra has no first-class fields for these)  |
+
+## Spec
+
+See [AIP-14](https://agentik.net/docs/aip-14).

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import { createTool } from '@mastra/core/tools';
+import { ToolContext } from '@agentproto/tool';
+export { ToolError } from '@agentproto/tool';
+import { DriverContext, ToolImplementation } from '@agentproto/driver';
+export { ToolImplementation } from '@agentproto/driver';
+
+/**
+ * @agentproto/adapter-mastra — Mastra adapter for AIP-30
+ * `ToolImplementation`s.
+ *
+ * One function: {@link toMastraTool} takes a typed `ToolImplementation`
+ * (an `(contract, body)` pair produced by
+ * {@link "@agentproto/driver".implementTool}) and returns a Mastra
+ * `createTool({...})` result. Same role as the AI SDK / LangChain
+ * adapters — re-express the canonical typed binding in a host
+ * framework's tool shape, without re-declaring the contract metadata.
+ *
+ * Why `ToolImplementation` (not `(handle, execute)`) is the input:
+ * the typed binding flows the contract's `inputSchema`, `outputSchema`,
+ * and `contextSchema` generics into the body, so the compiler enforces
+ * shape match between body and contract — Solidity's `is IERC20`
+ * pattern in TS. An adapter that consumed handle + execute separately
+ * would defeat that guarantee.
+ *
+ * Resolver / multi-provider dispatch: when the body should pick a
+ * provider per call instead of being statically bound, the caller
+ * wraps `runTool` in `implementTool` once — the adapter is unchanged.
+ *
+ * ```ts
+ * import { implementTool, runTool } from "@agentproto/driver"
+ *
+ * // Static body:
+ * const impl = implementTool(handle, async ({ input, context }) => …)
+ *
+ * // Resolver-driven body:
+ * const dispatchImpl = implementTool(handle, async args =>
+ *   runTool({ tool: handle, candidates: [...], ...args })
+ * )
+ * ```
+ *
+ * Spec: https://agentproto.sh/docs/aip-14, https://agentproto.sh/docs/aip-30
+ */
+
+/**
+ * Per-call context source. Two modes:
+ *
+ *  - **Static** (`{ context }`) — bind a fixed `TContext` once at
+ *    adapter time. Same value for every invocation. Use for tools
+ *    whose context is process-scoped (e.g. `governanceConfig` from
+ *    a single workspace).
+ *
+ *  - **Dynamic** (`{ fromMastraContext }`) — resolve `TContext`
+ *    per-call from Mastra's native execution context (agent,
+ *    workflow, requestContext, observability). Use when context
+ *    depends on per-request state (multi-tenant `guildId`, scoped
+ *    DB connections, …).
+ */
+type MastraContextSource<TContext extends ToolContext> = {
+    context: TContext;
+} | {
+    fromMastraContext: (mastraContext: unknown) => TContext;
+};
+interface ToMastraToolOptions<TContext extends ToolContext> {
+    /** Where the body's `context` arg comes from per call. */
+    source: MastraContextSource<TContext>;
+    /** Optional provider context (for non-builtin bodies). */
+    driverCtx?: DriverContext;
+}
+/**
+ * Adapt a {@link ToolImplementation} into a Mastra tool.
+ *
+ * Type inference: `TContext` is inferred from `impl` only —
+ * `options.source` is wrapped in `NoInfer<>` so a literal context
+ * doesn't narrow the contract's `TContext` and reject an impl whose
+ * body accepts a broader set (TS contravariant-position bug otherwise).
+ *
+ * Drop the result into `agent.stream({ tools: { [id]: adapted } })`
+ * or pass to Mastra's tool registry directly — same shape as
+ * authoring with `createTool` by hand, minus the duplication of
+ * contract metadata and minus the type drift risk between contract
+ * and body.
+ */
+declare function toMastraTool<TInput, TOutput, TContext extends ToolContext = ToolContext>(impl: ToolImplementation<TInput, TOutput, TContext>, options: ToMastraToolOptions<NoInfer<TContext>>): ReturnType<typeof createTool>;
+
+export { type MastraContextSource, type ToMastraToolOptions, toMastraTool };

package/dist/index.mjs

@@ -0,0 +1,42 @@
+import { createTool } from '@mastra/core/tools';
+import { toToolError } from '@agentproto/tool';
+export { ToolError } from '@agentproto/tool';
+
+/**
+ * @agentproto/adapter-mastra v0.1.0-alpha
+ * Mastra adapter for AIP-30 ToolImplementations.
+ */
+
+var DEFAULT_PROVIDER_CTX = Object.freeze({
+  secrets: {},
+  authState: "authed",
+  providerId: "mastra-adapter",
+  driverKind: "builtin",
+  implementsEntry: { tool: "mastra-adapter", version: "0.0.0" }
+});
+function toMastraTool(impl, options) {
+  return createTool({
+    id: impl.tool.id,
+    description: impl.tool.description,
+    inputSchema: impl.tool.inputSchema,
+    outputSchema: impl.tool.outputSchema,
+    execute: async (inputData, mastraContext) => {
+      const context = "context" in options.source ? options.source.context : options.source.fromMastraContext(mastraContext);
+      const typedInput = inputData;
+      try {
+        return await impl.body({
+          input: typedInput,
+          context,
+          driverCtx: options.driverCtx ?? DEFAULT_PROVIDER_CTX,
+          signal: mastraContext?.abortSignal ?? new AbortController().signal
+        });
+      } catch (thrown) {
+        throw toToolError(thrown);
+      }
+    }
+  });
+}
+
+export { toMastraTool };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;AAkDA,IAAM,oBAAA,GAAsC,OAAO,MAAA,CAAO;AAAA,EACxD,SAAS,EAAC;AAAA,EACV,SAAA,EAAW,QAAA;AAAA,EACX,UAAA,EAAY,gBAAA;AAAA,EACZ,UAAA,EAAY,SAAA;AAAA,EACZ,eAAA,EAAiB,EAAE,IAAA,EAAM,gBAAA,EAAkB,SAAS,OAAA;AACtD,CAAC,CAAA;AAyCM,SAAS,YAAA,CAKd,MACA,OAAA,EAC+B;AAC/B,EAAA,OAAO,UAAA,CAAW;AAAA,IAChB,EAAA,EAAI,KAAK,IAAA,CAAK,EAAA;AAAA,IACd,WAAA,EAAa,KAAK,IAAA,CAAK,WAAA;AAAA,IACvB,WAAA,EAAa,KAAK,IAAA,CAAK,WAAA;AAAA,IACvB,YAAA,EAAc,KAAK,IAAA,CAAK,YAAA;AAAA,IACxB,OAAA,EAAS,OAAO,SAAA,EAAW,aAAA,KAAkB;AAG3C,MAAA,MAAM,OAAA,GACJ,SAAA,IAAa,OAAA,CAAQ,MAAA,GACjB,OAAA,CAAQ,OAAO,OAAA,GACf,OAAA,CAAQ,MAAA,CAAO,iBAAA,CAAkB,aAAa,CAAA;AAMpD,MAAA,MAAM,UAAA,GAAqB,SAAA;AAE3B,MAAA,IAAI;AACF,QAAA,OAAO,MAAM,KAAK,IAAA,CAAK;AAAA,UACrB,KAAA,EAAO,UAAA;AAAA,UACP,OAAA;AAAA,UACA,SAAA,EAAW,QAAQ,SAAA,IAAa,oBAAA;AAAA,UAChC,MAAA,EACG,aAAA,EACG,WAAA,IAAe,IAAI,iBAAgB,CAAE;AAAA,SAC5C,CAAA;AAAA,MACH,SAAS,MAAA,EAAQ;AAEf,QAAA,MAAM,YAAY,MAAM,CAAA;AAAA,MAC1B;AAAA,IACF;AAAA,GACD,CAAA;AACH","file":"index.mjs","sourcesContent":["/**\n * @agentproto/adapter-mastra — Mastra adapter for AIP-30\n * `ToolImplementation`s.\n *\n * One function: {@link toMastraTool} takes a typed `ToolImplementation`\n * (an `(contract, body)` pair produced by\n * {@link \"@agentproto/driver\".implementTool}) and returns a Mastra\n * `createTool({...})` result. Same role as the AI SDK / LangChain\n * adapters — re-express the canonical typed binding in a host\n * framework's tool shape, without re-declaring the contract metadata.\n *\n * Why `ToolImplementation` (not `(handle, execute)`) is the input:\n * the typed binding flows the contract's `inputSchema`, `outputSchema`,\n * and `contextSchema` generics into the body, so the compiler enforces\n * shape match between body and contract — Solidity's `is IERC20`\n * pattern in TS. An adapter that consumed handle + execute separately\n * would defeat that guarantee.\n *\n * Resolver / multi-provider dispatch: when the body should pick a\n * provider per call instead of being statically bound, the caller\n * wraps `runTool` in `implementTool` once — the adapter is unchanged.\n *\n * ```ts\n * import { implementTool, runTool } from \"@agentproto/driver\"\n *\n * // Static body:\n * const impl = implementTool(handle, async ({ input, context }) => …)\n *\n * // Resolver-driven body:\n * const dispatchImpl = implementTool(handle, async args =>\n *   runTool({ tool: handle, candidates: [...], ...args })\n * )\n * ```\n *\n * Spec: https://agentproto.sh/docs/aip-14, https://agentproto.sh/docs/aip-30\n */\n\nimport { createTool } from \"@mastra/core/tools\"\nimport { toToolError, type ToolContext } from \"@agentproto/tool\"\nimport type {\n  DriverContext,\n  ToolImplementation,\n} from \"@agentproto/driver\"\n\n/**\n * Default {@link DriverContext} used when the caller doesn't pass\n * one. `kind: \"builtin\"` reflects the typical adapter use-case\n * (in-process bodies that don't read provider secrets / sandbox\n * handles). Override via `bind.driverCtx` for non-builtin bodies.\n */\nconst DEFAULT_PROVIDER_CTX: DriverContext = Object.freeze({\n  secrets: {},\n  authState: \"authed\",\n  providerId: \"mastra-adapter\",\n  driverKind: \"builtin\",\n  implementsEntry: { tool: \"mastra-adapter\", version: \"0.0.0\" },\n})\n\n/**\n * Per-call context source. Two modes:\n *\n *  - **Static** (`{ context }`) — bind a fixed `TContext` once at\n *    adapter time. Same value for every invocation. Use for tools\n *    whose context is process-scoped (e.g. `governanceConfig` from\n *    a single workspace).\n *\n *  - **Dynamic** (`{ fromMastraContext }`) — resolve `TContext`\n *    per-call from Mastra's native execution context (agent,\n *    workflow, requestContext, observability). Use when context\n *    depends on per-request state (multi-tenant `guildId`, scoped\n *    DB connections, …).\n */\nexport type MastraContextSource<TContext extends ToolContext> =\n  | { context: TContext }\n  | { fromMastraContext: (mastraContext: unknown) => TContext }\n\nexport interface ToMastraToolOptions<TContext extends ToolContext> {\n  /** Where the body's `context` arg comes from per call. */\n  source: MastraContextSource<TContext>\n  /** Optional provider context (for non-builtin bodies). */\n  driverCtx?: DriverContext\n}\n\n/**\n * Adapt a {@link ToolImplementation} into a Mastra tool.\n *\n * Type inference: `TContext` is inferred from `impl` only —\n * `options.source` is wrapped in `NoInfer<>` so a literal context\n * doesn't narrow the contract's `TContext` and reject an impl whose\n * body accepts a broader set (TS contravariant-position bug otherwise).\n *\n * Drop the result into `agent.stream({ tools: { [id]: adapted } })`\n * or pass to Mastra's tool registry directly — same shape as\n * authoring with `createTool` by hand, minus the duplication of\n * contract metadata and minus the type drift risk between contract\n * and body.\n */\nexport function toMastraTool<\n  TInput,\n  TOutput,\n  TContext extends ToolContext = ToolContext,\n>(\n  impl: ToolImplementation<TInput, TOutput, TContext>,\n  options: ToMastraToolOptions<NoInfer<TContext>>\n): ReturnType<typeof createTool> {\n  return createTool({\n    id: impl.tool.id,\n    description: impl.tool.description,\n    inputSchema: impl.tool.inputSchema,\n    outputSchema: impl.tool.outputSchema,\n    execute: async (inputData, mastraContext) => {\n      // Pull context per-call: static binding closes over `options.source.context`;\n      // dynamic binding reads from Mastra's native context.\n      const context: TContext =\n        \"context\" in options.source\n          ? options.source.context\n          : options.source.fromMastraContext(mastraContext)\n\n      // Mastra validates `inputData` against `inputSchema` BEFORE\n      // calling execute, so the structural shape matches `TInput` at\n      // this point. The local typed binding documents the post-\n      // validation contract.\n      const typedInput: TInput = inputData as TInput\n\n      try {\n        return await impl.body({\n          input: typedInput,\n          context,\n          driverCtx: options.driverCtx ?? DEFAULT_PROVIDER_CTX,\n          signal:\n            (mastraContext as { abortSignal?: AbortSignal } | undefined)\n              ?.abortSignal ?? new AbortController().signal,\n        })\n      } catch (thrown) {\n        // Re-throw as a structured error; Mastra catches and surfaces.\n        throw toToolError(thrown)\n      }\n    },\n  })\n}\n\nexport { ToolError } from \"@agentproto/tool\"\nexport type { ToolImplementation } from \"@agentproto/driver\"\n"]}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@agentproto/adapter-mastra",
+  "version": "0.1.1",
+  "description": "Generic Mastra adapter for AIP-14 ToolHandles. Wraps any `@agentproto/tool` ToolHandle into a Mastra createTool() handle so apps drop in tools authored once and used by any framework.",
+  "keywords": [
+    "agentproto",
+    "aip-14",
+    "tool",
+    "mastra",
+    "adapter",
+    "open-standard"
+  ],
+  "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"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentproto/driver": "0.1.1",
+    "@agentproto/tool": "0.1.1"
+  },
+  "peerDependencies": {
+    "@mastra/core": "*",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@mastra/core": "1.32.1",
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "zod": "^4.4.3",
+    "@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"
+  }
+}