@arvo-tools/agentic 1.1.1 → 1.2.1

package/dist/Agent/stream/schema.d.ts

@@ -452,5 +452,161 @@ export declare const AgentStreamEventSchema: z.ZodDiscriminatedUnion<"type", [z.
         content: string;
         delta: string;
     };
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"agent.tool.permission.blocked">;
+    data: z.ZodObject<{
+        tools: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            kind: z.ZodString;
+            originalName: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            kind: string;
+            name: string;
+            originalName: string;
+        }, {
+            kind: string;
+            name: string;
+            originalName: string;
+        }>, "many">;
+        usage: z.ZodObject<{
+            prompt: z.ZodNumber;
+            completion: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            prompt: number;
+            completion: number;
+        }, {
+            prompt: number;
+            completion: number;
+        }>;
+        executionunits: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        tools: {
+            kind: string;
+            name: string;
+            originalName: string;
+        }[];
+        usage: {
+            prompt: number;
+            completion: number;
+        };
+        executionunits: number;
+    }, {
+        tools: {
+            kind: string;
+            name: string;
+            originalName: string;
+        }[];
+        usage: {
+            prompt: number;
+            completion: number;
+        };
+        executionunits: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "agent.tool.permission.blocked";
+    data: {
+        tools: {
+            kind: string;
+            name: string;
+            originalName: string;
+        }[];
+        usage: {
+            prompt: number;
+            completion: number;
+        };
+        executionunits: number;
+    };
+}, {
+    type: "agent.tool.permission.blocked";
+    data: {
+        tools: {
+            kind: string;
+            name: string;
+            originalName: string;
+        }[];
+        usage: {
+            prompt: number;
+            completion: number;
+        };
+        executionunits: number;
+    };
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"agent.tool.permission.requested">;
+    data: z.ZodObject<{
+        tools: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            kind: z.ZodString;
+            originalName: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            kind: string;
+            name: string;
+            originalName: string;
+        }, {
+            kind: string;
+            name: string;
+            originalName: string;
+        }>, "many">;
+        usage: z.ZodObject<{
+            prompt: z.ZodNumber;
+            completion: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            prompt: number;
+            completion: number;
+        }, {
+            prompt: number;
+            completion: number;
+        }>;
+        executionunits: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        tools: {
+            kind: string;
+            name: string;
+            originalName: string;
+        }[];
+        usage: {
+            prompt: number;
+            completion: number;
+        };
+        executionunits: number;
+    }, {
+        tools: {
+            kind: string;
+            name: string;
+            originalName: string;
+        }[];
+        usage: {
+            prompt: number;
+            completion: number;
+        };
+        executionunits: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "agent.tool.permission.requested";
+    data: {
+        tools: {
+            kind: string;
+            name: string;
+            originalName: string;
+        }[];
+        usage: {
+            prompt: number;
+            completion: number;
+        };
+        executionunits: number;
+    };
+}, {
+    type: "agent.tool.permission.requested";
+    data: {
+        tools: {
+            kind: string;
+            name: string;
+            originalName: string;
+        }[];
+        usage: {
+            prompt: number;
+            completion: number;
+        };
+        executionunits: number;
+    };
 }>]>;
 //# sourceMappingURL=schema.d.ts.map

package/dist/Agent/stream/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/Agent/stream/schema.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,KAAK,CAAC;AAcpB,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAoEjC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/Agent/stream/schema.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,KAAK,CAAC;AAcpB,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAsGjC,CAAC"}

package/dist/Agent/stream/schema.js

@@ -84,5 +84,39 @@ exports.AgentStreamEventSchema = zod_1.default.discriminatedUnion('type', [
             content: zod_1.default.string(),
         }),
     }),
