@codesoul-co/hypha-tools / adapter-factory

• Package index: @codesoul-co/hypha-tools
• Source: packages/tools/src/adapter-factory.ts
• Exports: 17

Using this module

Use the Adapter factory module for binding external or local providers to Hypha ports. It exports 2 classes, 3 constants, 3 functions, 8 interfaces, 1 type.

Import from the package entrypoint

import {
  LoadedToolAdapterProfiles,
  ToolAdapterFactoryRegistry,
  toolAdapterKinds,
  toolAdapterProfileSchema,
  toolAdapterProfilesDocumentSchema,
  loadToolAdapterProfiles,
  parseToolAdapterProfilesDocument,
  registerConcreteToolAdapterFactories,
} from '@codesoul-co/hypha-tools';

import type {
  ConcreteToolAdapterFactoryDependencies,
  LoadedToolAdapterProfile,
  ToolAdapterFactory,
  ToolAdapterFactoryInput,
  ToolAdapterFactoryRegistryOptions,
  ToolAdapterProfile,
  ToolAdapterProfilesDocument,
  ToolSpecReference,
} from '@codesoul-co/hypha-tools';

// The complete export list is documented below.

Usage patterns

• Use the 9 type/interface exports as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.
• The module exposes 2 classes as constructable runtime implementations. Each symbol entry lists its constructor and public methods.
• The module exposes 3 functions as direct operation entrypoints. Every overload, required/optional parameter, and return type is documented below.
• The 3 constant/enum exports provide stable values, schemas, definitions, or defaults. Reuse these exports instead of copying internal values into an application.

Runtime validation example

import { toolAdapterProfileSchema } from '@codesoul-co/hypha-tools';

declare function loadExternalInput(): unknown;
const input: unknown = loadExternalInput();
const parsed = toolAdapterProfileSchema.parse(input);

Parse untrusted configuration, network, or persisted input with the runtime schema before passing it to functions or classes that expect a validated contract.

Public exports

