@codesoul-co/hypha-tools / index

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

Using this module

Aggregates the public entrypoint exports for @codesoul-co/hypha-tools; applications import these symbols from the package entrypoint instead of internal file paths.

Import from the package entrypoint

import {
  AllowAllToolAuthorizer,
  GovernedToolRunner,
  HttpToolAdapter,
  InMemoryToolApprovalStore,
  InMemoryToolInvocationStore,
  InMemoryToolResultCache,
  LocalFunctionToolAdapter,
  MCPToolAdapter,
} from '@codesoul-co/hypha-tools';

import type {
  AdapterCancellationRequest,
  AdapterExecutionRequest,
  HttpToolAdapterOptions,
  InMemoryToolResultCacheOptions,
  MCPToolInvocationPort,
  RedisLikeToolResultCacheClient,
  RedisToolResultCacheOptions,
  ToolAdapter,
} from '@codesoul-co/hypha-tools';

// The complete export list is documented below.

Usage patterns

• Use the 51 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 17 classes as constructable runtime implementations. Each symbol entry lists its constructor and public methods.
• The module exposes 5 functions as direct operation entrypoints. Every overload, required/optional parameter, and return type is documented below.
• The 12 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 { toolCacheValidityRecordSchema } from '@codesoul-co/hypha-tools';