+    zod_1.default.object({
+        type: zod_1.default.literal('agent.tool.permission.blocked'),
+        data: zod_1.default.object({
+            tools: zod_1.default
+                .object({
+                name: zod_1.default.string(),
+                kind: zod_1.default.string(),
+                originalName: zod_1.default.string(),
+            })
+                .array(),
+            usage: zod_1.default.object({
+                prompt: zod_1.default.number(),
+                completion: zod_1.default.number(),
+            }),
+            executionunits: zod_1.default.number(),
+        }),
+    }),
+    zod_1.default.object({
+        type: zod_1.default.literal('agent.tool.permission.requested'),
+        data: zod_1.default.object({
+            tools: zod_1.default
+                .object({
+                name: zod_1.default.string(),
+                kind: zod_1.default.string(),
+                originalName: zod_1.default.string(),
+            })
+                .array(),
+            usage: zod_1.default.object({
+                prompt: zod_1.default.number(),
+                completion: zod_1.default.number(),
+            }),
+            executionunits: zod_1.default.number(),
+        }),
+    }),
 ]);
 //# sourceMappingURL=schema.js.map

package/dist/Agent/stream/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/Agent/stream/schema.ts"],"names":[],"mappings":";;;;;;AAAA,4CAAoB;AAEpB,IAAM,gBAAgB,GAAG,aAAC,CAAC,MAAM,CAAC;IAChC,MAAM,EAAE,aAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,QAAQ,EAAE,aAAC,CAAC,MAAM,CAAC,aAAC,CAAC,MAAM,EAAE,EAAE,aAAC,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,EAAE;IAC/C,KAAK,EAAE,aAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE;IACzB,eAAe,EAAE,aAAC,CAAC,MAAM,EAAE;IAC3B,mBAAmB,EAAE,aAAC,CAAC,MAAM,CAAC;QAC5B,GAAG,EAAE,aAAC,CAAC,MAAM,EAAE;QACf,OAAO,EAAE,aAAC,CAAC,MAAM,EAAE;QACnB,SAAS,EAAE,aAAC,CAAC,OAAO,EAAE;KACvB,CAAC;CACH,CAAC,CAAC;AAEU,QAAA,sBAAsB,GAAG,aAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACjE,aAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,aAAC,CAAC,OAAO,CAAC,YAAY,CAAC;QAC7B,IAAI,EAAE,gBAAgB;KACvB,CAAC;IACF,aAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,aAAC,CAAC,OAAO,CAAC,cAAc,CAAC;QAC/B,IAAI,EAAE,gBAAgB;KACvB,CAAC;IACF,aAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,aAAC,CAAC,OAAO,CAAC,uBAAuB,CAAC;QACxC,IAAI,EAAE,gBAAgB;KACvB,CAAC;IACF,aAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,aAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC;QACrC,IAAI,EAAE,aAAC,CAAC,MAAM,CAAC;YACb,IAAI,EAAE,aAAC,CAAC,MAAM,CAAC;gBACb,IAAI,EAAE,aAAC,CAAC,MAAM,EAAE;gBAChB,IAAI,EAAE,aAAC,CAAC,MAAM,EAAE;gBAChB,YAAY,EAAE,aAAC,CAAC,MAAM,EAAE;aACzB,CAAC;YACF,KAAK,EAAE,aAAC,CAAC,MAAM,CAAC;gBACd,MAAM,EAAE,aAAC,CAAC,MAAM,EAAE;gBAClB,UAAU,EAAE,aAAC,CAAC,MAAM,EAAE;aACvB,CAAC;YACF,cAAc,EAAE,aAAC,CAAC,MAAM,EAAE;SAC3B,CAAC;KACH,CAAC;IACF,aAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,aAAC,CAAC,OAAO,CAAC,2BAA2B,CAAC;QAC5C,IAAI,EAAE,aAAC,CAAC,MAAM,CAAC;YACb,OAAO,EAAE,aAAC,CAAC,MAAM,EAAE;YACnB,KAAK,EAAE,aAAC,CAAC,MAAM,CAAC;gBACd,MAAM,EAAE,aAAC,CAAC,MAAM,EAAE;gBAClB,UAAU,EAAE,aAAC,CAAC,MAAM,EAAE;aACvB,CAAC;YACF,cAAc,EAAE,aAAC,CAAC,MAAM,EAAE;SAC3B,CAAC;KACH,CAAC;IACF,aAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,aAAC,CAAC,OAAO,CAAC,cAAc,CAAC;QAC/B,IAAI,EAAE,aAAC,CAAC,MAAM,CAAC;YACb,OAAO,EAAE,aAAC,CAAC,MAAM,EAAE;YACnB,KAAK,EAAE,aAAC,CAAC,MAAM,CAAC;gBACd,MAAM,EAAE,aAAC,CAAC,MAAM,EAAE;gBAClB,UAAU,EAAE,aAAC,CAAC,MAAM,EAAE;aACvB,CAAC;YACF,cAAc,EAAE,aAAC,CAAC,MAAM,EAAE;SAC3B,CAAC;KACH,CAAC;IACF,aAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,aAAC,CAAC,OAAO,CAAC,+BAA+B,CAAC;QAChD,IAAI,EAAE,aAAC,CAAC,MAAM,CAAC;YACb,KAAK,EAAE,aAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE;YACzB,KAAK,EAAE,aAAC,CAAC,MAAM,CAAC;gBACd,MAAM,EAAE,aAAC,CAAC,MAAM,EAAE;gBAClB,UAAU,EAAE,aAAC,CAAC,MAAM,EAAE;aACvB,CAAC;YACF,cAAc,EAAE,aAAC,CAAC,MAAM,EAAE;SAC3B,CAAC;KACH,CAAC;IACF,aAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,aAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC;QAClC,IAAI,EAAE,aAAC,CAAC,MAAM,CAAC;YACb,KAAK,EAAE,aAAC,CAAC,MAAM,EAAE;YACjB,OAAO,EAAE,aAAC,CAAC,MAAM,EAAE;SACpB,CAAC;KACH,CAAC;CACH,CAAC,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/Agent/stream/schema.ts"],"names":[],"mappings":"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"}

