Documentation / API

Decorator API contract

@theorvane/type-chain@0.1.1 is the current public TypeChain release. It supports standard TypeScript Stage 3 decorators and explicit runtime schemas. It does not infer schemas from TypeScript parameter types or use legacy reflect-metadata behavior.

Root package

import {
  Policy,
  Tool,
  getToolDefinitions,
  withToolPolicyGuard,
} from "@theorvane/type-chain";

The root package exposes metadata and policy APIs with no required optional peer imports.

@Tool(options)

@Tool({
  name: "portable_snake_case_name",
  description: "A non-empty tool description.",
  schema: runtimeSchema,
})

The decorator applies only to public, non-static instance methods. A decorated class hierarchy must not expose duplicate tool names.

getToolDefinitions(instance)

const definitions = getToolDefinitions(instance);

Returns a frozen array of receiver-bound ToolDefinition values:

interface ToolDefinition {
  readonly name: string;
  readonly description: string;
  readonly schema: object;
  readonly policy: Readonly<ToolPolicy> | undefined;
  readonly invoke: (input: unknown) => unknown;
}

@Policy(policy)

@Policy({
  authorization: "required",
  approval: "required",
  audit: "required",
  idempotency: "required",
  timeoutMs: 5_000,
  retry: { maxAttempts: 3 },
})

All fields are optional, but the object must contain at least one. @Policy() records immutable declarative intent only. It does not enforce policy.

withToolPolicyGuard(instance, guard)

const guarded = withToolPolicyGuard(instance, async ({ definition, policy, input }) => {
  await applicationOwnedEnforcement({ definition, policy, input });
});

guard is a function that may return void or a promise. Throw or reject to stop an invocation for a tool with declared policy. Tools without declared policy retain direct invocation behavior.

LangChain subpath

import {
  toGuardedLangChainTools,
  toLangChainTools,
} from "@theorvane/type-chain/langchain";

• toLangChainTools(instance) returns standard LangChain structured tools.
• toGuardedLangChainTools(instance, guard) applies the application-owned policy guard before policy-decorated invocation.

The adapter requires structured object input schemas supported by LangChain's tool() factory. It does not select a model or own agent state.

Agent subpath

import {
  Agent,
  buildAgent,
  buildGuardedAgent,
} from "@theorvane/type-chain/agent";

• @Agent({ systemPrompt? }) records an optional, non-empty system prompt on a class.
• buildAgent(instance, { model }) builds a LangChain agent from decorated tools.
• buildGuardedAgent(instance, { model, guard }) does the same with application-owned policy enforcement.

The caller supplies the LangChain model and owns provider credentials, lifecycle, state, persistence, errors, streaming, and deployment.

TypeMCP subpath

import {
  createGuardedTypeMcpAgent,
  createGuardedTypeMcpLangChainTools,
  createTypeMcpAgent,
  createTypeMcpLangChainTools,
} from "@theorvane/type-chain/typemcp";

These APIs compose a TypeMCP-decorated server into native LangChain tools and agents in the current process. They require a TypeMCP server class and an explicit resolver. The guarded variants call an application-owned guard after TypeMCP/LangChain validation and before resolver-backed invocation.

They do not open a TypeMCP HTTP or stdio transport, create MCP clients or sessions, supply credentials, or make authorization decisions.

Package boundary

For complete examples, read Getting started and the related integration guides.

View source at 90152f97834d (opens in a new tab)