maestro-core 0.1.0

package/dist/tool.d.ts

@@ -0,0 +1,86 @@
+import type { z } from 'zod';
+import type { BaseToolContext } from './context.js';
+import type { ToolEnvelope, ToolMeta } from './envelope.js';
+/**
+ * Coarse classification used by adapters and admin dashboards.
+ *
+ * - `read`        — pure lookup, no side effects.
+ * - `write`       — mutates host state. Usually pairs with `requiresConfirmation`.
+ * - `navigation`  — emits a UX hint (e.g. open a screen). No state change.
+ */
+export type ToolKind = 'read' | 'write' | 'navigation';
+/** Hint for rate-limit tiering and cost dashboards. */
+export type ToolCostBand = 'cheap' | 'medium' | 'expensive';
+/**
+ * Definition of a single agent tool. Pure — adapters translate this
+ * into AI-SDK / MCP / Anthropic-messages shape at the boundary.
+ *
+ * Required fields are the irreducible minimum every tool author must
+ * supply. Everything else is optional to keep the surface tight for
+ * sibling products that don't share barbeiro-specific governance
+ * (OAuth scopes, confirmation prompts, cost banding).
+ */
+export interface AgentToolDefinition<TInput extends z.ZodTypeAny, TOutput, TCtx extends BaseToolContext = BaseToolContext> {
+    /** Public identifier the model sees. camelCase by convention. */
+    name: string;
+    /**
+     * Entire selection signal for the model. Be explicit about *when*
+     * and *when not* to call this tool. Vague descriptions cause misfires.
+     */
+    description: string;
+    /** Zod schema for tool input. Drives both validation and JSON-Schema export. */
+    inputSchema: TInput;
+    /**
+     * Surfaces where this tool is offered. Adapters filter the registry
+     * via `def.transports.includes(transport)`. String values are the
+     * host's vocabulary — kernel does not enumerate.
+     */
+    transports: readonly string[];
+    /**
+     * Per-request gate. Runs BEFORE the tool is offered to the model.
+     * Failing gate = tool is not advertised that turn. Async OK
+     * (feature flags, downstream-config checks).
+     */
+    isAvailable?: (ctx: TCtx) => boolean | Promise<boolean>;
+    /**
+     * Tool body. Returns a `ToolEnvelope` so failures surface as data
+     * the model can recover from, instead of throwing.
+     *
+     * Throwing is allowed — adapters wrap `execute` so the throw is
+     * captured by the host-provided onError hook and surfaced as a
+     * tool-error result to the model. See `safe-tool.ts`.
+     */
+    execute: (input: z.infer<TInput>, ctx: TCtx) => Promise<ToolEnvelope<TOutput>>;
+    kind?: ToolKind;
+    costBand?: ToolCostBand;
+    /**
+     * Which host-defined actor strings may invoke this tool. Adapters
+     * filter on this in addition to `transports` so the same surface
+     * can serve different actor populations (owner-MCP vs client-MCP).
+     */
+    actorScope?: readonly string[];
+    /**
+     * OAuth scope strings consulted by the MCP adapter. Ignored by
+     * non-OAuth adapters.
+     */
+    scopes?: readonly string[];
+    /** Destructive writes should preview-then-commit at the surface layer. */
+    requiresConfirmation?: boolean;
+    /** Free-form grouping for admin UI and MCP directory listings. */
+    category?: string;
+    /** Default `meta` returned with every successful envelope. */
+    meta?: ToolMeta;
+    /** Schema version. Bump on input/output breaking changes. */
+    schemaVersion?: number;
+}
+/**
+ * Identity-factory for tool definitions. Lets call sites write
+ * `defineAgentTool({...})` without spelling out the generics — TS
+ * infers `TInput` from the zod literal and `TOutput` from the execute
+ * return type. `TCtx` defaults to `BaseToolContext` and is set
+ * explicitly when the host needs its extended context shape.
+ */
+export declare function defineAgentTool<TInput extends z.ZodTypeAny, TOutput, TCtx extends BaseToolContext = BaseToolContext>(def: AgentToolDefinition<TInput, TOutput, TCtx>): AgentToolDefinition<TInput, TOutput, TCtx>;
+/** Convenient existential for registries that hold mixed tools. */
+export type AnyAgentToolDefinition<TCtx extends BaseToolContext = BaseToolContext> = AgentToolDefinition<z.ZodTypeAny, unknown, TCtx>;
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE3D;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,YAAY,CAAA;AAEtD,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAA;AAE3D;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB,CAChC,MAAM,SAAS,CAAC,CAAC,UAAU,EAC3B,OAAO,EACP,IAAI,SAAS,eAAe,GAAG,eAAe;IAE9C,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAA;IAEZ;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;IAEnB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IAE7B;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEvD;;;;;;;OAOG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAA;IAG9E,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,QAAQ,CAAC,EAAE,YAAY,CAAA;IAEvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAE9B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAE1B,0EAA0E;IAC1E,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAE9B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,QAAQ,CAAA;IAEf,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC3B,MAAM,SAAS,CAAC,CAAC,UAAU,EAC3B,OAAO,EACP,IAAI,SAAS,eAAe,GAAG,eAAe,EAE9C,GAAG,EAAE,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,GAChD,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAE5C;AAED,mEAAmE;AACnE,MAAM,MAAM,sBAAsB,CAAC,IAAI,SAAS,eAAe,GAAG,eAAe,IAC7E,mBAAmB,CAAC,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,CAAA"}

