@voyant-travel/tools

The transport-neutral agent tool contract for the Voyant framework (voyant#2792).

Capabilities are authored once, headless, and scope-gated; exposure (MCP, remote agents, HTTP) is a thin adapter over this contract. Tool handlers return typed pure data validated by an outputSchema — never transport envelopes or presentation.

Shape

• defineTool({ capabilityId?, owner?, capabilityVersion?, name, aliases?, description, inputSchema, outputSchema, requiredScopes, audience?, tier, riskPolicy, annotations?, resolveActionTarget?, handler }) — a headless tool. Graph-driven hosts bind the stable package Tool id and owner; standalone tools should declare them directly. Ctx widens by intersection so a domain injects its services (ToolContext & { trips: … }) without this package depending on the domain.
• ToolContext — { db, actor, audience, tenantId, resolverScope, waitUntil?, toolActionPolicy? }. The optional gate is supplied by graph hosts and called by transport adapters before selected action dispatch.
• RiskTier + RiskPolicy — declarative risk data (destructive / reversible / dry-run / side effects) so remote consumers and the MCP layer gate approvals without executing tool code (D1).
• createToolRegistry() — register / registerAll / get / names / list / prepareAction / dispatchPrepared / dispatch. prepareAction validates input once and resolves the package target; only the same registry can dispatch that admitted parsed value. dispatch validates input, runs the handler, then validates output. list() returns the discovery manifest with real JSON Schema (zod v4 z.toJSONSchema), capability identity/version, owner, aliases/deprecation, audience, requiredScopes, MCP annotations, tier, and riskPolicy. Aliases dispatch to the canonical definition; capability lookup may require an exact supported version.
• Graph bindings add an actionPolicy to discovery. Generic transports pass the command and reserved invocation controls through ToolActionPolicyGate; the action-ledger package owns the implementation. actionPolicyEnforcement: "handler" is reserved for Tools whose existing package handler already performs the same selected-policy approval and ledger workflow.
• Generic ledgered actions resolve their target deterministically after domain input validation. A Tool may define resolveActionTarget(parsedArgs, ctx) for a complex target. Otherwise an existing-target action declares commandTargetField, and the registry reads that field from the already parsed input. Ledgered read collections without such a field use an authenticated ${targetType}:${tenantId} collection anchor. Migrated actions advertise their exact targetResolution; for those actions MCP clients supply an opaque UUID requestId, explicit confirmed when required, and an optional server-issued approvalId, never the target or command fingerprint. During the staged rollout only, generic executes without either package contract retain the previous invocation fields. This compatibility branch is discoverable by the absence of targetResolution and is removed after their package migrations land.
• Actions whose canonical targetId is generated by the handler declare targetLifecycle: "created" plus a createdTarget command identity, result-reference type, and handler-command-claim-v1 durability contract. They must use handler enforcement: the handler claims a stable command key before mutation, returns the prior typed reference on exact replay, and commits the claim, domain mutation, and canonical generated-target result together. MCP never asks callers to invent _voyant.targetId for these actions. A post-dispatch target extractor is not a durable created-target strategy. For handler-owned dispatch only, MCP supplies a fresh handlerActionPolicy context value containing the stripped invocation controls and selected policy metadata. Handlers use that request-scoped value to validate approval-required created commands without adding _voyant to their domain input schema. The MCP adapter removes any stale caller/base handlerActionPolicy before every dispatch and injects a fresh value only for selected handler enforcement; generic and unbound handlers never receive it.
• Authorization is not enforced in the registry — the transport binds each tool's requiredScopes to hasApiKeyPermission (AND semantics).

The package depends only on zod; it never imports hono, catalog, or any domain package.