Tools API

Generated public TypeScript reference for @relkit/tools.

Common APIs

• defineTool

For configuration and examples, read tools, organization, ai.

For a complete workflow, follow build an offline agent.

Public imports

• @relkit/tools — 55 exports

All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API’s inline sample, a maintained repository usage, or the shared module walkthrough.

define-tool-predicates.ts

assertToolDescriptor

Asserts a tool descriptor.

Throws

TypeError when the value is not a tool descriptor.

Example

assertToolDescriptor(value);

Signature

declare const assertToolDescriptor: (value: unknown) => asserts value is ToolDescriptor<string>;

Source

assertToolDescriptorEffect

Asserts a tool descriptor through Effect.

Example

Effect.runSync(assertToolDescriptorEffect(tool));

Signature

declare const assertToolDescriptorEffect: (
  value: unknown,
) => Effect.Effect<ToolDescriptor<string>, ToolOperationFailure, never>;

Source

isToolDescriptor

Checks a descriptor.

Example

if (isToolDescriptor(value)) await value.invoke({});

Signature

declare const isToolDescriptor: (value: unknown) => value is ToolDescriptor<string>;

Source

isToolDescriptorEffect

Checks a descriptor through Effect.

Example

Effect.runSync(isToolDescriptorEffect(tool));

Signature

declare const isToolDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

isToolRef

Checks a tool reference.

Example

isToolRef({ ref: { kind: "tool", id: "orders.lookup" } });

Signature

declare const isToolRef: (value: unknown) => value is ToolRefAny;

Source

isToolRefEffect

Checks a tool reference through Effect.

Example

Effect.runSync(isToolRefEffect({ ref: { kind: "tool", id: "orders.lookup" } }));

Signature

declare const isToolRefEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

define-tool-validation.ts

copyFunctionTarget

Copies a validated function target.

Throws

TypeError when the target is malformed.

Example

copyFunctionTarget(target);

Signature

declare const copyFunctionTarget: <Target extends FunctionRefAny>(
  target: Target,
) => FunctionToolTarget<Target>;

Source

copyFunctionTargetEffect

Copies and freezes a function target through Effect.

Example

Effect.runSync(copyFunctionTargetEffect(target));

Signature

declare const copyFunctionTargetEffect: <Target extends FunctionRefAny>(
  target: Target,
) => Effect.Effect<FunctionToolTarget<Target>, ToolOperationFailure, never>;

Source

hasOwn

Signature

declare const hasOwn: (value: object, key: PropertyKey) => boolean;

Source

hasOwnEffect

Signature

declare const hasOwnEffect: (
  value: object,
  key: PropertyKey,
) => Effect.Effect<boolean, never, never>;

Source

isFunctionTarget

Signature

declare const isFunctionTarget: (
  value: unknown,
) => value is import("@relkit/functions").FunctionRefAny;

Source

isFunctionTargetEffect

Signature

declare const isFunctionTargetEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

isNonEmptyString

Signature

declare const isNonEmptyString: (value: unknown) => value is string;

Source

isNonEmptyStringEffect

Signature

declare const isNonEmptyStringEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

isPositiveInteger

Signature

declare const isPositiveInteger: (value: unknown) => value is number;

Source

isPositiveIntegerEffect

Signature

declare const isPositiveIntegerEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

isRecord

Signature

declare const isRecord: (value: unknown) => value is Record<PropertyKey, unknown>;

Source

isRecordEffect

Signature

declare const isRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

isToolApproval

Signature

declare const isToolApproval: (
  value: unknown,
) => value is import("./define-tool.types.js").ToolApproval;

Source

isToolApprovalEffect

Signature

declare const isToolApprovalEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

isToolSideEffect

Signature

declare const isToolSideEffect: (
  value: unknown,
) => value is import("./define-tool.types.js").ToolSideEffect;

Source

isToolSideEffectEffect

Signature

declare const isToolSideEffectEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

positiveInteger

Asserts a safe positive integer.

Throws

TypeError when the value is invalid.

Example

positiveInteger(5, "timeoutMs");

