@adonis-agora/agent 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @adonis-agora/agent
 
+## 0.8.0
+
+### Minor Changes
+
+- [#23](https://github.com/DavideCarvalho/adonis-agent/pull/23) [`19c9ffd`](https://github.com/DavideCarvalho/adonis-agent/commit/19c9ffd9c285c7cab4e487c8bda73f7ce668be9e) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Add `authzActorResolver` (exported from `@adonis-agora/agent/authz`) — resolve the agent `Actor` from the Agora context populated by authkit (`userRef`, `tenantId`) plus authz `effectiveRoles` (the union global ∪ app ∪ store). Structural, zero hard dependency; authkit+authz apps can drop hand-written actor resolvers. Fail-closed: no identity in context → 401.
+
+## 0.7.1
+
+### Patch Changes
+
+- [#21](https://github.com/DavideCarvalho/adonis-agent/pull/21) [`d02b26b`](https://github.com/DavideCarvalho/adonis-agent/commit/d02b26bea2acd8d6f7daac166116a6813d321a02) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Internal: simplify `readAiToolMeta` metadata resolution
+
+  Refactor the tool-metadata lookup so the two authoring mechanisms (`@AiTool`
+  decorator and `static tool`) and the two subjects (the value, its constructor)
+  are composed explicitly — `metaOn(target) ?? metaOn(ctor)` — instead of a flat
+  four-way fallback chain. No behavior or API change; discovery of both forms is
+  unchanged (mutation-proven).
+
 ## 0.7.0
 
 ### Minor Changes

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

@@ -51,14 +51,15 @@ export type ToolClass = abstract new (...args: never[]) => ToolHandler;
  */
 export declare function AiTool(options: AiToolOptions): <T extends ToolClass>(target: T) => T;
 /**
- * Read a tool class's {@link AiToolMeta}. Two authoring forms are supported, in this order:
+ * Read a tool class's {@link AiToolMeta}. Two authoring forms are supported:
  *
  * 1. The `@AiTool({ … })` decorator (stamps {@link AI_TOOL_META_KEY}).
  * 2. A decorator-free `static tool = { name, kind, description, input, … }` config on the class — the
  *    same shape, mirroring `@adonis-agora/durable`'s `static workflow`. Preferred where you'd rather
  *    not rely on decorators.
  *
- * Accepts either the class itself or an instance (whose constructor carries the config).
+ * Accepts either the class itself or an instance: each mechanism is tried on the value, then on its
+ * constructor (so an instance resolves the class's metadata).
  */
 export declare function readAiToolMeta(target: unknown): AiToolMeta | undefined;
 /** A tool expressed as data + handler (from {@link defineTool}), not an `@AiTool` class. */

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

@@ -1 +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,wGAAwG;AACxG,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC,2FAA2F;AAC3F,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;AAYD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CActE;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"}
+{"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,wGAAwG;AACxG,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC,2FAA2F;AAC3F,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;AAyBD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAMtE;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

@@ -31,6 +31,13 @@ export function AiTool(options) {
         return target;
     };
 }
+/** Read the `@AiTool` decorator's stamped {@link AI_TOOL_META_KEY} metadata off a value, if present. */
+function decoratorMeta(target) {
+    if (target === null || (typeof target !== 'function' && typeof target !== 'object')) {
+        return undefined;
+    }
+    return target[AI_TOOL_META_KEY];
+}
 /** Read a class's tool metadata off its `static tool = { name, kind, … }` config, if any. */
 function staticToolMeta(target) {
     if (typeof target !== 'function')
@@ -41,30 +48,27 @@ function staticToolMeta(target) {
     }
     return undefined;
 }
+/** Resolve either authoring mechanism — `@AiTool` decorator or `static tool` — from one value. */
+function metaOn(target) {
+    return decoratorMeta(target) ?? staticToolMeta(target);
+}
 /**
- * Read a tool class's {@link AiToolMeta}. Two authoring forms are supported, in this order:
+ * Read a tool class's {@link AiToolMeta}. Two authoring forms are supported:
  *
  * 1. The `@AiTool({ … })` decorator (stamps {@link AI_TOOL_META_KEY}).
  * 2. A decorator-free `static tool = { name, kind, description, input, … }` config on the class — the
  *    same shape, mirroring `@adonis-agora/durable`'s `static workflow`. Preferred where you'd rather
  *    not rely on decorators.
  *
- * Accepts either the class itself or an instance (whose constructor carries the config).
+ * Accepts either the class itself or an instance: each mechanism is tried on the value, then on its
+ * constructor (so an instance resolves the class's metadata).
  */
 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;
-    const fromCtor = ctor?.[AI_TOOL_META_KEY];
-    if (fromCtor !== undefined) {
-        return fromCtor;
-    }
-    return staticToolMeta(target) ?? staticToolMeta(ctor);
+    return metaOn(target) ?? metaOn(ctor);
 }
 /** Narrows an arbitrary module export to a branded functional tool for boot-time registration. */
 export function isBrandedFunctionalTool(value) {

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

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

package/dist/src/authz/agora-context.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Structural, dependency-free reader for the Agora runtime context — mirrors
+ * `@adonis-agora/authz`'s `agora/context.ts`. The Agora context library publishes a READ accessor
+ * on the well-known symbol slot. We never import that package; when the slot is absent (context not
+ * installed) the reader degrades to `undefined` and the caller fails closed.
+ */
+/** The symbol slot the Agora context library writes its read accessor into. */
+export declare const AGORA_CONTEXT_ACCESSOR: unique symbol;
+/**
+ * The slice of the context accessor this package reads. `userRef` and `tenantId` are direct
+ * accessor fields (authkit writes them via the `set` slot); we never read `globalRoles` here —
+ * authz's `effectiveRoles` does that internally.
+ */
+export interface AgoraContextAccessor {
+    tenantId?: string;
+    userRef?: {
+        type?: string;
+        id?: string | number;
+    };
+    get?: () => unknown;
+}
+/** Read the active Agora context accessor from the global slot, if present. */
+export declare function readContextAccessor(): AgoraContextAccessor | undefined;
+//# sourceMappingURL=agora-context.d.ts.map

package/dist/src/authz/agora-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agora-context.d.ts","sourceRoot":"","sources":["../../../src/authz/agora-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,eAAwC,CAAC;AAE5E;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAClD,GAAG,CAAC,EAAE,MAAM,OAAO,CAAC;CACrB;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,IAAI,oBAAoB,GAAG,SAAS,CAItE"}

package/dist/src/authz/agora-context.js

@@ -0,0 +1,16 @@
+/**
+ * Structural, dependency-free reader for the Agora runtime context — mirrors
+ * `@adonis-agora/authz`'s `agora/context.ts`. The Agora context library publishes a READ accessor
+ * on the well-known symbol slot. We never import that package; when the slot is absent (context not
+ * installed) the reader degrades to `undefined` and the caller fails closed.
+ */
+/** The symbol slot the Agora context library writes its read accessor into. */
+export const AGORA_CONTEXT_ACCESSOR = Symbol.for('@agora/context:accessor');
+/** Read the active Agora context accessor from the global slot, if present. */
+export function readContextAccessor() {
+    const slot = globalThis[AGORA_CONTEXT_ACCESSOR];
+    if (slot == null || typeof slot !== 'object')
+        return undefined;
+    return slot;
+}
+//# sourceMappingURL=agora-context.js.map

package/dist/src/authz/agora-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agora-context.js","sourceRoot":"","sources":["../../../src/authz/agora-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAa5E,+EAA+E;AAC/E,MAAM,UAAU,mBAAmB;IACjC,MAAM,IAAI,GAAI,UAAsC,CAAC,sBAAsB,CAAC,CAAC;IAC7E,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC/D,OAAO,IAA4B,CAAC;AACtC,CAAC"}

package/dist/src/authz/authz-actor-resolver.d.ts

@@ -0,0 +1,35 @@
+import type { ActorResolver } from '../spi/actor-resolver.js';
+import type { Actor } from '../types.js';
+import type { AuthzTenantScope } from './authz-tool-authorizer.js';
+/**
+ * The structural slice of `@adonis-agora/authz`'s `AuthzService` this resolver needs: the user's
+ * effective roles (authz's union of global (context) ∪ app (`resolveRoles`) ∪ store (DB)). Typed
+ * structurally so `@adonis-agora/authz` stays an OPTIONAL lazy peer — zero import of the package.
+ */
+export interface AuthzRolesSourceLike {
+    effectiveRoles(user: unknown, scope?: AuthzTenantScope): Promise<string[]>;
+}
+/** Options for {@link AuthzActorResolver} / {@link authzActorResolver}. */
+export interface AuthzActorResolverConfig {
+    /** The `@adonis-agora/authz` `AuthzService` (or any structural match) the resolver reads roles from. */
+    authz: AuthzRolesSourceLike;
+}
+/**
+ * An {@link ActorResolver} that reads the caller from the Agora context authkit populates
+ * (`userRef`, `tenantId`) and takes the caller's roles from authz (`effectiveRoles`). It ignores
+ * the transport `req` and reads the active Agora context store, so it needs no `ctx.auth` and is
+ * framework-agnostic.
+ *
+ * Security posture — FAIL-CLOSED: no `userRef.id` in context → throws (the provider replies 401).
+ * An identity is never fabricated. The context `userRef` is passed straight to `effectiveRoles`;
+ * authz reads its `.id`/`.type` and re-reads `globalRoles` from the same context, so global roles
+ * (e.g. `ADMIN`) land in the result with no extra wiring.
+ */
+export declare class AuthzActorResolver implements ActorResolver {
+    #private;
+    constructor(config: AuthzActorResolverConfig);
+    resolve(_req: unknown): Promise<Actor>;
+}
+/** Factory for {@link AuthzActorResolver}. */
+export declare function authzActorResolver(config: AuthzActorResolverConfig): ActorResolver;
+//# sourceMappingURL=authz-actor-resolver.d.ts.map

package/dist/src/authz/authz-actor-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz-actor-resolver.d.ts","sourceRoot":"","sources":["../../../src/authz/authz-actor-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC5E;AAED,2EAA2E;AAC3E,MAAM,WAAW,wBAAwB;IACvC,wGAAwG;IACxG,KAAK,EAAE,oBAAoB,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,YAAW,aAAa;;gBAG1C,MAAM,EAAE,wBAAwB;IAItC,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC;CAsB7C;AAED,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,aAAa,CAElF"}

package/dist/src/authz/authz-actor-resolver.js

@@ -0,0 +1,41 @@
+import { readContextAccessor } from './agora-context.js';
+/**
+ * An {@link ActorResolver} that reads the caller from the Agora context authkit populates
+ * (`userRef`, `tenantId`) and takes the caller's roles from authz (`effectiveRoles`). It ignores
+ * the transport `req` and reads the active Agora context store, so it needs no `ctx.auth` and is
+ * framework-agnostic.
+ *
+ * Security posture — FAIL-CLOSED: no `userRef.id` in context → throws (the provider replies 401).
+ * An identity is never fabricated. The context `userRef` is passed straight to `effectiveRoles`;
+ * authz reads its `.id`/`.type` and re-reads `globalRoles` from the same context, so global roles
+ * (e.g. `ADMIN`) land in the result with no extra wiring.
+ */
+export class AuthzActorResolver {
+    #authz;
+    constructor(config) {
+        this.#authz = config.authz;
+    }
+    async resolve(_req) {
+        const accessor = readContextAccessor();
+        const ref = accessor?.userRef;
+        if (ref?.id === undefined || ref.id === null || String(ref.id).length === 0) {
+            throw new Error('authzActorResolver: no authenticated identity in @agora/context. The agent route must ' +
+                'sit behind authkit auth middleware (which populates the context), with the ' +
+                '@adonis-agora/context provider registered.');
+        }
+        const scope = accessor?.tenantId
+            ? { tenantId: accessor.tenantId }
+            : undefined;
+        const roles = await this.#authz.effectiveRoles(ref, scope);
+        return {
+            id: String(ref.id),
+            roles,
+            ...(accessor?.tenantId ? { tenantRef: accessor.tenantId } : {}),
+        };
+    }
+}
+/** Factory for {@link AuthzActorResolver}. */
+export function authzActorResolver(config) {
+    return new AuthzActorResolver(config);
+}
+//# sourceMappingURL=authz-actor-resolver.js.map

package/dist/src/authz/authz-actor-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz-actor-resolver.js","sourceRoot":"","sources":["../../../src/authz/authz-actor-resolver.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAkBzD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,kBAAkB;IACpB,MAAM,CAAuB;IAEtC,YAAY,MAAgC;QAC1C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAa;QACzB,MAAM,QAAQ,GAAG,mBAAmB,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,QAAQ,EAAE,OAAO,CAAC;QAC9B,IAAI,GAAG,EAAE,EAAE,KAAK,SAAS,IAAI,GAAG,CAAC,EAAE,KAAK,IAAI,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5E,MAAM,IAAI,KAAK,CACb,wFAAwF;gBACtF,6EAA6E;gBAC7E,4CAA4C,CAC/C,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAiC,QAAQ,EAAE,QAAQ;YAC5D,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE;YACjC,CAAC,CAAC,SAAS,CAAC;QACd,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAE3D,OAAO;YACL,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,KAAK;YACL,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChE,CAAC;IACJ,CAAC;CACF;AAED,8CAA8C;AAC9C,MAAM,UAAU,kBAAkB,CAAC,MAAgC;IACjE,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC"}

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

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

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

@@ -1 +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"}
+{"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;AACpC,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACnF,YAAY,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/src/authz/index.js

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

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

@@ -1 +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"}
+{"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;AAMpC,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.7.0";
+export declare const VERSION = "0.8.0";
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './spi/model-provider.js';

package/dist/src/index.js

@@ -1,4 +1,4 @@
-export const VERSION = '0.7.0';
+export const VERSION = '0.8.0';
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './spi/model-provider.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {