@inhuman.tools/harness-provider-sdk 0.0.0-stage → 0.2.0

package/dist/schemas/provider.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Named Zod shapes for provider descriptors, driver rows, and capability
+ * request envelopes. Sole definition home for this package.
+ */
+import { CompletionExpectation } from "@inhuman.tools/harness-model";
+import { type DriverConnectionClass } from "@inhuman.tools/plexus-expectations/driver";
+import { z } from "zod";
+export declare const PROVIDER_SDK_CONTRACT: 1;
+export declare const CAPABILITY_KINDS: readonly ["completion", "mcp", "web-search", "web-extract"];
+export declare const capabilityKindSchema: z.ZodEnum<{
+    completion: "completion";
+    mcp: "mcp";
+    "web-search": "web-search";
+    "web-extract": "web-extract";
+}>;
+export declare const multiplicitySchema: z.ZodEnum<{
+    "add-by-default": "add-by-default";
+    "add-as-secondary": "add-as-secondary";
+}>;
+export declare const driverDefinitionSchema: z.ZodPreprocess<z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    abilityClaim: z.ZodArray<z.ZodEnum<{
+        completion: "completion";
+        mcp: "mcp";
+        "web-search": "web-search";
+        "web-extract": "web-extract";
+    }>>;
+    multiplicity: z.ZodEnum<{
+        "add-by-default": "add-by-default";
+        "add-as-secondary": "add-as-secondary";
+    }>;
+    importPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export declare const providerDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    contract: z.ZodLiteral<1>;
+    drivers: z.ZodArray<z.ZodPreprocess<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        abilityClaim: z.ZodArray<z.ZodEnum<{
+            completion: "completion";
+            mcp: "mcp";
+            "web-search": "web-search";
+            "web-extract": "web-extract";
+        }>>;
+        multiplicity: z.ZodEnum<{
+            "add-by-default": "add-by-default";
+            "add-as-secondary": "add-as-secondary";
+        }>;
+        importPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const driverConnectionClassSchema: z.ZodCustom<DriverConnectionClass, DriverConnectionClass>;
+export declare const registeredDriverInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    abilityClaim: z.ZodArray<z.ZodEnum<{
+        completion: "completion";
+        mcp: "mcp";
+        "web-search": "web-search";
+        "web-extract": "web-extract";
+    }>>;
+    multiplicity: z.ZodEnum<{
+        "add-by-default": "add-by-default";
+        "add-as-secondary": "add-as-secondary";
+    }>;
+    importPath: z.ZodOptional<z.ZodString>;
+    connection: z.ZodCustom<DriverConnectionClass, DriverConnectionClass>;
+}, z.core.$strip>;
+export declare const providerRegistrationSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    contract: z.ZodLiteral<1>;
+    drivers: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        abilityClaim: z.ZodArray<z.ZodEnum<{
+            completion: "completion";
+            mcp: "mcp";
+            "web-search": "web-search";
+            "web-extract": "web-extract";
+        }>>;
+        multiplicity: z.ZodEnum<{
+            "add-by-default": "add-by-default";
+            "add-as-secondary": "add-as-secondary";
+        }>;
+        importPath: z.ZodOptional<z.ZodString>;
+        connection: z.ZodCustom<DriverConnectionClass, DriverConnectionClass>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const completeRequestSchema: z.ZodObject<{
+    connectionId: z.ZodString;
+    model: z.ZodString;
+    promptText: z.ZodOptional<z.ZodString>;
+    messages: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    responseSchemaJson: z.ZodOptional<z.ZodString>;
+    systemNote: z.ZodOptional<z.ZodString>;
+    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+    round: z.ZodCustom<CompletionExpectation, CompletionExpectation>;
+}, z.core.$strip>;
+export declare const mcpCallRequestSchema: z.ZodObject<{
+    connectionId: z.ZodString;
+    serverToolName: z.ZodString;
+    args: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+    onDispatch: z.ZodOptional<z.ZodCustom<() => void, () => void>>;
+}, z.core.$strip>;
+export declare const webSearchRequestSchema: z.ZodObject<{
+    connectionId: z.ZodString;
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+}, z.core.$strip>;
+export declare const webExtractRequestSchema: z.ZodObject<{
+    connectionId: z.ZodString;
+    url: z.ZodString;
+    charLimit: z.ZodOptional<z.ZodNumber>;
+    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+}, z.core.$strip>;
+export declare const capabilityRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"completion">;
+    request: z.ZodObject<{
+        connectionId: z.ZodString;
+        model: z.ZodString;
+        promptText: z.ZodOptional<z.ZodString>;
+        messages: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        responseSchemaJson: z.ZodOptional<z.ZodString>;
+        systemNote: z.ZodOptional<z.ZodString>;
+        signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+        round: z.ZodCustom<CompletionExpectation, CompletionExpectation>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"mcp">;
+    request: z.ZodObject<{
+        connectionId: z.ZodString;
+        serverToolName: z.ZodString;
+        args: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+        onDispatch: z.ZodOptional<z.ZodCustom<() => void, () => void>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"web-search">;
+    request: z.ZodObject<{
+        connectionId: z.ZodString;
+        query: z.ZodString;
+        limit: z.ZodOptional<z.ZodNumber>;
+        signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"web-extract">;
+    request: z.ZodObject<{
+        connectionId: z.ZodString;
+        url: z.ZodString;
+        charLimit: z.ZodOptional<z.ZodNumber>;
+        signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "kind">;
+export declare const AUTH_INTERACTION_KINDS: readonly ["none", "login", "refresh", "logout"];
+export declare const authInteractionKindSchema: z.ZodEnum<{
+    none: "none";
+    login: "login";
+    refresh: "refresh";
+    logout: "logout";
+}>;
+export declare const authInteractionSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        none: "none";
+        login: "login";
+        refresh: "refresh";
+        logout: "logout";
+    }>;
+    connectionId: z.ZodString;
+}, z.core.$strip>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/schemas/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/schemas/provider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,2CAA2C,CAAC;AAChH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAEhD,eAAO,MAAM,gBAAgB,6DAA8D,CAAC;AAE5F,eAAO,MAAM,oBAAoB;;;;;EAA2B,CAAC;AAE7D,eAAO,MAAM,kBAAkB;;;EAAiD,CAAC;AAoBjF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;kBAAyD,CAAC;AAE7F,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;iBAQnC,CAAC;AAEH,eAAO,MAAM,2BAA2B,2DAEtC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;iBAEtC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;iBAErC,CAAC;AAUH,eAAO,MAAM,qBAAqB;;;;;;;;;iBAShC,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;gDAMf,IAAI,QAAJ,IAAI;iBAIpB,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;iBAKjC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;iBAKlC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;oDApBlB,IAAI,QAAJ,IAAI;;;;;;;;;;;;;;;;;;2BA4BpB,CAAC;AAEH,eAAO,MAAM,sBAAsB,iDAAkD,CAAC;AAEtF,eAAO,MAAM,yBAAyB;;;;;EAAiC,CAAC;AAExE,eAAO,MAAM,qBAAqB;;;;;;;;iBAGhC,CAAC"}

package/dist/schemas/provider.js

@@ -0,0 +1,100 @@
+/**
+ * Named Zod shapes for provider descriptors, driver rows, and capability
+ * request envelopes. Sole definition home for this package.
+ */
+import { CompletionExpectation } from "@inhuman.tools/harness-model";
+import { isDriverConnectionClass } from "@inhuman.tools/plexus-expectations/driver";
+import { z } from "zod";
+export const PROVIDER_SDK_CONTRACT = 1;
+export const CAPABILITY_KINDS = ["completion", "mcp", "web-search", "web-extract"];
+export const capabilityKindSchema = z.enum(CAPABILITY_KINDS);
+export const multiplicitySchema = z.enum(["add-by-default", "add-as-secondary"]);
+const nonempty = z.string().trim().min(1, "non-empty string required");
+const driverDefinitionObject = z.object({
+    name: nonempty,
+    description: nonempty,
+    abilityClaim: z.array(capabilityKindSchema).min(1, "driver abilityClaim must name at least one kind"),
+    multiplicity: multiplicitySchema,
+    importPath: nonempty.optional(),
+});
+function liftAbilityClaim(value) {
+    if (value != null && typeof value === "object" && "can" in value && !("abilityClaim" in value)) {
+        const { can, ...rest } = value;
+        return { ...rest, abilityClaim: can };
+    }
+    return value;
+}
+export const driverDefinitionSchema = z.preprocess(liftAbilityClaim, driverDefinitionObject);
+export const providerDescriptorSchema = z.object({
+    id: nonempty,
+    name: nonempty,
+    description: z.string().optional(),
+    contract: z.literal(PROVIDER_SDK_CONTRACT, {
+        error: `contract is incompatible (supported: ${PROVIDER_SDK_CONTRACT})`,
+    }),
+    drivers: z.array(driverDefinitionSchema).min(1, "provider must declare at least one driver"),
+});
+export const driverConnectionClassSchema = z.custom((value) => isDriverConnectionClass(value), {
+    message: "PEW driver connection class required",
+});
+export const registeredDriverInputSchema = driverDefinitionObject.extend({
+    connection: driverConnectionClassSchema,
+});
+export const providerRegistrationSchema = providerDescriptorSchema.extend({
+    drivers: z.array(registeredDriverInputSchema).min(1, "provider must declare at least one driver"),
+});
+const abortSignal = z.custom((value) => value instanceof AbortSignal, {
+    message: "AbortSignal required",
+});
+const completionRound = z.custom((value) => value instanceof CompletionExpectation, {
+    message: "completion round required",
+});
+export const completeRequestSchema = z.object({
+    connectionId: nonempty,
+    model: z.string(),
+    promptText: z.string().optional(),
+    messages: z.array(z.unknown()).optional(),
+    responseSchemaJson: z.string().optional(),
+    systemNote: z.string().optional(),
+    signal: abortSignal.optional(),
+    round: completionRound,
+});
+export const mcpCallRequestSchema = z.object({
+    connectionId: nonempty,
+    serverToolName: nonempty,
+    args: z.record(z.string(), z.unknown()).default({}),
+    signal: abortSignal.optional(),
+    onDispatch: z
+        .custom((value) => typeof value === "function", {
+        message: "JS function required",
+    })
+        .optional(),
+});
+export const webSearchRequestSchema = z.object({
+    connectionId: nonempty,
+    query: nonempty,
+    limit: z.number().optional(),
+    signal: abortSignal.optional(),
+});
+export const webExtractRequestSchema = z.object({
+    connectionId: nonempty,
+    url: nonempty,
+    charLimit: z.number().optional(),
+    signal: abortSignal.optional(),
+});
+export const capabilityRequestSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("completion"), request: completeRequestSchema }),
+    z.object({ kind: z.literal("mcp"), request: mcpCallRequestSchema }),
+    z.object({ kind: z.literal("web-search"), request: webSearchRequestSchema }),
+    z.object({
+        kind: z.literal("web-extract"),
+        request: webExtractRequestSchema,
+    }),
+]);
+export const AUTH_INTERACTION_KINDS = ["none", "login", "refresh", "logout"];
+export const authInteractionKindSchema = z.enum(AUTH_INTERACTION_KINDS);
+export const authInteractionSchema = z.object({
+    kind: authInteractionKindSchema,
+    connectionId: nonempty,
+});
+//# sourceMappingURL=provider.js.map