Signature

declare const positiveInteger: (value: unknown, name: string) => asserts value is number;

Source

positiveIntegerEffect

Requires a safe positive integer through Effect.

Example

Effect.runSync(positiveIntegerEffect(5, "timeoutMs"));

Signature

declare const positiveIntegerEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<number, ToolOperationFailure, never>;

Source

requiredText

Requires nonempty trimmed text.

Throws

TypeError when the value is empty.

Example

requiredText(" read ", "description");

Signature

declare const requiredText: (value: unknown, name: string) => string;

Source

requiredTextEffect

Requires nonempty trimmed text through Effect.

Example

Effect.runSync(requiredTextEffect(" read ", "description"));

Signature

declare const requiredTextEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<string, ToolOperationFailure, never>;

Source

validateApproval

Validates a tool approval policy.

Throws

TypeError when the policy is unknown.

Example

validateApproval("never");

Signature

declare const validateApproval: (value: unknown) => ToolApproval;

Source

validateApprovalEffect

Validates a tool approval policy through Effect.

Example

Effect.runSync(validateApprovalEffect("never"));

Signature

declare const validateApprovalEffect: (
  value: unknown,
) => Effect.Effect<FunctionToolApproval, ToolOperationFailure, never>;

Source

validateSideEffect

Validates a tool side-effect policy.

Throws

TypeError when the policy is unknown.

Example

validateSideEffect("read");

Signature

declare const validateSideEffect: (value: unknown) => ToolSideEffect;

Source

validateSideEffectEffect

Validates a tool side-effect policy through Effect.

Example

Effect.runSync(validateSideEffectEffect("read"));

Signature

declare const validateSideEffectEffect: (
  value: unknown,
) => Effect.Effect<FunctionToolSideEffect, ToolOperationFailure, never>;

Source

define-tool.ts

defineTool

Defines a frozen, handler-free tool view over one function.

Throws

TypeError for malformed target, metadata, or ID.

Example

import { defineFunction } from "@relkit/functions";
import { z } from "@relkit/schema";
import { defineTool } from "@relkit/tools";
const lookup = defineFunction({
  id: "orders.lookup",
  input: z.string(),
  output: z.string(),
  handler: (id) => id,
});
const tool = defineTool({
  id: "orders.lookup-tool",
  target: lookup,
  description: "Read order",
  sideEffect: "read",
  approval: "never",
});

Signature

declare const defineTool: <const Id extends string, const Target extends FunctionRefAny>(
  options: DefineToolOptions<Id, Target>,
) => ToolDescriptor<Id, Target>;

Source

Since v0.1.0

“./define-tool.types.js” (namespace export)

Re-exports all named exports from the “./define-tool.types.js” module.

Signature

export * from "./define-tool.types.js";

Source

ToolApprovalDeniedError

Signature

declare const ToolApprovalDeniedError: typeof FunctionToolApprovalDeniedError;

Source

ToolApprovalRequiredError

Signature

declare const ToolApprovalRequiredError: typeof FunctionToolApprovalRequiredError;

Source

ToolArgumentValidationError

Signature

declare const ToolArgumentValidationError: typeof FunctionToolArgumentValidationError;

Source

ToolOperationCancelledError

Signature

declare const ToolOperationCancelledError: typeof FunctionToolOperationCancelledError;

Source

assertToolDescriptor

Signature

declare const assertToolDescriptor: (value: unknown) => asserts value is ToolDescriptor<string>;

Source

assertToolDescriptorEffect

Signature

declare const assertToolDescriptorEffect: (
  value: unknown,
) => Effect.Effect<ToolDescriptor<string>, ToolOperationFailure, never>;

Source

defineToolEffect

Defines a frozen, handler-free tool view through Effect.

Example

Effect.runSync(
  defineToolEffect({
    id: "orders.lookup",
    target,
    description: "Read order",
    sideEffect: "read",
    approval: "never",
  }),
);

Signature

declare const defineToolEffect: <const Id extends string, const Target extends FunctionRefAny>(
  options: DefineToolOptions<Id, Target>,
) => Effect.Effect<ToolDescriptor<Id, Target>, ToolOperationFailure, never>;

