@causyne/agent 1.10.12 → 1.10.17

package/src/agentLoop.js

@@ -7,6 +7,7 @@ import { TaskBuffer } from './taskBuffer.js';
 import { TOOL_DEFINITIONS, getDynamicTools, resolveTool, canonicalToolName } from './tools/registry.js';
 import { Sandbox } from './sandbox.js';
 import { auditLog } from './auditLog.js';
+import { hasMatchingHook, runConfiguredHooks } from './hooks.js';
 import { loadConfig } from './config.js';
 import { isDevEmulator } from './devMode.js';
 import { TokenTracker } from './tokenTracker.js';
@@ -14,7 +15,7 @@ import { TokenTracker } from './tokenTracker.js';
 import { getMemoryContextString } from './memory.js';
 import { MemoryManager } from './memoryManager.js';
 import { cortexDb } from './cortex/vectorDb.js';
-import { condenseAndSave } from './cortex/autoCondenser.js';
+import { buildStructuralSummary, condenseAndSave } from './cortex/autoCondenser.js';
 import { analyzeTask, buildTaskBrief, packsFromShape } from './taskShape.js';
 import { lookupPlan, recordPlan, recordMiss, renderPlanHint, toStep } from './planCache.js';
 import { routedConfig } from './modelRouter.js';
