@compilr-dev/sdk 0.7.32 → 0.8.0

package/dist/agent.js

@@ -314,7 +314,16 @@ class CompilrAgentImpl {
                     : false
                 : undefined,
             hooks: mergedHooks,
-            pins: {},
+            enableFileTracking: config?.enableFileTracking ?? true,
+            pins: config?.pins
+                ? {
+                    maxAnchors: config.pins.maxAnchors ?? 50,
+                    maxTokens: config.pins.maxTokens ?? 4000,
+                    includeDefaults: config.pins.includeDefaults ?? true,
+                }
+                : {},
+            onIterationLimitReached: config?.onIterationLimitReached,
+            iterationLimitBehavior: config?.iterationLimitBehavior,
             permissions: {
                 defaultLevel: permissionsConfig.defaultLevel,
                 onPermissionRequest: permissionsConfig.onPermissionRequest,
@@ -334,6 +343,8 @@ class CompilrAgentImpl {
                     this.totalUsage.outputTokens += event.tokens.outputTokens;
                     this.totalUsage.totalTokens += event.tokens.inputTokens + event.tokens.outputTokens;
                 }
+                // Forward to user-provided onEvent callback
+                config?.onEvent?.(event);
                 // Forward ALL events to external listener (if set via run/stream)
                 this.externalEventListener?.(event);
             },

package/dist/config.d.ts

@@ -245,6 +245,45 @@ export interface CompilrAgentConfig {
         action: string;
         reason?: string;
     }) => void;
+    /**
+     * Event handler for monitoring agent execution.
+     * Called alongside the SDK's internal usage tracking — both run on every event.
+     */
+    onEvent?: (event: AgentEvent) => void;
+    /**
+     * Enable file access tracking for context restoration hints.
+     * When enabled, the agent tracks which files were read, referenced, and modified.
+     * After context compaction, hints are injected to help the LLM understand
+     * what files it previously accessed.
+     * Default: true when contextManager is created (i.e., almost always).
+     */
+    enableFileTracking?: boolean;
+    /**
+     * Pin/anchor configuration. Controls the AnchorManager for critical information
+     * that survives context compaction.
+     */
+    pins?: {
+        /** Maximum number of pins. Default: 50 */
+        maxAnchors?: number;
+        /** Maximum total tokens for pins. Default: 4000 */
+        maxTokens?: number;
+        /** Include built-in safety pins. Default: true */
+        includeDefaults?: boolean;
+    };
+    /**
+     * Callback invoked when the agent reaches its iteration limit.
+     * Return a positive number to extend by that many iterations, or false to stop.
+     */
+    onIterationLimitReached?: (context: {
+        iteration: number;
+        maxIterations: number;
+        toolCallCount: number;
+    }) => Promise<number | false>;
+    /**
+     * Behavior when max iterations is reached and no onIterationLimitReached callback
+     * is provided. Default: 'error'.
+     */
+    iterationLimitBehavior?: 'error' | 'summarize' | 'continue';
     /**
      * Dynamic capability loading configuration.
      * When enabled, tools are loaded on-demand for token efficiency.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.7.32",
+  "version": "0.8.0",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",