package/dist/schemas/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/schemas/provider.ts"],"names":[],"mappings":"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"}

package/dist/visuals.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Read seam for stored pictures. The session's picture store belongs to the
+ * daemon; a provider that projects a turn onto its wire reads bytes through
+ * here and never imports the store.
+ */
+/** Bytes of one stored picture, or null when the id is unknown or unreadable. */
+export type VisualReader = (sessionId: string, id: string) => Uint8Array | null;
+/** The host that owns the store binds it once at boot. `null` unbinds. */
+export declare function bindVisualReader(read: VisualReader | null): void;
+/** Null while nothing is bound, so a wire projection names the picture as omitted. */
+export declare function readVisual(sessionId: string, id: string): Uint8Array | null;
+//# sourceMappingURL=visuals.d.ts.map

package/dist/visuals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visuals.d.ts","sourceRoot":"","sources":["../src/visuals.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,UAAU,GAAG,IAAI,CAAC;AAIhF,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAEhE;AAED,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAE3E"}

package/dist/visuals.js

@@ -0,0 +1,15 @@
+/**
+ * Read seam for stored pictures. The session's picture store belongs to the
+ * daemon; a provider that projects a turn onto its wire reads bytes through
+ * here and never imports the store.
+ */
+let reader = null;
+/** The host that owns the store binds it once at boot. `null` unbinds. */
+export function bindVisualReader(read) {
+    reader = read;
+}
+/** Null while nothing is bound, so a wire projection names the picture as omitted. */
+export function readVisual(sessionId, id) {
+    return reader === null ? null : reader(sessionId, id);
+}
+//# sourceMappingURL=visuals.js.map

