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

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @inhuman.tools/harness-provider-sdk — driver-provider descriptors,
+ * registration identity, and capability request/result contracts on PEW.
+ *
+ * Not a vendor completion class, not InhumanPlugin, not a plugin loader.
+ */
+
+export type * from "./auth.js";
+export { AUTH_INTERACTION_KINDS as AUTH_INTERACTION_KINDS } from "./schemas/index.js";
+export * from "./blobs.js";
+export * from "./capabilities.js";
+export { CAPABILITY_KINDS as CAPABILITY_KINDS } from "./schemas/index.js";
+export * from "./descriptor.js";
+export * from "./driver.js";
+export * from "./identity.js";
+export { PROVIDER_SDK_CONTRACT as PROVIDER_SDK_CONTRACT } from "./schemas/index.js";
+export * from "./registration.js";
+export * from "./visuals.js";
+export {
+  authInteractionSchema as authInteractionSchema,
+  capabilityKindSchema as capabilityKindSchema,
+  capabilityRequestSchema as capabilityRequestSchema,
+  completeRequestSchema as completeRequestSchema,
+  driverConnectionClassSchema as driverConnectionClassSchema,
+  driverDefinitionSchema as driverDefinitionSchema,
+  mcpCallRequestSchema as mcpCallRequestSchema,
+  multiplicitySchema as multiplicitySchema,
+  providerDescriptorSchema as providerDescriptorSchema,
+  providerRegistrationSchema as providerRegistrationSchema,
+  registeredDriverInputSchema as registeredDriverInputSchema,
+  webExtractRequestSchema as webExtractRequestSchema,
+  webSearchRequestSchema as webSearchRequestSchema,
+} from "./schemas/index.js";

package/src/parse.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export function parseWith<T>(schema: z.ZodType<T>, value: unknown, context = "provider-sdk"): T {
+  const result = schema.safeParse(value);
+  if (result.success) return result.data;
+  const issue = result.error.issues[0];
+  const path = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+  throw new Error(`${context}: ${path}${issue.message}`);
+}

package/src/registration.ts

@@ -0,0 +1,108 @@
+import type { DriverConnectionClass } from "@inhuman.tools/plexus-expectations/driver";
+
+import type { CapabilityKind } from "./capabilities.js";
+import { type DriverDefinition } from "./descriptor.js";
+import { providerBrand, type ProviderSdkContract } from "./identity.js";
+import { parseWith } from "./parse.js";
+import { PROVIDER_SDK_CONTRACT } from "./schemas/index.js";
+import { providerRegistrationSchema } from "./schemas/provider.js";
+
+export type RegisteredDriver = DriverDefinition & {
+  readonly [providerBrand.driver]: true;
+  readonly providerId: string;
+  readonly connection: DriverConnectionClass;
+};
+
+export type RegisteredProvider = {
+  readonly [providerBrand.registration]: true;
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  readonly contract: ProviderSdkContract;
+  readonly drivers: readonly RegisteredDriver[];
+};
+
+function freezeRegisteredDriver(
+  providerId: string,
+  row: {
+    name: string;
+    description: string;
+    abilityClaim: readonly CapabilityKind[];
+    multiplicity: DriverDefinition["multiplicity"];
+    importPath?: string;
+    connection: DriverConnectionClass;
+  },
+): RegisteredDriver {
+  return Object.freeze({
+    [providerBrand.driver]: true as const,
+    providerId,
+    name: row.name,
+    description: row.description,
+    abilityClaim: Object.freeze([...row.abilityClaim]),
+    multiplicity: row.multiplicity,
+    importPath: row.importPath ?? row.name,
+    connection: row.connection,
+  });
+}
+
+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 parseProviderRegistration(value: unknown): RegisteredProvider {
+  const parsed = parseWith(providerRegistrationSchema, value);
+  rejectDuplicateDrivers(parsed.drivers, "provider-sdk");
+  return Object.freeze({
+    [providerBrand.registration]: true as const,
+    id: parsed.id,
+    name: parsed.name,
+    description: parsed.description ?? "",
+    contract: PROVIDER_SDK_CONTRACT,
+    drivers: Object.freeze(parsed.drivers.map((row) => freezeRegisteredDriver(parsed.id, row))),
+  });
+}
+
+/**
+ * Compose a roster. Duplicate provider ids or driver names fail before any
+ * connection is constructed — identity is catalog keys, not intern slots.
+ */
+export function registerProviders(inputs: readonly unknown[]): RegisteredProvider[] {
+  const providers = inputs.map((input) => parseProviderRegistration(input));
+  const providerIds = new Set<string>();
+  const driverNames = new Set<string>();
+  for (const provider of providers) {
+    if (providerIds.has(provider.id)) {
+      throw new Error(`provider-sdk: provider "${provider.id}" collides`);
+    }
+    providerIds.add(provider.id);
+    for (const driver of provider.drivers) {
+      if (driverNames.has(driver.name)) {
+        throw new Error(`provider-sdk: driver "${driver.name}" collides`);
+      }
+      driverNames.add(driver.name);
+    }
+  }
+  return providers;
+}
+
+export function flattenDrivers(providers: readonly RegisteredProvider[]): readonly RegisteredDriver[] {
+  return providers.flatMap((provider) => provider.drivers);
+}
+
+export function isRegisteredProvider(value: unknown): value is RegisteredProvider {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { [k: symbol]: unknown })[providerBrand.registration] === true
+  );
+}
+
+export function isRegisteredDriver(value: unknown): value is RegisteredDriver {
+  return (
+    typeof value === "object" && value !== null && (value as { [k: symbol]: unknown })[providerBrand.driver] === true
+  );
+}

package/src/schemas/index.ts

@@ -0,0 +1 @@
+export * from "./provider.js";

package/src/schemas/provider.ts

@@ -0,0 +1,121 @@
+/**
+ * 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, type DriverConnectionClass } from "@inhuman.tools/plexus-expectations/driver";
+import { z } from "zod";
+
+export const PROVIDER_SDK_CONTRACT = 1 as const;
+
+export const CAPABILITY_KINDS = ["completion", "mcp", "web-search", "web-extract"] as const;
+
+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: unknown): unknown {
+  if (value != null && typeof value === "object" && "can" in value && !("abilityClaim" in value)) {
+    const { can, ...rest } = value as { can: unknown };
+    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<DriverConnectionClass>((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<AbortSignal>((value) => value instanceof AbortSignal, {
+  message: "AbortSignal required",
+});
+
+const completionRound = z.custom<CompletionExpectation>((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<() => void>((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"] as const;
+
+export const authInteractionKindSchema = z.enum(AUTH_INTERACTION_KINDS);
+
+export const authInteractionSchema = z.object({
+  kind: authInteractionKindSchema,
+  connectionId: nonempty,
+});

package/src/visuals.ts

@@ -0,0 +1,20 @@
+/**
+ * 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;
+
+let reader: VisualReader | null = null;
+
+/** The host that owns the store binds it once at boot. `null` unbinds. */
+export function bindVisualReader(read: VisualReader | null): void {
+  reader = read;
+}
+
+/** Null while nothing is bound, so a wire projection names the picture as omitted. */
+export function readVisual(sessionId: string, id: string): Uint8Array | null {
+  return reader === null ? null : reader(sessionId, id);
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.