@beignet/core/dist/agent-capabilities/index.d.ts

Core framework primitives for Beignet

import type { StandardSchemaV1 } from "@standard-schema/spec";
import { type ProviderInstrumentationTarget } from "../providers/index.js";
import type { TracingPort } from "../tracing/index.js";
/** Any Standard Schema compatible validator. */
export type AgentCapabilitySchema = StandardSchemaV1<unknown, unknown>;
/** Value or promise of that value. */
export type MaybePromise<T> = T | Promise<T>;
/** Infer the input accepted by a capability schema. */
export type InferAgentCapabilitySchemaInput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferInput<Schema>;
/** Infer the parsed output produced by a capability schema. */
export type InferAgentCapabilitySchemaOutput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
/** A typed action that an authenticated agent transport may expose. */
export interface AgentCapabilityDef<Name extends string = string, Input extends AgentCapabilitySchema = AgentCapabilitySchema, Output extends AgentCapabilitySchema = AgentCapabilitySchema, Ctx = unknown, Principal = unknown> {
    readonly kind: "agentCapability";
    readonly name: Name;
    readonly description: string;
    readonly input: Input;
    readonly output: Output;
    readonly handle: (args: {
        capability: AgentCapabilityDef<Name, Input, Output, Ctx, Principal>;
        ctx: Ctx;
        principal: Principal;
        input: InferAgentCapabilitySchemaOutput<Input>;
    }) => MaybePromise<InferAgentCapabilitySchemaInput<Output>>;
}
/** Broad capability definition shape tied to one context and principal. */
export interface AgentCapabilityFor<Ctx, Principal> {
    readonly kind: "agentCapability";
    readonly name: string;
    readonly description: string;
    readonly input: AgentCapabilitySchema;
    readonly output: AgentCapabilitySchema;
    readonly handle: (args: {
        capability: never;
        ctx: Ctx;
        principal: Principal;
        input: never;
    }) => MaybePromise<unknown>;
}
/** Broad capability definition shape used by registries and adapters. */
export type AnyAgentCapabilityDef = AgentCapabilityFor<never, never>;
/** Infer a capability's application context. */
export type AgentCapabilityContext<Capability extends AnyAgentCapabilityDef> = Capability extends {
    handle(args: {
        ctx: infer Ctx;
    }): unknown;
} ? Ctx : never;
/** Infer a capability's verified principal. */
export type AgentCapabilityPrincipal<Capability extends AnyAgentCapabilityDef> = Capability extends {
    handle(args: {
        principal: infer Principal;
    }): unknown;
} ? Principal : never;
/** Infer a capability's raw input. */
export type AgentCapabilityInput<Capability extends AnyAgentCapabilityDef> = InferAgentCapabilitySchemaInput<Capability["input"]>;
/** Infer the parsed input passed to capability context and execution. */
export type AgentCapabilityParsedInput<Capability extends AnyAgentCapabilityDef> = InferAgentCapabilitySchemaOutput<Capability["input"]>;
/** Infer a capability's validated output. */
export type AgentCapabilityOutput<Capability extends AnyAgentCapabilityDef> = InferAgentCapabilitySchemaOutput<Capability["output"]>;
/** Options accepted by `defineAgentCapability(...)`. */
export interface DefineAgentCapabilityOptions<Name extends string, Input extends AgentCapabilitySchema, Output extends AgentCapabilitySchema, Ctx, Principal> {
    description: string;
    input: Input;
    output: Output;
    handle(args: {
        capability: AgentCapabilityDef<Name, Input, Output, Ctx, Principal>;
        ctx: Ctx;
        principal: Principal;
        input: InferAgentCapabilitySchemaOutput<Input>;
    }): MaybePromise<InferAgentCapabilitySchemaInput<Output>>;
}
/** Context-bound capability definition helpers. */
export interface AgentCapabilities<Ctx, Principal> {
    defineAgentCapability<const Name extends string, Input extends AgentCapabilitySchema, Output extends AgentCapabilitySchema>(name: Name, options: DefineAgentCapabilityOptions<Name, Input, Output, Ctx, Principal>): AgentCapabilityDef<Name, Input, Output, Ctx, Principal>;
    defineAgentCapabilityRegistry<const Definitions extends readonly AgentCapabilityFor<Ctx, Principal>[]>(definitions: Definitions): AgentCapabilityRegistry<Definitions>;
}
/** Bind application context and principal types once for capability definitions. */
export declare function createAgentCapabilities<Ctx, Principal>(): AgentCapabilities<Ctx, Principal>;
/** Error thrown when a capability registry is ambiguous. */
export declare class AgentCapabilityRegistryError extends Error {
    constructor(message: string);
}
/** Registered capability definitions available to execution adapters. */
export interface AgentCapabilityRegistry<Definitions extends readonly AnyAgentCapabilityDef[] = readonly AnyAgentCapabilityDef[]> {
    readonly definitions: Definitions;
    get(name: string): Definitions[number] | undefined;
}
/** Stable capability execution failure categories. */
export type AgentCapabilityErrorCode = "unknown_capability" | "invalid_input" | "invalid_output" | "execution_failed";
/** Error raised by capability lookup, validation, or execution. */
export declare class AgentCapabilityError extends Error {
    readonly code: AgentCapabilityErrorCode;
    readonly capabilityName: string;
    readonly issues?: readonly StandardSchemaV1.Issue[];
    readonly cause?: unknown;
    constructor(args: {
        code: AgentCapabilityErrorCode;
        capabilityName: string;
        message: string;
        issues?: readonly StandardSchemaV1.Issue[];
        cause?: unknown;
    });
}
/** A parsed invocation passed to the app-owned context resolver. */
export type AgentCapabilityContextRequest<Definitions extends readonly AnyAgentCapabilityDef[], Principal> = {
    [Capability in Definitions[number] as Capability["name"]]: {
        capability: Capability;
        name: Capability["name"];
        principal: Principal;
        input: InferAgentCapabilitySchemaOutput<Capability["input"]>;
    };
}[Definitions[number]["name"]];
/** Stage reached by an agent capability attempt. */
export type AgentCapabilityRunStage = "lookup" | "input" | "authorization" | "context" | "handler" | "output";
/** Successful capability lifecycle event with validated application data. */
export type AgentCapabilityCompletedRunEvent<Ctx, Principal, Definitions extends readonly AnyAgentCapabilityDef[] = readonly AnyAgentCapabilityDef[], Capability extends Definitions[number] = Definitions[number]> = Capability extends Definitions[number] ? {
    name: Capability["name"];
    phase: "end";
    stage: "output";
    capability: Capability;
    ctx: Ctx;
    principal: Principal;
    input: AgentCapabilityParsedInput<Capability>;
    output: AgentCapabilityOutput<Capability>;
    durationMs: number;
    error?: undefined;
} : never;
/** Lifecycle event observed around a capability attempt. */
export type AgentCapabilityRunEvent<Ctx, Principal, Definitions extends readonly AnyAgentCapabilityDef[] = readonly AnyAgentCapabilityDef[]> = {
    name: string;
    phase: "start";
    stage: "lookup";
    capability?: Definitions[number];
    ctx?: undefined;
    principal: Principal;
    input?: undefined;
    output?: undefined;
    durationMs?: undefined;
    error?: undefined;
} | AgentCapabilityCompletedRunEvent<Ctx, Principal, Definitions> | {
    name: string;
    phase: "error";
    stage: AgentCapabilityRunStage;
    capability?: Definitions[number];
    ctx?: Ctx;
    principal: Principal;
    /** Present only when input validation completed successfully. */
    input?: unknown;
    output?: undefined;
    durationMs: number;
    error: unknown;
};
/** Best-effort lifecycle observer for capability execution. */
export type AgentCapabilityHook<Ctx, Principal, Definitions extends readonly AnyAgentCapabilityDef[] = readonly AnyAgentCapabilityDef[]> = (event: AgentCapabilityRunEvent<Ctx, Principal, Definitions>) => MaybePromise<void>;
/** Options for a capability executor. */
export interface CreateAgentCapabilityExecutorOptions<Ctx, Principal, Definitions extends readonly AnyAgentCapabilityDef[]> {
    registry: AgentCapabilityRegistry<Definitions>;
    createContext(request: AgentCapabilityContextRequest<Definitions, Principal>): MaybePromise<Ctx>;
    hooks?: readonly AgentCapabilityHook<Ctx, Principal, Definitions>[];
    /** Independent target used to observe failures before context exists. */
    instrumentation?: ProviderInstrumentationTarget;
    tracing?: TracingPort;
}
/** Raw dynamic invocation accepted by protocol adapters. */
export interface DynamicAgentCapabilityInvocation<Principal> {
    name: string;
    principal: Principal;
    input: unknown;
    /**
     * Transport-owned authorization against the exact parsed input that will be
     * passed to context construction and the capability handler.
     */
    authorize?(request: DynamicAgentCapabilityAuthorization<Principal>): MaybePromise<void>;
}
/** Parsed invocation exposed to a dynamic transport authorization callback. */
export interface DynamicAgentCapabilityAuthorization<Principal> {
    capability: AnyAgentCapabilityDef;
    name: string;
    principal: Principal;
    input: unknown;
}
/** Typed and dynamic execution surface for one capability registry. */
export interface AgentCapabilityExecutor<Principal, Definitions extends readonly AnyAgentCapabilityDef[]> {
    execute<Name extends Definitions[number]["name"]>(args: {
        name: Name;
        principal: Principal;
        input: AgentCapabilityInput<Extract<Definitions[number], {
            name: Name;
        }>>;
    }): Promise<AgentCapabilityOutput<Extract<Definitions[number], {
        name: Name;
    }>>>;
    executeDynamic(args: DynamicAgentCapabilityInvocation<Principal>): Promise<unknown>;
}
/** Create a validated, traced executor for a capability registry. */
export declare function createAgentCapabilityExecutor<const Definitions extends readonly AnyAgentCapabilityDef[]>(options: CreateAgentCapabilityExecutorOptions<AgentCapabilityContext<Definitions[number]>, AgentCapabilityPrincipal<Definitions[number]>, Definitions>): AgentCapabilityExecutor<AgentCapabilityPrincipal<Definitions[number]>, Definitions>;
//# sourceMappingURL=index.d.ts.map