package/dist/visuals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visuals.js","sourceRoot":"","sources":["../src/visuals.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,IAAI,MAAM,GAAwB,IAAI,CAAC;AAEvC,0EAA0E;AAC1E,MAAM,UAAU,gBAAgB,CAAC,IAAyB;IACxD,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,UAAU,CAAC,SAAiB,EAAE,EAAU;IACtD,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AACxD,CAAC"}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@inhuman.tools/harness-provider-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Driver-provider registration and capability contracts on top of PEW. No vendors, no plugin manifests.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/__tests__"
+  ],
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@inhuman.tools/harness-model": "^0.2.0",
+    "@inhuman.tools/plexus-expectations": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "eslint": "9.39.2",
+    "typescript": "6.0.2",
+    "vitest": "4.1.0",
+    "@-internal-/eslint-configs": "0.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/here-build/inhuman-harness.git",
+    "directory": "packages/harness-provider-sdk"
+  },
+  "browserslist": [
+    "node >= 22"
+  ],
+  "author": "Merkle Bonsai",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.json --noEmit && vitest run"
+  }
 }

package/src/auth.ts

@@ -0,0 +1,11 @@
+/**
+ * Auth interaction shapes. OAuth/OIDC/PKCE live in provider-auth; adopt
+ * helpers stay with the connection registry (D3).
+ */
+import { AUTH_INTERACTION_KINDS } from "./schemas/provider.js";
+
+export type AuthInteractionKind = (typeof AUTH_INTERACTION_KINDS)[number];
+export type AuthInteraction = {
+  readonly kind: AuthInteractionKind;
+  readonly connectionId: string;
+};