package/dist/Agent/types.d.ts

@@ -5,6 +5,7 @@ import type z from 'zod';
 import type { AgentInternalTool } from '../AgentTool/types';
 import type { AgentLLMIntegration, AgentLLMIntegrationOutput, AgentLLMIntegrationParam } from '../Integrations/types';
 import type { IMCPClient } from '../interfaces.mcp';
+import type { IPermissionManager } from '../interfaces.permission.manager';
 import type { NonEmptyArray, PromiseAble } from '../types';
 import type { AgentMediaContentSchema, AgentMessageContentSchema, AgentMessageSchema, AgentTextContentSchema, AgentToolCallContentSchema, AgentToolResultContentSchema } from './schema';
 import type { AgentStreamListener } from './stream/types';
@@ -234,6 +235,12 @@ export type CreateArvoAgentParam<TSelfContract extends AnyArvoOrchestratorContra
          * @remarks
          * Unlike local `tools`, calling a service here causes the Agent to **emit an event and suspend**.
          * It allows the Agent to orchestrate long-running or distributed workflows.
+         *
+         * Each service can specify:
+         * - `contract`: The versioned contract of the target service
+         * - `domains`: Event routing hints (e.g., ['human.interaction'] or [ArvoDomain.FROM_EVENT_CONTRACT])
+         * - `priority`: Execution precedence for batch tool calls
+         *
          */
         services: TServiceContract;
     };
@@ -258,45 +265,150 @@ export type CreateArvoAgentParam<TSelfContract extends AnyArvoOrchestratorContra
      */
     mcp?: IMCPClient;
     /**
-     * A map of JavaScript functions executed synchronously within the Agent's process.
-     * Best for lightweight logic (math, date checks, regex).
+     * Internal tools executed synchronously within the agent's process.
+     *
+     * Best suited for lightweight operations.
+     * Internal tools should complete in milliseconds. For operations requiring
+     * network I/O, database access, or extended computation, use Arvo services
+     * to avoid blocking the agent's execution.
+     *
+     * Each tool is created via `createAgentTool()` which adds automatic
+     * input validation and OpenTelemetry instrumentation.
      */
     tools?: TTools;
     /**
      * The default mechanism to force the Agent to generate a specific output structure.
      * - `'text'`: Standard conversational response.
      * - `'json'`: Structured Output / JSON Mode (validated against the contract's output schema).
+     *
+     * Individual versions can override this via their handler configuration,
+     * enabling progressive migration from text to structured outputs.
      * @defaultValue 'text'
      */
     llmResponseType?: AgentLLMIntegrationParam['outputFormat']['type'];
     /**
-     * The default llm integrations function which connect this agent to the intelligence layer
-     * (e.g., `openaiLLMIntegration`, `anthropicLLMIntegration`).
+     * Default LLM integration function connecting the agent to its reasoning engine.
+     * Individual versions can override this to use different models per version.
      */
     llm: AgentLLMIntegration;
-    /** A agent stream listener hook */
+    /**
+     * Optional event stream listener for real-time agent activity monitoring.
+     *
+     * Useful for building real-time UIs or logging.
+     * Events include contextual metadata (subject, initiator, agent version) for
+     * correlation across distributed traces.
+     */
     onStream?: AgentStreamListener;
     /**
-     * Arvo enforces strict version compliance. You must provide specific logic
-     * (System Prompt Building & Output Mapping) for **every semantic version**
-     * defined in `contracts.self`.
+     * Optional non-LLM authorization layer for deterministic tool access control.
+     *
+     * The permission manager enforces security policies outside the LLM's reasoning,
+     * preventing prompt injection attacks from bypassing authorization.
+     * This pattern is critical for systems requiring explicity permission policy implmentation,
+     * compliance enforcement, and defense against AI jailbreaking.
+     */
+    permissionManager?: IPermissionManager;
+    /**
+     * Version-specific handler implementations for each contract version.
+     *
+     * Arvo enforces complete version coverage: you must provide handlers for every
+     * version defined in `contracts.self.versions`.
      *
-     * This allows you to upgrade prompts or change output schemas in `v2` without
-     * breaking consumers of `v1`.
+     * Version handlers enable independent evolution of prompts, models, and output
+     * schemas without breaking existing consumers of older versions.
      */
     handler: {
         [K in keyof TSelfContract['versions'] & ArvoSemanticVersion]: {
             /**
-             * An optional override to forces the Agent to generate a specific output structure.
-             * - `'text'`: Standard conversational response.
-             * - `'json'`: Structured Output / JSON Mode (validated against the contract's output schema).
+             * Function defining which tools require explicit permission for this version.
+             *
+             * Tools not in this list bypass permission checks entirely. This enables
+             * selective authorization where only sensitive operations (data deletion,
+             * financial transactions, external integrations) require approval while
+             * read-only or low-risk tools execute freely.
+             *
+             * The function receives all available tools (services, MCP, internal) to
+             * support dynamic policy decisions based on the tool catalog.
+             *
+             * @example
+             * ```typescript
+             * explicityPermissionRequired: async ({ services, tools, mcp }) => [
+             *   services.deleteUser.name,
+             *   services.processRefund.name,
+             *   tools.executeSQL.name,
+             *   mcp['some_mcp_tool'].name,
+             * ]
+             * ```
+             */
+            explicityPermissionRequired?: (tools: AgentLLMContext<TServiceContract, TTools>['tools']) => PromiseAble<string[]>;
+            /**
+             * Version-specific override for the LLM response format.
+             * Overrides the agent-level `llmResponseType` default for this version only.
              */
             llmResponseType?: AgentLLMIntegrationParam['outputFormat']['type'];
-            /** An optional override llm integration specific to this version. This allows to completely version an agent */
+            /**
+             * Version-specific override for the LLM integration.
+             * Overrides the agent-level `llm` default for this version only.
+             * Enables model evolution across versions.
+             * Each version can use completely different models or providers without
+             * affecting other versions or requiring code changes in consumers.
+             */
             llm?: AgentLLMIntegration;
-            /** Generates the System Prompt and initial conversation context for this version. */
+            /**
+             * Context engineering function executed once during agent initialization.
+             *
+             * Transforms the initialization event into the agent's foundational state:
+             * - System prompt defining the agent's role and capabilities
+             * - Initial message history seeding the conversation
+             *
+             * The returned context persists in memory and forms the base that all
+             * subsequent tool results and LLM responses append to. This function
+             * runs only once per workflow—resumptions after service calls do not
+             * re-execute the context builder.
+             *
+             * @example
+             * ```typescript
+             * context: async ({ input, tools, span }) => ({
+             *   system: `You are a customer support agent. Available tools:
+             *            - ${tools.services.billing.name}: Access billing data
+             *            - ${tools.services.ticketing.name}: Create support tickets`,
+             *   messages: [
+             *     {
+             *       role: 'user',
+             *       content: { type: 'text', content: input.data.customerQuery },
+             *       seenCount: 0
+             *     }
+             *   ]
+             * })
+             * ```
+             */
             context: AgentContextBuilder<TSelfContract, K, TServiceContract, TTools>;
-            /** Maps the LLM's final response to the strict output contract for this version. */
+            /**
+             * Output validation function mapping LLM responses to contract-compliant events.
+             * Executes when the agent generates a final response (not a tool call).
+             *
+             * Returns either:
+             * - `{ data: {...} }`: Successfully validated output matching the contract
+             * - `{ error: Error }`: Validation failure triggering self-correction loop
+             *
+             * When validation fails, the agent appends the error to message history
+             * and re-invokes the LLM, enabling automatic correction of malformed outputs.
+             *
+             * @example
+             * ```typescript
+             * output: ({ content, parsedContent, outputFormat, span }) => {
+             *   const result = outputFormat.safeParse(
+             *     parsedContent ?? JSON.parse(content)
+             *   );
+             *
+             *   if (result.error) {
+             *     return { error: result.error };
+             *   }
+             *
+             *   return { data: result.data };
+             * }
+             * ```
+             */
             output: AgentOutputBuilder<TSelfContract, K>;
         };
     };