Source

isToolDescriptor

Signature

declare const isToolDescriptor: (value: unknown) => value is ToolDescriptor<string>;

Source

isToolDescriptorEffect

Signature

declare const isToolDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

isToolRef

Signature

declare const isToolRef: (value: unknown) => value is ToolRefAny;

Source

isToolRefEffect

Signature

declare const isToolRefEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

define-tool.types.ts

DefineToolOptions (interface)

Authoring options for a handler-free tool view.

Example

const options: DefineToolOptions<"orders.lookup", typeof target> = {
  id: "orders.lookup",
  target,
  description: "Read an order",
  sideEffect: "read",
  approval: "never",
};

Signature

export interface DefineToolOptions<
  Id extends string,
  Target extends FunctionRefAny,
> extends FunctionToolMetadata {
  readonly id?: Id;
  readonly target: Target;
  readonly onBefore?: import("@relkit/functions").FunctionToolHook<
    import("@relkit/schema").InferInput<Target["input"]>
  >;
  readonly onAfter?: import("@relkit/functions").FunctionToolHook<
    import("@relkit/schema").InferOutput<Target["output"]>
  >;
}

Source

ToolApproval (type alias)

Approval policy inherited from a function tool.

Signature

type ToolApproval = FunctionToolApproval;

Source

ToolApprovalDecision (type alias)

Decision returned by a tool approval resolver.

Signature

type ToolApprovalDecision = FunctionToolApprovalDecision;

Source

ToolApprovalRequest (type alias)

Request passed to a tool approval resolver.

Signature

type ToolApprovalRequest = FunctionToolApprovalRequest;

Source

ToolApprovalResolver (type alias)

Resolver for tool approval requests.

Signature

type ToolApprovalResolver = FunctionToolApprovalResolver;

Source

ToolDescriptor (type alias)

Frozen, handler-free tool descriptor.

Example

const descriptor: ToolDescriptor<"orders.lookup.tool"> = defineTool(options);

Signature

type ToolDescriptor<
  Id extends string,
  Target extends FunctionRefAny = FunctionRefAny,
> = FunctionToolDescriptor<Id, Target>;

Source

ToolInvokeOptions (type alias)

Options for invoking the function view of a tool.

Signature

type ToolInvokeOptions = FunctionToolInvokeOptions;

Source

ToolRef (interface)

Stable reference to a tool descriptor.

Example

const ref: ToolRef<"orders.lookup"> = { ref: { kind: "tool", id: "orders.lookup" } };

Signature

export interface ToolRef<Id extends string = string> {
  readonly ref: { readonly kind: "tool"; readonly id: Id };
}

Source

ToolRefAny (type alias)

Any stable tool reference.

Signature

type ToolRefAny = ToolRef;

Source

ToolSideEffect (type alias)

Effect policy inherited from a function tool.

Signature

type ToolSideEffect = FunctionToolSideEffect;

Source

ToolTarget (type alias)

Validated function target copied into a tool.

Example

const copied: ToolTarget<typeof target> = copyFunctionTarget(target);

Signature

type ToolTarget<Target extends FunctionRefAny> = FunctionToolTarget<Target>;

Source

index.ts

“./define-tool.js” (namespace export)

Re-exports all named exports from the “./define-tool.js” module.

Signature

export * from "./define-tool.js";

Source

“./runtime.js” (namespace export)

Re-exports all named exports from the “./runtime.js” module.

Signature

export * from "./runtime.js";

Source

ToolOperation

Signature

declare const ToolOperation: ToolOperation;

Source

ToolOperationFailure

Signature

declare const ToolOperationFailure: typeof ToolOperationFailure;

Source

ToolTelemetry

Signature

declare const ToolTelemetry: typeof ToolTelemetry;

Source

ToolTelemetryLive

Signature

declare const ToolTelemetryLive: Layer<ToolTelemetry, never, never>;

Source

ToolTelemetryService

Signature

declare const ToolTelemetryService: ToolTelemetryService;