package/src/blobs.ts

@@ -0,0 +1,21 @@
+/**
+ * Read seam for stored blobs. The kernel's blob bucket belongs to the daemon;
+ * code that needs a blob's bytes (a provider projecting a wire, a recall tool)
+ * reads them through here and never imports the store. Keys are content hashes,
+ * so there is no session or id to pass: a hash a document names is the whole address.
+ */
+
+/** Bytes of one stored blob, or null when the hash is unknown or unreadable. */
+export type BlobReader = (sha256: string) => Uint8Array | null;
+
+let reader: BlobReader | null = null;
+
+/** The host that owns the bucket binds it once at boot. `null` unbinds. */
+export function bindBlobReader(read: BlobReader | null): void {
+  reader = read;
+}
+
+/** Null while nothing is bound, so a caller falls back to the head the document kept. */
+export function readBlob(sha256: string): Uint8Array | null {
+  return reader === null ? null : reader(sha256);
+}

package/src/capabilities.ts

@@ -0,0 +1,127 @@
+/**
+ * Known capability kinds and request/result envelopes.
+ *
+ * `can` on a driver is these short names (product law). PEW/model kinds stay
+ * the existing Expectation classes — v1 does not invent third-party wire kinds.
+ */
+import type {
+  CompletionExpectation,
+  CompletionMessage,
+  CompletionResult,
+  McpToolResult,
+  WebExtractResult,
+  WebSearchResult,
+} from "@inhuman.tools/harness-model";
+
+import { parseWith } from "./parse.js";
+import { CAPABILITY_KINDS, capabilityKindSchema, capabilityRequestSchema } from "./schemas/provider.js";
+
+export type CapabilityKind = (typeof CAPABILITY_KINDS)[number];
+
+/** Sync tags of the harness-model PEW kinds each `can` token claims. */
+export const CAPABILITY_EXPECTATION = {
+  completion: "harness:expectation:completion",
+  mcp: "harness:expectation:mcp-tool",
+  "web-search": "harness:expectation:web-search",
+  "web-extract": "harness:expectation:web-extract",
+} as const satisfies Record<CapabilityKind, string>;
+
+export const CAPABILITY_METHOD = {
+  completion: "complete",
+  mcp: "callTool",
+  "web-search": "webSearch",
+  "web-extract": "webExtract",
+} as const satisfies Record<CapabilityKind, string>;
+
+export function isCapabilityKind(value: unknown): value is CapabilityKind {
+  return capabilityKindSchema.safeParse(value).success;
+}
+
+export function parseCapabilityKind(value: unknown): CapabilityKind {
+  return parseWith(capabilityKindSchema, value);
+}
+
+export function admitCapability(can: readonly string[], kind: CapabilityKind): boolean {
+  return can.includes(kind);
+}
+
+export type CompleteFields = {
+  readonly model: string;
+  readonly promptText?: string;
+  readonly messages?: CompletionMessage[];
+  readonly responseSchemaJson?: string;
+  readonly systemNote?: string;
+  readonly signal?: AbortSignal;
+  /** Required. Homed on a session plexus. Mutated in place. */
+  readonly round: CompletionExpectation;
+};
+
+export type CompleteRequest = CompleteFields & {
+  readonly connectionId: string;
+};
+export type ConnectionCompleteRequest = CompleteFields;
+export type CompleteResult = CompletionResult;
+
+export type McpCallRequest = {
+  readonly connectionId: string;
+  readonly serverToolName: string;
+  readonly args: Record<string, unknown>;
+  readonly signal?: AbortSignal;
+  readonly onDispatch?: () => void;
+};
+export type ConnectionMcpCallRequest = Omit<McpCallRequest, "connectionId">;
+export type McpCallResult = McpToolResult;
+
+export type WebSearchRequest = {
+  readonly connectionId: string;
+  readonly query: string;
+  readonly limit?: number;
+  readonly signal?: AbortSignal;
+};
+export type ConnectionWebSearchRequest = Omit<WebSearchRequest, "connectionId">;
+export type WebSearchCapabilityResult = WebSearchResult;
+
+export type WebExtractRequest = {
+  readonly connectionId: string;
+  readonly url: string;
+  readonly charLimit?: number;
+  readonly signal?: AbortSignal;
+};
+export type ConnectionWebExtractRequest = Omit<WebExtractRequest, "connectionId">;
+export type WebExtractCapabilityResult = WebExtractResult;
+
+export type CapabilityRequest =
+  | { readonly kind: "completion"; readonly request: CompleteRequest }
+  | { readonly kind: "mcp"; readonly request: McpCallRequest }
+  | { readonly kind: "web-search"; readonly request: WebSearchRequest }
+  | { readonly kind: "web-extract"; readonly request: WebExtractRequest };
+
+export type CapabilityResult =
+  | { readonly kind: "completion"; readonly result: CompleteResult }
+  | { readonly kind: "mcp"; readonly result: McpCallResult }
+  | { readonly kind: "web-search"; readonly result: WebSearchCapabilityResult }
+  | {
+      readonly kind: "web-extract";
+      readonly result: WebExtractCapabilityResult;
+    };
+
+/**
+ * Duck-typed interned connection face. Generic admission uses this, not a
+ * vendor `instanceof`.
+ */
+export type CapabilityConnection = {
+  readonly connectionId: string;
+  complete?(req: ConnectionCompleteRequest): Promise<CompleteResult>;
+  callTool?(req: ConnectionMcpCallRequest): Promise<McpCallResult>;
+  webSearch?(req: ConnectionWebSearchRequest): Promise<WebSearchCapabilityResult>;
+  webExtract?(req: ConnectionWebExtractRequest): Promise<WebExtractCapabilityResult>;
+};
+
+export function parseCapabilityRequest(value: unknown): CapabilityRequest {
+  return parseWith(capabilityRequestSchema, value) as CapabilityRequest;
+}
+
+export function connectionSupports(connection: CapabilityConnection, kind: CapabilityKind): boolean {
+  const method = CAPABILITY_METHOD[kind];
+  return typeof connection[method] === "function";
+}

