Skip to main content

@umbraculum/ai-tool-sdk

The library-agnostic AI-tool contract every callable tool the Umbraculum AI consultant may invoke must satisfy.

[!NOTE] Part of Umbraculum — an open-source toolset for building workspace-shaped operational applications.

Install​

npm install @umbraculum/ai-tool-sdk@^0.1.0

Public alpha — see third-party-module.md.

What this is​

The five interface types that define what an AI tool is, on the SDK side of the boundary: AiTool<Input, Output> (the tool itself — name, description, scope, inputSchema, handler), AiToolContext (per-invocation context: workspaceId, userId, requestId, AbortSignal), AiToolScope ("read" | "write" | "propose"), AiToolRegistry (the boot-time registry surface), and AiToolDefinition (the serializable descriptor — no handler, safe to send to clients). Zero runtime code, zero schema library dependencies. Third-party module authors and platform-internal tool authors both depend on this package; the platform orchestrator at services/api/src/services/ai/orchestrator.ts consumes it via the registry interface.

Scope​

  • Contains: the five interface types above (AiTool, AiToolContext, AiToolScope, AiToolRegistry, AiToolDefinition). Pure type declarations — no runtime code.
  • Does not contain: tool implementations (those live in services/api/src/services/ai/tools/<module>/); the orchestrator (lives in services/api/src/services/ai/orchestrator.ts); the in-process registry implementation (lives in services/api/src/services/ai/toolRegistry.ts); the workspace AI settings DTO (WorkspaceAiSettings, AiRoleLimits — those are wire-shape contracts in @umbraculum/contracts); the AI usage-ledger DTO (AiUsageLedgerEntry, AiToolCallRecord — also wire shape in @umbraculum/contracts).

Exports​

SymbolPurpose
AiTool<Input, Output>The tool itself — name, description, scope, inputSchema, handler.
AiToolContextPer-invocation context passed to every tool's handler.
AiToolScopeCapability scope union: "read" | "write".
AiToolRegistryThe boot-time registry surface (register / resolve / list).
AiToolDefinitionSerializable descriptor — same as AiTool minus the handler function.

Usage​

Authoring a tool inside a canonical-module slice (example from the platform-internal brewery slice; the same shape applies to third-party modules):

import type { AiTool } from "@umbraculum/ai-tool-sdk";

export const recipeLookupTool: AiTool<{ recipeId: string }, { name: string; abv: number }> = {
  name: "brewery.recipeLookup",
  description: "Fetch a recipe summary by id.",
  scope: "read",
  inputSchema: { type: "object", properties: { recipeId: { type: "string" } }, required: ["recipeId"] },
  async handler(input, ctx) {
    // implementation uses ctx.workspaceId for ACL, ctx.signal for cancellation
    return { name: "Saison du Brett", abv: 6.4 };
  },
};

Registering tools from a module-owned bundle:

import type { AiToolRegistry } from "@umbraculum/ai-tool-sdk";
import { recipeLookupTool } from "./tools/recipeLookup.js";

export function registerBreweryTools(registry: AiToolRegistry): void {
  registry.register(recipeLookupTool);
}

The registerAiTools slot of @umbraculum/module-sdk's RegisterModuleOptions accepts (registry, app) => void; module code usually calls a bundle function like the one above with dependencies from the host app (app.prisma, service factories, or other platform-owned runtime services). The SDK packages compose at the registration boundary.

Build / test / lint (local)​

Commands run from the repo root, container-friendly per the plugin-shipped 00-shared-node-npm-container-only.mdc shared guardrail:

  • Build: npm run build:packages (or ./scripts/build-packages-in-docker.sh for the Docker route)
  • Test: npm run test --workspace=@umbraculum/ai-tool-sdk (no tests today — pure type-only package; reserved for future schema-conformance tests if/when the surface grows runtime code)
  • Lint: npm run lint --workspace=@umbraculum/ai-tool-sdk
  • Typecheck: handled by the per-workspace typecheck CI gate; see docs/TYPING.md §"Per-workspace CI gate". All 6 candidate strict flags are on.

How it fits in​

  • Consumed by: @umbraculum/module-sdk (uses AiToolRegistry in RegisterModuleOptions.registerAiTools); services/api (the platform-internal tool implementations and the orchestrator's registry consumer); any third-party module authoring AiTool implementations.
  • Depends on: nothing. Zero runtime dependencies, zero schema-library coupling. This is intentional — the SDK boundary is library-agnostic so third parties can use any validation library that produces a JSON Schema for the tool's inputSchema field.

Status​

The interface surface is stable and intentionally minimal. Breaking changes follow the semver-discipline-at-SDK-boundary process committed in docs/PLATFORM-ARCHITECTURE.md §10 (RFC + deprecation window + major-version bump). Published on the public npm registry as part of the MIT SDK batch — see docs/design/npm-sdk-publish-execution-plan.md.

Further reading​