Source

observeTool

Signature

declare const observeTool: <A, E, R>(
  operation: ToolOperation,
  effect: Effect<A, E, R>,
) => Effect<A, E, R>;

Source

runtime-engine.ts

ToolEngineLive

Provides a common engine to an Effect invocation.

Throws

Unexpected construction defects.

Example

ToolEngineLive({ invoke: async ({ input }) => input });

Signature

declare const ToolEngineLive: (engine: ToolEngine) => Layer.Layer<ToolEngineService, never, never>;

Source

ToolEngineLiveEffect

Constructs a composable engine Layer through Effect.

Example

Effect.runSync(ToolEngineLiveEffect(engine));

Signature

declare const ToolEngineLiveEffect: (
  engine: ToolEngine,
) => Effect.Effect<Layer.Layer<ToolEngineService, never, never>, never, never>;

Source

ToolEngineService (class)

Replaceable engine used by Effect tool invocation.

Example

Effect.provide(invokeToolEffect(request), ToolEngineLive(engine));

Signature

declare class ToolEngineService

Source

runtime-errors.ts

ToolArgumentValidationError

Signature

declare const ToolArgumentValidationError: typeof ToolArgumentValidationError;

Source

ToolArgumentsFailure (class)

Tagged Effect failure for malformed JSON or schema validation.

Example

Effect.catchTag(invokeToolEffect(request), "ToolArgumentsFailure", () => Effect.void);

Signature

declare class ToolArgumentsFailure

Source

ToolCancelledFailure (class)

Tagged Effect failure for cancellation before engine dispatch.

Example

Effect.catchTag(invokeToolEffect(request), "ToolCancelledFailure", () => Effect.void);

Signature

declare class ToolCancelledFailure

Source

ToolEngineFailure (class)

Tagged Effect failure from the common engine boundary.

Example

Effect.catchTag(invokeToolEffect(request), "ToolEngineFailure", () => Effect.void);

Signature

declare class ToolEngineFailure

Source

ToolNotAllowedError (class)

Compatibility error for a registered tool excluded by policy.

Example

throw new ToolNotAllowedError("orders.delete");

Signature

declare class ToolNotAllowedError { constructor(readonly toolId: string) }

Source

code (property)

Signature

readonly code: "RELKIT_TOOL_NOT_ALLOWED"

Source

ToolNotAllowedFailure (class)

Tagged Effect failure for a tool excluded by the allowlist.

Example

Effect.catchTag(invokeToolEffect(request), "ToolNotAllowedFailure", () => Effect.void);

Signature

declare class ToolNotAllowedFailure

Source

ToolOperationCancelledError

Signature

declare const ToolOperationCancelledError: typeof ToolOperationCancelledError;

Source

ToolUnknownError (class)

Compatibility error for a tool ID absent from the registered source.

Example

throw new ToolUnknownError("orders.missing");

Signature

declare class ToolUnknownError { constructor(readonly toolId: string) }

Source

code (property)

Signature

readonly code: "RELKIT_TOOL_UNKNOWN"

Source

ToolUnknownFailure (class)

Tagged Effect failure for an unknown registered tool.

Example

Effect.catchTag(invokeToolEffect(request), "ToolUnknownFailure", () => Effect.void);

Signature

declare class ToolUnknownFailure

Source

runtime-input.ts

parseToolArgumentsEffect

Parses a model-returned argument value through Effect.

Example

Effect.runSync(parseToolArgumentsEffect('{"id":1}'));

Signature

declare const parseToolArgumentsEffect: (
  value: unknown,
) => Effect.Effect<unknown, ToolArgumentsFailure, never>;

Source

validateToolArgumentsEffect

Validates tool input through the inherited standard schema.

Example

await Effect.runPromise(validateToolArgumentsEffect(schema, { id: 1 }));

Signature

declare const validateToolArgumentsEffect: (
  schema: StandardSchemaV1<unknown, unknown>,
  value: unknown,
) => Effect.Effect<void, ToolArgumentsFailure, never>;

Source

runtime-resolution.ts