package/dist/tool.js

@@ -0,0 +1,11 @@
+/**
+ * Identity-factory for tool definitions. Lets call sites write
+ * `defineAgentTool({...})` without spelling out the generics — TS
+ * infers `TInput` from the zod literal and `TOutput` from the execute
+ * return type. `TCtx` defaults to `BaseToolContext` and is set
+ * explicitly when the host needs its extended context shape.
+ */
+export function defineAgentTool(def) {
+    return def;
+}
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAiGA;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAK3B,GAA+C;IAE/C,OAAO,GAAG,CAAA;AACd,CAAC"}

package/package.json

@@ -0,0 +1,83 @@
+{
+    "name": "maestro-core",
+    "version": "0.1.0",
+    "description": "Runtime kernel for the Maestro agent platform — tool envelope, tool definition factory, base context, port interfaces, and AI-SDK + MCP adapters.",
+    "license": "Apache-2.0",
+    "author": "Costa Software",
+    "homepage": "https://github.com/costasoftware/maestro/tree/main/packages/maestro-core#readme",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/costasoftware/maestro.git",
+        "directory": "packages/maestro-core"
+    },
+    "bugs": {
+        "url": "https://github.com/costasoftware/maestro/issues"
+    },
+    "keywords": [
+        "ai",
+        "agent",
+        "tool-calling",
+        "anthropic",
+        "openai",
+        "mcp",
+        "ai-sdk",
+        "llm",
+        "vercel-ai"
+    ],
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./ports": {
+            "types": "./dist/ports/index.d.ts",
+            "import": "./dist/ports/index.js"
+        },
+        "./adapters/ai-sdk": {
+            "types": "./dist/adapters/ai-sdk.d.ts",
+            "import": "./dist/adapters/ai-sdk.js"
+        },
+        "./adapters/mcp-server": {
+            "types": "./dist/adapters/mcp-server.d.ts",
+            "import": "./dist/adapters/mcp-server.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "test": "vitest run",
+        "lint": "echo \"(lint not yet configured)\" && exit 0",
+        "typecheck": "tsc -p tsconfig.build.json --noEmit",
+        "clean": "rm -rf dist .turbo *.tsbuildinfo"
+    },
+    "peerDependencies": {
+        "@modelcontextprotocol/sdk": "^1.29.0",
+        "ai": "^6.0.0",
+        "zod": "^3.25.0"
+    },
+    "peerDependenciesMeta": {
+        "@modelcontextprotocol/sdk": {
+            "optional": true
+        },
+        "ai": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@modelcontextprotocol/sdk": "^1.29.0",
+        "@types/node": "^22.10.0",
+        "ai": "^6.0.0",
+        "typescript": "^5.7.2",
+        "vitest": "^2.1.8",
+        "zod": "^3.25.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}