declare function loadExternalInput(): unknown;
const input: unknown = loadExternalInput();
const parsed = toolCacheValidityRecordSchema.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
AllowAllToolAuthorizer	class	new AllowAllToolAuthorizer(): AllowAllToolAuthorizer	Allow All Tool Authorizer class with 2 public constructor or member entries; its exact declarations are listed below.
GovernedToolRunner	class	new GovernedToolRunner(registry: ToolRegistry, trace: TraceRecorder, policy?: PolicyEngine, options?: { approvalStore?: ToolApprovalStore; invocationStore?: ToolInvocationStore; authorizer?: ToolAuthorizer; middleware?: ToolMiddleware[]; artifactPort?: ToolArtifactPort; snapshotStore?: ToolContractSnapshotStore; receiptReconciler?: ToolReceiptReconciler; resultCache?: ToolResultCache; resultCacheFailureMode?: "byp...	Governed Tool Runner class with 8 public constructor or member entries; its exact declarations are listed below.
HttpToolAdapter	class	new HttpToolAdapter(id: string, options: HttpToolAdapterOptions): HttpToolAdapter	Http Tool Adapter class with 7 public constructor or member entries; its exact declarations are listed below.
InMemoryToolApprovalStore	class	new InMemoryToolApprovalStore(): InMemoryToolApprovalStore	In Memory Tool Approval Store class with 6 public constructor or member entries; its exact declarations are listed below.
InMemoryToolInvocationStore	class	new InMemoryToolInvocationStore(): InMemoryToolInvocationStore	In Memory Tool Invocation Store class with 8 public constructor or member entries; its exact declarations are listed below.
InMemoryToolResultCache	class	new InMemoryToolResultCache(options?: InMemoryToolResultCacheOptions): InMemoryToolResultCache	In Memory Tool Result Cache class with 5 public constructor or member entries; its exact declarations are listed below.
LocalFunctionToolAdapter	class	new LocalFunctionToolAdapter<TInput = unknown, TOutput = unknown>(id: string, handler: ToolHandler<TInput, TOutput>): LocalFunctionToolAdapter<TInput, TOutput>	Local Function Tool Adapter class with 6 public constructor or member entries; its exact declarations are listed below.
MCPToolAdapter	class	new MCPToolAdapter(id: string, serverId: string, capabilityId: string, gateway: MCPToolInvocationPort): MCPToolAdapter	MCP Tool Adapter class with 7 public constructor or member entries; its exact declarations are listed below.
MockToolAdapter	class	new MockToolAdapter<TInput = unknown, TOutput = unknown>(id: string, handler: ToolHandler<TInput, TOutput>): MockToolAdapter<TInput, TOutput>	Mock Tool Adapter class with 6 public constructor or member entries; its exact declarations are listed below.
MockToolRunner	class	new MockToolRunner(defaultOutput?: unknown): MockToolRunner	Mock Tool Runner class with 4 public constructor or member entries; its exact declarations are listed below.
PermissionScopeToolAuthorizer	class	new PermissionScopeToolAuthorizer(): PermissionScopeToolAuthorizer	Permission Scope Tool Authorizer class with 2 public constructor or member entries; its exact declarations are listed below.
PluginToolAdapter	class	new PluginToolAdapter<TInput = unknown, TOutput = unknown>(id: string, handler: ToolHandler<TInput, TOutput>): PluginToolAdapter<TInput, TOutput>	Plugin Tool Adapter class with 6 public constructor or member entries; its exact declarations are listed below.
RedisToolResultCache	class	new RedisToolResultCache(options: RedisToolResultCacheOptions): RedisToolResultCache	Shared Redis-compatible Store for local, self-hosted, and managed Redis deployments.
ToolRegistry	class	new ToolRegistry(): ToolRegistry	Tool Registry class with 9 public constructor or member entries; its exact declarations are listed below.
ToolResultCacheEntryTooLargeError	class	new ToolResultCacheEntryTooLargeError(actualBytes: number, maxEntryBytes: number): ToolResultCacheEntryTooLargeError	Tool Result Cache Entry Too Large Error class with 11 public constructor or member entries; its exact declarations are listed below.
ToolResultCacheOperationTimeoutError	class	new ToolResultCacheOperationTimeoutError(operation: "get" | "set" | "delete" | "verify", timeoutMs: number): ToolResultCacheOperationTimeoutError	Tool Result Cache Operation Timeout Error class with 11 public constructor or member entries; its exact declarations are listed below.
ToolResultCacheValidationError	class	new ToolResultCacheValidationError(message: string): ToolResultCacheValidationError	Tool Result Cache Validation Error class with 9 public constructor or member entries; its exact declarations are listed below.
TOOL_INVOCATION_STATUSES	constant	const TOOL_INVOCATION_STATUSES: readonly ["created", "validating", "validated", "policy_checked", "waiting_approval", "approved", "rejected", "queued", "running", "cancelling", "completed", "failed", "timed_out", "expired", "conflict", "denied", "cancelled"]	TOOL INVOCATION STATUSES constant exported by the index module.
toolCacheValidityRecordSchema	constant	const toolCacheValidityRecordSchema: z.ZodObject<{ toolId: z.ZodString; toolRevision: z.ZodString; inputHash: z.ZodString; scopeHash: z.ZodString; policyRevision: z.ZodString; contractSnapshotHash: z.ZodOptional<z.ZodString>; capabilityHash: z.ZodOptional<z.ZodString>; externalStateVersion: z.ZodOptional<z.ZodString>; key: z.ZodString; validUntil: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { toolId: st...	Runtime schema for Tool Cache Validity Record.
toolProfileSpecDefinition	constant	const toolProfileSpecDefinition: SpecSchemaDefinition<ToolProfileSpec>	Runtime validation entrypoint for the Tool Profile spec, combining its parser, example and JSON Schema.
toolProfileSpecSchema	constant	const toolProfileSpecSchema: z.ZodObject<{ id: z.ZodString; version: z.ZodString; revision: z.ZodOptional<z.ZodString>; toolRefs: z.ZodArray<z.ZodObject<{ id: z.ZodString; version: z.ZodOptional<z.ZodString>; revision: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { id: string; revision?: string | undefined; version?: string | undefined; }, { id: string; revision?: string | undefined; version?: string | un...	Runtime schema for Tool Profile Spec.
toolResultCacheEntryJsonSchema	constant	const toolResultCacheEntryJsonSchema: JsonSchema	JSON Schema for Tool Result Cache Entry.
toolResultCacheEntrySchema	constant	const toolResultCacheEntrySchema: z.ZodObject<{ schemaVersion: z.ZodLiteral<"1.0">; keyVersion: z.ZodLiteral<"1">; validity: z.ZodObject<{ toolId: z.ZodString; toolRevision: z.ZodString; inputHash: z.ZodString; scopeHash: z.ZodString; policyRevision: z.ZodString; contractSnapshotHash: z.ZodOptional<z.ZodString>; capabilityHash: z.ZodOptional<z.ZodString>; externalStateVersion: z.ZodOptional<z.ZodString>; key: z.Zo...	Runtime schema for Tool Result Cache Entry.
toolSpecDefinition	constant	const toolSpecDefinition: SpecSchemaDefinition<ToolSpec>	Runtime validation entrypoint for the Tool spec, combining its parser, example and JSON Schema.
toolSpecDefinitions	constant	const toolSpecDefinitions: readonly [SpecSchemaDefinition<ToolSpec>, SpecSchemaDefinition<ToolProfileSpec>]	Tool Spec Definitions constant exported by the index module.
toolSpecExample	constant	const toolSpecExample: ToolSpec	Valid example value for Tool Spec.
toolSpecJsonSchema	constant	const toolSpecJsonSchema: JsonSchema	JSON Schema for Tool Spec.
toolSpecJsonSchemas	constant	const toolSpecJsonSchemas: Record<string, JsonSchema>	Tool Spec JSON Schemas constant exported by the index module.
toolSpecSchema	constant	const toolSpecSchema: z.ZodObject<{ id: z.ZodString; version: z.ZodString; revision: z.ZodOptional<z.ZodString>; name: z.ZodOptional<z.ZodString>; displayName: z.ZodOptional<z.ZodString>; description: z.ZodString; instructions: z.ZodOptional<z.ZodString>; tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; inputSchema: z.ZodType<JsonSchema, z.ZodTypeDef, JsonSchema>; outputSchema: z.ZodOptional<z.ZodType<JsonSch...	Runtime schema for Tool Spec.
normalizeToolSpec	function	normalizeToolSpec(spec: ToolSpec): ResolvedToolSpec	Normalize Tool Spec function with 1 public call signature; parameters and return types are listed below.
validateEffectiveCapabilityAccess	function	validateEffectiveCapabilityAccess(input: { snapshot: ToolContractSnapshot | null; context: ToolCallContext; spec: ToolSpec; }): string | null	Validate Effective Capability Access function with 1 public call signature; parameters and return types are listed below.
validateToolInput	function	validateToolInput(schema: JsonSchema, input: unknown): ToolSchemaValidationResult	Validate Tool Input function with 1 public call signature; parameters and return types are listed below.
validateToolResultCacheEntry	function	validateToolResultCacheEntry(value: unknown, maxEntryBytes?: number): ToolResultCacheEntry	Validate Tool Result Cache Entry function with 1 public call signature; parameters and return types are listed below.
validateToolSpec	function	validateToolSpec(input: unknown): ToolSpec	Validate Tool Spec function with 1 public call signature; parameters and return types are listed below.
AdapterCancellationRequest	interface	interface AdapterCancellationRequest	Adapter Cancellation Request interface with 3 public fields or methods.
AdapterExecutionRequest	interface	interface AdapterExecutionRequest	Adapter Execution Request interface with 3 public fields or methods.
HttpToolAdapterOptions	interface	interface HttpToolAdapterOptions	Http Tool Adapter Options interface with 4 public fields or methods.
InMemoryToolResultCacheOptions	interface	interface InMemoryToolResultCacheOptions	In Memory Tool Result Cache Options interface with 2 public fields or methods.
MCPToolInvocationPort	interface	interface MCPToolInvocationPort	MCP Tool Invocation Port interface with 3 public fields or methods.
RedisLikeToolResultCacheClient	interface	interface RedisLikeToolResultCacheClient	Redis Like Tool Result Cache Client interface with 3 public fields or methods.
RedisToolResultCacheOptions	interface	interface RedisToolResultCacheOptions	Redis Tool Result Cache Options interface with 5 public fields or methods.
ToolAdapter	interface	interface ToolAdapter	Tool Adapter interface with 7 public fields or methods.
ToolAdapterCapabilities	interface	interface ToolAdapterCapabilities	Tool Adapter Capabilities interface with 5 public fields or methods.
ToolApprovalGrant	interface	interface ToolApprovalGrant	Tool Approval Grant interface with 11 public fields or methods.
ToolApprovalRequest	interface	interface ToolApprovalRequest	Tool Approval Request interface with 15 public fields or methods.
ToolApprovalStore	interface	interface ToolApprovalStore	Tool Approval Store interface with 5 public fields or methods.
ToolArtifactPort	interface	interface ToolArtifactPort	Tool Artifact Port interface with 1 public fields or methods.
ToolAuthorizationDecision	interface	interface ToolAuthorizationDecision	Tool Authorization Decision interface with 3 public fields or methods.
ToolAuthorizationInput	interface	interface ToolAuthorizationInput	Tool Authorization Input interface with 4 public fields or methods.
ToolAuthorizer	interface	interface ToolAuthorizer	Tool Authorizer interface with 1 public fields or methods.
ToolCachedResultProjection	interface	interface ToolCachedResultProjection	Only stable, replay-safe output fields may cross invocation boundaries.
ToolCallContext	interface	interface ToolCallContext	Tool Call Context interface with 24 public fields or methods.
ToolCallError	interface	interface ToolCallError	Tool Call Error interface with 5 public fields or methods.
ToolCallRequest	interface	interface ToolCallRequest	Tool Call Request interface with 3 public fields or methods.
ToolCallResult	interface	interface ToolCallResult	Tool Call Result interface with 12 public fields or methods.
ToolExecutionEnvelope	interface	interface ToolExecutionEnvelope	Tool Execution Envelope interface with 7 public fields or methods.
ToolExecutionScope	interface	interface ToolExecutionScope	Tool Execution Scope interface with 3 public fields or methods.
ToolIdempotencyLookup	interface	interface ToolIdempotencyLookup	Tool Idempotency Lookup interface with 3 public fields or methods.
ToolInvocationListRequest	interface	interface ToolInvocationListRequest	Tool Invocation List Request interface with 4 public fields or methods.
ToolInvocationRecord	interface	interface ToolInvocationRecord	Tool Invocation Record interface with 37 public fields or methods.
ToolInvocationStore	interface	interface ToolInvocationStore	Tool Invocation Store interface with 7 public fields or methods.
ToolMiddleware	interface	interface ToolMiddleware	Tool Middleware interface with 5 public fields or methods.
ToolMiddlewareContext	interface	interface ToolMiddlewareContext	Tool Middleware Context interface with 5 public fields or methods.
ToolObservationPort	interface	interface ToolObservationPort	Tool Observation Port interface with 1 public fields or methods.
ToolPrincipal	interface	interface ToolPrincipal	Tool Principal interface with 13 public fields or methods.
ToolProfileSpec	interface	interface ToolProfileSpec extends VersionedSpec	Tool Profile Spec interface with 11 public fields or methods.
ToolProgressUpdate	interface	interface ToolProgressUpdate	Tool Progress Update interface with 6 public fields or methods.
ToolReceiptReconciler	interface	interface ToolReceiptReconciler	Tool Receipt Reconciler interface with 1 public fields or methods.
ToolReceiptReconciliation	interface	interface ToolReceiptReconciliation	Tool Receipt Reconciliation interface with 3 public fields or methods.
ToolResultCache	interface	interface ToolResultCache	Tool Result Cache interface with 3 public fields or methods.
ToolResultCacheArtifactVerifier	interface	interface ToolResultCacheArtifactVerifier	Tool Result Cache Artifact Verifier interface with 1 public fields or methods.
ToolResultCacheEntry	interface	interface ToolResultCacheEntry	Tool Result Cache Entry interface with 5 public fields or methods.
ToolRunner	interface	interface ToolRunner	Tool Runner interface with 2 public fields or methods.
ToolSchemaValidationIssue	interface	interface ToolSchemaValidationIssue	Tool Schema Validation Issue interface with 2 public fields or methods.
ToolSchemaValidationResult	interface	interface ToolSchemaValidationResult	Tool Schema Validation Result interface with 3 public fields or methods.
ToolSpec	interface	interface ToolSpec	Tool Spec interface with 33 public fields or methods.
ToolTargetResolution	interface	interface ToolTargetResolution	Tool Target Resolution interface with 3 public fields or methods.
ToolTargetResolver	interface	interface ToolTargetResolver	Tool Target Resolver interface with 1 public fields or methods.
MockToolHandler	type	type MockToolHandler = (request: ToolCallRequest) => Promise<ToolCallResult> | ToolCallResult	Public type alias for Mock Tool Handler; the declaration contains its complete type expression.
ResolvedToolSpec	type	type ResolvedToolSpec = ToolSpec & GovernedToolContractSpec	Public type alias for Resolved Tool Spec; the declaration contains its complete type expression.
ToolExecutionPhase	type	type ToolExecutionPhase = 'resolution' | 'authorization' | 'input_validation' | 'policy' | 'approval' | 'execution' | 'timeout' | 'output_validation'	Public type alias for Tool Execution Phase; the declaration contains its complete type expression.
ToolHandler	type	type ToolHandler = (input: TInput, context: ToolCallContext) => Promise<TOutput>	Public type alias for Tool Handler; the declaration contains its complete type expression.
ToolInvocationPatch	type	type ToolInvocationPatch = Partial<Pick<ToolInvocationRecord, 'status' | 'executionCycle' | 'attemptCount' | 'result' | 'approvalRequest' | 'updatedAt' | 'startedAt' | 'completedAt' | 'lateResultState' | 'outputHash' | 'artifactRefs' | 'observationRefs' | 'externalReceipt'>>	Public type alias for Tool Invocation Patch; the declaration contains its complete type expression.
ToolInvocationStatus	type	type ToolInvocationStatus = (typeof TOOL_INVOCATION_STATUSES)[number]	Public type alias for Tool Invocation Status; the declaration contains its complete type expression.
ToolResultContent	type	type ToolResultContent = { type: 'text'; text: string; } | { type: 'json'; value: unknown; } | { type: 'image'; artifactRef?: string; url?: string; mimeType?: string; alt?: string; } | { type: 'resource'; uri: string; mimeType?: string; title?: string; } | { type: 'artifact'; artifactRef: string; title?: string; mimeType?: string; }	Public type alias for Tool Result Content; the declaration contains its complete type expression.

AllowAllToolAuthorizer

Allow All Tool Authorizer class with 2 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class AllowAllToolAuthorizer implements ToolAuthorizer {
    authorize(): Promise<ToolAuthorizationDecision>;
}

Public members

Member	Kind	Signature	Description
authorize	method	authorize(): Promise<ToolAuthorizationDecision>	Public method; parameters and return type are shown in the signature.
constructor	constructor	(): AllowAllToolAuthorizer	Creates an instance of this class.

GovernedToolRunner

Governed Tool Runner class with 8 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class GovernedToolRunner implements ToolRunner {
    constructor(registry: ToolRegistry, trace: TraceRecorder, policy?: PolicyEngine, options?: {
            approvalStore?: ToolApprovalStore;
            invocationStore?: ToolInvocationStore;
            authorizer?: ToolAuthorizer;
            middleware?: ToolMiddleware[];
            artifactPort?: ToolArtifactPort;
            snapshotStore?: ToolContractSnapshotStore;
            receiptReconciler?: ToolReceiptReconciler;
            resultCache?: ToolResultCache;
            resultCacheFailureMode?: 'bypass' | 'strict';
            resultCacheTimeoutMs?: number;
            resultCacheMaxEntryBytes?: number;
            resultCacheArtifactVerifier?: ToolResultCacheArtifactVerifier;
            observationPort?: ToolObservationPort;
            telemetry?: TelemetryRecorder;
            now?: () => string;
        });
    getInvocation(invocationId: string): Promise<ToolInvocationRecord | null>;
    listInvocations(request?: ToolInvocationListRequest): Promise<ToolInvocationRecord[]>;
    recoverPendingInvocations(): Promise<ToolCallResult[]>;
    run(request: ToolCallRequest): Promise<ToolCallResult>;
    approveAndResume(invocationId: string, approvedBy: string, options?: {
            approvedAt?: string;
            expiresAt?: string;
        }): Promise<ToolCallResult>;
    rejectInvocation(invocationId: string): Promise<ToolCallResult>;
    cancelInvocation(invocationId: string, reason?: string): Promise<ToolCallResult>;
}

Public members

Member	Kind	Signature	Description
approveAndResume	method	approveAndResume(invocationId: string, approvedBy: string, options?: { approvedAt?: string; expiresAt?: string; }): Promise<ToolCallResult>	Public method; parameters and return type are shown in the signature.
cancelInvocation	method	cancelInvocation(invocationId: string, reason?: string): Promise<ToolCallResult>	Public method; parameters and return type are shown in the signature.
constructor	constructor	(registry: ToolRegistry, trace: TraceRecorder, policy?: PolicyEngine, options?: { approvalStore?: ToolApprovalStore; invocationStore?: ToolInvocationStore; authorizer?: ToolAuthorizer; middleware?: ToolMiddleware[]; artifactPort?: ToolArtifactPort; snapshotStore?: ToolContractSnapshotStore; receiptReconciler?: ToolReceiptReconciler; resultCache?: ToolResultCache; resultCacheFailureMode?: "bypass" | "strict"; resul...	Creates an instance of this class.
getInvocation	method	getInvocation(invocationId: string): Promise<ToolInvocationRecord | null>	Public method; parameters and return type are shown in the signature.
listInvocations	method	listInvocations(request?: ToolInvocationListRequest): Promise<ToolInvocationRecord[]>	Public method; parameters and return type are shown in the signature.
recoverPendingInvocations	method	recoverPendingInvocations(): Promise<ToolCallResult[]>	Public method; parameters and return type are shown in the signature.
rejectInvocation	method	rejectInvocation(invocationId: string): Promise<ToolCallResult>	Public method; parameters and return type are shown in the signature.
run	method	run(request: ToolCallRequest): Promise<ToolCallResult>	Public method; parameters and return type are shown in the signature.

HttpToolAdapter

Http Tool Adapter class with 7 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class HttpToolAdapter implements ToolAdapter {
    readonly id: string;
    readonly source: ToolSource;
    constructor(id: string, options: HttpToolAdapterOptions);
    capabilities(): Promise<ToolAdapterCapabilities>;
    execute(request: AdapterExecutionRequest): Promise<ToolExecutionEnvelope>;
    cancel(): Promise<void>;
    health(): Promise<ProviderHealth>;
}

Public members

Member	Kind	Signature	Description
cancel	method	cancel(): Promise<void>	Public method; parameters and return type are shown in the signature.
capabilities	method	capabilities(): Promise<ToolAdapterCapabilities>	Public method; parameters and return type are shown in the signature.
constructor	constructor	(id: string, options: HttpToolAdapterOptions): HttpToolAdapter	Creates an instance of this class.
execute	method	execute(request: AdapterExecutionRequest): Promise<ToolExecutionEnvelope>	Public method; parameters and return type are shown in the signature.
health	method	health(): Promise<ProviderHealth>	Public method; parameters and return type are shown in the signature.
id	property	readonly id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
source	property	readonly source: ToolSource	Public property; its type, readonly modifier and optionality are shown in the signature.

InMemoryToolApprovalStore

In Memory Tool Approval Store class with 6 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class InMemoryToolApprovalStore implements ToolApprovalStore {
    getRequest(invocationId: string): Promise<ToolApprovalRequest | null>;
    requestApproval(request: ToolApprovalRequest): Promise<ToolApprovalRequest>;
    getGrant(invocationId: string): Promise<ToolApprovalGrant | null>;
    approve(invocationId: string, approvedBy: string, options?: {
            approvedAt?: string;
            expiresAt?: string;
        }): Promise<ToolApprovalGrant>;
    reject(invocationId: string): Promise<ToolApprovalRequest>;
}

Public members

Member	Kind	Signature	Description
approve	method	approve(invocationId: string, approvedBy: string, options?: { approvedAt?: string; expiresAt?: string; }): Promise<ToolApprovalGrant>	Public method; parameters and return type are shown in the signature.
constructor	constructor	(): InMemoryToolApprovalStore	Creates an instance of this class.
getGrant	method	getGrant(invocationId: string): Promise<ToolApprovalGrant | null>	Public method; parameters and return type are shown in the signature.
getRequest	method	getRequest(invocationId: string): Promise<ToolApprovalRequest | null>	Public method; parameters and return type are shown in the signature.
reject	method	reject(invocationId: string): Promise<ToolApprovalRequest>	Public method; parameters and return type are shown in the signature.
requestApproval	method	requestApproval(request: ToolApprovalRequest): Promise<ToolApprovalRequest>	Public method; parameters and return type are shown in the signature.

InMemoryToolInvocationStore

In Memory Tool Invocation Store class with 8 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class InMemoryToolInvocationStore implements ToolInvocationStore {
    get(invocationId: string): Promise<ToolInvocationRecord | null>;
    findByIdempotency(request: ToolIdempotencyLookup): Promise<ToolInvocationRecord | null>;
    list(request?: ToolInvocationListRequest): Promise<ToolInvocationRecord[]>;
    create(record: ToolInvocationRecord): Promise<ToolInvocationRecord>;
    update(invocationId: string, patch: ToolInvocationPatch, options?: {
            expectedStatuses?: readonly ToolInvocationStatus[];
            expectedRevision?: number;
        }): Promise<ToolInvocationRecord>;
    getCompleted(invocationId: string): Promise<ToolCallResult | null>;
    saveCompleted(invocationId: string, result: ToolCallResult): Promise<void>;
}

Public members

Member	Kind	Signature	Description
constructor	constructor	(): InMemoryToolInvocationStore	Creates an instance of this class.
create	method	create(record: ToolInvocationRecord): Promise<ToolInvocationRecord>	Public method; parameters and return type are shown in the signature.
findByIdempotency	method	findByIdempotency(request: ToolIdempotencyLookup): Promise<ToolInvocationRecord | null>	Public method; parameters and return type are shown in the signature.
get	method	get(invocationId: string): Promise<ToolInvocationRecord | null>	Public method; parameters and return type are shown in the signature.
getCompleted	method	getCompleted(invocationId: string): Promise<ToolCallResult | null>	Public method; parameters and return type are shown in the signature.
list	method	list(request?: ToolInvocationListRequest): Promise<ToolInvocationRecord[]>	Public method; parameters and return type are shown in the signature.
saveCompleted	method	saveCompleted(invocationId: string, result: ToolCallResult): Promise<void>	Public method; parameters and return type are shown in the signature.
update	method	update(invocationId: string, patch: ToolInvocationPatch, options?: { expectedStatuses?: readonly ToolInvocationStatus[]; expectedRevision?: number; }): Promise<ToolInvocationRecord>	Public method; parameters and return type are shown in the signature.

InMemoryToolResultCache

In Memory Tool Result Cache class with 5 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class InMemoryToolResultCache implements ToolResultCache {
    constructor(options?: InMemoryToolResultCacheOptions);
    get(key: string): Promise<ToolResultCacheEntry | null>;
    set(entry: ToolResultCacheEntry): Promise<void>;
    delete(key: string): Promise<void>;
    size(): number;
}

Public members

Member	Kind	Signature	Description
constructor	constructor	(options?: InMemoryToolResultCacheOptions): InMemoryToolResultCache	Creates an instance of this class.
delete	method	delete(key: string): Promise<void>	Public method; parameters and return type are shown in the signature.
get	method	get(key: string): Promise<ToolResultCacheEntry | null>	Public method; parameters and return type are shown in the signature.
set	method	set(entry: ToolResultCacheEntry): Promise<void>	Public method; parameters and return type are shown in the signature.
size	method	size(): number	Public method; parameters and return type are shown in the signature.

LocalFunctionToolAdapter

Local Function Tool Adapter class with 6 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class LocalFunctionToolAdapter<TInput = unknown, TOutput = unknown> implements ToolAdapter<TInput, TOutput> {
    readonly id: string;
    readonly source: ToolSource;
    constructor(id: string, handler: ToolHandler<TInput, TOutput>);
    capabilities(): Promise<ToolAdapterCapabilities>;
    execute(request: AdapterExecutionRequest<TInput>): Promise<ToolExecutionEnvelope<TOutput>>;
    health(): Promise<ProviderHealth>;
}

Public members

Member	Kind	Signature	Description
capabilities	method	capabilities(): Promise<ToolAdapterCapabilities>	Public method; parameters and return type are shown in the signature.
constructor	constructor	<TInput = unknown, TOutput = unknown>(id: string, handler: ToolHandler<TInput, TOutput>): LocalFunctionToolAdapter<TInput, TOutput>	Creates an instance of this class.
execute	method	execute(request: AdapterExecutionRequest<TInput>): Promise<ToolExecutionEnvelope<TOutput>>	Public method; parameters and return type are shown in the signature.
health	method	health(): Promise<ProviderHealth>	Public method; parameters and return type are shown in the signature.
id	property	readonly id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
source	property	readonly source: ToolSource	Public property; its type, readonly modifier and optionality are shown in the signature.

MCPToolAdapter

MCP Tool Adapter class with 7 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class MCPToolAdapter implements ToolAdapter {
    readonly id: string;
    readonly source: ToolSource;
    constructor(id: string, serverId: string, capabilityId: string, gateway: MCPToolInvocationPort);
    capabilities(): Promise<ToolAdapterCapabilities>;
    execute(request: AdapterExecutionRequest): Promise<ToolExecutionEnvelope>;
    cancel(request: AdapterCancellationRequest): Promise<void>;
    health(): Promise<ProviderHealth>;
}

Public members

Member	Kind	Signature	Description
cancel	method	cancel(request: AdapterCancellationRequest): Promise<void>	Public method; parameters and return type are shown in the signature.
capabilities	method	capabilities(): Promise<ToolAdapterCapabilities>	Public method; parameters and return type are shown in the signature.
constructor	constructor	(id: string, serverId: string, capabilityId: string, gateway: MCPToolInvocationPort): MCPToolAdapter	Creates an instance of this class.
execute	method	execute(request: AdapterExecutionRequest): Promise<ToolExecutionEnvelope>	Public method; parameters and return type are shown in the signature.
health	method	health(): Promise<ProviderHealth>	Public method; parameters and return type are shown in the signature.
id	property	readonly id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
source	property	readonly source: ToolSource	Public property; its type, readonly modifier and optionality are shown in the signature.

MockToolAdapter

Mock Tool Adapter class with 6 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class MockToolAdapter<TInput = unknown, TOutput = unknown> extends LocalFunctionToolAdapter<TInput, TOutput> {
    readonly source: ToolSource;
}

Public members

Member	Kind	Signature	Description
capabilities	method	capabilities(): Promise<ToolAdapterCapabilities>	Public method; parameters and return type are shown in the signature.
constructor	constructor	<TInput = unknown, TOutput = unknown>(id: string, handler: ToolHandler<TInput, TOutput>): MockToolAdapter<TInput, TOutput>	Creates an instance of this class.
execute	method	execute(request: AdapterExecutionRequest<TInput>): Promise<ToolExecutionEnvelope<TOutput>>	Public method; parameters and return type are shown in the signature.
health	method	health(): Promise<ProviderHealth>	Public method; parameters and return type are shown in the signature.
id	property	readonly id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
source	property	readonly source: ToolSource	Public property; its type, readonly modifier and optionality are shown in the signature.

MockToolRunner

Mock Tool Runner class with 4 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class MockToolRunner implements ToolRunner {
    constructor(defaultOutput?: unknown);
    registerHandler(toolId: string, handler: MockToolHandler): void;
    registerResult(toolId: string, result: ToolCallResult): void;
    run(request: ToolCallRequest): Promise<ToolCallResult>;
}

Public members

Member	Kind	Signature	Description
constructor	constructor	(defaultOutput?: unknown): MockToolRunner	Creates an instance of this class.
registerHandler	method	registerHandler(toolId: string, handler: MockToolHandler): void	Public method; parameters and return type are shown in the signature.
registerResult	method	registerResult(toolId: string, result: ToolCallResult): void	Public method; parameters and return type are shown in the signature.
run	method	run(request: ToolCallRequest): Promise<ToolCallResult>	Public method; parameters and return type are shown in the signature.

PermissionScopeToolAuthorizer

Permission Scope Tool Authorizer class with 2 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class PermissionScopeToolAuthorizer implements ToolAuthorizer {
    authorize(input: ToolAuthorizationInput): Promise<ToolAuthorizationDecision>;
}

Public members

Member	Kind	Signature	Description
authorize	method	authorize(input: ToolAuthorizationInput): Promise<ToolAuthorizationDecision>	Public method; parameters and return type are shown in the signature.
constructor	constructor	(): PermissionScopeToolAuthorizer	Creates an instance of this class.

PluginToolAdapter

Plugin Tool Adapter class with 6 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class PluginToolAdapter<TInput = unknown, TOutput = unknown> extends LocalFunctionToolAdapter<TInput, TOutput> {
    readonly source: ToolSource;
}

Public members

Member	Kind	Signature	Description
capabilities	method	capabilities(): Promise<ToolAdapterCapabilities>	Public method; parameters and return type are shown in the signature.
constructor	constructor	<TInput = unknown, TOutput = unknown>(id: string, handler: ToolHandler<TInput, TOutput>): PluginToolAdapter<TInput, TOutput>	Creates an instance of this class.
execute	method	execute(request: AdapterExecutionRequest<TInput>): Promise<ToolExecutionEnvelope<TOutput>>	Public method; parameters and return type are shown in the signature.
health	method	health(): Promise<ProviderHealth>	Public method; parameters and return type are shown in the signature.
id	property	readonly id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
source	property	readonly source: ToolSource	Public property; its type, readonly modifier and optionality are shown in the signature.

RedisToolResultCache

Shared Redis-compatible Store for local, self-hosted, and managed Redis deployments.

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

Declaration

export declare class RedisToolResultCache implements ToolResultCache {
    constructor(options: RedisToolResultCacheOptions);
    get(key: string): Promise<ToolResultCacheEntry | null>;
    set(entry: ToolResultCacheEntry): Promise<void>;
    delete(key: string): Promise<void>;
}

Public members

Member	Kind	Signature	Description
constructor	constructor	(options: RedisToolResultCacheOptions): RedisToolResultCache	Creates an instance of this class.
delete	method	delete(key: string): Promise<void>	Public method; parameters and return type are shown in the signature.
get	method	get(key: string): Promise<ToolResultCacheEntry | null>	Public method; parameters and return type are shown in the signature.
set	method	set(entry: ToolResultCacheEntry): Promise<void>	Public method; parameters and return type are shown in the signature.

ToolRegistry

Tool Registry class with 9 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class ToolRegistry {
    register(spec: ToolSpec, handler: ToolHandler, options?: {
            replace?: boolean;
            targetResolver?: ToolTargetResolver;
        }): void;
    registerAdapter(spec: ToolSpec, adapter: ToolAdapter, options?: {
            replace?: boolean;
            targetResolver?: ToolTargetResolver;
        }): void;
    unregister(toolId: string): boolean;
    getSpec(toolId: string): ResolvedToolSpec | null;
    getAdapter(toolId: string): ToolAdapter | null;
    getTargetResolver(toolId: string): ToolTargetResolver | null;
    resolve(ref: {
            id: string;
            version?: string;
            revision?: string;
        }): {
            spec: ResolvedToolSpec;
            adapter: ToolAdapter;
        } | null;
    list(): ResolvedToolSpec[];
}

Public members

Member	Kind	Signature	Description
constructor	constructor	(): ToolRegistry	Creates an instance of this class.
getAdapter	method	getAdapter(toolId: string): ToolAdapter | null	Public method; parameters and return type are shown in the signature.
getSpec	method	getSpec(toolId: string): ResolvedToolSpec | null	Public method; parameters and return type are shown in the signature.
getTargetResolver	method	getTargetResolver(toolId: string): ToolTargetResolver | null	Public method; parameters and return type are shown in the signature.
list	method	list(): ResolvedToolSpec[]	Public method; parameters and return type are shown in the signature.
register	method	register(spec: ToolSpec, handler: ToolHandler, options?: { replace?: boolean; targetResolver?: ToolTargetResolver; }): void	Public method; parameters and return type are shown in the signature.
registerAdapter	method	registerAdapter(spec: ToolSpec, adapter: ToolAdapter, options?: { replace?: boolean; targetResolver?: ToolTargetResolver; }): void	Public method; parameters and return type are shown in the signature.
resolve	method	resolve(ref: { id: string; version?: string; revision?: string; }): { spec: ResolvedToolSpec; adapter: ToolAdapter; } | null	Public method; parameters and return type are shown in the signature.
unregister	method	unregister(toolId: string): boolean	Public method; parameters and return type are shown in the signature.

ToolResultCacheEntryTooLargeError

Tool Result Cache Entry Too Large Error class with 11 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class ToolResultCacheEntryTooLargeError extends Error {
    readonly actualBytes: number;
    readonly maxEntryBytes: number;
    readonly code = "TOOL_RESULT_CACHE_ENTRY_TOO_LARGE";
    constructor(actualBytes: number, maxEntryBytes: number);
}

Public members

Member	Kind	Signature	Description
actualBytes	property	readonly actualBytes: number	Public property; its type, readonly modifier and optionality are shown in the signature.
cause	property	cause?: unknown	Public property; its type, readonly modifier and optionality are shown in the signature.
code	property	readonly code: "TOOL_RESULT_CACHE_ENTRY_TOO_LARGE"	Public property; its type, readonly modifier and optionality are shown in the signature.
constructor	constructor	(actualBytes: number, maxEntryBytes: number): ToolResultCacheEntryTooLargeError	Creates an instance of this class.
maxEntryBytes	property	readonly maxEntryBytes: number	Public property; its type, readonly modifier and optionality are shown in the signature.
message	property	message: string	Public property; its type, readonly modifier and optionality are shown in the signature.
name	property	name: string	Public property; its type, readonly modifier and optionality are shown in the signature.
stack	property	stack?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
static captureStackTrace	method	static captureStackTrace(targetObject: object, constructorOpt?: Function): void	Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called. js const myObject = {}; Error.captureStackTrace(myObject); myObject.stack; // Similar to `new Error().stack` The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}. The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace. The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance: js function a() { b(); } function b() { c(); } function c() { // Create an error without stack trace to avoid calculating the stack trace twice. const { stackTraceLimit } = Error; Error.stackTraceLimit = 0; const error = new Error(); Error.stackTraceLimit = stackTraceLimit; // Capture the stack trace above function b Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace throw error; } a();
static prepareStackTrace	method	static prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any	Public method; parameters and return type are shown in the signature.
static stackTraceLimit	property	static stackTraceLimit: number	The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

ToolResultCacheOperationTimeoutError

Tool Result Cache Operation Timeout Error class with 11 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class ToolResultCacheOperationTimeoutError extends Error {
    readonly operation: 'get' | 'set' | 'delete' | 'verify';
    readonly timeoutMs: number;
    readonly code = "TOOL_RESULT_CACHE_TIMEOUT";
    constructor(operation: 'get' | 'set' | 'delete' | 'verify', timeoutMs: number);
}

Public members

Member	Kind	Signature	Description
cause	property	cause?: unknown	Public property; its type, readonly modifier and optionality are shown in the signature.
code	property	readonly code: "TOOL_RESULT_CACHE_TIMEOUT"	Public property; its type, readonly modifier and optionality are shown in the signature.
constructor	constructor	(operation: "get" | "set" | "delete" | "verify", timeoutMs: number): ToolResultCacheOperationTimeoutError	Creates an instance of this class.
message	property	message: string	Public property; its type, readonly modifier and optionality are shown in the signature.
name	property	name: string	Public property; its type, readonly modifier and optionality are shown in the signature.
operation	property	readonly operation: "delete" | "verify" | "get" | "set"	Public property; its type, readonly modifier and optionality are shown in the signature.
stack	property	stack?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
static captureStackTrace	method	static captureStackTrace(targetObject: object, constructorOpt?: Function): void	Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called. js const myObject = {}; Error.captureStackTrace(myObject); myObject.stack; // Similar to `new Error().stack` The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}. The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace. The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance: js function a() { b(); } function b() { c(); } function c() { // Create an error without stack trace to avoid calculating the stack trace twice. const { stackTraceLimit } = Error; Error.stackTraceLimit = 0; const error = new Error(); Error.stackTraceLimit = stackTraceLimit; // Capture the stack trace above function b Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace throw error; } a();
static prepareStackTrace	method	static prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any	Public method; parameters and return type are shown in the signature.
static stackTraceLimit	property	static stackTraceLimit: number	The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.
timeoutMs	property	readonly timeoutMs: number	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolResultCacheValidationError

Tool Result Cache Validation Error class with 9 public constructor or member entries; its exact declarations are listed below.

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

Declaration

export declare class ToolResultCacheValidationError extends Error {
    readonly code = "TOOL_RESULT_CACHE_CORRUPT";
    constructor(message: string);
}

Public members

Member	Kind	Signature	Description
cause	property	cause?: unknown	Public property; its type, readonly modifier and optionality are shown in the signature.
code	property	readonly code: "TOOL_RESULT_CACHE_CORRUPT"	Public property; its type, readonly modifier and optionality are shown in the signature.
constructor	constructor	(message: string): ToolResultCacheValidationError	Creates an instance of this class.
message	property	message: string	Public property; its type, readonly modifier and optionality are shown in the signature.
name	property	name: string	Public property; its type, readonly modifier and optionality are shown in the signature.
stack	property	stack?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
static captureStackTrace	method	static captureStackTrace(targetObject: object, constructorOpt?: Function): void	Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called. js const myObject = {}; Error.captureStackTrace(myObject); myObject.stack; // Similar to `new Error().stack` The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}. The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace. The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance: js function a() { b(); } function b() { c(); } function c() { // Create an error without stack trace to avoid calculating the stack trace twice. const { stackTraceLimit } = Error; Error.stackTraceLimit = 0; const error = new Error(); Error.stackTraceLimit = stackTraceLimit; // Capture the stack trace above function b Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace throw error; } a();
static prepareStackTrace	method	static prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any	Public method; parameters and return type are shown in the signature.
static stackTraceLimit	property	static stackTraceLimit: number	The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

TOOL_INVOCATION_STATUSES

TOOL INVOCATION STATUSES constant exported by the index module.

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

Declaration

export declare const TOOL_INVOCATION_STATUSES: readonly ["created", "validating", "validated", "policy_checked", "waiting_approval", "approved", "rejected", "queued", "running", "cancelling", "completed", "failed", "timed_out", "expired", "conflict", "denied", "cancelled"];

toolCacheValidityRecordSchema

Runtime schema for Tool Cache Validity Record.

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

Declaration

export declare const toolCacheValidityRecordSchema: z.ZodObject<{ toolId: z.ZodString; toolRevision: z.ZodString; inputHash: z.ZodString; scopeHash: z.ZodString; policyRevision: z.ZodString; contractSnapshotHash: z.ZodOptional<z.ZodString>; capabilityHash: z.ZodOptional<z.ZodString>; externalStateVersion: z.ZodOptional<z.ZodString>; key: z.ZodString; validUntil: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { toolId: string; toolRevision: string; policyRevision: string; scopeHash: string; inputHash: string; key: string; contractSnapshotHash?: string | undefined; capabilityHash?: string | undefined; externalStateVersion?: string | undefined; validUntil?: string | undefined; }, { toolId: string; toolRevision: string; policyRevision: string; scopeHash: string; inputHash: string; key: string; contractSnapshotHash?: string | undefined; capabilityHash?: string | undefined; externalStateVersion?: string | undefined; validUntil?: string | undefined; }>;

toolProfileSpecDefinition

Runtime validation entrypoint for the Tool Profile spec, combining its parser, example and JSON Schema.

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

Declaration

export declare const toolProfileSpecDefinition: SpecSchemaDefinition<ToolProfileSpec>;

toolProfileSpecSchema

Runtime schema for Tool Profile Spec.

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

Declaration

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

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.

toolResultCacheEntryJsonSchema

JSON Schema for Tool Result Cache Entry.

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

Declaration

export declare const toolResultCacheEntryJsonSchema: JsonSchema;

toolResultCacheEntrySchema

Runtime schema for Tool Result Cache Entry.

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

Declaration

export declare const toolResultCacheEntrySchema: z.ZodObject<{ schemaVersion: z.ZodLiteral<"1.0">; keyVersion: z.ZodLiteral<"1">; validity: z.ZodObject<{ toolId: z.ZodString; toolRevision: z.ZodString; inputHash: z.ZodString; scopeHash: z.ZodString; policyRevision: z.ZodString; contractSnapshotHash: z.ZodOptional<z.ZodString>; capabilityHash: z.ZodOptional<z.ZodString>; externalStateVersion: z.ZodOptional<z.ZodString>; key: z.ZodString; validUntil: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { toolId: string; toolRevision: string; policyRevision: string; scopeHash: string; inputHash: string; key: string; contractSnapshotHash?: string | undefined; capabilityHash?: string | undefined; externalStateVersion?: string | undefined; validUntil?: string | undefined; }, { toolId: string; toolRevision: string; policyRevision: string; scopeHash: string; inputHash: string; key: string; contractSnapshotHash?: string | undefined; capabilityHash?: string | undefined; externalStateVersion?: string | undefined; validUntil?: string | undefined; }>; result: z.ZodObject<{ output: z.ZodOptional<z.ZodUnknown>; content: z.ZodOptional<z.ZodArray<z.ZodType<ToolResultContent, z.ZodTypeDef, ToolResultContent>, "many">>; artifactRefs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; }, "strict", z.ZodTypeAny, { output?: unknown; artifactRefs?: string[] | undefined; content?: ToolResultContent[] | undefined; }, { output?: unknown; artifactRefs?: string[] | undefined; content?: ToolResultContent[] | undefined; }>; createdAt: z.ZodString; }, "strict", z.ZodTypeAny, { schemaVersion: "1.0"; result: { output?: unknown; artifactRefs?: string[] | undefined; content?: ToolResultContent[] | undefined; }; createdAt: string; keyVersion: "1"; validity: { toolId: string; toolRevision: string; policyRevision: string; scopeHash: string; inputHash: string; key: string; contractSnapshotHash?: string | undefined; capabilityHash?: string | undefined; externalStateVersion?: string | undefined; validUntil?: string | undefined; }; }, { schemaVersion: "1.0"; result: { output?: unknown; artifactRefs?: string[] | undefined; content?: ToolResultContent[] | undefined; }; createdAt: string; keyVersion: "1"; validity: { toolId: string; toolRevision: string; policyRevision: string; scopeHash: string; inputHash: string; key: string; contractSnapshotHash?: string | undefined; capabilityHash?: string | undefined; externalStateVersion?: string | undefined; validUntil?: string | undefined; }; }>;

toolSpecDefinition

Runtime validation entrypoint for the Tool spec, combining its parser, example and JSON Schema.

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

Declaration

export declare const toolSpecDefinition: SpecSchemaDefinition<ToolSpec>;

toolSpecDefinitions

Tool Spec Definitions constant exported by the index module.

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

Declaration

export declare const toolSpecDefinitions: readonly [SpecSchemaDefinition<ToolSpec>, SpecSchemaDefinition<ToolProfileSpec>];

toolSpecExample

Valid example value for Tool Spec.

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

Declaration

export declare const toolSpecExample: ToolSpec;

toolSpecJsonSchema

JSON Schema for Tool Spec.

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

Declaration

export declare const toolSpecJsonSchema: JsonSchema;

toolSpecJsonSchemas

Tool Spec JSON Schemas constant exported by the index module.

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

Declaration

export declare const toolSpecJsonSchemas: Record<string, JsonSchema>;

toolSpecSchema

Runtime schema for Tool Spec.

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

Declaration

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

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.

normalizeToolSpec

Normalize Tool Spec function with 1 public call signature; parameters and return types are listed below.

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

Declaration

export declare function normalizeToolSpec(spec: ToolSpec): ResolvedToolSpec;

Call signature

normalizeToolSpec(spec: ToolSpec): ResolvedToolSpec

Parameters

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

Returns

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

validateEffectiveCapabilityAccess

Validate Effective Capability Access function with 1 public call signature; parameters and return types are listed below.

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

Declaration

export declare function validateEffectiveCapabilityAccess(input: {
    snapshot: ToolContractSnapshot | null;
    context: ToolCallContext;
    spec: ToolSpec;
}): string | null;

Call signature

validateEffectiveCapabilityAccess(input: { snapshot: ToolContractSnapshot | null; context: ToolCallContext; spec: ToolSpec; }): string | null

Parameters

Parameter	Type	Required	Description
input	{ snapshot: ToolContractSnapshot | null; context: ToolCallContext; spec: ToolSpec; }	Yes	Required parameter; accepted values are defined by the type column.

Returns

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

validateToolInput

Validate Tool Input function with 1 public call signature; parameters and return types are listed below.

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

Declaration

export declare function validateToolInput(schema: JsonSchema, input: unknown): ToolSchemaValidationResult;

Call signature

validateToolInput(schema: JsonSchema, input: unknown): ToolSchemaValidationResult

Parameters

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

Returns

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

validateToolResultCacheEntry

Validate Tool Result Cache Entry function with 1 public call signature; parameters and return types are listed below.

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

Declaration

export declare function validateToolResultCacheEntry(value: unknown, maxEntryBytes?: number): ToolResultCacheEntry;

Call signature

validateToolResultCacheEntry(value: unknown, maxEntryBytes?: number): ToolResultCacheEntry

Parameters

Parameter	Type	Required	Description
value	unknown	Yes	Required parameter; accepted values are defined by the type column.
maxEntryBytes	number	No	Optional parameter; accepted values are defined by the type column.

Returns

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

validateToolSpec

Validate Tool Spec function with 1 public call signature; parameters and return types are listed below.

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

Declaration

export declare function validateToolSpec(input: unknown): ToolSpec;

Call signature

validateToolSpec(input: unknown): ToolSpec

Parameters

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

Returns

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

AdapterCancellationRequest

Adapter Cancellation Request interface with 3 public fields or methods.

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

Declaration

export interface AdapterCancellationRequest {
    toolId: string;
    invocationId: string;
    reason?: string;
}

Contract members

Member	Kind	Signature	Description
invocationId	property	invocationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
reason	property	reason?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
toolId	property	toolId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

AdapterExecutionRequest

Adapter Execution Request interface with 3 public fields or methods.

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

Declaration

export interface AdapterExecutionRequest<TInput = unknown> {
    toolId: string;
    input: TInput;
    context: ToolCallContext;
}

Contract members

Member	Kind	Signature	Description
context	property	context: ToolCallContext	Public property; its type, readonly modifier and optionality are shown in the signature.
input	property	input: TInput	Public property; its type, readonly modifier and optionality are shown in the signature.
toolId	property	toolId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

HttpToolAdapterOptions

Http Tool Adapter Options interface with 4 public fields or methods.

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

Declaration

export interface HttpToolAdapterOptions {
    endpoint: string;
    headers?: Record<string, string>;
    resolveHeaders?: () => Promise<Record<string, string>>;
    fetch?: typeof fetch;
}

Contract members

Member	Kind	Signature	Description
endpoint	property	endpoint: string	Public property; its type, readonly modifier and optionality 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.
headers	property	headers?: Record<string, string>	Public property; its type, readonly modifier and optionality are shown in the signature.
resolveHeaders	method	resolveHeaders?(): Promise<Record<string, string>>	Public method; parameters and return type are shown in the signature.

InMemoryToolResultCacheOptions

In Memory Tool Result Cache Options interface with 2 public fields or methods.

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

Declaration

export interface InMemoryToolResultCacheOptions {
    maxEntries?: number;
    maxEntryBytes?: number;
}

Contract members

Member	Kind	Signature	Description
maxEntries	property	maxEntries?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxEntryBytes	property	maxEntryBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

MCPToolInvocationPort

MCP Tool Invocation Port interface with 3 public fields or methods.

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

Declaration

export interface MCPToolInvocationPort {
    invoke(request: {
        serverId: string;
        capabilityId: string;
        input: unknown;
        context: ToolCallContext;
    }): Promise<unknown>;
    health(serverId: string): Promise<ProviderHealth>;
    cancel?(requestId: string): Promise<void>;
}

Contract members

Member	Kind	Signature	Description
cancel	method	cancel?(requestId: string): Promise<void>	Public method; parameters and return type are shown in the signature.
health	method	health(serverId: string): Promise<ProviderHealth>	Public method; parameters and return type are shown in the signature.
invoke	method	invoke(request: { serverId: string; capabilityId: string; input: unknown; context: ToolCallContext; }): Promise<unknown>	Public method; parameters and return type are shown in the signature.

RedisLikeToolResultCacheClient

Redis Like Tool Result Cache Client interface with 3 public fields or methods.

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

Declaration

export interface RedisLikeToolResultCacheClient {
    get(key: string): Promise<string | null>;
    set(key: string, value: string, mode?: 'PX', durationMilliseconds?: number): Promise<unknown>;
    del(...keys: string[]): Promise<number>;
}

Contract members

Member	Kind	Signature	Description
del	method	del(...keys: string[]): Promise<number>	Public method; parameters and return type are shown in the signature.
get	method	get(key: string): Promise<string | null>	Public method; parameters and return type are shown in the signature.
set	method	set(key: string, value: string, mode?: "PX", durationMilliseconds?: number): Promise<unknown>	Public method; parameters and return type are shown in the signature.

RedisToolResultCacheOptions

Redis Tool Result Cache Options interface with 5 public fields or methods.

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

Declaration

export interface RedisToolResultCacheOptions {
    client: RedisLikeToolResultCacheClient;
    namespace?: string;
    maxEntryBytes?: number;
    defaultTtlMs?: number;
    now?: () => string;
}

Contract members

Member	Kind	Signature	Description
client	property	client: RedisLikeToolResultCacheClient	Public property; its type, readonly modifier and optionality are shown in the signature.
defaultTtlMs	property	defaultTtlMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxEntryBytes	property	maxEntryBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
namespace	property	namespace?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
now	method	now?(): string	Public method; parameters and return type are shown in the signature.

ToolAdapter

Tool Adapter interface with 7 public fields or methods.

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

Declaration

export interface ToolAdapter<TInput = unknown, TOutput = unknown> {
    readonly id: string;
    readonly source: ToolSource;
    capabilities(): Promise<ToolAdapterCapabilities>;
    execute(request: AdapterExecutionRequest<TInput>): Promise<ToolExecutionEnvelope<TOutput>>;
    cancel?(request: AdapterCancellationRequest): Promise<void>;
    health(): Promise<ProviderHealth>;
    close?(): Promise<void>;
}

Contract members

Member	Kind	Signature	Description
cancel	method	cancel?(request: AdapterCancellationRequest): Promise<void>	Public method; parameters and return type are shown in the signature.
capabilities	method	capabilities(): Promise<ToolAdapterCapabilities>	Public method; parameters and return type are shown in the signature.
close	method	close?(): Promise<void>	Public method; parameters and return type are shown in the signature.
execute	method	execute(request: AdapterExecutionRequest<TInput>): Promise<ToolExecutionEnvelope<TOutput>>	Public method; parameters and return type are shown in the signature.
health	method	health(): Promise<ProviderHealth>	Public method; parameters and return type are shown in the signature.
id	property	readonly id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
source	property	readonly source: ToolSource	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolAdapterCapabilities

Tool Adapter Capabilities interface with 5 public fields or methods.

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

Declaration

export interface ToolAdapterCapabilities {
    execute: boolean;
    cancel: boolean;
    health: boolean;
    close: boolean;
    streaming?: boolean;
}

Contract members

Member	Kind	Signature	Description
cancel	property	cancel: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
close	property	close: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
execute	property	execute: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
health	property	health: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
streaming	property	streaming?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolApprovalGrant

Tool Approval Grant interface with 11 public fields or methods.

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

Declaration

export interface ToolApprovalGrant {
    requestId: string;
    invocationId: string;
    toolId: string;
    inputHash: string;
    toolRevision?: string;
    contractSnapshotRef?: string;
    principalId?: string;
    policyDecisionRef?: string;
    approvedBy: string;
    approvedAt: string;
    expiresAt?: string;
}

Contract members

Member	Kind	Signature	Description
approvedAt	property	approvedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
approvedBy	property	approvedBy: string	Public property; its type, readonly modifier and optionality are shown in the signature.
contractSnapshotRef	property	contractSnapshotRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
expiresAt	property	expiresAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
inputHash	property	inputHash: string	Public property; its type, readonly modifier and optionality are shown in the signature.
invocationId	property	invocationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
policyDecisionRef	property	policyDecisionRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
principalId	property	principalId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
requestId	property	requestId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
toolId	property	toolId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
toolRevision	property	toolRevision?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolApprovalRequest

Tool Approval Request interface with 15 public fields or methods.

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

Declaration

export interface ToolApprovalRequest {
    id: string;
    invocationId: string;
    toolId: string;
    toolRevision?: string;
    contractSnapshotRef?: string;
    principalId?: string;
    policyDecisionRef?: string;
    inputHash: string;
    runId: string;
    stepId: string;
    userId?: string;
    reason?: string;
    requestedAt: string;
    expiresAt?: string;
    status: 'pending' | 'approved' | 'rejected' | 'expired' | 'cancelled';
}

Contract members

Member	Kind	Signature	Description
contractSnapshotRef	property	contractSnapshotRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
expiresAt	property	expiresAt?: 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.
inputHash	property	inputHash: string	Public property; its type, readonly modifier and optionality are shown in the signature.
invocationId	property	invocationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
policyDecisionRef	property	policyDecisionRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
principalId	property	principalId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
reason	property	reason?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
requestedAt	property	requestedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
runId	property	runId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
status	property	status: "rejected" | "cancelled" | "expired" | "pending" | "approved"	Public property; its type, readonly modifier and optionality are shown in the signature.
stepId	property	stepId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
toolId	property	toolId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
toolRevision	property	toolRevision?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
userId	property	userId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolApprovalStore

Tool Approval Store interface with 5 public fields or methods.

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

Declaration

export interface ToolApprovalStore {
    getRequest(invocationId: string): Promise<ToolApprovalRequest | null>;
    requestApproval(request: ToolApprovalRequest): Promise<ToolApprovalRequest>;
    getGrant(invocationId: string): Promise<ToolApprovalGrant | null>;
    approve(invocationId: string, approvedBy: string, options?: {
        approvedAt?: string;
        expiresAt?: string;
    }): Promise<ToolApprovalGrant>;
    reject(invocationId: string): Promise<ToolApprovalRequest>;
}

Contract members

Member	Kind	Signature	Description
approve	method	approve(invocationId: string, approvedBy: string, options?: { approvedAt?: string; expiresAt?: string; }): Promise<ToolApprovalGrant>	Public method; parameters and return type are shown in the signature.
getGrant	method	getGrant(invocationId: string): Promise<ToolApprovalGrant | null>	Public method; parameters and return type are shown in the signature.
getRequest	method	getRequest(invocationId: string): Promise<ToolApprovalRequest | null>	Public method; parameters and return type are shown in the signature.
reject	method	reject(invocationId: string): Promise<ToolApprovalRequest>	Public method; parameters and return type are shown in the signature.
requestApproval	method	requestApproval(request: ToolApprovalRequest): Promise<ToolApprovalRequest>	Public method; parameters and return type are shown in the signature.

ToolArtifactPort

Tool Artifact Port interface with 1 public fields or methods.

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

Declaration

export interface ToolArtifactPort {
    store(request: {
        invocationId: string;
        toolId: string;
        value: unknown;
        mimeType?: string;
        metadata?: Record<string, unknown>;
    }): Promise<string>;
}

Contract members

Member	Kind	Signature	Description
store	method	store(request: { invocationId: string; toolId: string; value: unknown; mimeType?: string; metadata?: Record<string, unknown>; }): Promise<string>	Public method; parameters and return type are shown in the signature.

ToolAuthorizationDecision

Tool Authorization Decision interface with 3 public fields or methods.

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

Declaration

export interface ToolAuthorizationDecision {
    allowed: boolean;
    reason?: string;
    missingPermissionScopes?: string[];
}

Contract members

Member	Kind	Signature	Description
allowed	property	allowed: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
missingPermissionScopes	property	missingPermissionScopes?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
reason	property	reason?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolAuthorizationInput

Tool Authorization Input interface with 4 public fields or methods.

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

Declaration

export interface ToolAuthorizationInput {
    tool: ToolSpec;
    request: ToolCallRequest;
    principal?: ToolPrincipal;
    executionScope?: ToolExecutionScope;
}

Contract members

Member	Kind	Signature	Description
executionScope	property	executionScope?: ToolExecutionScope	Public property; its type, readonly modifier and optionality are shown in the signature.
principal	property	principal?: ToolPrincipal	Public property; its type, readonly modifier and optionality are shown in the signature.
request	property	request: ToolCallRequest<unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
tool	property	tool: ToolSpec	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolAuthorizer

Tool Authorizer interface with 1 public fields or methods.

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

Declaration

export interface ToolAuthorizer {
    authorize(input: ToolAuthorizationInput): Promise<ToolAuthorizationDecision>;
}

Contract members

Member	Kind	Signature	Description
authorize	method	authorize(input: ToolAuthorizationInput): Promise<ToolAuthorizationDecision>	Public method; parameters and return type are shown in the signature.

ToolCachedResultProjection

Only stable, replay-safe output fields may cross invocation boundaries.

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

Declaration

export interface ToolCachedResultProjection {
    output?: unknown;
    content?: ToolResultContent[];
    artifactRefs?: string[];
}

Contract members

Member	Kind	Signature	Description
artifactRefs	property	artifactRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
content	property	content?: ToolResultContent[]	Public property; its type, readonly modifier and optionality are shown in the signature.
output	property	output?: unknown	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolCallContext

Tool Call Context interface with 24 public fields or methods.

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

Declaration

export interface ToolCallContext {
    runId: string;
    stepId: string;
    invocationId?: string;
    userId?: string;
    tenantId?: string;
    workspaceId?: string;
    sessionId?: string;
    agentId?: string;
    fsmState?: string;
    idempotencyKey?: string;
    operationId?: string;
    correlationId?: string;
    causationId?: string;
    parentEventId?: string;
    contractSnapshotRef?: string;
    capabilitySnapshotRef?: string;
    capabilityApprovals?: EffectiveCapabilityApproval[];
    deadlineAt?: string;
    signal?: AbortSignal;
    abortSignal?: AbortSignal;
    reportProgress?: (update: ToolProgressUpdate) => void | Promise<void>;
    executionScope?: ToolExecutionScope;
    principal?: ToolPrincipal;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
abortSignal	property	abortSignal?: AbortSignal	Public property; its type, readonly modifier and optionality are shown in the signature.
agentId	property	agentId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
capabilityApprovals	property	capabilityApprovals?: EffectiveCapabilityApproval[]	Public property; its type, readonly modifier and optionality are shown in the signature.
capabilitySnapshotRef	property	capabilitySnapshotRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
causationId	property	causationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
contractSnapshotRef	property	contractSnapshotRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
correlationId	property	correlationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
deadlineAt	property	deadlineAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
executionScope	property	executionScope?: ToolExecutionScope	Public property; its type, readonly modifier and optionality are shown in the signature.
fsmState	property	fsmState?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
invocationId	property	invocationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
parentEventId	property	parentEventId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
principal	property	principal?: ToolPrincipal	Public property; its type, readonly modifier and optionality are shown in the signature.
reportProgress	method	reportProgress?(update: ToolProgressUpdate): void | Promise<void>	Public method; parameters and return type are shown in the signature.
runId	property	runId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sessionId	property	sessionId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
signal	property	signal?: AbortSignal	Public property; its type, readonly modifier and optionality are shown in the signature.
stepId	property	stepId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
tenantId	property	tenantId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
userId	property	userId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
workspaceId	property	workspaceId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolCallError

Tool Call Error interface with 5 public fields or methods.

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

Declaration

export interface ToolCallError {
    code: string;
    message: string;
    phase: ToolExecutionPhase;
    retryable?: boolean;
    details?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
code	property	code: string	Public property; its type, readonly modifier and optionality are shown in the signature.
details	property	details?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
message	property	message: string	Public property; its type, readonly modifier and optionality are shown in the signature.
phase	property	phase: ToolExecutionPhase	Public property; its type, readonly modifier and optionality are shown in the signature.
retryable	property	retryable?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolCallRequest

Tool Call Request interface with 3 public fields or methods.

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

Declaration

export interface ToolCallRequest<TInput = unknown> {
    toolId: string;
    input: TInput;
    context: ToolCallContext;
}

Contract members

Member	Kind	Signature	Description
context	property	context: ToolCallContext	Public property; its type, readonly modifier and optionality are shown in the signature.
input	property	input: TInput	Public property; its type, readonly modifier and optionality are shown in the signature.
toolId	property	toolId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolCallResult

Tool Call Result interface with 12 public fields or methods.

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

Declaration

export interface ToolCallResult<TOutput = unknown> {
    toolId: string;
    invocationId?: string;
    output?: TOutput;
    error?: ToolCallError | string;
    approvalRequest?: ToolApprovalRequest;
    attempts?: number;
    durationMs?: number;
    content?: ToolResultContent[];
    artifactRefs?: string[];
    observationRefs?: string[];
    externalReceipt?: ToolExternalReceipt;
    status: 'completed' | 'failed' | 'denied' | 'human_review_required' | 'cancelled' | 'conflict';
}

Contract members

Member	Kind	Signature	Description
approvalRequest	property	approvalRequest?: ToolApprovalRequest	Public property; its type, readonly modifier and optionality are shown in the signature.
artifactRefs	property	artifactRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
attempts	property	attempts?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
content	property	content?: ToolResultContent[]	Public property; its type, readonly modifier and optionality are shown in the signature.
durationMs	property	durationMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
error	property	error?: string | ToolCallError	Public property; its type, readonly modifier and optionality are shown in the signature.
externalReceipt	property	externalReceipt?: ToolExternalReceipt	Public property; its type, readonly modifier and optionality are shown in the signature.
invocationId	property	invocationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
observationRefs	property	observationRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
output	property	output?: TOutput	Public property; its type, readonly modifier and optionality are shown in the signature.
status	property	status: "completed" | "cancelled" | "failed" | "denied" | "conflict" | "human_review_required"	Public property; its type, readonly modifier and optionality are shown in the signature.
toolId	property	toolId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolExecutionEnvelope

Tool Execution Envelope interface with 7 public fields or methods.

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

Declaration

export interface ToolExecutionEnvelope<TOutput = unknown> {
    kind: 'tool_execution_envelope';
    output?: TOutput;
    content?: ToolResultContent[];
    artifactRefs?: string[];
    observationRefs?: string[];
    externalReceipt?: ToolExternalReceipt;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
artifactRefs	property	artifactRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
content	property	content?: ToolResultContent[]	Public property; its type, readonly modifier and optionality are shown in the signature.
externalReceipt	property	externalReceipt?: ToolExternalReceipt	Public property; its type, readonly modifier and optionality are shown in the signature.
kind	property	kind: "tool_execution_envelope"	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
observationRefs	property	observationRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
output	property	output?: TOutput	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolExecutionScope

Tool Execution Scope interface with 3 public fields or methods.

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

Declaration

export interface ToolExecutionScope {
    allowedToolIds?: readonly string[];
    policyRefs?: readonly string[];
    fsmState?: string;
}

Contract members

Member	Kind	Signature	Description
allowedToolIds	property	allowedToolIds?: readonly string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
fsmState	property	fsmState?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
policyRefs	property	policyRefs?: readonly string[]	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolIdempotencyLookup

Tool Idempotency Lookup interface with 3 public fields or methods.

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

Declaration

export interface ToolIdempotencyLookup {
    toolId: string;
    idempotencyKey: string;
    scopeHash: string;
}

Contract members

Member	Kind	Signature	Description
idempotencyKey	property	idempotencyKey: string	Public property; its type, readonly modifier and optionality are shown in the signature.
scopeHash	property	scopeHash: string	Public property; its type, readonly modifier and optionality are shown in the signature.
toolId	property	toolId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolInvocationListRequest

Tool Invocation List Request interface with 4 public fields or methods.

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

Declaration

export interface ToolInvocationListRequest {
    statuses?: readonly ToolInvocationStatus[];
    toolId?: string;
    runId?: string;
    limit?: number;
}

Contract members

Member	Kind	Signature	Description
limit	property	limit?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
runId	property	runId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
statuses	property	statuses?: readonly ("completed" | "rejected" | "queued" | "running" | "cancelling" | "cancelled" | "failed" | "timed_out" | "created" | "denied" | "expired" | "approved" | "conflict" | "policy_checked" | "waiting_approval" | "validating" | "validated")[]	Public property; its type, readonly modifier and optionality are shown in the signature.
toolId	property	toolId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolInvocationRecord

Tool Invocation Record interface with 37 public fields or methods.

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

Declaration

export interface ToolInvocationRecord {
    id: string;
    operationId?: string;
    toolId: string;
    toolVersion?: string;
    toolRevision?: string;
    contractSnapshotRef?: string;
    principal?: ToolPrincipal;
    scope?: {
        tenantId?: string;
        userId?: string;
        workspaceId?: string;
        sessionId?: string;
        runId: string;
        stepId?: string;
        agentId?: string;
        fsmState?: string;
    };
    status: ToolInvocationStatus;
    inputHash: string;
    redactedInput?: unknown;
    sideEffectLevel?: SideEffectLevel;
    idempotencyKey?: string;
    idempotencyFingerprint?: string;
    reusedFromInvocationId?: string;
    request: ToolCallRequest;
    executionCycle: number;
    attemptCount: number;
    revision: number;
    result?: ToolCallResult;
    approvalRequest?: ToolApprovalRequest;
    approvalRequestId?: string;
    maxAttempts?: number;
    queuedAt?: string;
    deadlineAt?: string;
    outputHash?: string;
    artifactRefs?: string[];
    observationRefs?: string[];
    externalReceipt?: {
        provider?: string;
        receiptId: string;
        status?: string;
        metadata?: Record<string, unknown>;
    };
    lateResultState?: 'none' | 'pending' | 'accepted' | 'discarded' | 'quarantined';
    correlationId?: string;
    causationId?: string;
    metadata?: Record<string, unknown>;
    createdAt: string;
    updatedAt: string;
    startedAt?: string;
    completedAt?: string;
}

Contract members

Member	Kind	Signature	Description
approvalRequest	property	approvalRequest?: ToolApprovalRequest	Public property; its type, readonly modifier and optionality are shown in the signature.
approvalRequestId	property	approvalRequestId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
artifactRefs	property	artifactRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
attemptCount	property	attemptCount: number	Public property; its type, readonly modifier and optionality are shown in the signature.
causationId	property	causationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
completedAt	property	completedAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
contractSnapshotRef	property	contractSnapshotRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
correlationId	property	correlationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
createdAt	property	createdAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
deadlineAt	property	deadlineAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
executionCycle	property	executionCycle: number	Public property; its type, readonly modifier and optionality are shown in the signature.
externalReceipt	property	externalReceipt?: { provider?: string; receiptId: string; status?: string; metadata?: Record<string, unknown>; }	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.
idempotencyFingerprint	property	idempotencyFingerprint?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
inputHash	property	inputHash: string	Public property; its type, readonly modifier and optionality are shown in the signature.
lateResultState	property	lateResultState?: "none" | "accepted" | "quarantined" | "pending" | "discarded"	Public property; its type, readonly modifier and optionality are shown in the signature.
maxAttempts	property	maxAttempts?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
observationRefs	property	observationRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
outputHash	property	outputHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
principal	property	principal?: ToolPrincipal	Public property; its type, readonly modifier and optionality are shown in the signature.
queuedAt	property	queuedAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
redactedInput	property	redactedInput?: unknown	Public property; its type, readonly modifier and optionality are shown in the signature.
request	property	request: ToolCallRequest<unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
result	property	result?: ToolCallResult<unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
reusedFromInvocationId	property	reusedFromInvocationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
revision	property	revision: number	Public property; its type, readonly modifier and optionality are shown in the signature.
scope	property	scope?: { tenantId?: string; userId?: string; workspaceId?: string; sessionId?: string; runId: string; stepId?: string; agentId?: string; fsmState?: string; }	Public property; its type, readonly modifier and optionality are shown in the signature.
sideEffectLevel	property	sideEffectLevel?: SideEffectLevel	Public property; its type, readonly modifier and optionality are shown in the signature.
startedAt	property	startedAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
status	property	status: "completed" | "rejected" | "queued" | "running" | "cancelling" | "cancelled" | "failed" | "timed_out" | "created" | "denied" | "expired" | "approved" | "conflict" | "policy_checked" | "waiting_approval" | "validating" | "validated"	Public property; its type, readonly modifier and optionality are shown in the signature.
toolId	property	toolId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
toolRevision	property	toolRevision?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
toolVersion	property	toolVersion?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
updatedAt	property	updatedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolInvocationStore

Tool Invocation Store interface with 7 public fields or methods.

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

Declaration

export interface ToolInvocationStore {
    get(invocationId: string): Promise<ToolInvocationRecord | null>;
    findByIdempotency(request: ToolIdempotencyLookup): Promise<ToolInvocationRecord | null>;
    list(request?: ToolInvocationListRequest): Promise<ToolInvocationRecord[]>;
    create(record: ToolInvocationRecord): Promise<ToolInvocationRecord>;
    update(invocationId: string, patch: ToolInvocationPatch, options?: {
        expectedStatuses?: readonly ToolInvocationStatus[];
        expectedRevision?: number;
    }): Promise<ToolInvocationRecord>;
    getCompleted(invocationId: string): Promise<ToolCallResult | null>;
    saveCompleted(invocationId: string, result: ToolCallResult): Promise<void>;
}

Contract members

Member	Kind	Signature	Description
create	method	create(record: ToolInvocationRecord): Promise<ToolInvocationRecord>	Public method; parameters and return type are shown in the signature.
findByIdempotency	method	findByIdempotency(request: ToolIdempotencyLookup): Promise<ToolInvocationRecord | null>	Public method; parameters and return type are shown in the signature.
get	method	get(invocationId: string): Promise<ToolInvocationRecord | null>	Public method; parameters and return type are shown in the signature.
getCompleted	method	getCompleted(invocationId: string): Promise<ToolCallResult | null>	Public method; parameters and return type are shown in the signature.
list	method	list(request?: ToolInvocationListRequest): Promise<ToolInvocationRecord[]>	Public method; parameters and return type are shown in the signature.
saveCompleted	method	saveCompleted(invocationId: string, result: ToolCallResult): Promise<void>	Public method; parameters and return type are shown in the signature.
update	method	update(invocationId: string, patch: ToolInvocationPatch, options?: { expectedStatuses?: readonly ToolInvocationStatus[]; expectedRevision?: number; }): Promise<ToolInvocationRecord>	Public method; parameters and return type are shown in the signature.

ToolMiddleware

Tool Middleware interface with 5 public fields or methods.

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

Declaration

export interface ToolMiddleware {
    id: string;
    beforeAuthorization?(context: ToolMiddlewareContext): Promise<void> | void;
    beforeExecution?(context: ToolMiddlewareContext): Promise<void> | void;
    afterExecution?(context: ToolMiddlewareContext, result: ToolExecutionEnvelope): Promise<ToolExecutionEnvelope | void> | ToolExecutionEnvelope | void;
    onError?(context: ToolMiddlewareContext, error: unknown): Promise<void> | void;
}

Contract members

Member	Kind	Signature	Description
afterExecution	method	afterExecution?(context: ToolMiddlewareContext, result: ToolExecutionEnvelope): Promise<ToolExecutionEnvelope | void> | ToolExecutionEnvelope | void	Public method; parameters and return type are shown in the signature.
beforeAuthorization	method	beforeAuthorization?(context: ToolMiddlewareContext): Promise<void> | void	Public method; parameters and return type are shown in the signature.
beforeExecution	method	beforeExecution?(context: ToolMiddlewareContext): Promise<void> | void	Public method; parameters and return type are shown in the signature.
id	property	id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
onError	method	onError?(context: ToolMiddlewareContext, error: unknown): Promise<void> | void	Public method; parameters and return type are shown in the signature.

ToolMiddlewareContext

Tool Middleware Context interface with 5 public fields or methods.

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

Declaration

export interface ToolMiddlewareContext {
    invocationId: string;
    request: ToolCallRequest;
    originalRequest: ToolCallRequest;
    spec: ResolvedToolSpec;
    attempt?: number;
}

Contract members

Member	Kind	Signature	Description
attempt	property	attempt?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
invocationId	property	invocationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
originalRequest	property	originalRequest: ToolCallRequest<unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
request	property	request: ToolCallRequest<unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
spec	property	spec: ResolvedToolSpec	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolObservationPort

Tool Observation Port interface with 1 public fields or methods.

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

Declaration

export interface ToolObservationPort {
    record(request: {
        invocationId: string;
        toolId: string;
        toolRevision: string;
        runId: string;
        stepId: string;
        inputHash: string;
        outputHash: string;
        value: unknown;
        artifactRefs?: string[];
        provenance: Record<string, unknown>;
    }): Promise<string>;
}

Contract members

Member	Kind	Signature	Description
record	method	record(request: { invocationId: string; toolId: string; toolRevision: string; runId: string; stepId: string; inputHash: string; outputHash: string; value: unknown; artifactRefs?: string[]; provenance: Record<string, unknown>; }): Promise<string>	Public method; parameters and return type are shown in the signature.

ToolPrincipal

Tool Principal interface with 13 public fields or methods.

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

Declaration

export interface ToolPrincipal {
    id: string;
    principalId?: string;
    type: 'user' | 'agent' | 'service' | 'system';
    permissionScopes: readonly string[];
    tenantId?: string;
    userId?: string;
    workspaceId?: string;
    agentId?: string;
    roles?: readonly string[];
    delegatedBy?: string;
    delegationDepth?: number;
    authenticationContext?: Record<string, unknown>;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
agentId	property	agentId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
authenticationContext	property	authenticationContext?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
delegatedBy	property	delegatedBy?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
delegationDepth	property	delegationDepth?: number	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.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
permissionScopes	property	permissionScopes: readonly string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
principalId	property	principalId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
roles	property	roles?: readonly string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
tenantId	property	tenantId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
type	property	type: "system" | "agent" | "user" | "service"	Public property; its type, readonly modifier and optionality are shown in the signature.
userId	property	userId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
workspaceId	property	workspaceId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolProfileSpec

Tool Profile Spec interface with 11 public fields or methods.

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

Declaration

export interface ToolProfileSpec extends VersionedSpec {
    toolRefs: SpecRef[];
    mcpProfileRefs?: SpecRef[];
    policyRefs?: SpecRef[];
    defaultPermissionScopes?: string[];
    contractSnapshotMode?: 'run' | 'state';
    lazyLoad?: boolean;
    maxLoadedTools?: number;
    metadata?: Record<string, unknown>;
    /** @deprecated Register Tool contracts separately and use toolRefs. */
    tools?: ToolSpec[];
}

Contract members

Member	Kind	Signature	Description
contractSnapshotMode	property	contractSnapshotMode?: "run" | "state"	Public property; its type, readonly modifier and optionality are shown in the signature.
defaultPermissionScopes	property	defaultPermissionScopes?: 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.
lazyLoad	property	lazyLoad?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
maxLoadedTools	property	maxLoadedTools?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
mcpProfileRefs	property	mcpProfileRefs?: SpecRef[]	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
policyRefs	property	policyRefs?: SpecRef[]	Public property; its type, readonly modifier and optionality are shown in the signature.
toolRefs	property	toolRefs: SpecRef[]	Public property; its type, readonly modifier and optionality are shown in the signature.
tools	property	tools?: ToolSpec[]	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.

ToolProgressUpdate

Tool Progress Update interface with 6 public fields or methods.

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

Declaration

export interface ToolProgressUpdate {
    message?: string;
    current?: number;
    total?: number;
    percentage?: number;
    stage?: string;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
current	property	current?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
message	property	message?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
percentage	property	percentage?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
stage	property	stage?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
total	property	total?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolReceiptReconciler

Tool Receipt Reconciler interface with 1 public fields or methods.

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

Declaration

export interface ToolReceiptReconciler {
    reconcile(request: {
        invocationId: string;
        tool: ResolvedToolSpec;
        call: ToolCallRequest;
        attempt: number;
    }): Promise<ToolReceiptReconciliation>;
}

Contract members

Member	Kind	Signature	Description
reconcile	method	reconcile(request: { invocationId: string; tool: ResolvedToolSpec; call: ToolCallRequest; attempt: number; }): Promise<ToolReceiptReconciliation>	Public method; parameters and return type are shown in the signature.

ToolReceiptReconciliation

Tool Receipt Reconciliation interface with 3 public fields or methods.

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

Declaration

export interface ToolReceiptReconciliation {
    state: 'committed' | 'not_committed' | 'unknown';
    receipt?: ToolExternalReceipt;
    details?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
details	property	details?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
receipt	property	receipt?: ToolExternalReceipt	Public property; its type, readonly modifier and optionality are shown in the signature.
state	property	state: "unknown" | "committed" | "not_committed"	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolResultCache

Tool Result Cache interface with 3 public fields or methods.

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

Declaration

export interface ToolResultCache {
    get(key: string): Promise<ToolResultCacheEntry | null>;
    set(entry: ToolResultCacheEntry): Promise<void>;
    delete?(key: string): Promise<void>;
}

Contract members

Member	Kind	Signature	Description
delete	method	delete?(key: string): Promise<void>	Public method; parameters and return type are shown in the signature.
get	method	get(key: string): Promise<ToolResultCacheEntry | null>	Public method; parameters and return type are shown in the signature.
set	method	set(entry: ToolResultCacheEntry): Promise<void>	Public method; parameters and return type are shown in the signature.

ToolResultCacheArtifactVerifier

Tool Result Cache Artifact Verifier interface with 1 public fields or methods.

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

Declaration

export interface ToolResultCacheArtifactVerifier {
    verify(request: {
        toolId: string;
        artifactRefs: readonly string[];
        tenantId?: string;
        userId?: string;
        workspaceId?: string;
    }): Promise<boolean>;
}

Contract members

Member	Kind	Signature	Description
verify	method	verify(request: { toolId: string; artifactRefs: readonly string[]; tenantId?: string; userId?: string; workspaceId?: string; }): Promise<boolean>	Public method; parameters and return type are shown in the signature.

ToolResultCacheEntry

Tool Result Cache Entry interface with 5 public fields or methods.

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

Declaration

export interface ToolResultCacheEntry {
    schemaVersion: '1.0';
    keyVersion: '1';
    validity: ToolCacheValidityRecord;
    result: ToolCachedResultProjection;
    createdAt: string;
}

Contract members

Member	Kind	Signature	Description
createdAt	property	createdAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
keyVersion	property	keyVersion: "1"	Public property; its type, readonly modifier and optionality are shown in the signature.
result	property	result: ToolCachedResultProjection	Public property; its type, readonly modifier and optionality are shown in the signature.
schemaVersion	property	schemaVersion: "1.0"	Public property; its type, readonly modifier and optionality are shown in the signature.
validity	property	validity: ToolCacheValidityRecord	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolRunner

Tool Runner interface with 2 public fields or methods.

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

Declaration

export interface ToolRunner {
    run(request: ToolCallRequest): Promise<ToolCallResult>;
    cancelInvocation?(invocationId: string, reason?: string): Promise<ToolCallResult | null>;
}

Contract members

Member	Kind	Signature	Description
cancelInvocation	method	cancelInvocation?(invocationId: string, reason?: string): Promise<ToolCallResult | null>	Public method; parameters and return type are shown in the signature.
run	method	run(request: ToolCallRequest): Promise<ToolCallResult>	Public method; parameters and return type are shown in the signature.

ToolSchemaValidationIssue

Tool Schema Validation Issue interface with 2 public fields or methods.

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

Declaration

export interface ToolSchemaValidationIssue {
    path: string;
    message: string;
}

Contract members

Member	Kind	Signature	Description
message	property	message: string	Public property; its type, readonly modifier and optionality are shown in the signature.
path	property	path: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolSchemaValidationResult

Tool Schema Validation Result interface with 3 public fields or methods.

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

Declaration

export interface ToolSchemaValidationResult {
    valid: boolean;
    error?: string;
    issues: ToolSchemaValidationIssue[];
}

Contract members

Member	Kind	Signature	Description
error	property	error?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
issues	property	issues: ToolSchemaValidationIssue[]	Public property; its type, readonly modifier and optionality are shown in the signature.
valid	property	valid: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolSpec

Tool Spec interface with 33 public fields or methods.

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

Declaration

export interface ToolSpec {
    id: string;
    version: string;
    revision?: string;
    name?: string;
    displayName?: string;
    description: string;
    instructions?: string;
    tags?: string[];
    inputSchema: JsonSchema;
    outputSchema?: JsonSchema;
    input?: ToolSchemaSpec;
    output?: ToolSchemaSpec;
    sideEffectLevel: SideEffectLevel;
    permissionScope?: string[];
    preconditions?: string[];
    postconditions?: string[];
    timeoutPolicy?: TimeoutPolicySpec;
    retryPolicy?: RetryPolicySpec;
    auditPolicy?: AuditPolicySpec;
    humanApprovalPolicy?: HumanReviewPolicySpec;
    idempotencyPolicy?: {
        mode: 'none' | 'optional' | 'required';
    };
    source?: ToolSource;
    sourceRef?: {
        serverId?: string;
        capabilityId?: string;
        capabilityHash?: string;
        trustLevel?: 'trusted' | 'reviewed' | 'untrusted';
        declarationSource?: 'framework' | 'user' | 'server' | 'unknown';
    } & ToolSourceRef;
    semantics?: ToolSemanticSpec;
    execution?: ToolExecutionPolicySpec;
    governance?: ToolGovernanceSpec;
    observability?: ToolObservabilitySpec;
    cache?: ToolCachePolicySpec;
    streaming?: ToolStreamingSpec;
    enabled?: boolean;
    deprecated?: boolean;
    replacedBy?: {
        id: string;
        version?: string;
        revision?: string;
    };
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
auditPolicy	property	auditPolicy?: AuditPolicySpec	Public property; its type, readonly modifier and optionality are shown in the signature.
cache	property	cache?: ToolCachePolicySpec	Public property; its type, readonly modifier and optionality are shown in the signature.
deprecated	property	deprecated?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
description	property	description: string	Public property; its type, readonly modifier and optionality are shown in the signature.
displayName	property	displayName?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
enabled	property	enabled?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
execution	property	execution?: ToolExecutionPolicySpec	Public property; its type, readonly modifier and optionality are shown in the signature.
governance	property	governance?: ToolGovernanceSpec	Public property; its type, readonly modifier and optionality are shown in the signature.
humanApprovalPolicy	property	humanApprovalPolicy?: HumanReviewPolicySpec	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.
idempotencyPolicy	property	idempotencyPolicy?: { mode: "none" | "optional" | "required"; }	Public property; its type, readonly modifier and optionality are shown in the signature.
input	property	input?: ToolSchemaSpec	Public property; its type, readonly modifier and optionality are shown in the signature.
inputSchema	property	inputSchema: JsonSchema	Public property; its type, readonly modifier and optionality are shown in the signature.
instructions	property	instructions?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
name	property	name?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
observability	property	observability?: ToolObservabilitySpec	Public property; its type, readonly modifier and optionality are shown in the signature.
output	property	output?: ToolSchemaSpec	Public property; its type, readonly modifier and optionality are shown in the signature.
outputSchema	property	outputSchema?: JsonSchema	Public property; its type, readonly modifier and optionality are shown in the signature.
permissionScope	property	permissionScope?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
postconditions	property	postconditions?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
preconditions	property	preconditions?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
replacedBy	property	replacedBy?: { id: string; version?: string; revision?: string; }	Public property; its type, readonly modifier and optionality are shown in the signature.
retryPolicy	property	retryPolicy?: RetryPolicySpec	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.
semantics	property	semantics?: ToolSemanticSpec	Public property; its type, readonly modifier and optionality are shown in the signature.
sideEffectLevel	property	sideEffectLevel: SideEffectLevel	Public property; its type, readonly modifier and optionality are shown in the signature.
source	property	source?: ToolSource	Public property; its type, readonly modifier and optionality are shown in the signature.
sourceRef	property	sourceRef?: { serverId?: string; capabilityId?: string; capabilityHash?: string; trustLevel?: "trusted" | "reviewed" | "untrusted"; declarationSource?: "framework" | "user" | "server" | "unknown"; } & ToolSourceRef	Public property; its type, readonly modifier and optionality are shown in the signature.
streaming	property	streaming?: ToolStreamingSpec	Public property; its type, readonly modifier and optionality are shown in the signature.
tags	property	tags?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
timeoutPolicy	property	timeoutPolicy?: TimeoutPolicySpec	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.

ToolTargetResolution

Tool Target Resolution interface with 3 public fields or methods.

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

Declaration

export interface ToolTargetResolution {
    toolId: string;
    input: unknown;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
input	property	input: unknown	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
toolId	property	toolId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ToolTargetResolver

Tool Target Resolver interface with 1 public fields or methods.

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

Declaration

export interface ToolTargetResolver {
    resolve(request: ToolCallRequest, registry: ToolRegistry): Promise<ToolTargetResolution>;
}

Contract members

Member	Kind	Signature	Description
resolve	method	resolve(request: ToolCallRequest, registry: ToolRegistry): Promise<ToolTargetResolution>	Public method; parameters and return type are shown in the signature.

MockToolHandler

Public type alias for Mock Tool Handler; the declaration contains its complete type expression.

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

Declaration

export type MockToolHandler = (request: ToolCallRequest) => Promise<ToolCallResult> | ToolCallResult;

ResolvedToolSpec

Public type alias for Resolved Tool Spec; the declaration contains its complete type expression.

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

Declaration

export type ResolvedToolSpec = ToolSpec & GovernedToolContractSpec;

ToolExecutionPhase

Public type alias for Tool Execution Phase; the declaration contains its complete type expression.

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

Declaration

export type ToolExecutionPhase = 'resolution' | 'authorization' | 'input_validation' | 'policy' | 'approval' | 'execution' | 'timeout' | 'output_validation';

ToolHandler

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

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

Declaration

export type ToolHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context: ToolCallContext) => Promise<TOutput>;

ToolInvocationPatch

Public type alias for Tool Invocation Patch; the declaration contains its complete type expression.

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

Declaration

export type ToolInvocationPatch = Partial<Pick<ToolInvocationRecord, 'status' | 'executionCycle' | 'attemptCount' | 'result' | 'approvalRequest' | 'updatedAt' | 'startedAt' | 'completedAt' | 'lateResultState' | 'outputHash' | 'artifactRefs' | 'observationRefs' | 'externalReceipt'>>;

ToolInvocationStatus

Public type alias for Tool Invocation Status; the declaration contains its complete type expression.

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

Declaration

export type ToolInvocationStatus = (typeof TOOL_INVOCATION_STATUSES)[number];

ToolResultContent

Public type alias for Tool Result Content; the declaration contains its complete type expression.

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

Declaration

export type ToolResultContent = {
    type: 'text';
    text: string;
} | {
    type: 'json';
    value: unknown;
} | {
    type: 'image';
    artifactRef?: string;
    url?: string;
    mimeType?: string;
    alt?: string;
} | {
    type: 'resource';
    uri: string;
    mimeType?: string;
    title?: string;
} | {
    type: 'artifact';
    artifactRef: string;
    title?: string;
    mimeType?: string;
};