package/src/descriptor.ts

@@ -0,0 +1,69 @@
+import type { DriverMultiplicity } from "@inhuman.tools/plexus-expectations";
+
+import type { CapabilityKind } from "./capabilities.js";
+import { providerBrand, type ProviderSdkContract } from "./identity.js";
+import { parseWith } from "./parse.js";
+import { PROVIDER_SDK_CONTRACT } from "./schemas/index.js";
+import { providerDescriptorSchema } from "./schemas/provider.js";
+
+export type DriverDefinition = {
+  readonly name: string;
+  readonly description: string;
+  readonly abilityClaim: readonly CapabilityKind[];
+  readonly multiplicity: DriverMultiplicity;
+  readonly importPath: string;
+};
+
+export type ProviderDescriptor = {
+  readonly [providerBrand.descriptor]: true;
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  readonly contract: ProviderSdkContract;
+  readonly drivers: readonly DriverDefinition[];
+};
+
+function freezeDriver(row: {
+  name: string;
+  description: string;
+  abilityClaim: CapabilityKind[];
+  multiplicity: DriverMultiplicity;
+  importPath?: string;
+}): DriverDefinition {
+  return Object.freeze({
+    name: row.name,
+    description: row.description,
+    abilityClaim: Object.freeze([...row.abilityClaim]),
+    multiplicity: row.multiplicity,
+    importPath: row.importPath ?? row.name,
+  });
+}
+
+function rejectDuplicateDrivers(drivers: readonly { name: string }[], context: string): void {
+  const seen = new Set<string>();
+  for (const driver of drivers) {
+    if (seen.has(driver.name)) throw new Error(`${context}: driver "${driver.name}" collides`);
+    seen.add(driver.name);
+  }
+}
+
+export function parseProviderDescriptor(value: unknown): ProviderDescriptor {
+  const parsed = parseWith(providerDescriptorSchema, value);
+  rejectDuplicateDrivers(parsed.drivers, "provider-sdk");
+  return Object.freeze({
+    [providerBrand.descriptor]: true as const,
+    id: parsed.id,
+    name: parsed.name,
+    description: parsed.description ?? "",
+    contract: PROVIDER_SDK_CONTRACT,
+    drivers: Object.freeze(parsed.drivers.map(freezeDriver)),
+  });
+}
+
+export function isProviderDescriptor(value: unknown): value is ProviderDescriptor {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { [k: symbol]: unknown })[providerBrand.descriptor] === true
+  );
+}

