@ghuri/agents 0.0.0-stage → 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,869 @@
+import { GhuriError, RequestUser, GhuriContext, AppConfig, UrlPatterns, Env } from '@ghuri/core';
+import * as _ghuri_rest from '@ghuri/rest';
+import { APIRequest, PermissionClass, AuthenticationClass, APIView, JSONRenderer, BaseAuthentication, BasePermission, APIResponse, APIException, RouterRegistration, BaseRouter } from '@ghuri/rest';
+import { ModelMessage, LanguageModel, LanguageModelUsage, ToolSet, StreamTextResult, UIMessageChunk } from 'ai';
+import * as _ghuri_orm from '@ghuri/orm';
+import { UUIDField, ForeignKey, ModelClass, CharField, JSONField, DateTimeField, Manager } from '@ghuri/orm';
+import { z } from 'zod';
+
+/** Base class of `@ghuri/agents` errors. */
+declare class AgentError extends GhuriError {
+}
+/**
+ * A tool failed in a way the model should see (permission denied, validation error, not found…). Thrown from a
+ * tool's `execute`, it becomes a tool error for the model (the run continues) and `isError: true` over MCP.
+ */
+declare class ToolError extends AgentError {
+    /** HTTP-like status (403, 400, 404…) when the error came from a view. */
+    status?: number;
+    /** Structured details (DRF error body, validation errors…). */
+    detail?: unknown;
+    constructor(message: string, opts?: {
+        status?: number;
+        detail?: unknown;
+        cause?: unknown;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/** Tool input did not match the tool's schema. */
+declare class ToolInputError extends ToolError {
+    constructor(message: string, detail?: unknown);
+}
+/** A tool name that no agent / MCP server exposes. */
+declare class UnknownToolError extends AgentError {
+}
+/** A `'provider:model'` string could not be resolved. */
+declare class ModelResolutionError extends AgentError {
+}
+
+declare function newConversationId(): string;
+declare function emptyMetadata(): Record<string, unknown>;
+declare const Conversation_base: _ghuri_orm.ModelBaseClass<{
+    id: UUIDField<{
+        readonly primaryKey: true;
+        readonly default: typeof newConversationId;
+        readonly editable: false;
+    }>;
+    user: ForeignKey<ModelClass<_ghuri_orm.BaseModel>, {
+        readonly null: true;
+        readonly blank: true;
+        readonly onDelete: "CASCADE";
+        readonly relatedName: "agentConversations";
+    }>;
+    agent: CharField<{
+        readonly maxLength: 100;
+        readonly dbIndex: true;
+    }>;
+    title: CharField<{
+        readonly maxLength: 200;
+        readonly blank: true;
+        readonly default: "";
+    }>;
+    metadata: JSONField<any, {
+        readonly default: typeof emptyMetadata;
+        readonly blank: true;
+    }>;
+    createdAt: DateTimeField<{
+        readonly autoNowAdd: true;
+    }>;
+    updatedAt: DateTimeField<{
+        readonly autoNow: true;
+    }>;
+}, typeof _ghuri_orm.BaseModel>;
+/** A chat thread between a user and one agent (table `agents_conversation`). */
+declare class Conversation extends Conversation_base {
+    static objects: Manager<Conversation>;
+    static Meta: {
+        appLabel: string;
+        ordering: string[];
+        verboseName: string;
+    };
+    toString(): string;
+}
+/** Roles stored in `Message.role` (AI SDK model message roles). */
+declare const MESSAGE_ROLES: readonly ["system", "user", "assistant", "tool"];
+type MessageRole = (typeof MESSAGE_ROLES)[number];
+declare const Message_base: _ghuri_orm.ModelBaseClass<{
+    conversation: ForeignKey<typeof Conversation, {
+        readonly onDelete: "CASCADE";
+        readonly relatedName: "messages";
+    }>;
+    role: CharField<{
+        readonly maxLength: 20;
+        readonly choices: [string, string][];
+    }>;
+    content: JSONField<any, {
+        readonly null: true;
+    }>;
+    createdAt: DateTimeField<{
+        readonly autoNowAdd: true;
+    }>;
+}, typeof _ghuri_orm.BaseModel>;
+/**
+ * One AI SDK model message of a conversation (table `agents_message`). `content` is the message content as
+ * JSON: a string, or parts (text, tool calls with their inputs, tool results / errors).
+ */
+declare class Message extends Message_base {
+    static objects: Manager<Message>;
+    conversationId: string;
+    static Meta: {
+        appLabel: string;
+        ordering: string[];
+        verboseName: string;
+    };
+}
+
+/** The conversation does not exist, belongs to another agent, or is not owned by the user. */
+declare class ConversationNotFound extends ToolError {
+    constructor(message: string);
+}
+/** Is conversation memory available (the `agents` app installed)? */
+declare function memoryAvailable(): boolean;
+/** A user's conversation with `agent`, or `ConversationNotFound`. */
+declare function getConversation(agent: string, id: string, user: RequestUser | null | undefined): Promise<Conversation>;
+/** Start a conversation owned by `user`. */
+declare function createConversation(agent: string, user: RequestUser | null | undefined, opts?: {
+    title?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<Conversation>;
+/** The stored messages of a conversation, as AI SDK model messages (oldest first). */
+declare function loadMessages(conversation: Conversation | string): Promise<ModelMessage[]>;
+/** Append messages to a conversation and touch its `updatedAt`. */
+declare function saveMessages(conversation: Conversation, messages: ModelMessage[]): Promise<void>;
+
+/** Message body sent to the queue by `enqueue()`. */
+interface AgentJob {
+    type: 'ghuri.agents.run';
+    agent: string;
+    input: AgentInput;
+    /** Primary key of the user to run as (null: anonymous). */
+    userId: unknown;
+    conversationId?: string;
+    context?: Record<string, unknown>;
+}
+declare const AGENT_JOB_TYPE = "ghuri.agents.run";
+interface EnqueueOptions {
+    user?: RequestUser | null;
+    conversationId?: string | null;
+    /** Queue producer binding (default `AGENTS.QUEUE_BINDING`, else `'AGENTS_QUEUE'`). */
+    binding?: string;
+    context?: Record<string, unknown>;
+}
+/**
+ * Send a run to a Cloudflare Queue (consumed by `AgentRouter.consumeQueue()`). A conversation is created up
+ * front (when memory is available) so callers can poll it.
+ */
+declare function enqueueRun(agent: Agent, input: AgentInput, opts?: EnqueueOptions): Promise<{
+    conversationId?: string;
+}>;
+/** Load the user a queued run acts for (`AUTH_USER_MODEL`); anonymous when `userId` is null. */
+declare function loadJobUser(userId: unknown): Promise<RequestUser>;
+/**
+ * Register a queue consumer running queued agent jobs with `create(name)` (an `AgentRouter`'s factory).
+ * Messages that are not agent jobs are left alone; failed runs are retried.
+ */
+declare function consumeAgentQueue(queue: string, create: (name: string) => Agent): () => void;
+
+/** A JSON Schema object (draft 2020-12). */
+type JSONSchema = Record<string, unknown>;
+/** Who and what a tool runs for. Every tool executes as `user`. */
+interface ToolContext {
+    /** The requesting user (tools never escalate beyond this user's permissions). */
+    user: RequestUser;
+    /** The agent running the tool (absent for direct MCP calls). */
+    agent?: unknown;
+    conversationId?: string;
+    toolCallId?: string;
+    signal?: AbortSignal;
+    /** The REST request of the HTTP chat / MCP call, when there is one. */
+    request?: APIRequest;
+}
+/** MCP tool annotations (hints for clients; also useful for UIs). */
+interface ToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+/**
+ * A normalized tool, the common currency of agents (AI SDK tools) and the MCP server. `ModelTools`,
+ * `ViewSetTools`, `RouterTools`, `tool()` and `@tool` methods all produce these.
+ */
+interface AgentTool {
+    /** Sanitized name (`posts_list`), unique within an agent / MCP server. */
+    name: string;
+    description: string;
+    /** JSON Schema of the arguments (always `type: 'object'`). */
+    inputSchema: JSONSchema;
+    /** JSON Schema of the result, when known. */
+    outputSchema?: JSONSchema;
+    annotations?: ToolAnnotations;
+    /** Validate / coerce raw arguments; throws `ToolInputError`. Defaults to accepting any object. */
+    parse?(input: unknown): unknown;
+    /** Run the tool. Throw `ToolError` for failures the model should see. */
+    execute(input: any, ctx: ToolContext): unknown;
+}
+/** A collection of tools (`ModelTools`, `ViewSetTools`, `RouterTools`, or your own). */
+declare abstract class Toolkit {
+    abstract getTools(): AgentTool[];
+}
+declare function isToolkit(value: unknown): value is Toolkit;
+declare function isAgentTool(value: unknown): value is AgentTool;
+
+/** Marker on methods decorated with `@tool`. */
+declare const TOOL: unique symbol;
+/** Options carried by the decorator returned from `tool()` (for `static tools = {...}` and standalone tools). */
+declare const TOOL_OPTIONS: unique symbol;
+type InputOf<S> = S extends z.ZodType ? z.output<S> : Record<string, any>;
+interface ToolOptions<S = z.ZodType | JSONSchema | undefined> {
+    /** Tool name (default: the method / key name). Sanitized to `[A-Za-z0-9_-]{1,64}`. */
+    name?: string;
+    /** What the tool does — the model reads this to decide when to call it. */
+    description: string;
+    /** Arguments: a Zod object schema (validated) or a JSON Schema object. Omit for no arguments. */
+    input?: S;
+    /** JSON Schema of the result (advertised over MCP as `outputSchema`). */
+    output?: JSONSchema;
+    annotations?: ToolAnnotations;
+    /** Standalone tools: the implementation (methods decorated with `@tool` don't need it). */
+    execute?: (input: InputOf<S>, ctx: ToolContext) => unknown;
+}
+/** A `tool()` result: a TC39 / legacy method decorator that also carries its options. */
+interface ToolDecorator<S = any> {
+    (value: any, context?: any, descriptor?: PropertyDescriptor): any;
+    readonly [TOOL_OPTIONS]: ToolOptions<S>;
+}
+/**
+ * Declare a tool. Three forms:
+ *
+ * ```ts
+ * class SupportAgent extends Agent {
+ *   // 1. decorator (standard TC39 decorators)
+ *   @tool({ description: 'Refund an order', input: z.object({ orderId: z.number() }) })
+ *   async refund({ orderId }, ctx) { ... }
+ *
+ *   // 2. without decorators: options in a static map, implementation in the method of the same name
+ *   static tools = { refund: tool({ description: 'Refund an order', input: z.object({ orderId: z.number() }) }) }
+ *
+ *   // 3. standalone, with `execute`
+ *   tools = [tool({ name: 'now', description: 'Current time', execute: () => new Date().toISOString() })]
+ * }
+ * ```
+ */
+declare function tool<S extends z.ZodType | JSONSchema | undefined = undefined>(opts: ToolOptions<S>): ToolDecorator<S>;
+declare function isToolDecorator(value: unknown): value is ToolDecorator;
+/** Build a normalized `AgentTool` from options and an implementation. */
+declare function defineTool(name: string, opts: ToolOptions<any>, execute: (input: any, ctx: ToolContext) => unknown): AgentTool;
+/** A standalone `tool({ ..., execute })` → `AgentTool` (`key` names tools declared in a map). */
+declare function standaloneTool(decorator: ToolDecorator, key?: string): AgentTool;
+/**
+ * Tools declared on a class: `@tool` methods and `static tools = { name: tool({...}) }` entries, bound to
+ * `instance` (methods receive `(input, ctx)` with `this` = the instance).
+ */
+declare function collectDeclaredTools(instance: object): AgentTool[];
+
+/** What can go in an agent's `tools`: toolkits, standalone `tool({...execute})`s and `AgentTool`s. */
+type ToolEntry = Toolkit | ToolDecorator | AgentTool;
+type ToolsInput = ToolEntry[] | Record<string, ToolEntry>;
+/** Input of a run: a user message, or AI SDK model messages to append. */
+type AgentInput = string | ModelMessage[];
+interface RunOptions {
+    /** The user the agent acts for; every tool runs with this user's permissions (default: anonymous). */
+    user?: RequestUser | null;
+    /** Continue a stored conversation (must belong to `user` and this agent). */
+    conversationId?: string | null;
+    signal?: AbortSignal;
+    /** Load / save conversation memory (default: when the `agents` app is installed and `agent.memory`). */
+    memory?: boolean;
+    /** Check the agent's `permissionClasses` for `user` first (HTTP and MCP always do). */
+    checkPermissions?: boolean;
+    /** The REST request when running for an HTTP / MCP call. */
+    request?: APIRequest;
+    /** Free-form values available to `instructions(ctx)` and hooks as `ctx.extra`. */
+    context?: Record<string, unknown>;
+    /** Title for a new conversation (default: from the first message). */
+    title?: string;
+}
+/** Per-run state passed to `instructions(ctx)` and the hooks. */
+interface AgentRunContext {
+    agent: Agent;
+    agentName: string;
+    user: RequestUser;
+    input: AgentInput;
+    conversationId?: string;
+    conversation?: Conversation;
+    /** Full prompt: stored history + the new messages. Hooks may edit it. */
+    messages: ModelMessage[];
+    /** The new messages of this run (saved to memory with the response). */
+    newMessages: ModelMessage[];
+    signal?: AbortSignal;
+    request?: APIRequest;
+    extra: Record<string, unknown>;
+}
+/** A tool call made during a run. */
+interface ToolCallRecord {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    output?: unknown;
+    /** Error message returned to the model (permission denied, validation…). */
+    error?: string;
+}
+interface AgentRunResult {
+    text: string;
+    /** Messages added by this run: the input and the response (assistant / tool messages). */
+    messages: ModelMessage[];
+    toolCalls: ToolCallRecord[];
+    usage: LanguageModelUsage;
+    finishReason: string;
+    steps: number;
+    conversationId?: string;
+}
+/** Passed to `onToolCall` before a tool runs. Throw (e.g. `ToolError`) to refuse the call. */
+interface ToolCallInfo {
+    toolName: string;
+    toolCallId?: string;
+    input: unknown;
+}
+interface Prepared {
+    ctx: AgentRunContext;
+    model: LanguageModel;
+    instructions?: string;
+    tools: ToolSet;
+    ghuri?: GhuriContext;
+}
+/**
+ * An LLM agent with tools that run as the requesting user.
+ *
+ * ```ts
+ * export class SupportAgent extends Agent {
+ *   model = 'workers-ai:@cf/meta/llama-3.3-70b-instruct-fp8-fast'
+ *   instructions = 'You help customers with their orders.'
+ *   tools = [new ModelTools(Order, { actions: ['list', 'retrieve'], filter: (qs, user) => qs.filter({ customer: user.pk }) })]
+ *   permissionClasses = [IsAuthenticated]
+ *
+ *   @tool({ description: 'Refund an order', input: z.object({ orderId: z.number() }) })
+ *   async refund({ orderId }, { user }) { ... }
+ * }
+ * const { text, conversationId } = await new SupportAgent().run('Where is my order?', { user })
+ * ```
+ */
+declare class Agent {
+    /** Name used for conversations, URLs and MCP (`ask_<name>`); default: class name minus `Agent`, kebab-case. */
+    static agentName?: string;
+    /** Shown to MCP clients for the `ask_<name>` tool. */
+    static description?: string;
+    /** Tools implemented by methods of the same name, without decorators: `{ refund: tool({...}) }`. */
+    static tools?: Record<string, ToolDecorator>;
+    /** `'provider:model-id'` or an AI SDK `LanguageModel` (default `AGENTS.DEFAULT_MODEL`). */
+    model?: string | LanguageModel;
+    /** System instructions, or a function of the run context. */
+    instructions?: string | ((ctx: AgentRunContext) => string | Promise<string>);
+    /** Toolkits and tools (plus `@tool` methods and `static tools`). */
+    tools?: ToolsInput;
+    /** REST permission classes checked for HTTP / MCP access (default `AGENTS.PERMISSION_CLASSES`). */
+    permissionClasses?: PermissionClass[];
+    /** Maximum model steps (tool round trips) per run (default `AGENTS.MAX_STEPS`, 10). */
+    maxSteps?: number;
+    temperature?: number;
+    maxOutputTokens?: number;
+    /** Provider-specific options passed to the AI SDK (`{ anthropic: { thinking: … } }`). */
+    providerOptions?: Record<string, any>;
+    /** Use conversation memory when the `agents` app is installed (default true). */
+    memory: boolean;
+    /** Set by `AgentRouter.register(name, …)`. */
+    agentName?: string;
+    /** Called before the model runs; may edit `ctx.messages`. Throw to abort the run. */
+    beforeRun?(ctx: AgentRunContext): void | Promise<void>;
+    /** Called after a run finished and was saved. */
+    afterRun?(result: AgentRunResult, ctx: AgentRunContext): void | Promise<void>;
+    /** Called before every tool call. Throw (e.g. `ToolError`) to refuse it; the model sees the error. */
+    onToolCall?(call: ToolCallInfo, ctx: AgentRunContext): void | Promise<void>;
+    /** `new this().run(input, opts)`. */
+    static run<T extends Agent>(this: new () => T, input: AgentInput, opts?: RunOptions): Promise<AgentRunResult>;
+    getName(): string;
+    getDescription(): string;
+    getPermissionClasses(): PermissionClass[];
+    /** System instructions for a run (override for dynamic instructions). */
+    getInstructions(ctx: AgentRunContext): Promise<string | undefined>;
+    /** All tools of this agent, normalized (toolkits expanded, declared methods bound). */
+    getTools(): AgentTool[];
+    /** Check `permissionClasses` for `user` (`NotAuthenticated` / `PermissionDenied` from `@ghuri/rest`). */
+    checkPermissions(user: RequestUser, request?: APIRequest): Promise<void>;
+    /** AI SDK tool set for a run: validation, `onToolCall`, context and error normalization included. */
+    buildToolSet(ctx: AgentRunContext, tools?: AgentTool[]): ToolSet;
+    protected prepare(input: AgentInput, opts: RunOptions): Promise<Prepared>;
+    protected callSettings(p: Prepared): Record<string, unknown>;
+    protected finish(p: Prepared, r: {
+        text: string;
+        responseMessages: ModelMessage[];
+        content: ReadonlyArray<any>;
+        usage: LanguageModelUsage;
+        finishReason: string;
+        steps: number;
+    }): Promise<AgentRunResult>;
+    /**
+     * Run the agent to completion (tool loop included). Tool failures (permission denied, validation, not
+     * found) are returned to the model as tool errors; the run itself only throws for model / config errors.
+     */
+    run(input: AgentInput, opts?: RunOptions): Promise<AgentRunResult>;
+    /**
+     * Run in the background through a Cloudflare Queue (`AGENTS.QUEUE_BINDING`); a consumer registered with
+     * `AgentRouter.consumeQueue()` performs the run. Returns the conversation id to poll.
+     */
+    enqueue(input: AgentInput, opts?: EnqueueOptions): Promise<{
+        conversationId?: string;
+    }>;
+    /**
+     * Stream a run. Use `toUIMessageStreamResponse()` for AI SDK UI (`useChat`) / SSE clients, or `textStream`.
+     * The conversation is saved when the stream finishes; `await stream.done` for the final result.
+     */
+    stream(input: AgentInput, opts?: RunOptions): Promise<AgentStream>;
+}
+/** A streaming run (`agent.stream()`). */
+declare class AgentStream {
+    /** The AI SDK `streamText` result (fullStream, textStream, …). */
+    readonly result: StreamTextResult<ToolSet, any, any>;
+    /** Resolves after the stream finished and the conversation was saved. */
+    readonly done: Promise<AgentRunResult>;
+    readonly conversationId?: string | undefined;
+    constructor(
+    /** The AI SDK `streamText` result (fullStream, textStream, …). */
+    result: StreamTextResult<ToolSet, any, any>, 
+    /** Resolves after the stream finished and the conversation was saved. */
+    done: Promise<AgentRunResult>, conversationId?: string | undefined);
+    /** Plain text deltas. */
+    get textStream(): AsyncIterable<string> & ReadableStream<string>;
+    /**
+     * AI SDK UI message stream chunks (`start`, `text-delta`, `tool-input-available`, `tool-output-available`,
+     * `finish`…). The `start` chunk carries `messageMetadata: { conversationId }`. The stream closes only after
+     * the conversation was saved.
+     */
+    toUIMessageStream(): ReadableStream<UIMessageChunk>;
+    /** An SSE `Response` in the AI SDK UI message stream protocol (header `x-conversation-id`). */
+    toUIMessageStreamResponse(init?: {
+        status?: number;
+        headers?: Record<string, string>;
+    }): Response;
+}
+
+/**
+ * The `agents` app: conversation memory (`Conversation`, `Message`) and its migrations. Add it to
+ * `INSTALLED_APPS` (after your user model's app) and run `ghuri migrate` to have agents load and save
+ * conversations automatically.
+ */
+declare class AgentsConfig extends AppConfig {
+    name: string;
+    label: string;
+    verboseName: string;
+    path: string | undefined;
+    migrations: Record<string, unknown>;
+    models: {
+        Conversation: typeof Conversation;
+        Message: typeof Message;
+    };
+}
+
+/** Protocol revisions this server speaks (newest first). */
+declare const MCP_PROTOCOL_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+declare const MCP_LATEST_PROTOCOL_VERSION: "2025-11-25";
+/** JSON-RPC 2.0 error codes. */
+declare const JSONRPC: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    /** Server-defined: authentication / authorization failures. */
+    readonly UNAUTHORIZED: -32001;
+};
+type JsonRpcId = string | number | null;
+interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+interface McpServerOptions {
+    /** Server name shown to clients (default `'ghuri'`). */
+    name?: string;
+    /** Server version (default `'0.1.0'`). */
+    version?: string;
+    title?: string;
+    /** Instructions for the client's model (returned by `initialize`). */
+    instructions?: string;
+    /** Tools to expose: toolkits (`ModelTools`, `ViewSetTools`, `RouterTools`), `tool({...execute})`, `AgentTool`s. */
+    tools?: ToolsInput;
+    /** Agents to expose as `ask_<name>` tools: `{ support: SupportAgent }` or a factory map. */
+    agents?: Record<string, () => Agent>;
+    /** Authentication (default `AGENTS.AUTHENTICATION_CLASSES`, then REST defaults). */
+    authenticationClasses?: AuthenticationClass[];
+    /** Access to the endpoint (default `AGENTS.PERMISSION_CLASSES`: `[IsAuthenticated]`). */
+    permissionClasses?: PermissionClass[];
+    /** Accept browser `Origin`s other than the server's own host / `CSRF_TRUSTED_ORIGINS` (default false). */
+    allowAnyOrigin?: boolean;
+}
+interface McpCallContext {
+    user: ToolContext['user'];
+    request?: APIRequest;
+    signal?: AbortSignal;
+}
+/**
+ * A Model Context Protocol server over **Streamable HTTP** (JSON-RPC 2.0 over POST, JSON responses; no
+ * server-initiated SSE stream, so GET answers 405). Implements `initialize`, `ping`, `tools/list`,
+ * `tools/call`, empty `resources/list` / `prompts/list`, notifications and batches. Requests are authenticated
+ * with REST authentication classes and every tool runs as the authenticated user.
+ */
+declare class McpServer {
+    readonly opts: McpServerOptions;
+    constructor(opts?: McpServerOptions);
+    /** All exposed tools (toolkits expanded, agents as `ask_<name>`). */
+    getTools(): AgentTool[];
+    /** `tools/list` entries. */
+    listTools(): Array<Record<string, unknown>>;
+    /** `tools/call`: run a tool as `ctx.user`. Tool failures are results with `isError: true`. */
+    callTool(name: string, args: unknown, ctx: McpCallContext): Promise<Record<string, unknown>>;
+    /** `initialize` result. */
+    initializeResult(params: Record<string, unknown>): Record<string, unknown>;
+    /** Handle one JSON-RPC message; `null` for notifications and client responses (nothing to send). */
+    handleMessage(message: unknown, ctx: McpCallContext): Promise<JsonRpcResponse | null>;
+    protected dispatch(method: string, params: Record<string, unknown>, ctx: McpCallContext): Promise<unknown>;
+    /** Handle a parsed POST body (single message or batch). Returns the HTTP status and JSON body (or none). */
+    handleBody(body: unknown, ctx: McpCallContext): Promise<{
+        status: number;
+        body?: unknown;
+    }>;
+    /** The Streamable HTTP endpoint view. */
+    asView(): _ghuri_rest.APIViewFunction;
+    /** URL patterns: mount with `path('mcp/', server.urls)`. */
+    get urls(): UrlPatterns;
+}
+/** A JSON-RPC error raised while dispatching. */
+declare class McpError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    constructor(code: number, message: string, data?: unknown | undefined);
+}
+/** An agent exposed as an MCP tool (`ask_<name>`). */
+declare function agentTool(name: string, factory: () => Agent): AgentTool;
+/** The Streamable HTTP endpoint (POST JSON-RPC; GET / DELETE → 405). */
+declare class McpView extends APIView {
+    mcpServer: McpServer;
+    rendererClasses: (typeof JSONRenderer)[];
+    getAuthenticators(): BaseAuthentication[];
+    getPermissions(): BasePermission[];
+    performContentNegotiation(request: APIRequest, _force?: boolean): [any, string];
+    /** Authentication / permission failures keep their HTTP status (401 + WWW-Authenticate) with a JSON-RPC body. */
+    handleException(exc: unknown): Promise<APIResponse>;
+    post(request: APIRequest): Promise<APIResponse | Response>;
+    get(): Promise<Response>;
+    delete(): Promise<Response>;
+}
+
+type AgentClass = new () => Agent;
+/**
+ * 503: the agent's model can't be used (missing provider package, API key or Workers AI binding). The reason
+ * is shown with `DEBUG`; production answers stay generic.
+ */
+declare class ModelUnavailable extends APIException {
+    static statusCode: number;
+    static defaultDetail: string;
+    static defaultCode: string;
+}
+/** `AGENTS.AUTHENTICATION_CLASSES`, else `REST_FRAMEWORK.DEFAULT_AUTHENTICATION_CLASSES`. */
+declare function agentAuthenticationClasses(): AuthenticationClass[] | undefined;
+/** Shared base: agent auth settings, permissions from the agent, JSON only (SSE returned as raw responses). */
+declare abstract class AgentBaseView extends APIView {
+    agentRouter: AgentRouter;
+    agentName: string;
+    _agent?: Agent;
+    rendererClasses: (typeof JSONRenderer)[];
+    /** The agent instance serving this request. */
+    get agent(): Agent;
+    getAuthenticators(): BaseAuthentication[];
+    getPermissions(): BasePermission[];
+    performContentNegotiation(request: APIRequest, _force?: boolean): [any, string];
+    protected requireMemory(): void;
+}
+/**
+ * `POST <name>/chat` — `{ message, conversationId? }` (or an AI SDK `useChat` body with `messages`). Streams the
+ * AI SDK UI message stream as SSE when `Accept: text/event-stream` or `?stream=1`, otherwise answers JSON
+ * `{ conversationId, text, toolCalls, usage, finishReason }`.
+ */
+declare class AgentChatView extends AgentBaseView {
+    post(request: APIRequest): Promise<Response | APIResponse>;
+}
+/** `GET <name>/conversations/` — the requesting user's conversations with the agent (newest first). */
+declare class ConversationListView extends AgentBaseView {
+    get(request: APIRequest): Promise<APIResponse>;
+}
+/** `GET / DELETE <name>/conversations/<id>/` — one conversation with its messages (owner only). */
+declare class ConversationDetailView extends AgentBaseView {
+    protected conversation(request: APIRequest, id: string): Promise<any>;
+    get(request: APIRequest, kwargs: Record<string, any>): Promise<APIResponse>;
+    delete(request: APIRequest, kwargs: Record<string, any>): Promise<APIResponse>;
+}
+interface AgentRouterOptions {
+    /** URL name prefix (default `'agents'`: `agents-support-chat`). */
+    urlNamePrefix?: string;
+}
+/**
+ * Serves agents over HTTP (and MCP).
+ *
+ * ```ts
+ * const agents = new AgentRouter()
+ * agents.register('support', SupportAgent)
+ * export const urlpatterns = [path('agents/', include(agents.urls)), path('mcp/', agents.mcp({ name: 'shop' }))]
+ * // POST /agents/support/chat   GET /agents/support/conversations/   GET|DELETE /agents/support/conversations/<id>/
+ * ```
+ */
+declare class AgentRouter {
+    readonly registry: Map<string, AgentClass>;
+    readonly opts: AgentRouterOptions;
+    _urls?: UrlPatterns;
+    constructor(opts?: AgentRouterOptions);
+    /** Register an agent class under `name` (URL segment, conversation `agent` value, MCP `ask_<name>`). */
+    register(name: string, agentClass: AgentClass): this;
+    /**
+     * Consume queued runs (`agent.enqueue()`) from the Cloudflare Queue named `queue` (default: every queue).
+     * Call it once, e.g. from an AppConfig's `ready()`. Returns an unregister function.
+     */
+    consumeQueue(queue?: string): () => void;
+    /** A fresh agent instance for `name`. */
+    create(name: string): Agent;
+    /** Registered agent names. */
+    get names(): string[];
+    getUrls(): UrlPatterns;
+    /**
+     * A Streamable HTTP MCP endpoint exposing `tools` plus the registered agents as `ask_<name>` tools
+     * (`agents: false` to leave them out, or a list of names). Mount it with `path('mcp/', agents.mcp())`.
+     */
+    mcp(opts?: Omit<McpServerOptions, 'agents'> & {
+        agents?: boolean | string[];
+    }): UrlPatterns;
+    /** The `McpServer` behind `mcp()` (for tests / custom mounting). */
+    mcpServer(opts?: Omit<McpServerOptions, 'agents'> & {
+        agents?: boolean | string[];
+    }): McpServer;
+    /** URL patterns to `include()`. */
+    get urls(): UrlPatterns;
+}
+
+/** Credentials / options for one provider (`AGENTS.PROVIDERS.anthropic`). */
+interface ProviderConfig {
+    apiKey?: string;
+    baseURL?: string;
+    /** Extra options passed to the provider factory (`createAnthropic({...})`). */
+    [option: string]: unknown;
+}
+/** `AGENTS` settings. Every key is optional. */
+interface AgentsSettings {
+    /** Model used by agents without a `model` (`'workers-ai:@cf/meta/llama-3.3-70b-instruct-fp8-fast'`). */
+    DEFAULT_MODEL?: string | LanguageModel;
+    /** Workers AI binding name (default `'AI'`). */
+    AI_BINDING?: string;
+    /** Provider credentials: `{ anthropic: { apiKey }, openai: { apiKey }, 'workers-ai': { gateway } }`. */
+    PROVIDERS?: Record<string, ProviderConfig>;
+    /** Default step limit of the tool loop (default 10). */
+    MAX_STEPS?: number;
+    /** Authentication for the chat / MCP endpoints (default `REST_FRAMEWORK.DEFAULT_AUTHENTICATION_CLASSES`). */
+    AUTHENTICATION_CLASSES?: AuthenticationClass[];
+    /** Permission classes for agents that don't set `permissionClasses` (default `[IsAuthenticated]`). */
+    PERMISSION_CLASSES?: PermissionClass[];
+    /** Queue producer binding used by `agent.enqueue()` (default `'AGENTS_QUEUE'`). */
+    QUEUE_BINDING?: string;
+}
+declare module '@ghuri/core' {
+    interface GhuriSettings {
+        /** `@ghuri/agents` settings. */
+        AGENTS?: AgentsSettings;
+    }
+}
+/** The `AGENTS` settings of the current context (empty outside a context). */
+declare function agentsSettings(): AgentsSettings;
+
+interface ProviderContext {
+    /** Worker bindings / environment variables of the current request. */
+    env: Env;
+    settings: AgentsSettings;
+    /** `AGENTS.PROVIDERS[name]` (empty object when unset). */
+    config: ProviderConfig;
+}
+/** Builds a model for `'<provider>:<modelId>'`. Import provider packages lazily inside the factory. */
+type ProviderFactory = (modelId: string, ctx: ProviderContext) => LanguageModel | Promise<LanguageModel>;
+/**
+ * Register (or replace) a model provider used by `'name:model-id'` strings.
+ *
+ * ```ts
+ * registerProvider('google', async (id, { config }) => {
+ *   const { createGoogleGenerativeAI } = await import('@ai-sdk/google')
+ *   return createGoogleGenerativeAI({ apiKey: config.apiKey })(id)
+ * })
+ * ```
+ */
+declare function registerProvider(name: string, factory: ProviderFactory): void;
+declare function unregisterProvider(name: string): boolean;
+/** Names of registered providers. */
+declare function getProviders(): string[];
+/** Is `value` an AI SDK language model instance (not a string id)? */
+declare function isLanguageModel(value: unknown): boolean;
+/**
+ * Resolve an agent's `model`: an AI SDK `LanguageModel` is returned as is; `'provider:model-id'` strings go
+ * through the provider registry (`workers-ai:`, `anthropic:`, `openai:` built in). Falls back to
+ * `AGENTS.DEFAULT_MODEL`.
+ */
+declare function resolveModel(model?: string | LanguageModel | null, env?: Env): Promise<LanguageModel>;
+
+/**
+ * Normalize anything thrown by a tool into a `ToolError` the model / MCP client may see. Expected failures
+ * (permission denied, not found, validation) keep their message; unexpected errors are reported generically
+ * unless `DEBUG` is on (the real error is logged).
+ */
+declare function toToolError(err: unknown, toolName?: string): ToolError;
+/** Validate arguments and run a tool, normalizing errors (used by agents and the MCP server). */
+declare function runTool(tool: AgentTool, args: unknown, ctx: ToolContext): Promise<unknown>;
+
+interface ViewSetToolsOptions {
+    /** Actions to expose (`['list', 'retrieve', 'create', 'partialUpdate', 'destroy', 'publish']`; `'delete'` is an
+     * alias of `'destroy'`). Default: every routed action of the viewset. */
+    actions?: string[];
+    /** Tool name prefix (default: the router prefix, or the model's plural name: `posts` → `posts_list`). */
+    prefix?: string;
+    /** Router basename when a viewset class is given (default: derived from `queryset`). */
+    basename?: string;
+    /** Override tool descriptions per action. */
+    descriptions?: Record<string, string>;
+}
+interface ActionToolSpec {
+    /** Viewset action (`destroy`). */
+    action: string;
+    /** Tool name suffix (`delete`). */
+    suffix: string;
+    description?: string;
+}
+/**
+ * Tools for a REST viewset, executed through `router.registry[i].invoke()`: the viewset's permission classes,
+ * throttles, queryset, filters, pagination, validation and serializers apply exactly as over HTTP, as the
+ * requesting user. HTTP errors (403, 404, 400…) become tool errors the model can read.
+ *
+ * ```ts
+ * new ViewSetTools(PostViewSet, { actions: ['list', 'retrieve', 'create'] })   // posts_list, posts_retrieve, …
+ * new ViewSetTools(router.registry[0])                                         // every action of a registration
+ * ```
+ */
+declare class ViewSetTools extends Toolkit {
+    readonly entry: RouterRegistration;
+    readonly opts: ViewSetToolsOptions;
+    readonly prefix: string;
+    protected specs?: ActionToolSpec[];
+    constructor(target: any, opts?: ViewSetToolsOptions);
+    /** The (action, tool suffix) pairs to expose. */
+    actionSpecs(): ActionToolSpec[];
+    getTools(): AgentTool[];
+    get model(): any;
+    protected modelNames(): {
+        one: string;
+        many: string;
+    };
+    protected lookup(): {
+        kwarg: string;
+        param: string;
+        schema: JSONSchema;
+    };
+    protected describe(spec: ActionToolSpec, endpoint: {
+        detail: boolean;
+        extra: boolean;
+        description?: string;
+    }): string;
+    protected buildTool(spec: ActionToolSpec): AgentTool;
+    /** OpenAPI query parameters of the list action (filter backends + paginator). */
+    protected listParameters(): Array<Record<string, unknown>>;
+}
+
+type ModelToolAction = 'list' | 'retrieve' | 'create' | 'update' | 'delete';
+interface ModelToolsOptions {
+    /** Tools to generate (default `['list', 'retrieve']`: read-only unless you opt into writes). */
+    actions?: ModelToolAction[];
+    /** Serializer class (default: a `ModelSerializer` with `fields: '__all__'`). */
+    serializer?: any;
+    /** Scope the queryset to the requesting user: `(qs, user) => qs.filter({ owner: user.pk })`. Applies to
+     * every action (list, retrieve, update, delete), so other users' rows are invisible (404). */
+    filter?: (qs: any, user: RequestUser) => any;
+    /** Enable `search` over these fields (SearchFilter lookups: `'title'`, `'^slug'`, `'=email'`). */
+    searchFields?: string[];
+    /** Fields the model may order by (`ordering=-createdAt`); `'__all__'` for any readable field. */
+    orderingFields?: string[] | '__all__';
+    /** Default ordering. */
+    ordering?: string | string[];
+    /** Exact-match filters (FieldFilter): `['status']` or `{ createdAt: ['gte', 'lte'] }`. */
+    filterFields?: string[] | Record<string, string[]>;
+    /** Page size of `list` (default 20; the model may request up to `maxPageSize` with `pageSize`). */
+    pageSize?: number;
+    maxPageSize?: number;
+    /** REST permission classes checked for every call (default `REST_FRAMEWORK.DEFAULT_PERMISSION_CLASSES`). */
+    permissionClasses?: PermissionClass[];
+    /** Extra values saved on create / update, e.g. the owner: `(user) => ({ owner: user.pk })`. */
+    saveKwargs?: (user: RequestUser, action: 'create' | 'update') => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /** Tool name prefix (default: the model's plural verbose name: `posts`). */
+    prefix?: string;
+    /** Override tool descriptions per action. */
+    descriptions?: Partial<Record<ModelToolAction, string>>;
+}
+/**
+ * CRUD tools for a model: `posts_list`, `posts_retrieve`, `posts_create`, `posts_update`, `posts_delete`.
+ * Built on a generated `ModelViewSet`, so serializers (validation, read-only fields), permission classes,
+ * filters and pagination behave exactly like your REST API, and every call runs as the requesting user.
+ *
+ * ```ts
+ * new ModelTools(Order, {
+ *   actions: ['list', 'retrieve'],
+ *   serializer: OrderSerializer,
+ *   filter: (qs, user) => qs.filter({ customer: user.pk }),
+ *   searchFields: ['number'], orderingFields: ['createdAt'],
+ * })
+ * ```
+ */
+declare class ModelTools extends ViewSetTools {
+    readonly modelClass: any;
+    readonly modelOptions: ModelToolsOptions;
+    constructor(model: any, opts?: ModelToolsOptions);
+    actionSpecs(): ActionToolSpec[];
+}
+
+interface RouterToolsOptions {
+    /** Only these registrations (by prefix or basename), or a predicate. */
+    include?: string[] | ((entry: RouterRegistration) => boolean);
+    /** Skip these registrations (by prefix or basename), or tool names (`posts_destroy`). */
+    exclude?: string[] | ((entry: RouterRegistration) => boolean);
+    /** Restrict actions per registration: `{ posts: ['list', 'retrieve'] }`. */
+    actions?: Record<string, string[]>;
+    /** Only read-only actions (GET). */
+    readOnly?: boolean;
+}
+/**
+ * Expose a whole REST API as tools: one `ViewSetTools` per router registration.
+ *
+ * ```ts
+ * new RouterTools(router, { exclude: ['users'], readOnly: true })
+ * ```
+ */
+declare class RouterTools extends Toolkit {
+    readonly router: BaseRouter;
+    readonly opts: RouterToolsOptions;
+    constructor(router: BaseRouter, opts?: RouterToolsOptions);
+    /** The `ViewSetTools` of each included registration. */
+    toolkits(): ViewSetTools[];
+    getTools(): AgentTool[];
+}
+
+/** Make `name` a valid LLM / MCP tool name: `[A-Za-z0-9_-]{1,64}`. */
+declare function sanitizeToolName(name: string): string;
+/** JSON Schema of a tool input given as a Zod schema, a JSON Schema object or nothing (no arguments). */
+declare function toJSONSchema(input: unknown): JSONSchema;
+
+export { AGENT_JOB_TYPE, type ActionToolSpec, Agent, AgentChatView, type AgentClass, AgentError, type AgentInput, type AgentJob, AgentRouter, type AgentRouterOptions, type AgentRunContext, type AgentRunResult, AgentStream, type AgentTool, AgentsConfig, type AgentsSettings, Conversation, ConversationDetailView, ConversationListView, ConversationNotFound, type EnqueueOptions, JSONRPC, type JSONSchema, type JsonRpcId, type JsonRpcResponse, MCP_LATEST_PROTOCOL_VERSION, MCP_PROTOCOL_VERSIONS, MESSAGE_ROLES, type McpCallContext, McpError, McpServer, type McpServerOptions, McpView, Message, type MessageRole, ModelResolutionError, type ModelToolAction, ModelTools, type ModelToolsOptions, ModelUnavailable, type ProviderConfig, type ProviderContext, type ProviderFactory, RouterTools, type RouterToolsOptions, type RunOptions, TOOL, TOOL_OPTIONS, type ToolAnnotations, type ToolCallInfo, type ToolCallRecord, type ToolContext, type ToolDecorator, type ToolEntry, ToolError, ToolInputError, type ToolOptions, Toolkit, type ToolsInput, UnknownToolError, ViewSetTools, type ViewSetToolsOptions, agentAuthenticationClasses, agentTool, agentsSettings, collectDeclaredTools, consumeAgentQueue, createConversation, defineTool, enqueueRun, getConversation, getProviders, isAgentTool, isLanguageModel, isToolDecorator, isToolkit, loadJobUser, loadMessages, memoryAvailable, registerProvider, resolveModel, runTool, sanitizeToolName, saveMessages, standaloneTool, toJSONSchema, toToolError, tool, unregisterProvider };