@arvo-tools/agentic 1.2.15 → 1.2.17

package/dist/interfaces.permission.manager.d.ts

@@ -1,6 +1,6 @@
 import type { InferVersionedArvoContract, SimpleArvoContract, VersionedArvoContract } from 'arvo-core';
 import type { SimpleArvoContractEmitType } from 'arvo-core/dist/ArvoContract/SimpleArvoContract/types';
-import type { AgentToolDefinition } from './Agent/types';
+import type { AgentToolCallContent, AgentToolDefinition } from './Agent/types';
 import type { AgentInternalTool } from './AgentTool/types';
 import type { NonEmptyArray, OtelInfoType, PromiseAble } from './types';
 /**
@@ -57,85 +57,6 @@ export type PermissionManagerContext = {
  *
  * Permission managers should be fast on the read path (hot path during tool execution)
  * and can be slower on the write path (triggered only when authorization changes).
- *
- * @example
- * ```typescript
- * const permissionContract = createSimpleArvoContract({
- *   uri: '#/permissions/tool-access',
- *   type: 'permission.tool.access',
- *   domain: 'human.interaction',
- *   versions: {
- *     '1.0.0': {
- *       accepts: z.object({
- *         agentId: z.string(),
- *         requestedTools: z.array(z.string()),
- *         reason: z.string(),
- *         workflowContext: z.string(),
- *       }),
- *       emits: z.object({
- *         granted: z.array(z.string()),
- *         denied: z.array(z.string()),
- *         expiresAt: z.string().datetime().optional(),
- *       }),
- *     },
- *   },
- * });
- *
- * class ToolPermissionManager implements IPermissionManager<typeof permissionContract> {
- *   public readonly contract = permissionContract.version('1.0.0');
- *   // public readonly domains = ['human.interaction'];
- *   public readonly domains = [ArvoDomain.FROM_EVENT_CONTRACT];
- *   // Both domains are the same
- *
- *   private permissions = new Map<string, Set<string>>();
- *
- *   private getKey(source: PermissionManagerContext): string {
- *     return `${source.name}:${source.subject}`;
- *   }
- *
- *   async get(source, tools) {
- *     const key = this.getKey(source);
- *     const granted = this.permissions.get(key) ?? new Set();
- *     return Object.fromEntries(
- *       tools.map(tool => [
- *         tool.name,
- *         granted.has(tool.name) ? 'APPROVED' : 'REQUESTABLE'
- *       ])
- *     );
- *   }
- *
- *   async set(source, event) {
- *     const key = this.getKey(source);
- *     const granted = this.permissions.get(key) ?? new Set();
- *     for (const tool of event.data.granted) {
- *       granted.add(tool);
- *     }
- *     this.permissions.set(key, granted);
- *   }
- *
- *   async requestBuilder(source, tools) {
- *     return {
- *       agentId: source.name,
- *       requestedTools: tools.map(t => t.name),
- *       reason: `Agent requires permission: ${tools.map(t => t.name).join(', ')}`,
- *       workflowContext: source.subject,
- *     };
- *   }
- * }
- *
- * const agent = createArvoAgent({
- *   permissionManager: new ToolPermissionManager(),
- *   handler: {
- *     '1.0.0': {
- *       permissionPolicy: async ({ services }) => [
- *         services.deleteUser.name,
- *         services.processRefund.name
- *       ],
- *       // ... context and output builders
- *     }
- *   }
- * });
- * ```
  */
 export interface IPermissionManager<T extends VersionedArvoContract<SimpleArvoContract<any, any, any>, any> = VersionedArvoContract<SimpleArvoContract<any, any, any>, any>> {
     /**
@@ -163,8 +84,12 @@ export interface IPermissionManager<T extends VersionedArvoContract<SimpleArvoCo
      * @param source - Context identifying the agent and workflow for scoped storage
      * @param event - Authorization response matching contract's success emission schema
      */
-    set(source: PermissionManagerContext, event: InferVersionedArvoContract<T>['emits'][SimpleArvoContractEmitType<T['metadata']['rootType']>], config: {
-        otelInfo: OtelInfoType;
+    set(param: {
+        source: PermissionManagerContext;
+        event: InferVersionedArvoContract<T>['emits'][SimpleArvoContractEmitType<T['metadata']['rootType']>];
+        config: {
+            otelInfo: OtelInfoType;
+        };
     }): PromiseAble<void>;
     /**
      * Checks current authorization status for requested tools.
@@ -179,8 +104,15 @@ export interface IPermissionManager<T extends VersionedArvoContract<SimpleArvoCo
      *          'DENIED' blocks execution without requesting permission, and 'REQUESTABLE'
      *          blocks execution but triggers a permission request event
      */
-    get(source: PermissionManagerContext, tools: AgentToolDefinition<VersionedArvoContract<any, any> | AgentInternalTool | null>[], config: {
-        otelInfo: OtelInfoType;
+    get(param: {
+        source: PermissionManagerContext;
+        tools: Record<string, {
+            definition: AgentToolDefinition<VersionedArvoContract<any, any> | AgentInternalTool | null>;
+            requests: Omit<AgentToolCallContent, 'type'>[];
+        }>;
+        config: {
+            otelInfo: OtelInfoType;
+        };
     }): PromiseAble<Record<string, ToolAuthorizationState>>;
     /**
      * Constructs permission request event payload for blocked tools.
@@ -195,8 +127,15 @@ export interface IPermissionManager<T extends VersionedArvoContract<SimpleArvoCo
      * @returns Event payload matching contract's accepts schema. Use agent-oriented
      *          tool names from `tools[i].name` for consistency with permission checks.
      */
-    requestBuilder(source: PermissionManagerContext, tools: AgentToolDefinition<VersionedArvoContract<any, any> | AgentInternalTool | null>[], config: {
-        otelInfo: OtelInfoType;
+    requestBuilder(param: {
+        source: PermissionManagerContext;
+        tools: Record<string, {
+            definition: AgentToolDefinition<VersionedArvoContract<any, any> | AgentInternalTool | null>;
+            requests: Omit<AgentToolCallContent, 'type'>[];
+        }>;
+        config: {
+            otelInfo: OtelInfoType;
+        };
     }): PromiseAble<InferVersionedArvoContract<T>['accepts']['data']>;
     /**
      * Cleanup hook invoked when agent execution completes or fails.
@@ -218,8 +157,11 @@ export interface IPermissionManager<T extends VersionedArvoContract<SimpleArvoCo
      *
      * @param source - Context identifying the agent and workflow for cleanup
      */
-    cleanup?(source: PermissionManagerContext, config: {
-        otelInfo: OtelInfoType;
+    cleanup?(param: {
+        source: PermissionManagerContext;
+        config: {
+            otelInfo: OtelInfoType;
+        };
     }): PromiseAble<void>;
 }
 //# sourceMappingURL=interfaces.permission.manager.d.ts.map

package/dist/interfaces.permission.manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.permission.manager.d.ts","sourceRoot":"","sources":["../src/interfaces.permission.manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sDAAsD,CAAC;AACvG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAExE;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AACH,MAAM,WAAW,kBAAkB,CAEjC,CAAC,SAAS,qBAAqB,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,qBAAqB,CAE7F,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAEjC,GAAG,CACJ;IAED;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,CAAC;IAEZ;;;;;;OAMG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAEtC;;;;;;;;;OASG;IACH,GAAG,CACD,MAAM,EAAE,wBAAwB,EAChC,KAAK,EAAE,0BAA0B,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,0BAA0B,CACtE,CAAC,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,CAC1B,CAAC,EACF,MAAM,EAAE;QAAE,QAAQ,EAAE,YAAY,CAAA;KAAE,GACjC,WAAW,CAAC,IAAI,CAAC,CAAC;IAErB;;;;;;;;;;;;OAYG;IACH,GAAG,CACD,MAAM,EAAE,wBAAwB,EAChC,KAAK,EAAE,mBAAmB,CAExB,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,iBAAiB,GAAG,IAAI,CAC3D,EAAE,EACH,MAAM,EAAE;QAAE,QAAQ,EAAE,YAAY,CAAA;KAAE,GACjC,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;IAEvD;;;;;;;;;;;;OAYG;IACH,cAAc,CACZ,MAAM,EAAE,wBAAwB,EAChC,KAAK,EAAE,mBAAmB,CAExB,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,iBAAiB,GAAG,IAAI,CAC3D,EAAE,EACH,MAAM,EAAE;QAAE,QAAQ,EAAE,YAAY,CAAA;KAAE,GACjC,WAAW,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAEjE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,CAAC,MAAM,EAAE,wBAAwB,EAAE,MAAM,EAAE;QAAE,QAAQ,EAAE,YAAY,CAAA;KAAE,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;CACnG"}
+{"version":3,"file":"interfaces.permission.manager.d.ts","sourceRoot":"","sources":["../src/interfaces.permission.manager.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arvo-tools/agentic",
-  "version": "1.2.15",
+  "version": "1.2.17",
   "description": "Agentic toolset for building applications using arvo-core and arvo-event-handler",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -35,8 +35,8 @@
     "@arizeai/openinference-semantic-conventions": "2.1.2",
     "@modelcontextprotocol/sdk": "1.24.3",
     "@opentelemetry/api": "1.9.0",
-    "arvo-core": "3.0.27",
-    "arvo-event-handler": "3.0.27",
+    "arvo-core": "3.0.28",
+    "arvo-event-handler": "3.0.28",
     "openai": "6.10.0",
     "uuid": "11.1.0",
     "zod": "3.25.76",