findToolEffect

Finds a canonical descriptor in any supported collection.

Example

Effect.runSync(findToolEffect([tool], tool.id));

Signature

declare const findToolEffect: (
  source: ToolSource,
  id: string,
) => Effect.Effect<any, ToolOperationFailure, never>;

Source

isToolAllowedEffect

Checks a tool’s canonical ID against an allowlist.

Example

Effect.runSync(isToolAllowedEffect(tool.id, [tool.id]));

Signature

declare const isToolAllowedEffect: (
  id: string,
  allowlist: ReadonlyArray<ToolAllowlistEntry>,
) => Effect.Effect<boolean, ToolOperationFailure, never>;

Source

resolveToolTarget

Resolves a tool’s function ID and inherited schemas.

Throws

TypeError when the descriptor is invalid.

Example

resolveToolTarget(tool);

Signature

declare const resolveToolTarget: (tool: ToolDescriptor<string>) => ResolvedToolTarget;

Source

resolveToolTargetEffect

Resolves a tool’s function ID and inherited schemas through Effect.

Example

Effect.runSync(resolveToolTargetEffect(tool));

Signature

declare const resolveToolTargetEffect: (tool: ToolDescriptor<string>) => Effect.Effect<
  Readonly<{
    errors?: ReadonlyArray<ErrorDescriptorAny>;
    functionId: string;
    input: StandardSchemaV1<unknown, unknown>;
    output: StandardSchemaV1<unknown, unknown>;
  }>,
  ToolOperationFailure,
  never
>;

Source

runtime.ts

“./runtime.types.js” (namespace export)

Re-exports all named exports from the “./runtime.types.js” module.

Signature

export * from "./runtime.types.js";

Source

ToolArgumentValidationError

Signature

declare const ToolArgumentValidationError: typeof FunctionToolArgumentValidationError;

Source

ToolArgumentsFailure

Signature

declare const ToolArgumentsFailure: typeof ToolArgumentsFailure;

Source

ToolCancelledFailure

Signature

declare const ToolCancelledFailure: typeof ToolCancelledFailure;

Source

ToolEngineFailure

Signature

declare const ToolEngineFailure: typeof ToolEngineFailure;

Source

ToolEngineLive

Signature

declare const ToolEngineLive: (engine: ToolEngine) => Layer<ToolEngineService, never, never>;

Source

ToolEngineLiveEffect

Signature

declare const ToolEngineLiveEffect: (
  engine: ToolEngine,
) => Effect.Effect<Layer<ToolEngineService, never, never>, never, never>;

Source

ToolEngineService

Signature

declare const ToolEngineService: typeof ToolEngineService;

Source

ToolNotAllowedError

Signature

declare const ToolNotAllowedError: typeof ToolNotAllowedError;

Source

ToolNotAllowedFailure

Signature

declare const ToolNotAllowedFailure: typeof ToolNotAllowedFailure;

Source

ToolOperationCancelledError

Signature

declare const ToolOperationCancelledError: typeof ToolOperationCancelledError;

Source

ToolUnknownError

Signature

declare const ToolUnknownError: typeof ToolUnknownError;

Source

ToolUnknownFailure

Signature

declare const ToolUnknownFailure: typeof ToolUnknownFailure;

Source

createToolRuntime

Creates a reusable Promise runtime.

Throws

Unexpected defects from runtime construction.

Example

const runtime = createToolRuntime({ tools: [tool], engine });

Signature

declare const createToolRuntime: (options: ToolRuntimeOptions) => ToolRuntime;

Source

createToolRuntimeEffect

Creates a reusable compatibility runtime through Effect. The allowlist is copied at creation; the caller retains ownership of tools and engine.

Example

Effect.runSync(createToolRuntimeEffect({ tools: [tool], engine }));

Signature

declare const createToolRuntimeEffect: (
  options: ToolRuntimeOptions,
) => Effect.Effect<ToolRuntime, never, never>;

Source

invokeTool

Invokes one allowlisted tool through the common engine.

Throws

ToolUnknownError, ToolNotAllowedError, argument errors, or engine rejection.

Example

await invokeTool({ tools: [tool], engine, toolId: "orders.lookup", arguments: {} });

Signature

declare const invokeTool: (options: ToolRuntimeOptions & ToolEffectOptions) => Promise<unknown>;

Source

invokeToolEffect

Invokes an allowlisted tool with a replaceable Effect engine service. Validation finishes before engine dispatch. Cancellation before dispatch prevents the engine from starting. Interruption and caller cancellation reach the engine through its invocation signal.

Example

await Effect.runPromise(
  Effect.provide(
    invokeToolEffect({ tools: [tool], toolId: "orders.lookup", arguments: {} }),
    ToolEngineLive(engine),
  ),
);

Signature

declare const invokeToolEffect: (
  options: ToolEffectOptions,
) => Effect.Effect<
  unknown,
  | ToolOperationFailure
  | ToolArgumentsFailure
  | ToolUnknownFailure
  | ToolNotAllowedFailure
  | ToolCancelledFailure
  | ToolEngineFailure,
  ToolEngineService
>;

Source

resolveToolTarget

Signature

declare const resolveToolTarget: (tool: ToolDescriptor<string>) => ResolvedToolTarget;

Source

resolveToolTargetEffect

Signature

declare const resolveToolTargetEffect: (tool: ToolDescriptor<string>) => Effect.Effect<
  Readonly<{
    errors?: ReadonlyArray<ErrorDescriptorAny>;
    functionId: string;
    input: StandardSchemaV1<unknown, unknown>;
    output: StandardSchemaV1<unknown, unknown>;
  }>,
  ToolOperationFailure,
  never
>;

Source

runtime.types.ts

ResolvedToolTarget (interface)

Function target and schemas resolved from a tool.

Example

const target: ResolvedToolTarget = resolveToolTarget(tool);

Signature

export interface ResolvedToolTarget {
  readonly functionId: string;
  readonly input: StandardSchemaV1;
  readonly output: StandardSchemaV1;
  readonly errors?: readonly ErrorDescriptorAny[];
}

Source

ToolAllowlistEntry (type alias)

One allowed tool ID or reference.

Example

const allowed: ToolAllowlistEntry = "orders.lookup.tool";

Signature

type ToolAllowlistEntry = string | ToolRefAny | ToolRefAny["ref"];

Source

ToolEffectOptions (type alias)

Effect invocation input; the engine arrives from ToolEngineService.

Example

const request: ToolEffectOptions = { tools: [tool], toolId: tool.id, arguments: {} };

Signature

type ToolEffectOptions = Omit<ToolRuntimeOptions, "engine"> & ToolInvocationRequest;

Source

ToolEngine (interface)

Small engine seam that keeps tools independent of the engine package.

Example

const engine: ToolEngine = { invoke: async (request) => request.input };

Signature

export interface ToolEngine {
  /** Invoke a validated target through the common engine.
   * @param options - Target schemas, input, and inherited invocation context.
   * @returns The function output or an engine rejection.
   * @example await engine.invoke(invocation);
   */
  readonly invoke: (options: ToolEngineInvocation) => Promise<unknown>;
}

Source

ToolEngineInvocation (interface)

Invocation forwarded to the common function engine.

Example

const invocation: ToolEngineInvocation = {
  functionId: "orders.lookup",
  input: {},
  source: "tool",
  inputSchema,
  outputSchema,
};

Signature

export interface ToolEngineInvocation {
  readonly functionId: string;
  readonly input: unknown;
  readonly source: "tool";
  readonly inputSchema: StandardSchemaV1;
  readonly outputSchema: StandardSchemaV1;
  readonly errors?: readonly ErrorDescriptorAny[];
  readonly timeoutMs?: number;
  readonly signal?: AbortSignal;
  readonly hooks?: unknown;
  readonly toolHooks?: unknown;
  readonly progressSink?: ProgressSink;
  readonly parent?: unknown;
}

Source

ToolInvocationContext (interface)

Optional cancellation context for a runtime call.

Example

const context: ToolInvocationContext = { signal: controller.signal };