package/dist/Agent/types.d.ts.map

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

package/dist/SimplePermissionManager/contract.d.ts

@@ -0,0 +1,35 @@
+import z from 'zod';
+/**
+ * Default permission contract for simple approval workflows.
+ */
+export declare const simplePermissionContract: import("arvo-core").SimpleArvoContract<"#/arvo/tools/default/agentic/permission/simple", "arvo.default.simple.permission.request", {
+    '1.0.0': {
+        accepts: z.ZodObject<{
+            agentId: z.ZodString;
+            requestedTools: z.ZodArray<z.ZodString, "many">;
+            reason: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            agentId: string;
+            requestedTools: string[];
+            reason: string;
+        }, {
+            agentId: string;
+            requestedTools: string[];
+            reason: string;
+        }>;
+        emits: z.ZodObject<{
+            commentary: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            granted: z.ZodArray<z.ZodString, "many">;
+            denied: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            commentary: string;
+            granted: string[];
+            denied: string[];
+        }, {
+            granted: string[];
+            denied: string[];
+            commentary?: string | undefined;
+        }>;
+    };
+}, Record<string, any>>;
+//# sourceMappingURL=contract.d.ts.map

package/dist/SimplePermissionManager/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/SimplePermissionManager/contract.ts"],"names":[],"mappings":"AACA,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uBA0BnC,CAAC"}

