@agentproto/driver 0.1.1

package/dist/types-U3ItqOQG.d.ts

@@ -0,0 +1,383 @@
+import { ToolContext, ToolHandle, DriverKind } from '@agentproto/tool';
+
+/**
+ * Body signature derived from a contract handle's generics.
+ *
+ * Analogous to a Solidity function `override` against an interface
+ * declaration: `input` matches the contract's `inputSchema` type,
+ * `context` matches `contextSchema`, and the return is checked against
+ * `outputSchema`. Drift between the body and its contract is a compile
+ * error, not a runtime one.
+ *
+ * Compare with the legacy {@link ExecuteFn} — `unknown`-typed inputs
+ * that require manual `as InputType` casts at every body. That form
+ * stays available for `.md`-driven dynamic loading where the contract
+ * handle isn't in scope; TypeScript authors should prefer the typed
+ * form via {@link implementTool}.
+ */
+type TypedExecuteFn<TInput, TOutput, TContext extends ToolContext> = (args: {
+    input: TInput;
+    context: TContext;
+    driverCtx: DriverContext;
+    signal: AbortSignal;
+}) => Promise<TOutput> | TOutput;
+/**
+ * Typed `(contract, body)` pair — the missing "concrete tool" layer
+ * between AIP-14 `ITool` (the contract handle) and AIP-30 PROVIDER
+ * (the shared-infra bundle).
+ *
+ * Authored via {@link implementTool}, consumed by {@link defineDriver}
+ * via `implementations: [...]` and by per-surface adapters
+ * (`toAiSdkTool`, `toMastraTool`) that close the body over a
+ * per-request `context`.
+ */
+interface ToolImplementation<TInput = unknown, TOutput = unknown, TContext extends ToolContext = ToolContext> {
+    /** The AIP-14 contract handle this implementation binds to. */
+    readonly tool: ToolHandle<TInput, TOutput, TContext>;
+    /** Typed body — see {@link TypedExecuteFn}. */
+    readonly body: TypedExecuteFn<TInput, TOutput, TContext>;
+}
+/**
+ * Bind a typed body to an AIP-14 `ITool` contract handle.
+ *
+ * Equivalent to Solidity's `MyToken is IERC20` pattern: the compiler
+ * enforces that the body's input/output/context match the contract's
+ * generics. No string-keyed indirection, no manual `as` casts at
+ * call sites.
+ *
+ * The returned {@link ToolImplementation} is the canonical typed
+ * binding; downstream surfaces consume it via:
+ *
+ * - {@link defineDriver} — bundle ≥1 implementations into a
+ *   shared-infra provider for the AIP-30 resolver to dispatch through.
+ * - `toAiSdkTool(impl, { context })` — adapt to AI SDK's
+ *   `tool({...})` shape for `streamText` / `generateText` consumers.
+ * - `toMastraTool(impl, { context })` — adapt to Mastra's `createTool`
+ *   for `agent.stream` / `agent.generate` consumers.
+ *
+ * The same `impl` can be re-adapted with different per-request
+ * contexts; the body is captured once and the context flows through
+ * the closure each time.
+ */
+declare function implementTool<TInput, TOutput, TContext extends ToolContext = ToolContext>(tool: ToolHandle<TInput, TOutput, TContext>, body: TypedExecuteFn<TInput, TOutput, TContext>): ToolImplementation<TInput, TOutput, TContext>;
+
+/**
+ * AIP-30 DriverDefinition — what an author hands to {@link defineDriver}.
+ *
+ * Field set mirrors `DRIVER.md` frontmatter. Bodies live in the
+ * `execute` map keyed by tool id; one provider MAY implement multiple
+ * tools.
+ */
+interface DriverDefinition {
+    /** Machine identifier. Lowercase, digits, dashes, dots. 2–80 chars. */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /** One-paragraph purpose. */
+    description: string;
+    /** Spec version of THIS provider (semver). */
+    version?: string;
+    /** Concrete subtype. */
+    kind: DriverKind;
+    /** Per-tool dispatch bindings. ≥1 entry. */
+    implements: readonly ImplementsEntry[];
+    /**
+     * Per-tool execute bodies, keyed by `implements[].tool` id. Legacy
+     * form — used for `.md`-driven dynamic loading where the contract
+     * handle isn't in scope at module load time. TypeScript authors
+     * SHOULD prefer {@link DriverDefinition.implementations} for
+     * compile-time type safety against the contract's generics.
+     *
+     * `defineDriver` accepts either field; both can coexist when a
+     * provider mixes typed and dynamic bodies. On the same tool id,
+     * `implementations` wins (typed beats untyped).
+     */
+    execute?: Record<string, ExecuteFn>;
+    /**
+     * Typed implementations bound to their contract handles via
+     * {@link implementTool}(handle, body). Each carries `impl.tool.id`,
+     * so the author doesn't restate the binding as a string key.
+     * `defineDriver` reads `impl.tool.id` to populate the runtime
+     * execute map.
+     *
+     * Equivalent in role to Solidity's `is IERC20` declarations on a
+     * contract: the compiler enforces shape match between the body
+     * and the interface it claims to implement.
+     *
+     * Type note: the array element generics are erased to
+     * `ToolImplementation<any, any, any>` because heterogeneous
+     * implementations (different contracts, different input/output
+     * types) must coexist. Per-impl type safety is enforced at
+     * `implementTool(handle, body)` call sites, not at the array
+     * collection level. Without `any` here TS's contravariant function
+     * positions reject heterogeneous arrays — see TS issue #21534.
+     */
+    implementations?: readonly ToolImplementation<any, any, any>[];
+    /** Universal lifecycle / policy / sandbox blocks (subset of frontmatter). */
+    install?: readonly InstallMethod[];
+    versionCheck?: VersionCheck;
+    auth?: AuthConfig;
+    network?: {
+        egress?: readonly string[];
+        ingress?: readonly string[];
+    };
+    region?: readonly string[];
+    policyTags?: readonly string[];
+    costOverride?: CostOverride;
+    timeoutOverrideMs?: number;
+    retryOverride?: RetryPolicy;
+    healthCheck?: HealthCheckConfig;
+    /** Optional behavioural adapters. */
+    login?: (args: LoginArgs) => Promise<LoginResult>;
+    refresh?: (args: RefreshArgs) => Promise<RefreshResult>;
+    parseOutput?: (args: ParseOutputArgs) => ParseOutputResult;
+    detectExpiry?: (args: DetectExpiryArgs) => boolean;
+    /** Bookkeeping. */
+    tags?: readonly string[];
+    metadata?: Record<string, unknown>;
+}
+interface ImplementsEntry {
+    /** Workspace-relative path or registry id of a TOOL.md. */
+    tool: string;
+    /** Contract semver range (npm-style). */
+    version: string;
+    /** Optional: drop optional inputs/outputs the provider doesn't support. */
+    schemaNarrowing?: {
+        dropInputs?: readonly string[];
+        dropOutputs?: readonly string[];
+    };
+    /**
+     * Optional: rename or transform contract-input keys to provider-arg keys.
+     * String value = identity/rename. Object = `{ from, transform }` calling
+     * a named transformer exposed by the provider's entry.
+     */
+    mapping?: Record<string, MappingValue>;
+    /** Per-tool overrides; fall through to provider-level overrides. */
+    costOverride?: CostOverride;
+    timeoutOverrideMs?: number;
+    retryOverride?: RetryPolicy;
+    /** Per-tool, kind-specific dispatch hints (argv / endpoint / mcp_tool_name / function_ref). */
+    metadata?: Record<string, unknown>;
+}
+type MappingValue = string | {
+    from: string;
+    transform?: string;
+};
+type ExecuteFn = (args: ExecuteArgs) => Promise<unknown> | unknown;
+interface ExecuteArgs {
+    /** Validated input matching the contract's `inputSchema` (post-narrowing+mapping). */
+    input: unknown;
+    /** Per-call context, validated against the contract's `contextSchema` when declared. */
+    context: ToolContext;
+    /** Resolved provider state — auth, secrets, sandbox handle, region. */
+    driverCtx: DriverContext;
+    /** Caller-set abort signal — MUST be honoured. */
+    signal: AbortSignal;
+}
+interface DriverContext {
+    /** Resolved secrets keyed by env-var name. Hosts MUST NOT log values. */
+    secrets: Record<string, string>;
+    /** The provider's auth state at dispatch time. */
+    authState: "unknown" | "unauthed" | "authed" | "expired";
+    /** Free-form, namespaced (CLI runtimes stash sandbox handle, HTTP runtimes stash baseUrl, …). */
+    [key: string]: unknown;
+}
+interface AuthConfig {
+    /** Path to a SECRETS.md inventory (AIP-19). */
+    ref?: string;
+    state?: {
+        paths?: readonly string[];
+        env?: readonly string[];
+    };
+    login?: AuthLoginConfig;
+    refresh?: AuthRefreshConfig;
+    expiry?: {
+        detect?: string;
+    };
+}
+interface AuthLoginConfig {
+    cmd?: string;
+    url?: string;
+    interactive?: boolean;
+    requiresCallbackUrl?: boolean;
+    completesWhen?: {
+        cmd?: string;
+        exitCode?: number;
+        http?: {
+            method: string;
+            url: string;
+            expectStatus: number;
+        };
+    };
+}
+interface AuthRefreshConfig {
+    cmd?: string;
+    url?: string;
+    every?: string;
+}
+interface InstallMethod {
+    method: string;
+    package?: string;
+    url?: string;
+    path?: string;
+    extractBin?: string;
+    verifySha256?: string;
+    global?: boolean;
+    user?: boolean;
+}
+interface VersionCheck {
+    cmd: string;
+    parse: string;
+    range: string;
+    timeoutMs?: number;
+}
+interface CostOverride {
+    costClass?: "trivial" | "metered" | "expensive";
+    costUnitsPerCall?: number;
+    currency?: string;
+}
+interface RetryPolicy {
+    maxAttempts: number;
+    backoff?: "fixed" | "exponential";
+    initialMs?: number;
+}
+interface HealthCheckConfig {
+    method: "ping" | "exec" | "http" | "noop";
+    cmd?: string;
+    http?: {
+        method: string;
+        url: string;
+        expectStatus: number;
+    };
+    expectExit?: number;
+    every?: string;
+    timeoutMs?: number;
+}
+interface LoginArgs {
+    context: DriverContext;
+    signal: AbortSignal;
+}
+type LoginResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "user_cancelled" | "callback_failed" | "upstream_error";
+    message?: string;
+};
+interface RefreshArgs {
+    context: DriverContext;
+    signal: AbortSignal;
+}
+type RefreshResult = {
+    ok: true;
+    nextRefreshAt?: string;
+} | {
+    ok: false;
+    reason: "auth_expired" | "upstream_error";
+    message?: string;
+};
+interface ParseOutputArgs {
+    exitCode?: number;
+    stdout: string | Uint8Array;
+    stderr: string;
+    expected: {
+        format: "text" | "json" | "yaml" | "binary";
+    };
+}
+interface ParseOutputResult {
+    ok: boolean;
+    value?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        retryable?: boolean;
+    };
+}
+interface DetectExpiryArgs {
+    exitCode?: number;
+    httpStatus?: number;
+    exception?: {
+        name: string;
+        message: string;
+    };
+    headers?: Record<string, string>;
+}
+/**
+ * Host-registrable provider handle returned by {@link defineDriver}.
+ * Resolver consumes this; kind-specific runtimes wrap their dispatch
+ * around the handle's `execute` map.
+ */
+interface DriverHandle {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly version?: string;
+    readonly kind: DriverKind;
+    readonly implements: readonly ImplementsEntry[];
+    readonly install: readonly InstallMethod[];
+    readonly versionCheck?: VersionCheck;
+    readonly auth?: AuthConfig;
+    readonly network: {
+        egress: readonly string[];
+        ingress: readonly string[];
+    };
+    readonly region: readonly string[];
+    readonly policyTags: readonly string[];
+    readonly costOverride?: CostOverride;
+    readonly timeoutOverrideMs?: number;
+    readonly retryOverride?: RetryPolicy;
+    readonly healthCheck?: HealthCheckConfig;
+    readonly tags: readonly string[];
+    readonly metadata: Record<string, unknown>;
+    /** Execute body for tool id; throws if the id isn't in `implements[]`. */
+    readonly execute: Record<string, ExecuteFn>;
+    /** Optional behavioural adapters. */
+    readonly login?: (args: LoginArgs) => Promise<LoginResult>;
+    readonly refresh?: (args: RefreshArgs) => Promise<RefreshResult>;
+    readonly parseOutput?: (args: ParseOutputArgs) => ParseOutputResult;
+    readonly detectExpiry?: (args: DetectExpiryArgs) => boolean;
+}
+/**
+ * Resolver decision: which provider to dispatch a contract call to.
+ */
+interface ResolverInput {
+    tool: ToolHandle;
+    /** Set of registered providers implementing this tool. */
+    candidates: readonly DriverHandle[];
+    /** Per-call context (workspace policy, region constraint, pinned provider, user). */
+    context: ResolverContext;
+}
+interface ResolverContext {
+    /** Workspace-level policy filter. */
+    policyAllowedTags?: readonly string[];
+    policyForbiddenTags?: readonly string[];
+    /** Region constraint (e.g. "EU"). */
+    regionConstraint?: string;
+    /** Caller-pinned provider id (overrides cost ranking). */
+    pinnedProvider?: string;
+    /** User context for tier-aware routing. */
+    user?: {
+        id?: string;
+        tier?: string;
+    };
+    /** Free-form additional context. */
+    [key: string]: unknown;
+}
+type ResolverResult = {
+    ok: true;
+    provider: DriverHandle;
+    implementsEntry: ImplementsEntry;
+} | {
+    ok: false;
+    error: {
+        code: "no_route" | "pinned_provider_unavailable" | "policy_violation" | "region_mismatch";
+        message: string;
+        rejected?: ReadonlyArray<{
+            providerId: string;
+            phase: number;
+            reason: string;
+        }>;
+    };
+};
+
+export { type AuthConfig as A, type CostOverride as C, type DriverDefinition as D, type ExecuteArgs as E, type HealthCheckConfig as H, type ImplementsEntry as I, type LoginArgs as L, type MappingValue as M, type ParseOutputArgs as P, type ResolverContext as R, type ToolImplementation as T, type VersionCheck as V, type DriverHandle as a, type ResolverResult as b, type AuthLoginConfig as c, type AuthRefreshConfig as d, type DetectExpiryArgs as e, type DriverContext as f, type ExecuteFn as g, type InstallMethod as h, type LoginResult as i, type ParseOutputResult as j, type RefreshArgs as k, type RefreshResult as l, type ResolverInput as m, type RetryPolicy as n, type TypedExecuteFn as o, implementTool as p };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@agentproto/driver",
+  "version": "0.1.1",
+  "description": "agentproto/provider-runtime — reference implementation of AIP-30 DRIVER.md `defineDriver` contract. Resolves multi-provider routing, applies schema-narrowing + mapping, and dispatches contract calls to provider bodies. Composes with @agentproto/tool (AIP-14 contracts) and the kind-specific runtime packages (provider-cli, provider-http, provider-mcp, provider-sdk). Framework adapters (Mastra, AI SDK, …) live in sibling `@agentproto/adapter-*` packages.",
+  "keywords": [
+    "agentproto",
+    "aip-30",
+    "provider",
+    "provider-runtime",
+    "defineDriver",
+    "resolver",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/aip-30",
+  "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": {
+    "gray-matter": "^4.0.3",
+    "zod": "^4.4.3",
+    "@agentproto/define-doctype": "0.1.0",
+    "@agentproto/manifest": "0.2.0",
+    "@agentproto/tool": "0.1.1"
+  },
+  "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"
+  }
+}