Signature

export interface ToolInvocationContext {
  readonly signal?: AbortSignal;
}

Source

ToolInvocationRequest (interface)

Input for one engine-backed tool invocation.

Example

const request: ToolInvocationRequest = { toolId: "orders.lookup", arguments: {} };

Signature

export interface ToolInvocationRequest {
  readonly toolId: string;
  /** Parsed JSON or model-returned JSON text. */
  readonly arguments: unknown;
  readonly signal?: AbortSignal;
  readonly hooks?: unknown;
  readonly parent?: unknown;
}

Source

ToolRuntime (interface)

Reusable Promise compatibility runtime.

Example

await runtime.invoke("orders.lookup", { id: "a" });

Signature

export interface ToolRuntime {
  /** Invoke one registered tool.
   * @param toolId - Canonical tool ID.
   * @param arguments_ - Parsed input or JSON text.
   * @param options - Optional cancellation context.
   * @returns Engine output or a rejected compatibility error.
   * @example await runtime.invoke("orders.lookup.tool", { id: "one" });
   */
  readonly invoke: (
    toolId: string,
    arguments_: unknown,
    options?: ToolInvocationContext,
  ) => Promise<unknown>;
}

Source

ToolRuntimeOptions (interface)

Runtime dependencies and optional allowlist.

Example

const options: ToolRuntimeOptions = { tools: [tool], engine };

Signature

export interface ToolRuntimeOptions {
  readonly tools: ToolSource;
  readonly engine: ToolEngine;
  readonly allowedTools?: readonly ToolAllowlistEntry[];
}

Source

ToolSource (type alias)

Supported tool collections.

Example

const tools: ToolSource = [tool];

Signature

type ToolSource =
  | readonly ToolDescriptor<string>[]
  | ReadonlyMap<string, ToolDescriptor<string>>
  | Readonly<Record<string, ToolDescriptor<string>>>;

Source

tool-observability.ts

ToolOperation

Signature

declare const ToolOperation: ToolOperation;

Source

ToolOperationFailure (class)

Expected tool input or authoring failure with the original adapter error.

Example

Effect.catchTag(defineToolEffect(options), "ToolOperationFailure", () => Effect.void);

Signature

declare class ToolOperationFailure

Source

ToolTelemetry (class)

Replaceable telemetry boundary for all tool operations.

Example

Effect.provide(defineToolEffect(options), ToolTelemetryLive);

Signature

declare class ToolTelemetry

Source

ToolTelemetryLive

Live Effect metric and span observer.

Example

Effect.runSync(Effect.provide(Effect.void, ToolTelemetryLive));

Signature

declare const ToolTelemetryLive: Layer.Layer<ToolTelemetry, never, never>;

Source

ToolTelemetryService

Signature

declare const ToolTelemetryService: ToolTelemetryService;

Source

observeTool

Adds bounded operation telemetry while preserving the original channels.

Example

observeTool("is-ref", Effect.succeed(true));

Signature

