@compilr-dev/agents 0.5.5 → 0.5.7

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this package are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Beta notice:** versions in the `0.x` range may contain breaking changes
+> between minors. Read each release entry before upgrading.
+
+---
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+---
+
+For full git history see the repository commit log. Older `0.x` entries will be
+backfilled here over time.

package/dist/index.d.ts

@@ -52,7 +52,7 @@ export type { Guardrail, GuardrailInput, GuardrailAction, GuardrailResult, Guard
 export { MCPClient, MCPManager, mcpToolToTool, mcpToolsToTools, convertMCPResult, contentBlocksToString, generateToolName, normalizeServerConfig, MCPError, MCPErrorCode, isMCPError, createSDKNotInstalledError, } from './mcp/index.js';
 export type { MCPTransport, MCPConnectionStatus, MCPStdioOptions, MCPHttpOptions, MCPClientConfig, MCPServerConfig, MCPToolDefinition, MCPContentBlock, MCPToolResult, MCPClientEventType, MCPClientEvent, MCPClientEventHandler, MCPManagerOptions, MCPToolConversionOptions, } from './mcp/index.js';
 export { PermissionManager } from './permissions/index.js';
-export type { PermissionLevel, ToolPermission, PermissionRequest, PermissionCheckResult, PermissionHandler, PreviewGenerator, PermissionManagerOptions, PermissionEventType, PermissionEvent, PermissionEventHandler, } from './permissions/index.js';
+export type { PermissionLevel, ToolPermission, PermissionRequest, PermissionCheckResult, PermissionHandler, PermissionHandlerResponse, PreviewGenerator, PermissionManagerOptions, PermissionEventType, PermissionEvent, PermissionEventHandler, } from './permissions/index.js';
 export { ProjectMemoryLoader, createProjectMemoryLoader, loadProjectMemory, hasProjectMemory, getProviderPatterns, getSupportedProviders, getGenericPatterns, PROVIDER_PATTERNS, GENERIC_PATTERNS, } from './memory/index.js';
 export type { LLMProviderName, MemoryFile, ProjectMemory, FilePattern, CombineStrategy, ProjectMemoryOptions, ProjectMemoryEventType, ProjectMemoryEvent, ProjectMemoryEventHandler, MemoryDiscoveryResult, ProviderPatterns, } from './memory/index.js';
 export { UsageTracker, createUsageTracker } from './costs/index.js';

package/dist/mcp/client.js

@@ -8,7 +8,7 @@
 import { MCPError, MCPErrorCode, createSDKNotInstalledError } from './errors.js';
 /**
  * Cached SDK imports
- * Using loose constructor types to accommodate SDK version changes
+ * Using loose constructor types to accommodate SDK version changes (see comment above SDKClient)
  */
 let sdkCache = null;
 /**
@@ -205,12 +205,12 @@ export class MCPClient {
     async callTool(toolName, args) {
         const client = this.getConnectedClient();
         try {
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- MCP SDK boundary, see SDKClient header comment
             const result = await client.callTool({
                 name: toolName,
                 arguments: args,
             });
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- MCP SDK boundary
             return result;
         }
         catch (error) {

package/dist/permissions/index.d.ts

@@ -2,4 +2,4 @@
  * Permissions module - Tool-level permission management
  */
 export { PermissionManager } from './manager.js';
-export type { PermissionLevel, ToolPermission, PermissionRequest, PermissionCheckResult, PermissionHandler, PreviewGenerator, PermissionManagerOptions, PermissionEventType, PermissionEvent, PermissionEventHandler, } from './types.js';
+export type { PermissionLevel, ToolPermission, PermissionRequest, PermissionCheckResult, PermissionHandler, PermissionHandlerResponse, PreviewGenerator, PermissionManagerOptions, PermissionEventType, PermissionEvent, PermissionEventHandler, } from './types.js';

package/dist/permissions/manager.js

@@ -226,8 +226,8 @@ export class PermissionManager {
                     return { allowed: true, level, askedUser: false, rule };
                 }
                 // Ask for permission
-                const allowed = await this.askPermission(toolName, input, level, rule);
-                if (allowed) {
+                const askResult = await this.askPermission(toolName, input, level, rule);
+                if (askResult.allowed) {
                     this.sessionGrants.add(toolName);
                     this.emit({ type: 'permission:session_granted', toolName, level, input, rule });
                 }
@@ -235,11 +235,11 @@ export class PermissionManager {
                     this.emit({ type: 'permission:denied', toolName, level, input, rule });
                 }
                 return {
-                    allowed,
+                    allowed: askResult.allowed,
                     level,
                     askedUser: true,
                     rule,
-                    reason: allowed ? undefined : 'User denied permission',
+                    reason: askResult.allowed ? undefined : (askResult.reason ?? 'User denied permission'),
                 };
             }
             case 'once': {
@@ -249,19 +249,19 @@ export class PermissionManager {
                     return { allowed: true, level, askedUser: false, rule };
                 }
                 // Ask for permission each time (unless session-granted above)
-                const allowed = await this.askPermission(toolName, input, level, rule);
-                if (allowed) {
+                const askResult = await this.askPermission(toolName, input, level, rule);
+                if (askResult.allowed) {
                     this.emit({ type: 'permission:granted', toolName, level, input, rule });
                 }
                 else {
                     this.emit({ type: 'permission:denied', toolName, level, input, rule });
                 }
                 return {
-                    allowed,
+                    allowed: askResult.allowed,
                     level,
                     askedUser: true,
                     rule,
-                    reason: allowed ? undefined : 'User denied permission',
+                    reason: askResult.allowed ? undefined : (askResult.reason ?? 'User denied permission'),
                 };
             }
         }
@@ -281,7 +281,7 @@ export class PermissionManager {
     async askPermission(toolName, input, level, rule) {
         // If no handler, default to allow
         if (!this.handler) {
-            return true;
+            return { allowed: true };
         }
         const preview = this.previewGenerator(toolName, input);
         const request = {
@@ -292,7 +292,12 @@ export class PermissionManager {
             preview,
         };
         this.emit({ type: 'permission:asked', toolName, level, input, rule });
-        return this.handler(request);
+        const response = await this.handler(request);
+        // Normalize legacy boolean responses (backward compat)
+        if (typeof response === 'boolean') {
+            return { allowed: response };
+        }
+        return response;
     }
     /**
      * Grant session-level permission for a tool

package/dist/permissions/types.d.ts

@@ -84,25 +84,52 @@ export interface PermissionCheckResult {
      */
     reason?: string;
 }
+/**
+ * Response shape from a permission handler.
+ *
+ * Either a plain boolean (legacy — backward compatible) OR a structured
+ * object that can carry an optional reason. The reason is delivered to
+ * the agent inline with the tool's permission-denied error so the agent
+ * sees the user's context immediately, in the same turn.
+ *
+ * @example
+ * ```typescript
+ * // Legacy (still supported):
+ * return true;
+ * return false;
+ *
+ * // With reason:
+ * return { allowed: false, reason: 'Use project_document_add instead' };
+ * return { allowed: true };
+ * ```
+ */
+export type PermissionHandlerResponse = boolean | {
+    allowed: boolean;
+    reason?: string;
+};
 /**
  * Handler called when permission is needed
  *
  * @param request - Information about the permission request
- * @returns true to allow execution, false to deny
+ * @returns true to allow / false to deny — or { allowed, reason? } to
+ *          carry context (especially useful when denying with a message)
  *
  * @example
  * ```typescript
  * const handler: PermissionHandler = async (request) => {
  *   // Show UI prompt to user
- *   const allowed = await showConfirmDialog(
+ *   const result = await showConfirmDialog(
  *     `Allow ${request.toolName}?`,
  *     request.description
  *   );
- *   return allowed;
+ *   if (!result.allowed && result.message) {
+ *     return { allowed: false, reason: result.message };
+ *   }
+ *   return result.allowed;
  * };
  * ```
  */
-export type PermissionHandler = (request: PermissionRequest) => boolean | Promise<boolean>;
+export type PermissionHandler = (request: PermissionRequest) => PermissionHandlerResponse | Promise<PermissionHandlerResponse>;
 /**
  * Preview generator for permission requests
  *

package/dist/providers/gemini-native.js

@@ -318,7 +318,7 @@ export class GeminiNativeProvider {
                 const toolId = funcCall.id ?? `tool_${String(Date.now())}_${Math.random().toString(36).slice(2, 9)}`;
                 // Capture thought signature if present (Gemini 3 attaches it to function calls)
                 // Note: thoughtSignature is not in the SDK types yet but exists on the response
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access -- @google/genai types lag the actual API surface
                 const signature = part.thoughtSignature;
                 chunks.push({
                     type: 'tool_use_start',

package/dist/tracing/hooks.js

@@ -253,7 +253,7 @@ export function createTracingHooks(manager, config = {}) {
  * ```
  */
 export function createLoggingHooks(
-// eslint-disable-next-line no-console
+// eslint-disable-next-line no-console -- callers can pass a real logger; default to console for zero-config use
 logger = console.log) {
     return {
         beforeIteration: [

package/dist/tracing/logging.js

@@ -129,7 +129,7 @@ export function createStructuredLogger(options = {}) {
  */
 function defaultOutput(entry) {
     const json = JSON.stringify(entry);
-    /* eslint-disable no-console */
+    /* eslint-disable no-console -- this IS the default console output sink; callers can pass a custom output */
     switch (entry.level) {
         case 'debug':
             console.debug(json);

package/dist/tracing/otel.js

@@ -35,10 +35,10 @@ async function getOTelSDK() {
     try {
         // Use dynamic import with string to avoid TypeScript trying to resolve the module
         const modulePath = '@opentelemetry/api';
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- optional peer dep loaded via dynamic-import string; types unavailable at compile time
         const api = await import(modulePath);
         otelCache = {
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access -- optional peer dep, see above
             trace: api.trace,
         };
         return otelCache;
@@ -132,7 +132,7 @@ export async function createOTelExporter(tracerName = 'agent-tracing', tracerVer
  * ```
  */
 export function createConsoleExporter(options = {}) {
-    // eslint-disable-next-line no-console
+    // eslint-disable-next-line no-console -- console exporter — callers expect output to go to the console by default
     const { prettyPrint = true, output = console.log } = options;
     return {
         name: 'console',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",
@@ -12,8 +12,11 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "LICENSE",
+    "CHANGELOG.md"
   ],
+  "sideEffects": false,
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",
@@ -49,7 +52,7 @@
   },
   "homepage": "https://github.com/compilr-dev/agents#readme",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=20.0.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.72.1",