@@ -343,6 +344,11 @@ export class AgentLoop {
     this.circuitBreakerUnlocked = false;
     this.stopRequested = false;
     this.pendingApprovals = new Map(); // Maps toolCallId -> resolve function
+    // A delegated subagent can tighten these two ceilings. They are applied
+    // after every config refresh so run() cannot accidentally replace a
+    // worker's declared bounds with the parent tier defaults.
+    this.maxStepsCeiling = null;
+    this.taskTokenLimit = null;
     
     // Limits based on tier/budget & emulator fast bypass
     this.updateTierLimits();
@@ -497,18 +503,9 @@ export class AgentLoop {
     // once per task rather than once per step.
     let planHint = '';
     try {
-      const match = lookupPlan({
-        prompt: this.currentTaskPrompt || this.userPrompt,
-        archetype: this.taskShape ? this.taskShape.archetype : ''
-      });
-      if (match) {
-        planHint = renderPlanHint(match);
-        this._offeredPlanId = match.template.id;
-        this._planSimilarity = match.similarity;
-        this.debugLog(`plan cache hit ${(match.similarity * 100).toFixed(0)}% (${match.template.steps.length} steps)`);
-      }
+      planHint = renderPlanHint(this._planMatch);
     } catch (e) {
-      this.debugLog(`plan cache lookup skipped: ${e.message}`);
+      this.debugLog(`plan cache hint skipped: ${e.message}`);
     }
 
     return { lessonsLearned, designContext, antiRepeatDirective, universalSkillsContext, planHint };
@@ -601,6 +598,10 @@ export class AgentLoop {
     for (const toolCall of toolCalls) {
       const functionName = canonicalToolName(toolCall.function.name);
       if (!AgentLoop.READ_ONLY_TOOLS.has(functionName)) continue;
+      // Prefetch begins before the serial dispatch path. If this tool has a
+      // PreToolUse hook, running it here would create a temporal pre-trust
+      // window where the read happens before the hook can deny it.
+      if (hasMatchingHook(this.config.hooks, 'PreToolUse', functionName)) continue;
 
       let args;
       try {
@@ -723,6 +724,17 @@ export class AgentLoop {
     } else {
       this.maxSteps = 300;
     }
+    if (Number.isInteger(this.maxStepsCeiling) && this.maxStepsCeiling > 0) {
+      this.maxSteps = Math.min(this.maxSteps, this.maxStepsCeiling);
+    }
+    if (Number.isInteger(this.taskTokenLimit) && this.taskTokenLimit > 0 && this.tokenTracker) {
+      this.tokenTracker.budget = {
+        ...this.tokenTracker.budget,
+        enabled: true,
+        hardStop: true,
+        maxTokensPerTask: this.taskTokenLimit
+      };
+    }
     this.maxCircuitBreaker = this.maxSteps;
   }
 
@@ -800,6 +812,7 @@ export class AgentLoop {
     this._planSteps = [];
     this._offeredPlanId = null;
     this._planSimilarity = 0;
+    this._planMatch = null;
     this._lessonSimilarity = 0;
     this._lastToolResult = null;
     this._paradigmShiftPending = false;
@@ -816,6 +829,36 @@ export class AgentLoop {
         this.unlockPack(pack);
       }
 
+      // Reuse a known route before the first model call. Exact keyword-set
+      // matches are always eligible; fuzzy reuse requires at least medium task
+      // classification confidence because APC's threshold study shows that
+      // aggressive fuzzy hits trade accuracy for speed.
+      try {
+        this._planMatch = lookupPlan({
+          prompt: this.userPrompt,
+          archetype: this.taskShape ? this.taskShape.archetype : '',
+          allowFuzzy: this.taskShape?.confidence !== 'low'
+        });
+        if (this._planMatch) {
+          this._offeredPlanId = this._planMatch.template.id;
+          this._planSimilarity = this._planMatch.similarity;
+          for (const step of this._planMatch.template.steps || []) {
+            if (!step.ok || !resolveTool(step.tool)) continue;
+            this.unlockedTools.add(step.tool);
+            const pack = packForTool(step.tool);
+            if (pack) this.unlockPack(pack);
+          }
+          this.debugLog(
+            `plan cache ${this._planMatch.matchType || 'fuzzy'} hit `
+              + `${(this._planMatch.similarity * 100).toFixed(0)}% `
+              + `(${this._planMatch.template.steps.length} steps, `
+              + `${this._planMatch.telemetry?.lookupMs?.toFixed(2) || '0.00'} ms)`
+          );
+        }
+      } catch (e) {
+        this.debugLog(`plan cache lookup skipped: ${e.message}`);
+      }
+
       this.debugLog(`task shape: ${this.taskShape.archetype} (${this.taskShape.confidence} confidence)`);
     }
 
@@ -972,6 +1015,13 @@ export class AgentLoop {
         });
         if (compaction.totalReclaimed > 0) {
           this.debugLog(`progressive compaction reclaimed ${(compaction.totalReclaimed / 1024).toFixed(1)} KB [${compaction.stagesFired.join(', ')}]`);
+          auditLog.log({
+            event: 'context_compaction', taskId: this.taskId,
+            kind: 'progressive', stages: compaction.stagesFired,
+            reclaimedChars: compaction.totalReclaimed,
+            finalChars: compaction.finalChars,
+            limitChars: MAX_CHAR_POOL
+          });
         }
 
         const { window: slidingWindow, splitIndex } = buildWindow(this.messages, MAX_CHAR_POOL);
@@ -996,9 +1046,17 @@ export class AgentLoop {
         if (splitIndex >= 1) {
           const dropped = this.messages.slice(1, splitIndex + 1);
           if (dropped.length > 0) {
-            const removed = compactInPlace(this.messages, splitIndex, describeDroppedMessages(dropped));
+            const compactSummary = buildStructuralSummary(dropped) || describeDroppedMessages(dropped);
+            const removed = compactInPlace(this.messages, splitIndex, compactSummary);
             this._lastCompactionIndex = null;
             this.debugLog(`compacted ${removed} messages out of the live context`);
+            auditLog.log({
+              event: 'context_compaction', taskId: this.taskId,
+              kind: 'summary', removedMessages: removed,
+              retainedSummaryChars: compactSummary.length,
+              limitChars: MAX_CHAR_POOL
+            });
+            this.notice(`Context compacted: ${removed} earlier messages condensed into a reviewable summary.`);
 
             // V5 Cortex tiered condensation. Tier 1 (structural, free) always
             // runs so the Digital Brain keeps learning on every provider. Tier 2
@@ -1029,6 +1087,8 @@ export class AgentLoop {
           unlockedTools: this.unlockedTools,
           unlockOrder: this.unlockOrder,
           grantAllTools: this.config.grantAllTools === true,
+          allowedTools: this.sandbox.allowedTools,
+          deniedTools: this.config.deniedTools,
           residentOnly
         });
         // A delegated subagent runs with a declared toolScope. Enforcing it
@@ -1477,18 +1537,24 @@ export class AgentLoop {
             // if it was declined, fall through to the path that needs nothing.
             let visionReady = false;
             let visionDeclined = false;
+            let browserReady = false;
+            let browserDeclined = false;
             try {
               const { groupStatus, isGroupDeclined } = await import('./provisioning/capabilityProvisioner.js');
               visionReady = groupStatus('vision').state === 'ready';
               visionDeclined = isGroupDeclined('vision');
+              browserReady = groupStatus('browser').state === 'ready';
+              browserDeclined = isGroupDeclined('browser');
             } catch (e) { /* treat as not ready */ }
             let webGuardMsg = '';
 
-            if (hasVision && !visionReady && !visionDeclined) {
-              webGuardMsg = `[ANTI-SLOP CHECK: You are building a Web/UI project and must look at it before finishing, but the browser and screen-capture capability is not enabled yet. Call \`manage_local_dependencies\` with action "grant_capability" and group "vision" to request it from the user. If the user declines, read the final compiled HTML/CSS instead and verify it that way. This check fires once.]`;
+            if (!browserReady && !browserDeclined) {
+              webGuardMsg = `[ANTI-SLOP CHECK: You are building a Web/UI project and must inspect it before finishing, but the dedicated browser capability is not enabled yet. Call \`manage_local_dependencies\` with action "grant_capability" and group "browser" to request the Causyne Camoufox runtime. If the user declines, read the final compiled HTML/CSS instead. This check fires once.]`;
+            } else if (hasVision && !visionReady && !visionDeclined) {
+              webGuardMsg = `[ANTI-SLOP CHECK: The browser is available, but desktop screen capture is not enabled. Call \`manage_local_dependencies\` with action "grant_capability" and group "vision" to request it, or use \`browser_act\` snapshots and its workspace-scoped screenshot action. This check fires once.]`;
             } else if (hasVision && visionReady && !this.webVerificationState.screenshotTaken) {
               webGuardMsg = `[ANTI-SLOP CHECK: You are building a Web/UI project but attempted to finish without VISUALLY verifying your work. Use \`screenshot\` or \`vision_inspect_ui\` to look at the UI in a browser. A human looks at their work to avoid slop. This check fires once — if there is genuinely nothing visual to inspect, say so plainly and finish.]`;
-            } else if ((!hasVision || visionDeclined) && !this.webVerificationState.browserActUsed && !this.webVerificationState.screenshotTaken) {
+            } else if ((!hasVision || visionDeclined) && browserReady && !this.webVerificationState.browserActUsed && !this.webVerificationState.screenshotTaken) {
               webGuardMsg = `[TRANSCENDENCE CHECK: You are building a Web/UI project. As a vision-disabled model you cannot screenshot, but you MUST use \`browser_act\` to inspect the DOM, or read the final compiled HTML/CSS, to verify semantic correctness before finishing. This check fires once.]`;
             }
 
@@ -1699,58 +1765,10 @@ export class AgentLoop {
           
           this.consecutiveBlockedActions = 0; // Reset counter on allowed action
 
-          // Approval flow for dangerous actions (Mode A/B) or ALWAYS for heavy AI downloads
-          // The schema name is manage_local_dependencies. Comparing against the
-          // old alias meant this consent gate never fired and multi-GB model
-          // downloads ran unannounced.
-          const isHeavyAiDownload = functionName === 'manage_local_dependencies' &&
-            ['pipInst', 'fetchBin', 'fetchMod'].includes(args.action);
-          // A standing approval from "Allow always" lifts the gate for this
-          // tool until the process restarts. It is checked HERE rather than
-          
-          // asking and then auto-answering would still interrupt the user,
-          // which is the entire thing they were trying to stop.
-          //
-          // Nothing else is bypassed: the sandbox has already run above, so a
-          // FORBIDDEN command is still refused and a path outside the workspace
-          // is still blocked. This waives the QUESTION, not the guard.
-          const standingApproval = isAlwaysAllowed(functionName);
-          if (standingApproval) {
-            auditLog.log({
-              event: 'approval_auto_granted', taskId: this.taskId,
-              tool: functionName, risk: validation.risk, reason: 'allow_always'
-            });
-          }
-
-          if (!standingApproval && (
-              validation.risk === 'extreme' ||
-              isHeavyAiDownload ||
-              (this.config.autonomyMode !== 'C' && validation.risk === 'dangerous') ||
-              this.config.autonomyMode === 'A')) {
-            
-            // Wait for local approval
-            this.emitEvent({ type: 'approval_request', toolCallId: toolCall.id, tool: functionName, args, risk: validation.risk });
-
-            const approved = await this.waitForApproval(toolCall.id);
-            
-            if (!approved) {
-              this.messages.push({
-                role: 'tool',
-                tool_call_id: toolCall.id,
-                name: functionName,
-                content: JSON.stringify({ success: false, error: 'User denied this action' })
-              });
-              continue;
-            }
-          }
-
-          // Execute
+          // Resolve and validate before asking the user for approval. Unknown or
+          // malformed calls should self-correct without creating approval fatigue.
           const tool = resolveTool(functionName);
-
-          // GUARD: Prevent crash if LLM hallucinates a non-existent tool name
           if (!tool || typeof tool.execute !== 'function') {
-            // Only advertise what is currently in context. Listing all 69 names
-            // here re-bloated the very context progressive disclosure protects.
             this.messages.push({
               role: 'tool',
               tool_call_id: toolCall.id,
@@ -1763,10 +1781,6 @@ export class AgentLoop {
             continue;
           }
 
-          // AUTO-UNLOCK RECOVERY: the model named a real tool whose pack is not
-          // loaded yet (it remembered it from an earlier task, or guessed well).
-          // Unlock the pack and run it rather than dead-ending — capability is
-          // deferred, never removed.
           if (!isCoreTool(functionName) && !this.unlockedTools.has(functionName)) {
             const pack = packForTool(functionName);
             if (this.unlockPack(pack)) {
@@ -1775,26 +1789,29 @@ export class AgentLoop {
             this.unlockedTools.add(functionName);
           }
 
-          // V5: Tool Call Argument Validation Layer
           const validationErrors = this.validateToolArgs(functionName, args);
           if (validationErrors) {
             this.messages.push({
               role: 'tool',
               tool_call_id: toolCall.id,
               name: functionName,
-              content: JSON.stringify({ 
-                success: false, 
-                error: `Invalid arguments: ${validationErrors}. Please fix and retry.` 
+              content: JSON.stringify({
+                success: false,
+                error: `Invalid arguments: ${validationErrors}. Please fix and retry.`
               })
             });
             continue;
           }
 
-          // Stage 3 seam: PreToolUse hook. A no-op that always allows today; when
-          // hooks are configured it can deny a call before it runs, returned as an
-          // is_error tool result so the model self-corrects (never thrown).
+          // A policy hook runs after the built-in sandbox but before any user
+          // approval prompt, so a deterministic denial never asks the user to
+          // approve work that will be rejected anyway.
           const preHook = await this.runPreToolUse(functionName, args, toolCall.id);
           if (preHook && preHook.denied) {
+            auditLog.log({
+              event: 'hook_denied', taskId: this.taskId, hookEvent: 'PreToolUse',
+              tool: functionName, reason: preHook.reason || 'hook denied'
+            });
             this.messages.push({
               role: 'tool',
               tool_call_id: toolCall.id,
@@ -1808,6 +1825,51 @@ export class AgentLoop {
             continue;
           }
 
+          // Approval flow for dangerous actions (Mode A/B) or ALWAYS for heavy AI downloads
+          // The schema name is manage_local_dependencies. Comparing against the
+          // old alias meant this consent gate never fired and multi-GB model
+          // downloads ran unannounced.
+          const isHeavyAiDownload = functionName === 'manage_local_dependencies' &&
+            ['pipInst', 'fetchBin', 'fetchMod'].includes(args.action);
+          // A standing approval from "Allow always" lifts the gate for this
+          // tool until the process restarts. It is checked HERE rather than
+
+          // asking and then auto-answering would still interrupt the user,
+          // which is the entire thing they were trying to stop.
+          //
+          // Nothing else is bypassed: the sandbox has already run above, so a
+          // FORBIDDEN command is still refused and a path outside the workspace
+          // is still blocked. This waives the QUESTION, not the guard.
+          const standingApproval = isAlwaysAllowed(functionName);
+          if (standingApproval) {
+            auditLog.log({
+              event: 'approval_auto_granted', taskId: this.taskId,
+              tool: functionName, risk: validation.risk, reason: 'allow_always'
+            });
+          }
+
+          if (!standingApproval && (
+              validation.risk === 'extreme' ||
+              isHeavyAiDownload ||
+              (this.config.autonomyMode !== 'C' && validation.risk === 'dangerous') ||
+              this.config.autonomyMode === 'A')) {
+
+            // Wait for local approval
+            this.emitEvent({ type: 'approval_request', toolCallId: toolCall.id, tool: functionName, args, risk: validation.risk });
+
+            const approved = await this.waitForApproval(toolCall.id);
+
+            if (!approved) {
+              this.messages.push({
+                role: 'tool',
+                tool_call_id: toolCall.id,
+                name: functionName,
+                content: JSON.stringify({ success: false, error: 'User denied this action' })
+              });
+              continue;
+            }
+          }
+
           // P2: snapshot the files this call is about to change, before it runs.
           // Only the mutating fs tools match; everything else returns immediately.
           // Fail-open by contract — this can never block or fail a tool call.
@@ -2393,26 +2455,32 @@ export class AgentLoop {
     return hints[errorType] || hints['unknown_error'];
   }
 
-  // V5: Validate tool call arguments before execution
-  /**
-   * PreToolUse / PostToolUse seams (Stage 3 fills these in).
-   *
-   * Today they are no-ops that always allow, so the dispatch behaviour is exactly
-   * what it was. When `.causyne/settings.json` gains a `hooks` block (Stage 3),
-   * these run the user's shell hooks with the exit-code protocol
-   * (0 allow / 2 deny / else warn) and return { denied, messages }. The loop
-   * already branches on `denied`, so Stage 3 is a fill-in here, not another edit
-   * to the dispatch path. See src/tools/toolDispatch.js for the discipline these
-   * plug into.
-   */
-  async runPreToolUse(_toolName, _args, _toolCallId) {
-    return { denied: false, messages: [] };
+  async runPreToolUse(toolName, args, toolCallId) {
+    return runConfiguredHooks({
+      hooks: this.config?.hooks,
+      event: 'PreToolUse',
+      toolName,
+      args,
+      taskId: this.taskId,
+      toolCallId,
+      workspacePaths: this.sandbox?.workspacePaths
+    });
   }
 
-  async runPostToolUse(_toolName, _args, _result) {
-    return { denied: false, messages: [] };
+  async runPostToolUse(toolName, args, result) {
+    return runConfiguredHooks({
+      hooks: this.config?.hooks,
+      event: 'PostToolUse',
+      toolName,
+      args,
+      result,
+      taskId: this.taskId,
+      workspacePaths: this.sandbox?.workspacePaths
+    });
   }
 
+  // V5: Validate tool call arguments before execution
+
   validateToolArgs(toolName, args) {
     // Check for common LLM mistakes
     

package/src/agentProfiles.js

@@ -0,0 +1,135 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { causyneHome } from './utils/paths.js';
+const PROFILE_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const TOOL_NAME = /^[a-zA-Z][a-zA-Z0-9_.-]{0,127}$/;
+const MAX_PROFILES = 64;
+const MAX_PROFILE_BYTES = 24 * 1024;
+const MAX_INSTRUCTIONS = 16 * 1024;
+const MAX_TOOLS = 64;
+export function agentProfilesRoot() {
+    return path.join(causyneHome(), 'agents');
+}
+function cleanLine(value, maximum) {
+    return String(value ?? '')
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\x00-\x1f\x7f]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, maximum);
+}
+function cleanInstructions(value) {
+    return String(value ?? '')
+        // Preserve newlines and tabs while excluding prompt-control bytes.
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '')
+        .trim();
+}
+function boundedInteger(value, fallback, minimum, maximum) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value))
+        return null;
+    return Math.max(minimum, Math.min(Number(value), maximum));
+}
+function parseProfile(file, expectedName) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return { ok: false, error: 'profile must be a regular file' };
+        if (stat.size > MAX_PROFILE_BYTES)
+            return { ok: false, error: `profile exceeds ${MAX_PROFILE_BYTES / 1024} KB` };
+        const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            return { ok: false, error: 'profile must be a JSON object' };
+        }
+        const value = raw;
+        if (value.schemaVersion !== 1)
+            return { ok: false, error: 'schemaVersion must be 1' };
+        if (value.name !== expectedName || !PROFILE_ID.test(expectedName)) {
+            return { ok: false, error: 'profile name must match its lowercase file name' };
+        }
+        const description = cleanLine(value.description, 400);
+        if (!description)
+            return { ok: false, error: 'description is required' };
+        const instructions = cleanInstructions(value.instructions);
+        if (!instructions)
+            return { ok: false, error: 'instructions are required' };
+        if (Buffer.byteLength(instructions, 'utf8') > MAX_INSTRUCTIONS) {
+            return { ok: false, error: `instructions exceed ${MAX_INSTRUCTIONS / 1024} KB` };
+        }
+        if (!Array.isArray(value.toolScope) || value.toolScope.length === 0 || value.toolScope.length > MAX_TOOLS) {
+            return { ok: false, error: `toolScope must contain 1-${MAX_TOOLS} tool names` };
+        }
+        const toolScope = [];
+        for (const rawTool of value.toolScope) {
+            if (typeof rawTool !== 'string' || !TOOL_NAME.test(rawTool)) {
+                return { ok: false, error: `invalid tool name ${JSON.stringify(rawTool)}` };
+            }
+            const normalized = rawTool.replace(/\./g, '_');
+            if (!toolScope.includes(normalized))
+                toolScope.push(normalized);
+        }
+        const maxSteps = boundedInteger(value.maxSteps, 25, 1, 100);
+        if (maxSteps === null)
+            return { ok: false, error: 'maxSteps must be an integer' };
+        const maxTokens = boundedInteger(value.maxTokens, 50_000, 1_000, 200_000);
+        if (maxTokens === null)
+            return { ok: false, error: 'maxTokens must be an integer' };
+        return {
+            ok: true,
+            profile: {
+                schemaVersion: 1,
+                name: expectedName,
+                description,
+                instructions,
+                toolScope,
+                maxSteps,
+                maxTokens,
+                path: file
+            }
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: message };
+    }
+}
+export function loadAgentProfile(name) {
+    const id = String(name ?? '');
+    if (!PROFILE_ID.test(id))
+        return { ok: false, error: 'invalid profile name' };
+    return parseProfile(path.join(agentProfilesRoot(), `${id}.json`), id);
+}
+export function listAgentProfiles() {
+    const profiles = [];
+    const problems = [];
+    const root = agentProfilesRoot();
+    try {
+        if (!fs.existsSync(root))
+            return { profiles, problems };
+        const entries = fs.readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.name.endsWith('.json') && !entry.name.startsWith('.'))
+            .slice(0, MAX_PROFILES + 1);
+        if (entries.length > MAX_PROFILES)
+            problems.push(`only the first ${MAX_PROFILES} profiles were inspected`);
+        for (const entry of entries.slice(0, MAX_PROFILES)) {
+            const name = entry.name.slice(0, -5);
+            if (!entry.isFile() || !PROFILE_ID.test(name)) {
+                problems.push(`${entry.name}: invalid profile file`);
+                continue;
+            }
+            const loaded = parseProfile(path.join(root, entry.name), name);
+            if (loaded.ok)
+                profiles.push(loaded.profile);
+            else
+                problems.push(`${entry.name}: ${loaded.error}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        problems.push(`could not read profiles: ${message}`);
+    }
+    return { profiles, problems };
+}
+export { MAX_PROFILES, MAX_PROFILE_BYTES, MAX_INSTRUCTIONS, MAX_TOOLS };

package/src/agentProfiles.ts

@@ -0,0 +1,143 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { causyneHome } from './utils/paths.js';
+
+const PROFILE_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const TOOL_NAME = /^[a-zA-Z][a-zA-Z0-9_.-]{0,127}$/;
+const MAX_PROFILES = 64;
+const MAX_PROFILE_BYTES = 24 * 1024;
+const MAX_INSTRUCTIONS = 16 * 1024;
+const MAX_TOOLS = 64;
+
+export interface AgentProfile {
+  schemaVersion: 1;
+  name: string;
+  description: string;
+  instructions: string;
+  toolScope: string[];
+  maxSteps: number;
+  maxTokens: number;
+  path: string;
+}
+
+export type AgentProfileResult =
+  | { ok: true; profile: AgentProfile }
+  | { ok: false; error: string };
+
+export function agentProfilesRoot(): string {
+  return path.join(causyneHome(), 'agents');
+}
+
+function cleanLine(value: unknown, maximum: number): string {
+  return String(value ?? '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1f\x7f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, maximum);
+}
+
+function cleanInstructions(value: unknown): string {
+  return String(value ?? '')
+    // Preserve newlines and tabs while excluding prompt-control bytes.
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '')
+    .trim();
+}
+
+function boundedInteger(value: unknown, fallback: number, minimum: number, maximum: number): number | null {
+  if (value === undefined) return fallback;
+  if (!Number.isInteger(value)) return null;
+  return Math.max(minimum, Math.min(Number(value), maximum));
+}
+
+function parseProfile(file: string, expectedName: string): AgentProfileResult {
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) return { ok: false, error: 'profile must be a regular file' };
+    if (stat.size > MAX_PROFILE_BYTES) return { ok: false, error: `profile exceeds ${MAX_PROFILE_BYTES / 1024} KB` };
+    const raw: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+      return { ok: false, error: 'profile must be a JSON object' };
+    }
+    const value = raw as Record<string, unknown>;
+    if (value.schemaVersion !== 1) return { ok: false, error: 'schemaVersion must be 1' };
+    if (value.name !== expectedName || !PROFILE_ID.test(expectedName)) {
+      return { ok: false, error: 'profile name must match its lowercase file name' };
+    }
+    const description = cleanLine(value.description, 400);
+    if (!description) return { ok: false, error: 'description is required' };
+    const instructions = cleanInstructions(value.instructions);
+    if (!instructions) return { ok: false, error: 'instructions are required' };
+    if (Buffer.byteLength(instructions, 'utf8') > MAX_INSTRUCTIONS) {
+      return { ok: false, error: `instructions exceed ${MAX_INSTRUCTIONS / 1024} KB` };
+    }
+    if (!Array.isArray(value.toolScope) || value.toolScope.length === 0 || value.toolScope.length > MAX_TOOLS) {
+      return { ok: false, error: `toolScope must contain 1-${MAX_TOOLS} tool names` };
+    }
+    const toolScope: string[] = [];
+    for (const rawTool of value.toolScope) {
+      if (typeof rawTool !== 'string' || !TOOL_NAME.test(rawTool)) {
+        return { ok: false, error: `invalid tool name ${JSON.stringify(rawTool)}` };
+      }
+      const normalized = rawTool.replace(/\./g, '_');
+      if (!toolScope.includes(normalized)) toolScope.push(normalized);
+    }
+    const maxSteps = boundedInteger(value.maxSteps, 25, 1, 100);
+    if (maxSteps === null) return { ok: false, error: 'maxSteps must be an integer' };
+    const maxTokens = boundedInteger(value.maxTokens, 50_000, 1_000, 200_000);
+    if (maxTokens === null) return { ok: false, error: 'maxTokens must be an integer' };
+
+    return {
+      ok: true,
+      profile: {
+        schemaVersion: 1,
+        name: expectedName,
+        description,
+        instructions,
+        toolScope,
+        maxSteps,
+        maxTokens,
+        path: file
+      }
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, error: message };
+  }
+}
+
+export function loadAgentProfile(name: unknown): AgentProfileResult {
+  const id = String(name ?? '');
+  if (!PROFILE_ID.test(id)) return { ok: false, error: 'invalid profile name' };
+  return parseProfile(path.join(agentProfilesRoot(), `${id}.json`), id);
+}
+
+export function listAgentProfiles(): { profiles: AgentProfile[]; problems: string[] } {
+  const profiles: AgentProfile[] = [];
+  const problems: string[] = [];
+  const root = agentProfilesRoot();
+  try {
+    if (!fs.existsSync(root)) return { profiles, problems };
+    const entries = fs.readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.name.endsWith('.json') && !entry.name.startsWith('.'))
+      .slice(0, MAX_PROFILES + 1);
+    if (entries.length > MAX_PROFILES) problems.push(`only the first ${MAX_PROFILES} profiles were inspected`);
+    for (const entry of entries.slice(0, MAX_PROFILES)) {
+      const name = entry.name.slice(0, -5);
+      if (!entry.isFile() || !PROFILE_ID.test(name)) {
+        problems.push(`${entry.name}: invalid profile file`);
+        continue;
+      }
+      const loaded = parseProfile(path.join(root, entry.name), name);
+      if (loaded.ok) profiles.push(loaded.profile);
+      else problems.push(`${entry.name}: ${loaded.error}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    problems.push(`could not read profiles: ${message}`);
+  }
+  return { profiles, problems };
+}
+
+export { MAX_PROFILES, MAX_PROFILE_BYTES, MAX_INSTRUCTIONS, MAX_TOOLS };