declare const observeTool: <A, E, R>(
  operation: ToolOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;

Source

runToolPromise

Runs a Promise compatibility adapter and restores its original error.

Throws

The original input error or an unexpected defect.

Example

await runToolPromise(Effect.succeed(1));

Signature

declare const runToolPromise: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;

Source

runToolSync

Runs a synchronous compatibility adapter and restores its original error.

Throws

The original input error or an unexpected defect.

Example

runToolSync(Effect.succeed(1));

Signature

declare const runToolSync: <A, E>(effect: Effect.Effect<A, E>) => A;

Source

toolAttempt

Evaluates a step within an already observed operation.

Example

yield * toolAttempt("define", () => descriptor);

Signature

declare const toolAttempt: <A>(
  operation: ToolOperation,
  evaluate: () => A,
) => Effect.Effect<A, ToolOperationFailure>;

Source

toolTry

Captures a marked validation error from a synchronous calculation.

Example

Effect.runSync(toolTry("required-text", () => "ok"));

Signature

declare const toolTry: <A>(
  operation: ToolOperation,
  evaluate: () => A,
) => Effect.Effect<A, ToolOperationFailure>;

Source

tool-observability.types.ts

ToolOperation (type alias)

Fixed names for tool operations; values must never contain user input.

Example

const operation: ToolOperation = "invoke";

Signature

type ToolOperation =
  | "define"
  | "is-descriptor"
  | "assert-descriptor"
  | "is-ref"
  | "copy-target"
  | "validate-side-effect"
  | "validate-approval"
  | "is-side-effect"
  | "is-approval"
  | "required-text"
  | "positive-integer"
  | "is-positive-integer"
  | "is-function-target"
  | "is-non-empty-string"
  | "is-record"
  | "has-own"
  | "resolve-target"
  | "engine-layer"
  | "invoke"
  | "create-runtime";

Source

ToolTelemetryService (interface)

Replaceable observer used to verify spans and metrics in tests.

Signature

export interface ToolTelemetryService {
  /** Observe an operation without changing its channels.
   * @param operation - Stable, bounded operation name.
   * @param effect - Work to observe.
   * @returns The same success and failure channels.
   * @example telemetry.observe("is-ref", Effect.succeed(true));
   */
  readonly observe: <A, E, R>(
    operation: ToolOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}

Source

tool-predicates.ts

hasOwn

Checks an own property.

Example

hasOwn({ id: 1 }, "id");

Signature

declare const hasOwn: (value: object, key: PropertyKey) => boolean;

Source

hasOwnEffect

Checks an own property through Effect.

Example

Effect.runSync(hasOwnEffect({ id: 1 }, "id"));

Signature

declare const hasOwnEffect: (
  value: object,
  key: PropertyKey,
) => Effect.Effect<boolean, never, never>;

Source

isFunctionTarget

Checks a function target.

Example

isFunctionTarget(target);

Signature

declare const isFunctionTarget: (
  value: unknown,
) => value is import("@relkit/functions").FunctionRefAny;

Source

isFunctionTargetEffect

Checks a function target through Effect.

Example

Effect.runSync(isFunctionTargetEffect(target));

Signature

declare const isFunctionTargetEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

isNonEmptyString

Checks a nonempty string.

Example

isNonEmptyString("hello");

Signature

declare const isNonEmptyString: (value: unknown) => value is string;

Source

isNonEmptyStringEffect

Checks a nonempty string through Effect.

Example

Effect.runSync(isNonEmptyStringEffect("hello"));

Signature

declare const isNonEmptyStringEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

isPositiveInteger

Checks a safe positive integer.

Example

isPositiveInteger(2);

Signature

declare const isPositiveInteger: (value: unknown) => value is number;

Source

isPositiveIntegerEffect

Checks a safe positive integer through Effect.

Example

Effect.runSync(isPositiveIntegerEffect(2));

Signature

declare const isPositiveIntegerEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

isRecord

Checks a plain non-array object.

Example

isRecord({ id: 1 });

Signature

declare const isRecord: (value: unknown) => value is Record<PropertyKey, unknown>;

Source

isRecordEffect

Checks a plain non-array object through Effect.

Example

Effect.runSync(isRecordEffect({ id: 1 }));

Signature

declare const isRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

isToolApproval

Checks a tool approval policy.

Example

isToolApproval("never");

Signature

declare const isToolApproval: (
  value: unknown,
) => value is import("./define-tool.types.js").ToolApproval;

Source

isToolApprovalEffect

Checks a tool approval policy through Effect.

Example

Effect.runSync(isToolApprovalEffect("never"));

Signature

declare const isToolApprovalEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source

isToolSideEffect

Checks a tool side-effect policy.

Example

isToolSideEffect("read");

Signature

declare const isToolSideEffect: (
  value: unknown,
) => value is import("./define-tool.types.js").ToolSideEffect;

Source

isToolSideEffectEffect

Checks a tool side-effect policy through Effect.

Example

Effect.runSync(isToolSideEffectEffect("read"));

Signature

declare const isToolSideEffectEffect: (value: unknown) => Effect.Effect<boolean, never, never>;

Source