package/dist/SimplePermissionManager/contract.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simplePermissionContract = void 0;
+var arvo_core_1 = require("arvo-core");
+var zod_1 = __importDefault(require("zod"));
+/**
+ * Default permission contract for simple approval workflows.
+ */
+exports.simplePermissionContract = (0, arvo_core_1.createSimpleArvoContract)({
+    uri: '#/arvo/tools/default/agentic/permission/simple',
+    type: 'arvo.default.simple.permission.request',
+    description: 'Simple permission request contract for agent tool authorization',
+    versions: {
+        '1.0.0': {
+            accepts: zod_1.default.object({
+                agentId: zod_1.default.string().describe('The agent requesting permission'),
+                requestedTools: zod_1.default.array(zod_1.default.string()).describe('Tool names requiring authorization'),
+                reason: zod_1.default.string().describe('Explanation of why these tools are needed'),
+            }),
+            emits: zod_1.default.object({
+                commentary: zod_1.default
+                    .string()
+                    .optional()
+                    .default((0, arvo_core_1.cleanString)("\n              In case the same tool appears in granted and denied list, then consider it denied. \n              If the permission blocked tools does not appear in the granted list, the consider it denied as well   \n            ")),
+                granted: zod_1.default.array(zod_1.default.string()).describe('Tool names that were granted permission'),
+                denied: zod_1.default.array(zod_1.default.string()).describe('Tool names that were denied permission'),
+            }),
+        },
+    },
+});
+//# sourceMappingURL=contract.js.map

package/dist/SimplePermissionManager/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/SimplePermissionManager/contract.ts"],"names":[],"mappings":";;;;;;AAAA,uCAAkE;AAClE,4CAAoB;AAEpB;;GAEG;AACU,QAAA,wBAAwB,GAAG,IAAA,oCAAwB,EAAC;IAC/D,GAAG,EAAE,gDAAgD;IACrD,IAAI,EAAE,wCAAwC;IAC9C,WAAW,EAAE,iEAAiE;IAC9E,QAAQ,EAAE;QACR,OAAO,EAAE;YACP,OAAO,EAAE,aAAC,CAAC,MAAM,CAAC;gBAChB,OAAO,EAAE,aAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;gBAC/D,cAAc,EAAE,aAAC,CAAC,KAAK,CAAC,aAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,oCAAoC,CAAC;gBAClF,MAAM,EAAE,aAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;aACzE,CAAC;YACF,KAAK,EAAE,aAAC,CAAC,MAAM,CAAC;gBACd,UAAU,EAAE,aAAC;qBACV,MAAM,EAAE;qBACR,QAAQ,EAAE;qBACV,OAAO,CACN,IAAA,uBAAW,EAAC,yOAGX,CAAC,CACH;gBACH,OAAO,EAAE,aAAC,CAAC,KAAK,CAAC,aAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,yCAAyC,CAAC;gBAChF,MAAM,EAAE,aAAC,CAAC,KAAK,CAAC,aAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,wCAAwC,CAAC;aAC/E,CAAC;SACH;KACF;CACF,CAAC,CAAC"}

package/dist/SimplePermissionManager/index.d.ts

