@adonis-agora/agent 0.1.0

package/dist/src/ai-sdk/ai-sdk-model.js

@@ -0,0 +1,263 @@
+import { jsonSchema, streamText, tool, } from 'ai';
+/**
+ * Adapt a Vercel AI SDK v7 `LanguageModel` to the core `ModelProvider` SPI so a host app writes
+ * zero provider code. Streams text deltas to `args.sink`, returns the assembled text, requested
+ * tool calls, usage, and (when a gateway reports it) the real USD cost. It never executes tools —
+ * tools are handed to the SDK WITHOUT an `execute` fn, so the SDK returns tool-calls for the agent
+ * loop to run as its own (replay-safe) steps.
+ */
+export function aiSdkModel(model, opts) {
+    return {
+        async runTurn(args) {
+            const result = streamText({
+                ...opts,
+                model,
+                instructions: args.system,
+                messages: mapMessages(args.messages),
+                tools: mapTools(args.tools),
+                ...(args.abortSignal ? { abortSignal: args.abortSignal } : {}),
+            });
+            // Encode deltas to bytes for the live token sink, exactly as the reference fake provider does.
+            const encoder = new TextEncoder();
+            let text = '';
+            for await (const part of result.stream) {
+                if (part.type === 'text-delta') {
+                    text += part.text;
+                    await args.sink.write(encoder.encode(part.text));
+                }
+            }
+            // The promise accessors resolve once the stream is fully consumed above. `modelId` and the
+            // reported cost live on the final step (the top-level aliases are deprecated in AI SDK v7).
+            const [toolCalls, usage, finalStep] = await Promise.all([
+                result.toolCalls,
+                result.usage,
+                result.finalStep,
+            ]);
+            const modelId = finalStep.response.modelId;
+            const costUsd = extractCostUsd(finalStep.providerMetadata);
+            return {
+                text,
+                toolCalls: toolCalls.map(mapToolCall),
+                usage: mapUsage(usage),
+                ...(typeof modelId === 'string' && modelId.length > 0 ? { modelId } : {}),
+                ...(costUsd !== undefined ? { costUsd } : {}),
+            };
+        },
+    };
+}
+/**
+ * Map core `ModelMessage[]` → SDK messages. Tool calls ride on the assistant message as
+ * `tool-call` content parts; tool results become a following `tool` message. A message can
+ * therefore expand into two SDK messages, so we build the list imperatively.
+ */
+function mapMessages(messages) {
+    const out = [];
+    for (const message of messages) {
+        if (message.role === 'system') {
+            out.push({ role: 'system', content: message.content });
+            continue;
+        }
+        if (message.role === 'user') {
+            const attachments = message.attachments ?? [];
+            out.push(attachments.length === 0
+                ? { role: 'user', content: message.content }
+                : { role: 'user', content: userContentWithAttachments(message.content, attachments) });
+            continue;
+        }
+        const toolCalls = message.toolCalls ?? [];
+        if (toolCalls.length > 0) {
+            const content = [];
+            if (message.content.length > 0) {
+                content.push({ type: 'text', text: message.content });
+            }
+            for (const call of toolCalls) {
+                content.push({
+                    type: 'tool-call',
+                    toolCallId: call.id,
+                    toolName: call.name,
+                    input: call.input,
+                });
+            }
+            out.push({ role: 'assistant', content: assistantContent(content) });
+        }
+        else {
+            out.push({ role: 'assistant', content: message.content });
+        }
+        const toolResults = message.toolResults ?? [];
+        if (toolResults.length > 0) {
+            out.push({
+                role: 'tool',
+                content: toolResults.map((result) => ({
+                    type: 'tool-result',
+                    toolCallId: result.id,
+                    toolName: result.name,
+                    output: toModelOutput(result),
+                })),
+            });
+        }
+    }
+    return out;
+}
+/** `Array<TextPart | ToolCallPart>` is a valid `AssistantContent`; name the widening explicitly. */
+function assistantContent(parts) {
+    return parts;
+}
+/**
+ * Build a multimodal user content array: the text (when non-empty) followed by one part per
+ * attachment — `image/*` → an image part, everything else → a file part (Bedrock Claude reads a PDF
+ * this way). The attachment's `url` is passed straight through as the part's source; making it
+ * reachable by the provider is the consumer's concern (the staging SPI's job), not the adapter's.
+ */
+function userContentWithAttachments(text, attachments) {
+    const parts = [];
+    if (text.length > 0) {
+        parts.push({ type: 'text', text });
+    }
+    for (const attachment of attachments) {
+        parts.push(attachment.contentType.startsWith('image/')
+            ? { type: 'image', image: new URL(attachment.url), mediaType: attachment.contentType }
+            : {
+                type: 'file',
+                data: new URL(attachment.url),
+                mediaType: attachment.contentType,
+                filename: attachment.name,
+            });
+    }
+    return parts;
+}
+/**
+ * NOTE: core tool `output` is `unknown`, but the SDK's structured `json` output demands a
+ * `JSONValue`. Rather than an unsafe cast we serialise every result to text — the model reads
+ * tool output as text regardless, and the loop already validated the tool INPUT via the schema.
+ */
+function toModelOutput(result) {
+    if (result.error !== undefined) {
+        return { type: 'text', value: result.error };
+    }
+    const { output } = result;
+    if (typeof output === 'string') {
+        return { type: 'text', value: output };
+    }
+    return { type: 'text', value: JSON.stringify(output ?? null) };
+}
+/**
+ * Map core `ToolDefinition[]` → an SDK `ToolSet`. Each tool is built WITHOUT an `execute` fn so the
+ * SDK surfaces the tool-call for the agent loop to run, instead of executing it inline.
+ */
+function mapTools(tools) {
+    const set = {};
+    for (const definition of tools) {
+        set[definition.name] = tool({
+            description: definition.description,
+            inputSchema: toSdkInputSchema(definition.inputSchema),
+        });
+    }
+    return set;
+}
+/**
+ * Convert a core `StandardSchemaV1` into the schema the SDK feeds the model as tool parameters.
+ * The SDK's own `asSchema` derives a precise JSON schema from exactly two kinds of Standard Schema,
+ * so we hand those straight through and let it do the conversion:
+ *
+ *  - **Zod** (`~standard.vendor === 'zod'`) — the SDK runs zod-to-json-schema natively. Zod 3 does
+ *    NOT expose the Standard JSON Schema extension, so this vendor tag is the only way to recognise
+ *    it, and it's the common case (`@AiTool({ input: z.object(...) })`).
+ *  - **Standard JSON Schema** (`~standard.jsonSchema`) — Valibot, ArkType, and Zod 4 implement the
+ *    extension; the SDK calls its `input()` converter to derive the schema.
+ *
+ * Anything else is a bare Standard Schema the SDK can't introspect (its `asSchema` throws on one), so
+ * we degrade to a permissive object schema — the model loses the parameter shapes, but the agent loop
+ * still validates the tool input against the real schema via `~standard.validate` before running it.
+ */
+function toSdkInputSchema(schema) {
+    if (isZodSchema(schema) || hasStandardJsonSchema(schema)) {
+        return schema;
+    }
+    return jsonSchema({ type: 'object', properties: {}, additionalProperties: true });
+}
+/**
+ * True for a Zod schema. Zod tags its Standard Schema props with `vendor: 'zod'`, and its own type
+ * declares `~standard`, so this narrows to `ZodTypeAny` — a member of the SDK's `FlexibleSchema` —
+ * without a cast, letting the SDK convert it natively.
+ */
+function isZodSchema(schema) {
+    return schema['~standard'].vendor === 'zod';
+}
+/** True when the schema carries the Standard JSON Schema converter (`~standard.jsonSchema.input`). */
+function hasStandardJsonSchema(schema) {
+    const standard = schema['~standard'];
+    if (!('jsonSchema' in standard)) {
+        return false;
+    }
+    const converter = standard.jsonSchema;
+    return (typeof converter === 'object' &&
+        converter !== null &&
+        'input' in converter &&
+        typeof converter.input === 'function');
+}
+function mapToolCall(call) {
+    return { id: call.toolCallId, name: call.toolName, input: call.input };
+}
+/**
+ * Map SDK usage → core `MessageUsage`. Cache/reasoning breakdowns are optional and only added when
+ * the provider reports them (conditional spread, never an `undefined` assignment). AI SDK v7 carries
+ * them on the `*Details` objects; the deprecated flat aliases (`cachedInputTokens`, `reasoningTokens`)
+ * were removed.
+ */
+function mapUsage(usage) {
+    const cacheReadTokens = usage.inputTokenDetails?.cacheReadTokens;
+    const cacheWriteTokens = usage.inputTokenDetails?.cacheWriteTokens;
+    const reasoningTokens = usage.outputTokenDetails?.reasoningTokens;
+    return {
+        inputTokens: usage.inputTokens ?? 0,
+        outputTokens: usage.outputTokens ?? 0,
+        ...(cacheWriteTokens !== undefined ? { cacheWriteTokens } : {}),
+        ...(cacheReadTokens !== undefined ? { cacheReadTokens } : {}),
+        ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
+    };
+}
+/**
+ * A gateway reports the ACTUAL spend for the turn; a direct provider (Anthropic/OpenAI/Bedrock)
+ * doesn't, leaving this undefined so the governance read-model estimates from tokens. We read the
+ * Vercel AI Gateway shape (`gateway.cost`) first, then OpenRouter (`openrouter.total_cost`, also
+ * nested under `openrouter.usage.total_cost`).
+ */
+function extractCostUsd(metadata) {
+    if (!metadata) {
+        return undefined;
+    }
+    const gateway = metadata.gateway;
+    const gatewayCost = gateway ? toFiniteNumber(gateway.cost) : undefined;
+    if (gatewayCost !== undefined) {
+        return gatewayCost;
+    }
+    const openrouter = metadata.openrouter;
+    if (openrouter) {
+        const direct = toFiniteNumber(openrouter.total_cost);
+        if (direct !== undefined) {
+            return direct;
+        }
+        const usage = asJsonObject(openrouter.usage);
+        if (usage) {
+            const nested = toFiniteNumber(usage.total_cost);
+            if (nested !== undefined) {
+                return nested;
+            }
+        }
+    }
+    return undefined;
+}
+function toFiniteNumber(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number.parseFloat(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function asJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
+//# sourceMappingURL=ai-sdk-model.js.map

package/dist/src/ai-sdk/ai-sdk-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk-model.js","sourceRoot":"","sources":["../../../src/ai-sdk/ai-sdk-model.ts"],"names":[],"mappings":"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"}

package/dist/src/ai-sdk/index.d.ts

@@ -0,0 +1,2 @@
+export { aiSdkModel, type AiSdkModelOptions } from './ai-sdk-model.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/ai-sdk/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/src/ai-tool-ref.d.ts

@@ -0,0 +1,79 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { AiToolCtx, ToolHandler } from './spi/tool.js';
+import type { ToolSpec } from './types.js';
+/**
+ * The symbol the `@AiTool` decorator stamps its options onto (the tool class), read back by
+ * discovery to register the class into the {@link import('./tool-registry.js').ToolRegistry}. A
+ * global-registry symbol (`Symbol.for`) so it survives duplicate copies of this package in a tree.
+ */
+export declare const AI_TOOL_META_KEY: unique symbol;
+/**
+ * Brand stamped on the object {@link defineTool} returns so discovery picks it up when it walks a
+ * module's exports — the functional alternative to an `@AiTool` class.
+ */
+export declare const AGENT_TOOL_BRAND: unique symbol;
+export interface AiToolOptions {
+    name: string;
+    /**
+     * `read` auto-executes; `action` requires HITL approval. (Core's `ToolKind` also has `agent` for
+     * delegation, but that kind is synthesized from an agent's `delegatesTo` — never authored here.)
+     */
+    kind: 'read' | 'action';
+    description: string;
+    /**
+     * Input schema as a [Standard Schema](https://standardschema.dev) — Zod, Valibot, or ArkType.
+     * Validated (again) before the handler runs.
+     */
+    input: StandardSchemaV1;
+    /** Roles allowed to invoke. Omit to inherit the config's `defaultRoles` (ADMIN-only by default). */
+    roles?: string[];
+    /**
+     * Authz ability checked by an ability-aware `RolesPolicy` (e.g. an `@adonis-agora/authz` Bouncer
+     * adapter → `bouncer.forUser(actor).allows(ability)`). Ignored by the default role-based policy.
+     */
+    ability?: string;
+}
+/** The metadata the `@AiTool` decorator stamps onto a class for discovery + registration. */
+export type AiToolMeta = AiToolOptions;
+/** Structural shape of an `@AiTool` class: a constructor whose instance implements `execute`. */
+export type ToolClass = abstract new (...args: never[]) => ToolHandler;
+/**
+ * Marks a class as an AI tool. The class must implement `execute(input, ctx)`. The provider's
+ * `app/agent_tools` discovery (or the generated `hooks/tools` barrel) registers every `@AiTool`
+ * class into the shared `ToolRegistry` at boot.
+ *
+ * ```ts
+ * @AiTool({ name: 'getWeather', kind: 'read', description: '...', input: z.object({ city: z.string() }) })
+ * export default class GetWeatherTool implements ToolHandler<{ city: string }> {
+ *   async execute(input: { city: string }, ctx: AiToolCtx) { return { tempC: 21 } }
+ * }
+ * ```
+ */
+export declare function AiTool(options: AiToolOptions): <T extends ToolClass>(target: T) => T;
+/** Read the {@link AiToolMeta} an `@AiTool` decorator stamped on a class (or an instance's ctor). */
+export declare function readAiToolMeta(target: unknown): AiToolMeta | undefined;
+/** A tool expressed as data + handler (from {@link defineTool}), not an `@AiTool` class. */
+export interface FunctionalTool {
+    spec: ToolSpec;
+    handler: ToolHandler;
+}
+/** A {@link FunctionalTool} carrying {@link AGENT_TOOL_BRAND} — what {@link defineTool} returns. */
+export interface BrandedFunctionalTool extends FunctionalTool {
+    readonly [AGENT_TOOL_BRAND]: true;
+}
+/** Narrows an arbitrary module export to a branded functional tool for boot-time registration. */
+export declare function isBrandedFunctionalTool(value: unknown): value is BrandedFunctionalTool;
+/**
+ * The functional form of a tool: pass the same options as `@AiTool` plus an `execute` function, get
+ * back a branded `{ spec, handler }` that discovery auto-registers. Export it from an `app/agent_tools`
+ * module (or pass it to `defineConfig({ tools })`).
+ *
+ * ```ts
+ * export const purgeCache = defineTool(
+ *   { name: 'purgeCache', kind: 'action', description: '...', input: z.object({ key: z.string() }) },
+ *   async ({ key }, ctx) => { ... },
+ * )
+ * ```
+ */
+export declare function defineTool<I = unknown>(options: AiToolOptions, execute: (input: I, ctx: AiToolCtx) => Promise<unknown> | unknown): BrandedFunctionalTool;
+//# sourceMappingURL=ai-tool-ref.d.ts.map

package/dist/src/ai-tool-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-tool-ref.d.ts","sourceRoot":"","sources":["../../src/ai-tool-ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAgD,CAAC;AAEvF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAmD,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,EAAE,gBAAgB,CAAC;IACxB,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6FAA6F;AAC7F,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC,iGAAiG;AACjG,MAAM,MAAM,SAAS,GAAG,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,WAAW,CAAC;AAEvE;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,IACnC,CAAC,SAAS,SAAS,EAAE,QAAQ,CAAC,KAAG,CAAC,CAQ3C;AAED,qGAAqG;AACrG,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAUtE;AAED,4FAA4F;AAC5F,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,oGAAoG;AACpG,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,IAAI,CAAC;CACnC;AAED,kGAAkG;AAClG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAQtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EACpC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,GAChE,qBAAqB,CAcvB"}

package/dist/src/ai-tool-ref.js

@@ -0,0 +1,81 @@
+/**
+ * The symbol the `@AiTool` decorator stamps its options onto (the tool class), read back by
+ * discovery to register the class into the {@link import('./tool-registry.js').ToolRegistry}. A
+ * global-registry symbol (`Symbol.for`) so it survives duplicate copies of this package in a tree.
+ */
+export const AI_TOOL_META_KEY = Symbol.for('@agora/agent:ai-tool-meta');
+/**
+ * Brand stamped on the object {@link defineTool} returns so discovery picks it up when it walks a
+ * module's exports — the functional alternative to an `@AiTool` class.
+ */
+export const AGENT_TOOL_BRAND = Symbol.for('@agora/agent:functional-tool');
+/**
+ * Marks a class as an AI tool. The class must implement `execute(input, ctx)`. The provider's
+ * `app/agent_tools` discovery (or the generated `hooks/tools` barrel) registers every `@AiTool`
+ * class into the shared `ToolRegistry` at boot.
+ *
+ * ```ts
+ * @AiTool({ name: 'getWeather', kind: 'read', description: '...', input: z.object({ city: z.string() }) })
+ * export default class GetWeatherTool implements ToolHandler<{ city: string }> {
+ *   async execute(input: { city: string }, ctx: AiToolCtx) { return { tempC: 21 } }
+ * }
+ * ```
+ */
+export function AiTool(options) {
+    return (target) => {
+        Object.defineProperty(target, AI_TOOL_META_KEY, {
+            value: options,
+            enumerable: false,
+            configurable: true,
+        });
+        return target;
+    };
+}
+/** Read the {@link AiToolMeta} an `@AiTool` decorator stamped on a class (or an instance's ctor). */
+export function readAiToolMeta(target) {
+    if (target === null || (typeof target !== 'function' && typeof target !== 'object')) {
+        return undefined;
+    }
+    const direct = target[AI_TOOL_META_KEY];
+    if (direct !== undefined) {
+        return direct;
+    }
+    const ctor = target.constructor;
+    return ctor?.[AI_TOOL_META_KEY];
+}
+/** Narrows an arbitrary module export to a branded functional tool for boot-time registration. */
+export function isBrandedFunctionalTool(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        AGENT_TOOL_BRAND in value &&
+        'spec' in value &&
+        'handler' in value);
+}
+/**
+ * The functional form of a tool: pass the same options as `@AiTool` plus an `execute` function, get
+ * back a branded `{ spec, handler }` that discovery auto-registers. Export it from an `app/agent_tools`
+ * module (or pass it to `defineConfig({ tools })`).
+ *
+ * ```ts
+ * export const purgeCache = defineTool(
+ *   { name: 'purgeCache', kind: 'action', description: '...', input: z.object({ key: z.string() }) },
+ *   async ({ key }, ctx) => { ... },
+ * )
+ * ```
+ */
+export function defineTool(options, execute) {
+    const spec = {
+        name: options.name,
+        kind: options.kind,
+        description: options.description,
+        inputSchema: options.input,
+        ...(options.roles !== undefined ? { roles: options.roles } : {}),
+        ...(options.ability !== undefined ? { ability: options.ability } : {}),
+    };
+    return {
+        [AGENT_TOOL_BRAND]: true,
+        spec,
+        handler: { execute: (input, ctx) => Promise.resolve(execute(input, ctx)) },
+    };
+}
+//# sourceMappingURL=ai-tool-ref.js.map

package/dist/src/ai-tool-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-tool-ref.js","sourceRoot":"","sources":["../../src/ai-tool-ref.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAkB,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAEvF;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAkB,MAAM,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;AA8B1F;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,MAAM,CAAC,OAAsB;IAC3C,OAAO,CAAsB,MAAS,EAAK,EAAE;QAC3C,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,gBAAgB,EAAE;YAC9C,KAAK,EAAE,OAAO;YACd,UAAU,EAAE,KAAK;YACjB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,cAAc,CAAC,MAAe;IAC5C,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,MAAM,KAAK,UAAU,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,EAAE,CAAC;QACpF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,MAAM,GAAI,MAA8C,CAAC,gBAAgB,CAAC,CAAC;IACjF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,IAAI,GAAI,MAAgE,CAAC,WAAW,CAAC;IAC3F,OAAO,IAAI,EAAE,CAAC,gBAAgB,CAAC,CAAC;AAClC,CAAC;AAaD,kGAAkG;AAClG,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,gBAAgB,IAAI,KAAK;QACzB,MAAM,IAAI,KAAK;QACf,SAAS,IAAI,KAAK,CACnB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CACxB,OAAsB,EACtB,OAAiE;IAEjE,MAAM,IAAI,GAAa;QACrB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,WAAW,EAAE,OAAO,CAAC,KAAK;QAC1B,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAC;IACF,OAAO;QACL,CAAC,gBAAgB,CAAC,EAAE,IAAI;QACxB,IAAI;QACJ,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,KAAU,EAAE,GAAG,CAAC,CAAC,EAAE;KAChF,CAAC;AACJ,CAAC"}

package/dist/src/authorizer.d.ts

@@ -0,0 +1,18 @@
+import { DefaultRolesPolicy } from './tool-registry.js';
+import type { Actor, ToolSpec } from './types.js';
+/**
+ * The default tool authorizer the provider binds when `config/agent.ts` sets no `authorizer` /
+ * `rolesPolicy`. Fail-closed and ADMIN-only by default: a tool that declares no `roles` is offered
+ * (and invocable) ONLY to an actor holding one of the configured `defaultRoles` (`['ADMIN']` unless
+ * overridden). Authorization is a plain set intersection of the actor's roles against the tool's.
+ *
+ * This is a thin, explicitly-named binding over core's {@link DefaultRolesPolicy} (the `RolesPolicy`
+ * seam) so apps that plug an ability-aware gate (`@adonis-agora/authz` Bouncer adapter) swap ONLY the
+ * binding, never the seam. The double check — offered-tools filter AND an invoke-time re-check inside
+ * `ToolRegistry.invoke` — both run through this same `can(actor, tool)`.
+ */
+export declare class DefaultToolAuthorizer extends DefaultRolesPolicy {
+    constructor(defaultRoles?: string[]);
+    can(actor: Actor, tool: ToolSpec): boolean;
+}
+//# sourceMappingURL=authorizer.d.ts.map

package/dist/src/authorizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorizer.d.ts","sourceRoot":"","sources":["../../src/authorizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,kBAAkB;gBAC/C,YAAY,GAAE,MAAM,EAAc;IAIrC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO;CAGpD"}

package/dist/src/authz/authz-tool-authorizer.d.ts

@@ -0,0 +1,85 @@
+import type { RolesPolicy } from '../spi/roles-policy.js';
+import type { Actor, ToolSpec } from '../types.js';
+/**
+ * Tenant scope shape — a structural mirror of `@adonis-agora/authz`'s `TenantScope`
+ * (`{ tenantId?: string }`). Kept local so the adapter references the authz package
+ * only by structure, never by import (see {@link AuthzServiceLike}).
+ */
+export interface AuthzTenantScope {
+    tenantId?: string;
+}
+/**
+ * The structural slice of `@adonis-agora/authz`'s `AuthzService` this adapter needs: a
+ * tenant-scoped, wildcard permission check.
+ *
+ * Typing it structurally (rather than `import type { AuthzService } from '@adonis-agora/authz'`)
+ * is what keeps `@adonis-agora/authz` an OPTIONAL lazy peer — the adapter carries zero import of
+ * the package, so it is pulled in only by an app that has already wired authz and hands its
+ * `AuthzService` to the factory. The `./authz` subpath is the load boundary: the main entry never
+ * references this file, so apps that don't use authz never load it.
+ */
+export interface AuthzServiceLike {
+    /**
+     * Does `user` hold `permission` (with wildcard matching, e.g. `posts.*` ⊇ `posts.edit`),
+     * scoped to `options.scope`? Mirrors `AuthzService.can`.
+     */
+    can(user: unknown, permission: string, options?: {
+        scope?: AuthzTenantScope;
+    }): Promise<boolean>;
+}
+/** Options for {@link AuthzToolAuthorizer} / {@link authzToolAuthorizer}. */
+export interface AuthzToolAuthorizerConfig {
+    /**
+     * The `@adonis-agora/authz` `AuthzService` (or any structural match) the adapter consults for
+     * each tool's declared `ability`. The app builds it from its own `config/authz.ts` and passes
+     * the instance here — no host user entity is required.
+     */
+    authz: AuthzServiceLike;
+    /**
+     * Maps an {@link Actor} onto the user object authz resolves a `UserRef` from. Defaults to
+     * `{ id: actor.id }` — enough for authz's `defaultResolveUserRef` (which reads `.id`, defaulting
+     * the type to `user`). Override to attach a polymorphic `type` or a host user entity.
+     */
+    userFromActor?: (actor: Actor) => unknown;
+}
+/** Default {@link Actor} → authz user mapping: the minimal `{ id }` authz needs to resolve a `UserRef`. */
+export declare function defaultUserFromActor(actor: Actor): unknown;
+/**
+ * A {@link RolesPolicy} (the agent's `ToolAuthorizer` seam) backed by `@adonis-agora/authz`
+ * (AdonisJS Bouncer). For each tool it checks the actor against the tool's declared `ability`
+ * via {@link AuthzServiceLike.can}, scoped to the actor's tenant.
+ *
+ * Security posture — FAIL-CLOSED:
+ * - A tool that declares no `ability` is NEVER authorized (deny). Unlike the role-based default,
+ *   there is no ADMIN fallback: with authz selected, an un-annotated tool is simply not reachable.
+ * - Any error thrown while resolving the decision denies.
+ *
+ * Tenant isolation: `actor.tenantRef` is passed as the authz **scope** (`{ tenantId }`), so a
+ * permission granted in one tenant never authorizes a tool call made in another. When the actor has
+ * no `tenantRef`, the check runs against the global scope (authz's default).
+ *
+ * The agent's double check — the offered-tools filter AND the invoke-time re-check inside
+ * `ToolRegistry` — both run through this same `can(actor, tool)`, so offer and invoke stay
+ * consistent.
+ */
+export declare class AuthzToolAuthorizer implements RolesPolicy {
+    #private;
+    constructor(config: AuthzToolAuthorizerConfig);
+    can(actor: Actor, tool: ToolSpec): Promise<boolean>;
+}
+/**
+ * Factory for an {@link AuthzToolAuthorizer}. Wire it in `config/agent.ts` as the tool authorizer,
+ * replacing the ADMIN-only `DefaultToolAuthorizer`:
+ *
+ * ```ts
+ * import { defineConfig } from '@adonis-agora/agent'
+ * import { authzToolAuthorizer } from '@adonis-agora/agent/authz'
+ *
+ * export default defineConfig({
+ *   model: () => aiSdkModel({ model: '...' }),
+ *   authorizer: authzToolAuthorizer({ authz: await app.container.make('authz.service') }),
+ * })
+ * ```
+ */
+export declare function authzToolAuthorizer(config: AuthzToolAuthorizerConfig): AuthzToolAuthorizer;
+//# sourceMappingURL=authz-tool-authorizer.d.ts.map

package/dist/src/authz/authz-tool-authorizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz-tool-authorizer.d.ts","sourceRoot":"","sources":["../../../src/authz/authz-tool-authorizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClG;AAED,6EAA6E;AAC7E,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;CAC3C;AAED,2GAA2G;AAC3G,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAE1D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,mBAAoB,YAAW,WAAW;;gBAIzC,MAAM,EAAE,yBAAyB;IAKvC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;CAa1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,yBAAyB,GAAG,mBAAmB,CAE1F"}

package/dist/src/authz/authz-tool-authorizer.js

@@ -0,0 +1,63 @@
+/** Default {@link Actor} → authz user mapping: the minimal `{ id }` authz needs to resolve a `UserRef`. */
+export function defaultUserFromActor(actor) {
+    return { id: actor.id };
+}
+/**
+ * A {@link RolesPolicy} (the agent's `ToolAuthorizer` seam) backed by `@adonis-agora/authz`
+ * (AdonisJS Bouncer). For each tool it checks the actor against the tool's declared `ability`
+ * via {@link AuthzServiceLike.can}, scoped to the actor's tenant.
+ *
+ * Security posture — FAIL-CLOSED:
+ * - A tool that declares no `ability` is NEVER authorized (deny). Unlike the role-based default,
+ *   there is no ADMIN fallback: with authz selected, an un-annotated tool is simply not reachable.
+ * - Any error thrown while resolving the decision denies.
+ *
+ * Tenant isolation: `actor.tenantRef` is passed as the authz **scope** (`{ tenantId }`), so a
+ * permission granted in one tenant never authorizes a tool call made in another. When the actor has
+ * no `tenantRef`, the check runs against the global scope (authz's default).
+ *
+ * The agent's double check — the offered-tools filter AND the invoke-time re-check inside
+ * `ToolRegistry` — both run through this same `can(actor, tool)`, so offer and invoke stay
+ * consistent.
+ */
+export class AuthzToolAuthorizer {
+    #authz;
+    #userFromActor;
+    constructor(config) {
+        this.#authz = config.authz;
+        this.#userFromActor = config.userFromActor ?? defaultUserFromActor;
+    }
+    async can(actor, tool) {
+        // Fail-closed: no declared ability → deny. There is no role fallback under authz.
+        if (tool.ability === undefined)
+            return false;
+        try {
+            // Pass the actor's tenant as the authz scope so the grant is tenant-isolated. Omit the option
+            // entirely when there is no tenantRef (global scope) — honors `exactOptionalPropertyTypes`.
+            const options = actor.tenantRef !== undefined ? { scope: { tenantId: actor.tenantRef } } : {};
+            return await this.#authz.can(this.#userFromActor(actor), tool.ability, options);
+        }
+        catch {
+            // Fail-closed: any failure resolving the decision denies.
+            return false;
+        }
+    }
+}
+/**
+ * Factory for an {@link AuthzToolAuthorizer}. Wire it in `config/agent.ts` as the tool authorizer,
+ * replacing the ADMIN-only `DefaultToolAuthorizer`:
+ *
+ * ```ts
+ * import { defineConfig } from '@adonis-agora/agent'
+ * import { authzToolAuthorizer } from '@adonis-agora/agent/authz'
+ *
+ * export default defineConfig({
+ *   model: () => aiSdkModel({ model: '...' }),
+ *   authorizer: authzToolAuthorizer({ authz: await app.container.make('authz.service') }),
+ * })
+ * ```
+ */
+export function authzToolAuthorizer(config) {
+    return new AuthzToolAuthorizer(config);
+}
+//# sourceMappingURL=authz-tool-authorizer.js.map

package/dist/src/authz/authz-tool-authorizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz-tool-authorizer.js","sourceRoot":"","sources":["../../../src/authz/authz-tool-authorizer.ts"],"names":[],"mappings":"AA8CA,2GAA2G;AAC3G,MAAM,UAAU,oBAAoB,CAAC,KAAY;IAC/C,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,mBAAmB;IACrB,MAAM,CAAmB;IACzB,cAAc,CAA4B;IAEnD,YAAY,MAAiC;QAC3C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC,aAAa,IAAI,oBAAoB,CAAC;IACrE,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAAY,EAAE,IAAc;QACpC,kFAAkF;QAClF,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAC7C,IAAI,CAAC;YACH,8FAA8F;YAC9F,4FAA4F;YAC5F,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9F,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAClF,CAAC;QAAC,MAAM,CAAC;YACP,0DAA0D;YAC1D,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAiC;IACnE,OAAO,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACzC,CAAC"}

package/dist/src/authz/index.d.ts

@@ -0,0 +1,3 @@
+export { AuthzToolAuthorizer, authzToolAuthorizer, defaultUserFromActor, } from './authz-tool-authorizer.js';
+export type { AuthzToolAuthorizerConfig, AuthzServiceLike, AuthzTenantScope, } from './authz-tool-authorizer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/authz/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/authz/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,yBAAyB,EACzB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,4BAA4B,CAAC"}

package/dist/src/authz/index.js

@@ -0,0 +1,2 @@
+export { AuthzToolAuthorizer, authzToolAuthorizer, defaultUserFromActor, } from './authz-tool-authorizer.js';
+//# sourceMappingURL=index.js.map

package/dist/src/authz/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/authz/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,4BAA4B,CAAC"}