Agents API

Generated public TypeScript reference for @relkit/agents.

Common APIs

• approveApproval
• denyApproval
• defineAgent

For configuration and examples, read approvals, agents, organization.

For a complete workflow, follow build an offline agent.

Frontend usage

Observe an agent and send controls shows the client side of this capability.

Public imports

• @relkit/agents — 182 exports
• @relkit/agents/client-events — 5 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.

agent-client-chat.ts

copyAgentChat

Copies a chat mapping for synchronous descriptor callers.

Throws

TypeError for a noncanonical mapping.

Example

import { copyAgentChat } from "@relkit/agents";

const chat = copyAgentChat({ input: "message", output: "answer" });
void chat;

Signature

declare const copyAgentChat: (value: unknown) => AgentChatMapping | undefined;

Source

copyAgentChatEffect

Validates the fixed chat input and output mapping.

Example

import { Effect } from "effect";
import { copyAgentChatEffect } from "@relkit/agents";

const chat = Effect.runSync(copyAgentChatEffect({ input: "message", output: "answer" }));
void chat;

Signature

declare const copyAgentChatEffect: (
  value: unknown,
) => Effect.Effect<
  Readonly<{ input: "message"; output: "answer" }> | undefined,
  AgentClientPolicyError,
  never
>;

Source

agent-client-controls.ts

copyAgentControls

Copies client controls for synchronous descriptor callers.

Throws

TypeError when an unsupported or duplicate control is present.

Example

import { copyAgentControls } from "@relkit/agents";

const controls = copyAgentControls(["stop"]);
void controls;

Signature

declare const copyAgentControls: (value: unknown) => readonly AgentControl[] | undefined;

Source

copyAgentControlsEffect

Validates and freezes client control capabilities.

Example

import { Effect } from "effect";
import { copyAgentControlsEffect } from "@relkit/agents";

const controls = Effect.runSync(copyAgentControlsEffect(["stop"]));
void controls;

Signature

declare const copyAgentControlsEffect: (
  value: unknown,
) => Effect.Effect<ReadonlyArray<AgentControl> | undefined, AgentClientPolicyError, never>;

Source

agent-client-error.ts

AgentClientPolicyError (class)

Expected client configuration failure in the Effect error channel.

Signature

declare class AgentClientPolicyError

Source

clientPolicyCount

Signature

declare const clientPolicyCount: Metric.Counter<number>;

Source

clientPolicyFailures

Signature

declare const clientPolicyFailures: Metric.Counter<number>;

Source

agent-client-policy.ts

copyAgentClientPolicy

Copies a client policy for synchronous descriptor callers.

Throws

TypeError for malformed access, state, or event declarations.

Example

import { copyAgentClientPolicy } from "@relkit/agents";

const policy = copyAgentClientPolicy({ public: true }, new Set<string>());
void policy;

Signature

declare const copyAgentClientPolicy: <StateKey extends string>(
  value: unknown,
  allowedStateKeys?: ReadonlySet<StateKey>,
) => AgentClientPolicy<(...args: any[]) => unknown, StateKey> | undefined;

Source

copyAgentClientPolicyEffect

Validates and freezes client access, state keys, and event schemas.

Example

import { Effect } from "effect";
import { copyAgentClientPolicyEffect } from "@relkit/agents";

const policy = Effect.runSync(copyAgentClientPolicyEffect({ public: true }, new Set<string>()));
void policy;

Signature

declare const copyAgentClientPolicyEffect: <StateKey extends string>(
  value: unknown,
  allowedStateKeys?: ReadonlySet<StateKey> | undefined,
) => Effect.Effect<
  | Readonly<{
      events?: Readonly<Record<string, StandardSchemaV1<unknown, unknown>>>;
      state?: ReadonlyArray<StateKey>;
      public: true;
    }>
  | Readonly<{
      events?: Readonly<Record<string, StandardSchemaV1<unknown, unknown>>>;
      state?: ReadonlyArray<StateKey>;
      authorize: (...args: any[]) => unknown;
    }>
  | undefined,
  AgentClientPolicyError,
  never
>;

Source

agent-client.ts

“./agent-client-chat.js” (namespace export)

Re-exports all named exports from the “./agent-client-chat.js” module.

Signature

export * from "./agent-client-chat.js";

Source

“./agent-client-controls.js” (namespace export)

Re-exports all named exports from the “./agent-client-controls.js” module.

Signature

export * from "./agent-client-controls.js";

Source

“./agent-client-error.js” (namespace export)

Re-exports all named exports from the “./agent-client-error.js” module.

Signature

export * from "./agent-client-error.js";

Source

“./agent-client-policy.js” (namespace export)

Re-exports all named exports from the “./agent-client-policy.js” module.

Signature

export * from "./agent-client-policy.js";

Source

AgentChatMapping

Signature

declare const AgentChatMapping: AgentChatMapping;

Source

AgentClientEvents

Signature

declare const AgentClientEvents: Readonly<Record<string, StandardSchemaV1<unknown, unknown>>>;

Source

AgentClientPolicy

Signature

declare const AgentClientPolicy: AgentClientPolicy<Guard, StateKey, Events>;

Source

AgentControl

Signature

declare const AgentControl: AgentControl;

Source

agent-client.types.ts

AgentChatMapping (interface)

Fixed input and output field mapping for an agent chat client.

Example