package/src/driver.ts

@@ -0,0 +1,12 @@
+import { DriverSpec } from "@inhuman.tools/plexus-expectations";
+
+import type { DriverDefinition } from "./descriptor.js";
+
+/** Declarations fill DriverSpec inventory. Process facts stay untouched. */
+export function applyDriverDefinition(spec: DriverSpec, driver: DriverDefinition): void {
+  spec.name = driver.name;
+  spec.description = driver.description;
+  spec.importPath = driver.importPath;
+  spec.abilityClaim = [...driver.abilityClaim];
+  spec.multiplicity = driver.multiplicity;
+}

package/src/identity.ts

@@ -0,0 +1,14 @@
+import { PROVIDER_SDK_CONTRACT } from "./schemas/provider.js";
+
+/** Process-local brands. Not plugin-sdk InhumanPlugin and not a PEW kind. */
+export const providerBrand = {
+  descriptor: Symbol.for("@inhuman.tools/harness-provider-sdk:descriptor"),
+  registration: Symbol.for("@inhuman.tools/harness-provider-sdk:registration"),
+  driver: Symbol.for("@inhuman.tools/harness-provider-sdk:driver"),
+} as const;
+
+export type ProviderSdkContract = typeof PROVIDER_SDK_CONTRACT;
+
+export function isCompatibleContract(contract: unknown): contract is ProviderSdkContract {
+  return contract === PROVIDER_SDK_CONTRACT;
+}