Generated package and CLI reference

This page is generated from package.json and the CLI parser. Run node docs-site/reference.mjs after changing those sources. npm run docs:check fails if this page drifts. Agent Native 1.0.0. Stable and experimental entry points are listed in stability.

Typed package entrypoints

The package's optional peers are listed in installation. Import only the subpath needed by the application. A package-level executable is not shipped.

Application CLI arguments

The application calls runCapabilityCli(argv, options, streams). One command or canonical capability ID is positional. A command override or alias retains the canonical identity and has no version fallback.

For a runnable instance, use Node.js 22 or newer, npm ci, and npm run example:e10 from the repository root. The exported E10 CLI runs npm run search -- --query night --limit 1 successfully. An empty query exits 2 with invalid-input; provide a nonempty query to retry. See CLI behavior and E10 instructions.

Typed adapter configuration

These exported declarations are copied from the checked TypeScript source at build time. Framework mounts and security ownership are explained in the linked guides.

CLI

View source

export type CliCredentialProfile = {
  readonly baseUrl: string;
  readonly token: string;
};

export type CapabilityCliOptions = {
  readonly registry: CapabilityRegistry;
  readonly authorization: AuthorizationPort;
  readonly caller: ExecutionCaller;
  readonly credentialProfiles?: Readonly<Record<string, CliCredentialProfile>>;
  readonly packageVersion?: string;
  readonly fetcher?: typeof fetch;
  readonly surfaceExposure?: CapabilitySurfaceExposure;
  readonly canDiscover?: (
    definition: CapabilityDefinition<unknown, unknown>,
  ) => boolean | Promise<boolean>;
};

HTTP

View source

export type HttpAdapterOptions = {
  readonly basePath?: string;
  readonly maxRequestBytes?: number;
  readonly deadlineMs?: number;
  readonly resolveExecutionContext?: (
    request: Request,
  ) => HttpExecutionContext | Promise<HttpExecutionContext>;
};

MCP

View source

export type McpAdapterOptions = {
  readonly endpoint?: string;
  readonly surfaceExposure?: CapabilitySurfaceExposure;
  readonly maxRequestBytes?: number;
  readonly deadlineMs?: number;
  readonly canDiscover?: (
    definition: CapabilityDefinition<unknown, unknown>,
    request: Request,
  ) => boolean | Promise<boolean>;
  readonly discoverProtected?: (
    definition: CapabilityDefinition<unknown, unknown>,
    request: Request,
    authInfo: AuthInfo,
  ) => boolean | Promise<boolean>;
  readonly bearerAuth?: {
    readonly verifier: OAuthTokenVerifier;
    readonly expectedResource: URL;
    readonly requiredScopes?: readonly string[];
    readonly resourceMetadataUrl?: string;
    // Answer requests without an Authorization header with the SDK's 401 challenge. Defaults to
    // true when no capability is a public read, so hosts are prompted to authenticate instead of
    // receiving an empty tool list.
    readonly required?: boolean;
  };
  // Operator hook for tool calls that end in an error. It runs after the response is decided;
  // a throwing or rejecting hook is ignored.
  readonly onToolFailure?: (failure: McpToolFailure) => void | Promise<void>;
  // Overrides the default collision-free tool name. Names must be unique and match MCP's name rules.
  readonly toolName?: (definition: CapabilityDefinition<unknown, unknown>) => string;
  // AuthInfo comes from the SDK verifier; issuer/subject/tenant must be supplied by that
  // verifier's trusted metadata, never inferred from request headers or MCP clientInfo.
  readonly resolveTrustedPrincipal?: (
    authInfo: AuthInfo,
  ) => TrustedPrincipal | null | Promise<TrustedPrincipal | null>;
  readonly grantAuthorization?: Omit<GrantAuthorizationOptions, 'principal'>;
  readonly resolveExecutionContext?: (
    request: Request,
    authInfo?: AuthInfo,
  ) => McpExecutionContext | Promise<McpExecutionContext>;
};

Doctor

View source

export type DoctorRunOptions = {
  readonly now?: () => Date;
  readonly profile?: DoctorCheckProfile;
};