const chat: AgentChatMapping = { input: "message", output: "answer" };

Signature

export interface AgentChatMapping {
  readonly input: "message";
  readonly output: "answer";
}

Source

AgentClientEvents (type alias)

Named public events and their Standard Schema validators. Names must be nonempty before the policy is published.

Example

import { z } from "@relkit/schema";
const events: AgentClientEvents = { completed: z.string() };

Signature

type AgentClientEvents = Readonly<Record<string, StandardSchemaV1>>;

Source

AgentClientPolicy (type alias)

Client visibility, selected state, and public event schemas. Exactly one of public access and an authorization guard must be supplied.

Example

const policy: AgentClientPolicy = { public: true, state: ["answer"] };

Signature

type AgentClientPolicy<
  Guard = (...args: any[]) => unknown,
  StateKey extends string = string,
  Events extends AgentClientEvents = AgentClientEvents,
> = (
  | { readonly public: true; readonly authorize?: never }
  | { readonly authorize: Guard; readonly public?: never }
) & {
  readonly state?: readonly StateKey[];
  readonly events?: Events;
};

Source

AgentControl (type alias)

Durable control capabilities that may be exposed to an agent client.

Example

const control: AgentControl = "stop";

Signature

type AgentControl = "steer" | "follow-up" | "stop" | "approve";

Source

agent-telemetry.ts

AgentOperation

Signature

declare const AgentOperation: AgentOperation;

Source

AgentTelemetry (class)

Injectable telemetry boundary for agent operations.

Example

Effect.provide(observeAgent("capture.policy", Effect.void), AgentTelemetryLive);

Signature

declare class AgentTelemetry

Source

AgentTelemetryLive

Live metric observer for traced agent operations.

Example

Effect.runSync(Effect.provide(observeAgent("capture.policy", Effect.void), AgentTelemetryLive));

Signature

declare const AgentTelemetryLive: Layer.Layer<AgentTelemetry, never, never>;

Source

AgentTelemetryService

Signature

declare const AgentTelemetryService: AgentTelemetryService;

Source

observeAgent

Records a call, duration, and failure with a fixed operation label.

Example

observeAgent("capture.policy", Effect.succeed({ mode: "off" }));

Signature

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

Source

agent-telemetry.types.ts

AgentOperation (type alias)

Fixed operation labels for agent telemetry; no user value is a label.

Example

const operation: AgentOperation = "runtime.invoke-tool";

Signature

type AgentOperation =
  | "client.controls"
  | "client.chat"
  | "client.copy"
  | "validation.schema"
  | "validation.is-schema"
  | "validation.positive-integer"
  | "validation.is-positive-integer"
  | "validation.is-record"
  | "capture.policy"
  | "capture.content"
  | "capture.span"
  | "client-schema.merge"
  | "client-schema.select"
  | "client-schema.project"
  | "client-events.project"
  | "graph-state.select"
  | "graph-interruption.response"
  | "graph-interruption.requests"
  | "graph-interruption.is-error"
  | "thread-transition.decide"
  | "runtime.invoke"
  | "runtime.create"
  | "approval.requires"
  | "approval.create"
  | "approval.approve"
  | "approval.deny"
  | "approval.assert-granted"
  | "approval.is-record"
  | "model-selector.normalize"
  | "model-selector.parse"
  | "model-selector.resolve"
  | "persistence.release"
  | "persistence.resolve-graph"
  | "persistence.resolve-agent"
  | "bucket.list"
  | "bucket.delete"
  | "bucket.glob"
  | "bucket.grep"
  | "bucket.read-data"
  | "bucket.write-data"
  | "bucket.scoped-keys"
  | "bucket.info"
  | "bucket.read-raw"
  | "bucket.read"
  | "bucket.write"
  | "bucket.edit"
  | "bucket.upload"
  | "bucket.download"
  | "bucket.create"
  | "bucket.thread"
  | "definition.copy-instructions"
  | "definition.is-instructions"
  | "definition.is-descriptor"
  | "definition.assert-descriptor"
  | "definition.normalize-model"
  | "definition.copy-deep"
  | "definition.has-deep"
  | "definition.is-model"
  | "definition.copy-middleware"
  | "definition.state-keys"
  | "definition.copy-tools"
  | "definition.tool-refs"
  | "graph.validate-resume"
  | "graph.waiting"
  | "graph.config"
  | "graph.resume-command"
  | "graph-node.destinations"
  | "graph-node.copy-ends"
  | "graph-node.result"
  | "graph-node.input"
  | "graph-node.handle"
  | "graph-node.define"
  | "graph-node.is-descriptor"
  | "definition.copy-limits"
  | "definition.define"
  | "generated.id"
  | "generated.create"
  | "generated.is-function"
  | "persistence.is-resource"
  | "persistence.assert-protocol"
  | "persistence.define-checkpointer"
  | "persistence.define-memory"
  | "runtime.resolve-model"
  | "runtime.content-limits"
  | "graph.invoke"
  | "graph.workflow"
  | "graph.requires-persistence"
  | "graph.define"
  | "graph.execution"
  | "graph.is-descriptor"
  | "graph.subgraph-create"
  | "graph.subgraph-is-node"
  | "graph.subgraph-source"
  | "native-hitl.response-schema"
  | "native-hitl.is-request"
  | "native-hitl.public-request"
  | "native-hitl.is-decision"
  | "native-hitl.is-record"
  | "native-hitl.resume-command"
  | "native-hitl.waiting"
  | "native-hitl.validate-reply"
  | "graph.compile"
  | "graph.route"
  | "graph.edge-builder"
  | "graph.add-edge"
  | "graph.add-conditional-edge"
  | "graph.destination"
  | "graph.validate-route"
  | "graph.prepare-definition"
  | "runtime.validate-value"
  | "runtime.json-value"
  | "runtime.model-failure"
  | "runtime.selected-state-schemas"
  | "graph-node.validate-destinations"
  | "graph-node.command-update"
  | "graph-node.validated-update"
  | "graph-node.validated-value"
  | "bucket.context"
  | "bucket.virtual-path"
  | "bucket.key"
  | "bucket.file-path"
  | "bucket.page"
  | "bucket.control-failure"
  | "bucket.error-message"
  | "bucket.text-mime-type"
  | "runtime.collect-native-events"
  | "runtime.emit-native-tool-event"
  | "runtime.selected-state"
  | "runtime.select-state-fields"
  | "runtime.native-public-event"
  | "runtime.public-event-value"
  | "runtime.public-tool-value"
  | "runtime.message-update"
  | "runtime.native-limits"
  | "runtime.model-limit"
  | "runtime.tool-limit"
  | "runtime.combine-native-tools"
  | "runtime.native-instructions"
  | "runtime.load-deepagents"
  | "runtime.assert-dependencies"
  | "runtime.model-tool-name"
  | "runtime.find-model-tool"
  | "runtime.find-tool"
  | "runtime.run-tool"
  | "runtime.emit-tool"
  | "runtime.resolve-approval"
  | "runtime.create-tool-dispatcher"
  | "runtime.invoke-tool"
  | "graph.stream-compiled"
  | "graph.run-compiled"
  | "observability.emit-edge"
  | "runtime.create-native-tools"
  | "runtime.create-agent-tools"
  | "runtime.response-format"
  | "runtime.child-model"
  | "runtime.create-subagents"
  | "runtime.create-native-agent"
  | "runtime.native-messages"
  | "runtime.response-value"
  | "runtime.unwrap-native-cause"
  | "runtime.run-loop"
  | "signal.failure"
  | "signal.create"
  | "signal.acquire"
  | "signal.with-signal"
  | "client.agent-metadata"
  | "client.graph-metadata";