Symbol	Kind	Signature	Description
LoadedToolAdapterProfiles	class	new LoadedToolAdapterProfiles(entries: Map<string, LoadedToolAdapterProfile>): LoadedToolAdapterProfiles	Loaded Tool Adapter Profiles class with 5 public constructor or member entries; its exact declarations are listed below.
ToolAdapterFactoryRegistry	class	new ToolAdapterFactoryRegistry(options: ToolAdapterFactoryRegistryOptions): ToolAdapterFactoryRegistry	Creates adapters from declarative profiles without allowing profiles to smuggle executable factories or plaintext credentials through configuration.
toolAdapterKinds	constant	const toolAdapterKinds: readonly ["local_function", "http", "plugin", "mcp_stdio", "mcp_streamable_http", "execution"]	Tool Adapter Kinds constant exported by the adapter-factory module.
toolAdapterProfileSchema	constant	const toolAdapterProfileSchema: z.ZodEffects<z.ZodObject<{ id: z.ZodString; kind: z.ZodEnum<["local_function", "http", "plugin", "mcp_stdio", "mcp_streamable_http", "execution"]>; required: z.ZodDefault<z.ZodBoolean>; toolSpecRef: z.ZodObject<{ id: z.ZodString; version: z.ZodOptional<z.ZodString>; revision: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { id: string; version?: string | undefined; revision?...	Runtime schema for Tool Adapter Profile.
toolAdapterProfilesDocumentSchema	constant	const toolAdapterProfilesDocumentSchema: z.ZodObject<{ profiles: z.ZodArray<z.ZodEffects<z.ZodObject<{ id: z.ZodString; kind: z.ZodEnum<["local_function", "http", "plugin", "mcp_stdio", "mcp_streamable_http", "execution"]>; required: z.ZodDefault<z.ZodBoolean>; toolSpecRef: z.ZodObject<{ id: z.ZodString; version: z.ZodOptional<z.ZodString>; revision: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { id: str...	Runtime schema for Tool Adapter Profiles Document.
loadToolAdapterProfiles	function	loadToolAdapterProfiles(input: unknown, registry: ToolAdapterFactoryRegistry): Promise<LoadedToolAdapterProfiles>	Load Tool Adapter Profiles function with 1 public call signature; parameters and return types are listed below.
parseToolAdapterProfilesDocument	function	parseToolAdapterProfilesDocument(input: unknown): ToolAdapterProfilesDocument	Parse Tool Adapter Profiles Document function with 1 public call signature; parameters and return types are listed below.
registerConcreteToolAdapterFactories	function	registerConcreteToolAdapterFactories(registry: ToolAdapterFactoryRegistry, dependencies?: ConcreteToolAdapterFactoryDependencies): void	Registers the complete declarative factory surface used by server composition.
ConcreteToolAdapterFactoryDependencies	interface	interface ConcreteToolAdapterFactoryDependencies	Concrete Tool Adapter Factory Dependencies interface with 6 public fields or methods.
LoadedToolAdapterProfile	interface	interface LoadedToolAdapterProfile	Loaded Tool Adapter Profile interface with 5 public fields or methods.
ToolAdapterFactory	interface	interface ToolAdapterFactory	Tool Adapter Factory interface with 2 public fields or methods.
ToolAdapterFactoryInput	interface	interface ToolAdapterFactoryInput	Tool Adapter Factory Input interface with 4 public fields or methods.
ToolAdapterFactoryRegistryOptions	interface	interface ToolAdapterFactoryRegistryOptions	Tool Adapter Factory Registry Options interface with 2 public fields or methods.
ToolAdapterProfile	interface	interface ToolAdapterProfile	Tool Adapter Profile interface with 9 public fields or methods.
ToolAdapterProfilesDocument	interface	interface ToolAdapterProfilesDocument	Tool Adapter Profiles Document interface with 1 public fields or methods.
ToolSpecReference	interface	interface ToolSpecReference	Tool Spec Reference interface with 3 public fields or methods.
ToolAdapterKind	type	type ToolAdapterKind = (typeof toolAdapterKinds)[number]	Public type alias for Tool Adapter Kind; the declaration contains its complete type expression.

LoadedToolAdapterProfiles

Loaded Tool Adapter Profiles class with 5 public constructor or member entries; its exact declarations are listed below.

• Kind: class
• Import: import { LoadedToolAdapterProfiles } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export declare class LoadedToolAdapterProfiles {
    constructor(entries: Map<string, LoadedToolAdapterProfile>);
    list(): LoadedToolAdapterProfile[];
    get(profileId: string): LoadedToolAdapterProfile | undefined;
    health(): Promise<Record<string, Awaited<ReturnType<ToolAdapter['health']>>>>;
    close(): Promise<void>;
}

Public members

Member	Kind	Signature	Description
close	method	close(): Promise<void>	Public method; parameters and return type are shown in the signature.
constructor	constructor	(entries: Map<string, LoadedToolAdapterProfile>): LoadedToolAdapterProfiles	Creates an instance of this class.
get	method	get(profileId: string): LoadedToolAdapterProfile | undefined	Public method; parameters and return type are shown in the signature.
health	method	health(): Promise<Record<string, Awaited<ReturnType<ToolAdapter["health"]>>>>	Public method; parameters and return type are shown in the signature.
list	method	list(): LoadedToolAdapterProfile[]	Public method; parameters and return type are shown in the signature.

ToolAdapterFactoryRegistry

Creates adapters from declarative profiles without allowing profiles to smuggle executable factories or plaintext credentials through configuration.

• Kind: class
• Import: import { ToolAdapterFactoryRegistry } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export declare class ToolAdapterFactoryRegistry {
    constructor(options: ToolAdapterFactoryRegistryOptions);
    register(factory: ToolAdapterFactory): void;
    create(untrustedProfile: ToolAdapterProfile): Promise<{
            profile: ToolAdapterProfile;
            toolSpec: ToolSpec;
            adapter: ToolAdapter;
        }>;
}

Public members

Member	Kind	Signature	Description
constructor	constructor	(options: ToolAdapterFactoryRegistryOptions): ToolAdapterFactoryRegistry	Creates an instance of this class.
create	method	create(untrustedProfile: ToolAdapterProfile): Promise<{ profile: ToolAdapterProfile; toolSpec: ToolSpec; adapter: ToolAdapter; }>	Public method; parameters and return type are shown in the signature.
register	method	register(factory: ToolAdapterFactory): void	Public method; parameters and return type are shown in the signature.

toolAdapterKinds

Tool Adapter Kinds constant exported by the adapter-factory module.

• Kind: constant
• Import: import { toolAdapterKinds } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export declare const toolAdapterKinds: readonly ["local_function", "http", "plugin", "mcp_stdio", "mcp_streamable_http", "execution"];

toolAdapterProfileSchema

Runtime schema for Tool Adapter Profile.

• Kind: constant
• Import: import { toolAdapterProfileSchema } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

// Exact type resolved from the package entrypoint; see source for the compiler expansion.
export declare const toolAdapterProfileSchema: (typeof import('@codesoul-co/hypha-tools'))['toolAdapterProfileSchema'];

This compiler-expanded constant type is compacted. Its public name, top-level type, and source location remain here; use the module’s exported interfaces, types, or runtime schema for input/output fields.

toolAdapterProfilesDocumentSchema

Runtime schema for Tool Adapter Profiles Document.

• Kind: constant
• Import: import { toolAdapterProfilesDocumentSchema } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

// Exact type resolved from the package entrypoint; see source for the compiler expansion.
export declare const toolAdapterProfilesDocumentSchema: (typeof import('@codesoul-co/hypha-tools'))['toolAdapterProfilesDocumentSchema'];

This compiler-expanded constant type is compacted. Its public name, top-level type, and source location remain here; use the module’s exported interfaces, types, or runtime schema for input/output fields.

loadToolAdapterProfiles

Load Tool Adapter Profiles function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { loadToolAdapterProfiles } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export declare function loadToolAdapterProfiles(input: unknown, registry: ToolAdapterFactoryRegistry): Promise<LoadedToolAdapterProfiles>;

Call signature

loadToolAdapterProfiles(input: unknown, registry: ToolAdapterFactoryRegistry): Promise<LoadedToolAdapterProfiles>

Parameters

Parameter	Type	Required	Description
input	unknown	Yes	Required parameter; accepted values are defined by the type column.
registry	ToolAdapterFactoryRegistry	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: Promise<LoadedToolAdapterProfiles>
• Description: The return contract is defined by the type shown above.

parseToolAdapterProfilesDocument

Parse Tool Adapter Profiles Document function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { parseToolAdapterProfilesDocument } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export declare function parseToolAdapterProfilesDocument(input: unknown): ToolAdapterProfilesDocument;

Call signature

parseToolAdapterProfilesDocument(input: unknown): ToolAdapterProfilesDocument

Parameters

Parameter	Type	Required	Description
input	unknown	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: ToolAdapterProfilesDocument
• Description: The return contract is defined by the type shown above.

registerConcreteToolAdapterFactories

Registers the complete declarative factory surface used by server composition.

• Kind: function
• Import: import { registerConcreteToolAdapterFactories } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export declare function registerConcreteToolAdapterFactories(registry: ToolAdapterFactoryRegistry, dependencies?: ConcreteToolAdapterFactoryDependencies): void;

Call signature

registerConcreteToolAdapterFactories(registry: ToolAdapterFactoryRegistry, dependencies?: ConcreteToolAdapterFactoryDependencies): void

Registers the complete declarative factory surface used by server composition.

Parameters

Parameter	Type	Required	Description
registry	ToolAdapterFactoryRegistry	Yes	Required parameter; accepted values are defined by the type column.
dependencies	ConcreteToolAdapterFactoryDependencies	No	Optional parameter; accepted values are defined by the type column.

Returns

• Type: void
• Description: Returns no value.

ConcreteToolAdapterFactoryDependencies

Concrete Tool Adapter Factory Dependencies interface with 6 public fields or methods.

• Kind: interface
• Import: import type { ConcreteToolAdapterFactoryDependencies } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export interface ConcreteToolAdapterFactoryDependencies {
    localFunctions?: Readonly<Record<string, ToolHandler>>;
    plugins?: Readonly<Record<string, ToolHandler>>;
    mcpPort?: MCPToolInvocationPort;
    prepareMCPConnection?(input: ToolAdapterFactoryInput): Promise<{
        port: MCPToolInvocationPort;
        close?(): Promise<void>;
    }>;
    createExecutionAdapter?(input: ToolAdapterFactoryInput): Promise<ToolAdapter>;
    fetch?: typeof fetch;
}

Contract members

Member	Kind	Signature	Description
createExecutionAdapter	method	createExecutionAdapter?(input: ToolAdapterFactoryInput): Promise<ToolAdapter>	Public method; parameters and return type are shown in the signature.
fetch	method	fetch?(input: RequestInfo | URL, init?: RequestInit): Promise<Response> | fetch?(input: string | URL | Request, init?: RequestInit): Promise<Response>	Public method; parameters and return type are shown in the signature.
localFunctions	property	localFunctions?: Readonly<Record<string, ToolHandler>>	Public property; its type, readonly modifier and optionality are shown in the signature.
mcpPort	property	mcpPort?: MCPToolInvocationPort	Public property; its type, readonly modifier and optionality are shown in the signature.
plugins	property	plugins?: Readonly<Record<string, ToolHandler>>	Public property; its type, readonly modifier and optionality are shown in the signature.
prepareMCPConnection	method	prepareMCPConnection?(input: ToolAdapterFactoryInput): Promise<{ port: MCPToolInvocationPort; close?(): Promise<void>; }>	Public method; parameters and return type are shown in the signature.

LoadedToolAdapterProfile

Loaded Tool Adapter Profile interface with 5 public fields or methods.

• Kind: interface
• Import: import type { LoadedToolAdapterProfile } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export interface LoadedToolAdapterProfile {
    profile: ToolAdapterProfile;
    toolSpec?: ToolSpec;
    adapter?: ToolAdapter;
    status: 'ready' | 'degraded';
    error?: string;
}

Contract members

Member	Kind	Signature	Description
adapter	property	adapter?: ToolAdapter<unknown, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
error	property	error?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
profile	property	profile: ToolAdapterProfile	Public property; its type, readonly modifier and optionality are shown in the signature.
status	property	status: "degraded" | "ready"	Public property; its type, readonly modifier and optionality are shown in the signature.
toolSpec	property	toolSpec?: ToolSpec	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolAdapterFactory

Tool Adapter Factory interface with 2 public fields or methods.

• Kind: interface
• Import: import type { ToolAdapterFactory } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export interface ToolAdapterFactory {
    readonly kind: ToolAdapterKind;
    create(input: ToolAdapterFactoryInput): Promise<ToolAdapter>;
}

Contract members

Member	Kind	Signature	Description
create	method	create(input: ToolAdapterFactoryInput): Promise<ToolAdapter>	Public method; parameters and return type are shown in the signature.
kind	property	readonly kind: "http" | "execution" | "plugin" | "local_function" | "mcp_stdio" | "mcp_streamable_http"	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolAdapterFactoryInput

Tool Adapter Factory Input interface with 4 public fields or methods.

• Kind: interface
• Import: import type { ToolAdapterFactoryInput } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export interface ToolAdapterFactoryInput {
    profile: ToolAdapterProfile;
    toolSpec: ToolSpec;
    resolveCredential(): Promise<string | null>;
    acquireCredential(): Promise<CredentialLease | null>;
}

Contract members

Member	Kind	Signature	Description
acquireCredential	method	acquireCredential(): Promise<CredentialLease | null>	Public method; parameters and return type are shown in the signature.
profile	property	profile: ToolAdapterProfile	Public property; its type, readonly modifier and optionality are shown in the signature.
resolveCredential	method	resolveCredential(): Promise<string | null>	Public method; parameters and return type are shown in the signature.
toolSpec	property	toolSpec: ToolSpec	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolAdapterFactoryRegistryOptions

Tool Adapter Factory Registry Options interface with 2 public fields or methods.

• Kind: interface
• Import: import type { ToolAdapterFactoryRegistryOptions } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export interface ToolAdapterFactoryRegistryOptions {
    resolveToolSpec(reference: ToolSpecReference): Promise<ToolSpec | null>;
    secretResolver?: ToolSecretResolver;
}

Contract members

Member	Kind	Signature	Description
resolveToolSpec	method	resolveToolSpec(reference: ToolSpecReference): Promise<ToolSpec | null>	Public method; parameters and return type are shown in the signature.
secretResolver	property	secretResolver?: ToolSecretResolver	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolAdapterProfile

Tool Adapter Profile interface with 9 public fields or methods.

• Kind: interface
• Import: import type { ToolAdapterProfile } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export interface ToolAdapterProfile {
    id: string;
    kind: ToolAdapterKind;
    required?: boolean;
    toolSpecRef: ToolSpecReference;
    endpoint?: string;
    credentialRef?: string;
    requiredCapabilities?: Array<keyof ToolAdapterCapabilities>;
    binding?: {
        localFunctionId?: string;
        pluginId?: string;
        executionPortRef?: string;
        mcpServerId?: string;
        mcpCapabilityId?: string;
        mcpConnectionProfileRef?: string;
    };
    /** @deprecated Use the typed binding object. */
    config?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
binding	property	binding?: { localFunctionId?: string; pluginId?: string; executionPortRef?: string; mcpServerId?: string; mcpCapabilityId?: string; mcpConnectionProfileRef?: string; }	Public property; its type, readonly modifier and optionality are shown in the signature.
config	property	config?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
credentialRef	property	credentialRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
endpoint	property	endpoint?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
id	property	id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
kind	property	kind: "http" | "execution" | "plugin" | "local_function" | "mcp_stdio" | "mcp_streamable_http"	Public property; its type, readonly modifier and optionality are shown in the signature.
required	property	required?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
requiredCapabilities	property	requiredCapabilities?: (keyof ToolAdapterCapabilities)[]	Public property; its type, readonly modifier and optionality are shown in the signature.
toolSpecRef	property	toolSpecRef: ToolSpecReference	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolAdapterProfilesDocument

Tool Adapter Profiles Document interface with 1 public fields or methods.

• Kind: interface
• Import: import type { ToolAdapterProfilesDocument } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export interface ToolAdapterProfilesDocument {
    profiles: ToolAdapterProfile[];
}

Contract members

Member	Kind	Signature	Description
profiles	property	profiles: ToolAdapterProfile[]	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolSpecReference

Tool Spec Reference interface with 3 public fields or methods.

• Kind: interface
• Import: import type { ToolSpecReference } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export interface ToolSpecReference {
    id: string;
    version?: string;
    revision?: string;
}

Contract members

Member	Kind	Signature	Description
id	property	id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
revision	property	revision?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
version	property	version?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolAdapterKind

Public type alias for Tool Adapter Kind; the declaration contains its complete type expression.

• Kind: type
• Import: import type { ToolAdapterKind } from '@codesoul-co/hypha-tools';
• Source module: adapter-factory

Declaration

export type ToolAdapterKind = (typeof toolAdapterKinds)[number];