@@ -0,0 +1,144 @@
+import { type VersionedArvoContract } from 'arvo-core';
+import type { AgentToolDefinition } from '../Agent/types';
+import type { IPermissionManager, PermissionManagerContext } from '../interfaces.permission.manager';
+import type { NonEmptyArray, OtelInfoType } from '../types';
+import { simplePermissionContract } from './contract';
+/**
+ * Simple in-memory permission manager for development and testing.
+ *
+ * Stores permissions in a Map keyed by `${source.name}:${source.subject}`,
+ * providing workflow-scoped authorization that persists only for the lifetime
+ * of the process.
+ *
+ * @example
+ * ```typescript
+ * const agent = createArvoAgent({
+ *   permissionManager: new SimplePermissionManager(),
+ *   handler: {
+ *     '1.0.0': {
+ *       permissionPolicy: async ({ services }) => [
+ *         services.deleteUser.name
+ *       ],
+ *       // ... other config
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare class SimplePermissionManager implements IPermissionManager<VersionedArvoContract<typeof simplePermissionContract, '1.0.0'>> {
+    static readonly CONTRACT: import("arvo-core").SimpleArvoContract<"#/arvo/tools/default/agentic/permission/simple", "arvo.default.simple.permission.request", {
+        '1.0.0': {
+            accepts: import("zod").ZodObject<{
+                agentId: import("zod").ZodString;
+                requestedTools: import("zod").ZodArray<import("zod").ZodString, "many">;
+                reason: import("zod").ZodString;
+            }, "strip", import("zod").ZodTypeAny, {
+                agentId: string;
+                requestedTools: string[];
+                reason: string;
+            }, {
+                agentId: string;
+                requestedTools: string[];
+                reason: string;
+            }>;
+            emits: import("zod").ZodObject<{
+                commentary: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodString>>;
+                granted: import("zod").ZodArray<import("zod").ZodString, "many">;
+                denied: import("zod").ZodArray<import("zod").ZodString, "many">;
+            }, "strip", import("zod").ZodTypeAny, {
+                commentary: string;
+                granted: string[];
+                denied: string[];
+            }, {
+                granted: string[];
+                denied: string[];
+                commentary?: string | undefined;
+            }>;
+        };
+    }, Record<string, any>>;
+    static readonly VERSIONED_CONTRACT: VersionedArvoContract<import("arvo-core").SimpleArvoContract<"#/arvo/tools/default/agentic/permission/simple", "arvo.default.simple.permission.request", {
+        '1.0.0': {
+            accepts: import("zod").ZodObject<{
+                agentId: import("zod").ZodString;
+                requestedTools: import("zod").ZodArray<import("zod").ZodString, "many">;
+                reason: import("zod").ZodString;
+            }, "strip", import("zod").ZodTypeAny, {
+                agentId: string;
+                requestedTools: string[];
+                reason: string;
+            }, {
+                agentId: string;
+                requestedTools: string[];
+                reason: string;
+            }>;
+            emits: import("zod").ZodObject<{
+                commentary: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodString>>;
+                granted: import("zod").ZodArray<import("zod").ZodString, "many">;
+                denied: import("zod").ZodArray<import("zod").ZodString, "many">;
+            }, "strip", import("zod").ZodTypeAny, {
+                commentary: string;
+                granted: string[];
+                denied: string[];
+            }, {
+                granted: string[];
+                denied: string[];
+                commentary?: string | undefined;
+            }>;
+        };
+    }, Record<string, any>>, "1.0.0">;
+    readonly contract: VersionedArvoContract<import("arvo-core").SimpleArvoContract<"#/arvo/tools/default/agentic/permission/simple", "arvo.default.simple.permission.request", {
+        '1.0.0': {
+            accepts: import("zod").ZodObject<{
+                agentId: import("zod").ZodString;
+                requestedTools: import("zod").ZodArray<import("zod").ZodString, "many">;
+                reason: import("zod").ZodString;
+            }, "strip", import("zod").ZodTypeAny, {
+                agentId: string;
+                requestedTools: string[];
+                reason: string;
+            }, {
+                agentId: string;
+                requestedTools: string[];
+                reason: string;
+            }>;
+            emits: import("zod").ZodObject<{
+                commentary: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodString>>;
+                granted: import("zod").ZodArray<import("zod").ZodString, "many">;
+                denied: import("zod").ZodArray<import("zod").ZodString, "many">;
+            }, "strip", import("zod").ZodTypeAny, {
+                commentary: string;
+                granted: string[];
+                denied: string[];
+            }, {
+                granted: string[];
+                denied: string[];
+                commentary?: string | undefined;
+            }>;
+        };
+    }, Record<string, any>>, "1.0.0">;
+    readonly domains: NonEmptyArray<string> | null;
+    private permissions;
+    constructor(config: {
+        domains: NonEmptyArray<string> | null;
+    });
+    private getKey;
+    get(source: PermissionManagerContext, tools: AgentToolDefinition<any>[], config: {
+        otelInfo: OtelInfoType;
+    }): Promise<Record<string, boolean>>;
+    set(source: PermissionManagerContext, event: {
+        data: {
+            granted: string[];
+            denied: string[];
+        };
+    }, config: {
+        otelInfo: OtelInfoType;
+    }): Promise<void>;
+    requestBuilder(source: PermissionManagerContext, tools: AgentToolDefinition<any>[], config: {
+        otelInfo: OtelInfoType;
+    }): Promise<{
+        agentId: string;
+        requestedTools: string[];
+        reason: string;
+    }>;
+}
+//# sourceMappingURL=index.d.ts.map