Source

AgentTelemetryService (interface)

Replaceable observer used by Effect operations and deterministic tests.

Signature

export interface AgentTelemetryService {
  /** Records an operation without changing its Effect channels.
   * @param operation - Fixed agent operation name.
   * @param effect - Work to instrument.
   * @returns The same success, error, and dependency channels.
   * @example telemetry.observe("capture.policy", Effect.succeed({ mode: "off" }));
   */
  readonly observe: <A, E, R>(
    operation: AgentOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}

Source

agent-validation-error.ts

AgentValidationError (class)

Typed validation failure raised by an Effect agent-authoring operation.

Example

const error = new AgentValidationError({
  operation: "positiveInteger",
  message: "limit must be positive",
});

Signature

declare class AgentValidationError

Source

validationCount

Signature

declare const validationCount: Metric.Counter<number>;

Source

validationFailures

Signature

declare const validationFailures: Metric.Counter<number>;

Source

agent-validation-schema.ts

assertAgentSchema

Throws for an invalid schema in existing synchronous authoring calls.

Throws

TypeError when the value is not a Standard Schema v1 validator.

Example

assertAgentSchema(z.string(), "input");

Signature

declare const assertAgentSchema: (
  value: unknown,
  name: string,
) => asserts value is StandardSchemaV1;

Source

assertAgentSchemaEffect

Validates that a value implements the Standard Schema v1 protocol.

Example

const schema = Effect.runSync(assertAgentSchemaEffect(z.string(), "input"));

Signature

declare const assertAgentSchemaEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<StandardSchemaV1<unknown, unknown>, AgentValidationError, never>;

Source

isAgentSchema

Checks whether a candidate implements Standard Schema v1.

Example

if (isAgentSchema(value)) value["~standard"].validate(input);

Signature

declare const isAgentSchema: (value: unknown) => value is StandardSchemaV1;

Source

isAgentSchemaEffect

Checks the Standard Schema v1 protocol without throwing.

Example

const valid = Effect.runSync(isAgentSchemaEffect(z.string()));

Signature

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

Source

agent-validation-value.ts

isPositiveInteger

Checks a finite positive integer for existing synchronous callers.

Example

if (isPositiveInteger(value)) console.log(value + 1);

Signature

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

Source

isPositiveIntegerEffect

Checks for a finite positive integer without throwing.

Example

const valid = Effect.runSync(isPositiveIntegerEffect(3));

Signature

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

Source

isRecord

Checks a record for existing synchronous callers.

Example

if (isRecord(value)) console.log(value.id);

Signature

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

Source

isRecordEffect

Checks a non-null, non-array record through an Effect operation.

Example

const valid = Effect.runSync(isRecordEffect({ id: "one" }));

Signature

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

Source

positiveInteger

Validates a finite positive integer for existing synchronous callers.

Throws

TypeError when the value is not a finite positive integer.

Example

const limit = positiveInteger(3, "maxSteps");

Signature

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

Source

positiveIntegerEffect

Validates a finite positive integer with a typed Effect failure.

Example

const limit = Effect.runSync(positiveIntegerEffect(3, "maxSteps"));

Signature

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

Source

agent-validation.ts

“./agent-validation-error.js” (namespace export)

Re-exports all named exports from the “./agent-validation-error.js” module.

Signature

export * from "./agent-validation-error.js";

Source

“./agent-validation-schema.js” (namespace export)

Re-exports all named exports from the “./agent-validation-schema.js” module.

Signature

export * from "./agent-validation-schema.js";

Source

“./agent-validation-value.js” (namespace export)

Re-exports all named exports from the “./agent-validation-value.js” module.

Signature

export * from "./agent-validation-value.js";

Source

approval-core.ts

APPROVAL_STATES

Signature

declare const APPROVAL_STATES: readonly ["pending", "approved", "denied"];

Source

approveApprovalValue

Grants a pending approval.

Throws

ApprovalStateError for an invalid transition.

Example

approveApprovalValue(pending);

Signature

declare const approveApprovalValue: (approval: ApprovalRecord) => ApprovedApproval;

Source

assertApprovalGrantedValue

Checks whether execution is approved.

Throws

ApprovalRequiredError, ApprovalDeniedError, or ApprovalStateError.

Example

assertApprovalGrantedValue(approved);

Signature

declare const assertApprovalGrantedValue: (
  approval: ApprovalRecord,
) => asserts approval is ApprovedApproval;

Source

createApprovalValue

Constructs a canonical approval record.

Throws

TypeError or ApprovalStateError for invalid metadata.

Example

createApprovalValue(options);

Signature

declare const createApprovalValue: (options: ApprovalOptions) => ApprovalRecord;

Source

denyApprovalValue

Denies a pending approval.

Throws

ApprovalStateError for an invalid transition.

Example

denyApprovalValue(pending);

Signature

declare const denyApprovalValue: (approval: ApprovalRecord) => DeniedApproval;

Source

isApprovalRecordValue

Recognizes canonical approval records.

Example

isApprovalRecordValue(value);

Signature

declare const isApprovalRecordValue: (value: unknown) => value is ApprovalRecord;

Source

requiresApprovalValue

Computes whether a policy requires approval.

Throws

TypeError for invalid inputs.

Example

requiresApprovalValue("always", "read");

Signature

declare const requiresApprovalValue: (
  policy: ApprovalPolicy,
  sideEffect: ApprovalSideEffect,
) => boolean;

Source

approval-effect-error.ts

ApprovalEffectError (class)

Tagged failure for an invalid approval or denied execution.

Signature

declare class ApprovalEffectError

Source

approvalEffectError

Preserves an approval error for typed Effect recovery and compatibility adapters.

Example

approvalEffectError(new ApprovalStateError("invalid state"));

Signature

declare const approvalEffectError: (cause: unknown) => ApprovalEffectError;

Source

approval-error.ts

ApprovalDeniedError (class)

Execution was attempted after an approval was denied.

Example

throw new ApprovalDeniedError(denied);

Signature

declare class ApprovalDeniedError { constructor(readonly approval: DeniedApproval) }

Source

code (property)

Signature

readonly code: "RELKIT_APPROVAL_DENIED"

Source

ApprovalRequiredError (class)

Execution was attempted while an approval remains pending.

Example

throw new ApprovalRequiredError(pending);

Signature

declare class ApprovalRequiredError { constructor(readonly approval: PendingApproval) }

Source

code (property)

Signature

readonly code: "RELKIT_APPROVAL_REQUIRED"

Source

ApprovalStateError (class)

A malformed approval or invalid state transition.

Example

throw new ApprovalStateError("Cannot transition approved approval");

Signature

declare class ApprovalStateError {
  constructor(message: string);
}

Source

code (property)

Signature

readonly code: "RELKIT_APPROVAL_STATE_INVALID"

Source

approval.ts

approveApproval

Moves a pending approval to the approved state.

Throws

ApprovalStateError for a malformed or final decision.

Example

import { approveApproval, createApproval } from "@relkit/app/agents";

const pending = createApproval({
  invocationId: "run",
  toolCallId: "call",
  toolId: "send",
  sideEffect: "write",
  policy: "always",
});
const approved = approveApproval(pending);
void approved;

Signature

declare const approveApproval: (approval: ApprovalRecord) => ApprovedApproval;

Source

Since v0.4.0

denyApproval

Moves a pending approval to the denied state.

Throws

ApprovalStateError for a malformed or final decision.

Example

import { createApproval, denyApproval } from "@relkit/app/agents";

const pending = createApproval({
  invocationId: "run",
  toolCallId: "call",
  toolId: "send",
  sideEffect: "write",
  policy: "always",
});
const denied = denyApproval(pending);
void denied;

Signature

declare const denyApproval: (approval: ApprovalRecord) => DeniedApproval;

Source

Since v0.4.0

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

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

Signature

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

Source

APPROVAL_STATES

Signature

declare const APPROVAL_STATES: readonly ["pending", "approved", "denied"];

Source

ApprovalDeniedError

Signature

declare const ApprovalDeniedError: typeof ApprovalDeniedError;

Source

ApprovalEffectError

Signature

declare const ApprovalEffectError: typeof ApprovalEffectError;

Source

ApprovalRequiredError

Signature

declare const ApprovalRequiredError: typeof ApprovalRequiredError;

Source

ApprovalStateError

Signature

declare const ApprovalStateError: typeof ApprovalStateError;

Source

approveApprovalEffect

Moves a pending approval to the approved state.

Example

Effect.runSync(approveApprovalEffect(pending));

Signature

declare const approveApprovalEffect: (
  approval: ApprovalRecord,
) => Effect.Effect<ApprovedApproval, ApprovalEffectError, never>;

Source

assertApprovalGranted

Rejects execution unless the record is approved.

Throws

ApprovalRequiredError, ApprovalDeniedError, or ApprovalStateError.

Example

assertApprovalGranted(approved);

Signature

declare const assertApprovalGranted: (
  approval: ApprovalRecord,
) => asserts approval is ApprovedApproval;

Source

assertApprovalGrantedEffect

Fails unless the record was approved.

Example

Effect.runSync(assertApprovalGrantedEffect(approved));

Signature

declare const assertApprovalGrantedEffect: (
  approval: ApprovalRecord,
) => Effect.Effect<void, ApprovalEffectError, never>;

Source

createApproval

Creates an immutable pending or policy-approved record.

Throws

TypeError or ApprovalStateError for invalid metadata.

Example

createApproval({
  invocationId: "run",
  toolCallId: "call",
  toolId: "send",
  sideEffect: "write",
  policy: "always",
});

Signature

declare const createApproval: (options: ApprovalOptions) => ApprovalRecord;

Source

createApprovalEffect

Creates an immutable pending or policy-approved record.

Example

Effect.runSync(createApprovalEffect(options));

Signature

declare const createApprovalEffect: (
  options: ApprovalOptions,
) => Effect.Effect<ApprovalRecord, ApprovalEffectError, never>;

Source

denyApprovalEffect

Moves a pending approval to the denied state.

Example

Effect.runSync(denyApprovalEffect(pending));

Signature

declare const denyApprovalEffect: (
  approval: ApprovalRecord,
) => Effect.Effect<DeniedApproval, ApprovalEffectError, never>;

Source

isApprovalRecord

Checks whether a value is a canonical approval record.

Example

if (isApprovalRecord(value)) console.log(value.state);

Signature

declare const isApprovalRecord: (value: unknown) => value is ApprovalRecord;

Source

isApprovalRecordEffect

Checks whether a value is a canonical approval record.

Example

Effect.runSync(isApprovalRecordEffect(value));

Signature

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

Source

requiresApproval

Tests whether a tool call needs an explicit approval decision.

Throws

TypeError for an invalid policy or side effect.

Example

requiresApproval("on-write", "write");

Signature

declare const requiresApproval: (policy: ApprovalPolicy, sideEffect: ApprovalSideEffect) => boolean;

Source

requiresApprovalEffect

Tests whether a tool call needs an explicit approval decision.

Example

Effect.runSync(requiresApprovalEffect("on-write", "write"));

Signature

declare const requiresApprovalEffect: (
  policy: FunctionToolApproval,
  sideEffect: FunctionToolSideEffect,
) => Effect.Effect<boolean, ApprovalEffectError, never>;

Source

approval.types.ts

ApprovalMetadata (interface)

Argument-free metadata for one invocation and tool-call decision.

Signature

export interface ApprovalMetadata extends ApprovalOptions {
  readonly required: boolean;
  readonly state: ApprovalState;
}

Source

ApprovalOptions (interface)

Inputs used to create an approval record.

Signature

export interface ApprovalOptions {
  readonly invocationId: string;
  readonly toolCallId: string;
  readonly toolId: string;
  readonly sideEffect: ApprovalSideEffect;
  readonly policy: ApprovalPolicy;
}

Source

ApprovalPolicy (type alias)

Policy controlling which tool calls require approval.

Signature

type ApprovalPolicy = ToolApproval;

Source

ApprovalRecord (type alias)

Canonical approval record in any valid state.

Signature

type ApprovalRecord = PendingApproval | ApprovedApproval | DeniedApproval;

Source

ApprovalSideEffect (type alias)

Declared side effect of a tool call.

Signature

type ApprovalSideEffect = ToolSideEffect;

Source

ApprovalState (type alias)

One canonical approval state.

Signature

type ApprovalState = "pending" | "approved" | "denied";

Source

ApprovedApproval (interface)

Approval granted by policy or an explicit decision.

Signature

export interface ApprovedApproval extends ApprovalMetadata {
  readonly state: "approved";
}

Source

DeniedApproval (interface)

Approval explicitly denied.

Signature

export interface DeniedApproval extends ApprovalMetadata {
  readonly state: "denied";
}

Source

PendingApproval (interface)

Approval that must receive a decision before execution.

Signature

export interface PendingApproval extends ApprovalMetadata {
  readonly state: "pending";
}

Source

capture-content.ts

captureAgentContent

Captures redacted content for synchronous runtime callers.

Example

const record = captureAgentContent({ token: "secret" }, policy);

Signature

declare const captureAgentContent: (
  value: unknown,
  policy: AgentCapturePolicy,
) => AgentCaptureRecord | undefined;

Source

captureAgentContentEffect

Redacts and bounds a JSON-compatible agent value.

Example

const record = Effect.runSync(captureAgentContentEffect({ token: "secret" }, policy));

Signature

declare const captureAgentContentEffect: (
  value: unknown,
  policy: AgentCapturePolicy,
) => Effect.Effect<AgentCaptureRecord | undefined, never, never>;

Source

capture-policy.ts

AgentCapturePolicyError (class)

Invalid capture configuration in the Effect error channel.

Signature

declare class AgentCapturePolicyError

Source

createAgentCapturePolicy

Creates a capture policy for synchronous descriptor callers.

Throws

TypeError when mode, size, or redaction keys are invalid.

Example

const policy = createAgentCapturePolicy({ mode: "development-redacted", maxBytes: 1024 });

Signature

declare const createAgentCapturePolicy: (
  value: AgentCapturePolicy | undefined,
) => AgentCapturePolicy;

Source

createAgentCapturePolicyEffect

Validates and freezes a content capture policy.

Example

const policy = Effect.runSync(createAgentCapturePolicyEffect({ mode: "off" }));

Signature

declare const createAgentCapturePolicyEffect: (
  value: AgentCapturePolicy | undefined,
) => Effect.Effect<AgentCapturePolicy, AgentCapturePolicyError, never>;

Source

capture-span.ts

createAgentSpanCapture

Combines captured input and output for synchronous runtime callers.

Example

const capture = createAgentSpanCapture(input, output);

Signature

declare const createAgentSpanCapture: (
  input: AgentCaptureRecord | undefined,
  output: AgentCaptureRecord | undefined,
) => AgentSpanCapture | undefined;

Source

createAgentSpanCaptureEffect

Combines optional captured input and output for an agent span.

Example

const capture = Effect.runSync(createAgentSpanCaptureEffect(input, output));

Signature

declare const createAgentSpanCaptureEffect: (
  input: AgentCaptureRecord | undefined,
  output: AgentCaptureRecord | undefined,
) => Effect.Effect<
  Readonly<{ output?: AgentCaptureRecord; input?: AgentCaptureRecord }> | undefined,
  never,
  never
>;

Source

capture.ts

“./capture-content.js” (namespace export)

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

Signature

export * from "./capture-content.js";

Source

“./capture-policy.js” (namespace export)

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

Signature

export * from "./capture-policy.js";

Source

“./capture-span.js” (namespace export)

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

Signature

export * from "./capture-span.js";

Source

AgentCapturePolicy

Signature

declare const AgentCapturePolicy: AgentCapturePolicy;

Source

AgentCaptureRecord

Signature

declare const AgentCaptureRecord: AgentCaptureRecord;

Source

AgentSpanCapture

Signature

declare const AgentSpanCapture: AgentSpanCapture;

Source

capture.types.ts

AgentCapturePolicy (interface)

Controls whether an agent may retain redacted content in its spans. Development capture requires a positive byte limit; off ignores the other fields.

Example

const policy: AgentCapturePolicy = { mode: "development-redacted", maxBytes: 1024 };

Signature

export interface AgentCapturePolicy {
  readonly mode: "off" | "development-redacted";
  readonly maxBytes?: number;
  readonly redactKeys?: readonly string[];
}

Source

AgentCaptureRecord (interface)

Captured JSON and its encoded size, or a marker when capture was truncated. The content property is absent whenever truncated is true.

Example

const record: AgentCaptureRecord = { mode: "development-redacted", bytes: 0, truncated: true };

Signature

export interface AgentCaptureRecord {
  readonly mode: "development-redacted";
  readonly bytes: number;
  readonly truncated: boolean;
  readonly content?: JsonValue;
}

Source

AgentSpanCapture (interface)

Optional input and output captures attached to one agent span. Absent fields were disabled or unavailable at capture time.

Example

const capture: AgentSpanCapture = {
  input: { mode: "development-redacted", bytes: 0, truncated: true },
};

Signature

export interface AgentSpanCapture {
  readonly input?: AgentCaptureRecord;
  readonly output?: AgentCaptureRecord;
}

Source

client-contract-metadata.ts

Projects generic RELKIT tool references and public event schemas into client metadata. Native middleware, graph state and SDK schema projection remain in @relkit/langchain.

“./client-contract-metadata.types.js” (namespace export)

Re-exports all named exports from the “./client-contract-metadata.types.js” module.

Signature

export * from "./client-contract-metadata.types.js";

Source

agentClientContractMetadata

Projects generic metadata for synchronous authoring.

Throws

The original metadata projection error.

Signature

declare const agentClientContractMetadata: (
  options: AgentClientMetadataOptions,
) => AgentClientContractMetadata;

Source

agentClientContractMetadataEffect

Projects an ordinary agent’s public contract without evaluating native schemas.

Signature

declare const agentClientContractMetadataEffect: (
  options: AgentClientMetadataOptions,
) => Effect.Effect<AgentClientContractMetadata, AgentDefinitionFailure, never>;

Source

client-contract-metadata.types.ts

Declares serializable agent client contract metadata shared by SDK-free authoring, graph normalization and runtime client projections. This companion contains the shared planning contracts without executing work.

AgentClientContractMetadata (interface)

Complete metadata needed to generate an agent client contract.

Signature

export interface AgentClientContractMetadata {
  readonly tools: readonly ClientToolMetadata[];
  readonly state: readonly ClientTypeField[];
  readonly events: readonly ClientEventMetadata[];
  readonly scopes: readonly ClientScopeMetadata[];
  readonly waiting: readonly ClientWaitingMetadata[];
}

Source

AgentClientMetadataOptions (interface)

Inputs for native agent client metadata.

Signature

export interface AgentClientMetadataOptions {
  readonly id: string;
  readonly tools: readonly ToolRefAny[];
  readonly middleware?: readonly [];
  readonly client?: AgentClientPolicy;
  readonly subagents?: readonly SubagentMetadataSource[];
  readonly interruptOn?: Readonly<Record<string, unknown>>;
}

Source

ClientEventMetadata (type alias)

Client visible event schema or dynamic event marker.

Signature

type ClientEventMetadata = ClientTypeField | { readonly kind: "dynamic" };

Source

ClientScopeMetadata (interface)

Client visible agent, subagent, or graph node scope.

Signature

export interface ClientScopeMetadata {
  readonly kind: "agent" | "subagent" | "node" | "dynamic";
  readonly id?: string;
}

Source

ClientToolMetadata (type alias)

Client visible tool schema or dynamic tool marker.

Signature

type ClientToolMetadata =
  | {
      readonly id: string;
      readonly input: ClientSchemaMetadata;
      readonly output: ClientSchemaMetadata;
    }
  | { readonly kind: "dynamic" };

Source

ClientWaitingMetadata (interface)

Client visible continuation response schema.

Signature

export interface ClientWaitingMetadata {
  readonly scope: ClientScopeMetadata;
  readonly response: ClientSchemaMetadata;
}

Source

SubagentMetadataSource (interface)

Source of nested subagent scope identities.

Signature

export interface SubagentMetadataSource {
  readonly id: string;
  readonly subagents?: readonly SubagentMetadataSource[];
}

Source

client-contract-schema.ts

Describes Standard Schema input and output contracts for generic agent clients without importing a native model or graph SDK.

ClientSchemaMetadata

Signature

declare const ClientSchemaMetadata: ClientSchemaMetadata;

Source

ClientTypeField

Signature

declare const ClientTypeField: ClientTypeField;

Source

clientSchemaMetadata

Synchronously projects schema metadata for existing descriptor callers.

Example

const metadata = clientSchemaMetadata({ type: "string" });

Signature

declare const clientSchemaMetadata: (value: unknown) => ClientSchemaMetadata;

Source

clientSchemaMetadataEffect

Projects a schema-like value to safe client metadata.

Example

const metadata = Effect.runSync(clientSchemaMetadataEffect({ type: "string" }));

Signature

declare const clientSchemaMetadataEffect: (
  value: unknown,
) => Effect.Effect<ClientSchemaMetadata, never, never>;

Source

dynamicClientSchema

Marker for a schema that cannot be represented in the client contract.

Signature

declare const dynamicClientSchema: Readonly<{ kind: "dynamic" }>;

Source

mergeClientSchemas

Synchronously merges client schemas for existing descriptor callers.

Example

const schema = mergeClientSchemas([{ type: "object" }]);

Signature

declare const mergeClientSchemas: (values: readonly unknown[]) => ClientSchemaMetadata;

Source

mergeClientSchemasEffect

Merges projected object schemas while preserving input order.

Example

const schema = Effect.runSync(mergeClientSchemasEffect([{ type: "object" }]));

Signature

declare const mergeClientSchemasEffect: (
  values: ReadonlyArray<unknown>,
) => Effect.Effect<JsonValue, never, never>;

Source

selectedClientFields

Synchronously selects client fields for existing descriptor callers.

Example

const fields = selectedClientFields({ type: "object" }, ["name"]);

Signature

declare const selectedClientFields: (
  schema: ClientSchemaMetadata,
  keys?: readonly string[],
) => readonly ClientTypeField[];

Source

selectedClientFieldsEffect

Selects named client state fields from a projected object schema.

Example

const fields = Effect.runSync(selectedClientFieldsEffect({ type: "object" }, ["name"]));

Signature

declare const selectedClientFieldsEffect: (
  schema: ClientSchemaMetadata,
  keys?: ReadonlyArray<string> | undefined,
) => Effect.Effect<ReadonlyArray<ClientTypeField>, never, never>;

Source

client-contract-schema.types.ts

ClientSchemaMetadata (type alias)

A projected JSON Schema fragment or an intentionally dynamic field.

Signature

type ClientSchemaMetadata = JsonValue | { readonly kind: "dynamic" };

Source

ClientTypeField (interface)

One client-visible state field with its projected schema.

Signature

export interface ClientTypeField {
  readonly name: string;
  readonly schema: ClientSchemaMetadata;
  readonly optional?: true;
}

Source

client-events.ts

Projects durable agent journal records into bounded client lifecycle events while preserving tool identity and declared public values.

AgentClientEvent

Signature

declare const AgentClientEvent: AgentClientEvent;

Source

AgentProgressEvent

Signature

declare const AgentProgressEvent: AgentProgressEvent;

Source

AgentToolEvent

Signature

declare const AgentToolEvent: AgentToolEvent;

Source

agentClientEvents

Projects a journal record for existing synchronous client callers.

Example

const events = agentClientEvents(record);

Signature

declare const agentClientEvents: (record: JournalRecord) => readonly AgentClientEvent[];

Source

agentClientEventsEffect

Projects one journal record into ordered, public client events.

Example

const events = Effect.runSync(agentClientEventsEffect(record));

Signature

declare const agentClientEventsEffect: (
  record: JournalRecord,
) => Effect.Effect<ReadonlyArray<AgentClientEvent>, never, never>;

Source

client-tool-events.ts

Projects tool message parts into stable public event identities in authored order.

toolClientEvents

Signature

declare const toolClientEvents: (
  base: ClientEventBase,
  message: BrowserMessage,
) => readonly AgentClientEvent[];

Source

define-agent-build.ts

Validates generic authoring inputs before binding a descriptor identity. Native fields are rejected with their integration import so no capability is silently ignored.

prepareAgentDescriptor

Prepares immutable generic metadata before applying its stable identity.

Throws

TypeError for unsupported native fields or invalid generic inputs.

Signature

declare const prepareAgentDescriptor: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const Tools extends readonly ToolRefAny[],
>(
  options: DefineAgentOptions<Id, InputSchema, OutputSchema, Tools>,
) => (
  id: Id,
) => AgentDescriptor<
  Id,
  InferInput<InputSchema>,
  InferOutput<OutputSchema>,
  InputSchema,
  OutputSchema,
  Tools
>;

Source

define-agent-error.ts

AgentDefinitionFailure (class)

Tagged validation failure while copying an agent definition.

Signature

declare class AgentDefinitionFailure

Source

agentDefinitionFailure

Preserves the original authoring error in a tagged Effect failure.

Example

agentDefinitionFailure(new TypeError("invalid"));

Signature

declare const agentDefinitionFailure: (cause: unknown) => AgentDefinitionFailure;

Source

define-agent-limits.ts

copyAgentLimits

Copies limits for existing synchronous authoring callers.

Throws

The original invalid limits TypeError.

Example

const limits = copyAgentLimits({ maxSteps: 3, maxToolCalls: 2, timeoutMs: 1000 });

Signature

declare const copyAgentLimits: (value: unknown) => AgentLimits;

Source

copyAgentLimitsEffect

Validates and freezes an agent’s execution limits.

Example

Effect.runSync(copyAgentLimitsEffect({ maxSteps: 3, maxToolCalls: 2, timeoutMs: 1000 }));

Signature

declare const copyAgentLimitsEffect: (
  value: unknown,
) => Effect.Effect<
  Readonly<{ maxSteps: number; maxToolCalls: number; timeoutMs: number }>,
  AgentDefinitionFailure,
  never
>;

Source

define-agent-support.ts

copyAgentInstructions

Copies instructions for existing synchronous authoring callers.

Throws

The original invalid instruction error.

Example

const instructions = copyAgentInstructions("Answer clearly");

Signature

declare const copyAgentInstructions: (value: unknown) => AgentInstructions;

Source

copyAgentInstructionsEffect

Validates and freezes agent instructions.

Example

Effect.runSync(copyAgentInstructionsEffect("Answer clearly"));

Signature

declare const copyAgentInstructionsEffect: (
  value: unknown,
) => Effect.Effect<AgentInstructions, AgentDefinitionFailure, never>;

Source

isAgentInstructions

Checks instructions for existing synchronous authoring callers.

Example

if (isAgentInstructions(value)) use(value);

Signature

declare const isAgentInstructions: (value: unknown) => value is AgentInstructions;

Source

isAgentInstructionsEffect

Checks whether a value is an agent instruction descriptor.

Example

Effect.runSync(isAgentInstructionsEffect("Answer clearly"));

Signature

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

Source

define-agent-validation.ts

Validates generic agent descriptors and selector models before assembly, rejecting native execution options with an explicit integration import diagnostic.

assertAgentDescriptor

Requires a descriptor for existing synchronous authoring callers.

Throws

TypeError when the descriptor is invalid.

Example

assertAgentDescriptor(candidate);

Signature

declare const assertAgentDescriptor: (value: unknown) => asserts value is AgentAny;

Source

assertAgentDescriptorEffect

Requires a valid agent descriptor.

Example

Effect.runSync(assertAgentDescriptorEffect(agent));

Signature

declare const assertAgentDescriptorEffect: (
  value: unknown,
) => Effect.Effect<void, AgentDefinitionFailure, never>;

Source

isAgentDescriptor

Checks a descriptor for existing synchronous authoring callers.

Example

if (isAgentDescriptor(candidate)) use(candidate);

Signature

declare const isAgentDescriptor: (value: unknown) => value is AgentAny;

Source

isAgentDescriptorEffect

Checks the complete runtime shape of an agent descriptor.

Example

Effect.runSync(isAgentDescriptorEffect(candidate));

Signature

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

Source

normalizeAgentModel

Normalizes a model for existing synchronous authoring callers.

Throws

The original invalid selector error.

Example

const model = normalizeAgentModel("openai:gpt");

Signature

declare const normalizeAgentModel: (value: string | undefined) => string | undefined;

Source

normalizeAgentModelEffect

Normalizes the selector of a string model definition.

Example

Effect.runSync(normalizeAgentModelEffect("openai:gpt"));

Signature

declare const normalizeAgentModelEffect: (
  value: string | undefined,
) => Effect.Effect<string | undefined, AgentDefinitionFailure, never>;

Source

define-agent.ts

Builds plain agent descriptors without loading an execution SDK. The compiler selects native execution when an application actually declares agents.

defineAgent

Defines an SDK-independent agent using validated schemas and RELKIT tool references.

Throws