@causyne/agent 1.10.13 → 1.10.17

package/docs/ARCHITECTURE.md

@@ -31,18 +31,23 @@ are application policies and require adversarial review.
 | Concern | Source |
 | --- | --- |
 | Invocation and local session | `entrypoint.js`, `cliMode.js`, `tui/` |
-| Orchestration and budgets | `agentLoop.js`, `modelRouter.js`, `tokenTracker.js` |
+| Orchestration and budgets | `agentLoop.js`, `agentProfiles.ts`, `subagentJournal.ts`, `modelRouter.js`, `tokenTracker.js` |
 | Host execution | `tools/registry.js`, `sandbox.js`, `execSafe.js` |
 | Models | `providers/`, `modelCatalogue.js` |
 | Context and memory | `memory.js`, `memoryManager.js`, `contextManager.js`, `cortex/` |
-| Recovery | `checkpoints.js`, `gitSnapshot.js`, `sessionStore.js` |
-| Extensions | `mcp/`, `plugins/`, `hooks.js`, `skillsManager.js`, `toolPacks.js` |
+| Recovery | `checkpoints.js`, `gitSnapshot.js`, `sessionJournal.ts`, `sessionStore.js` |
+| Extensions | `mcp/`, `plugins/`, `hooks.ts`, `skillsManager.js`, `toolPacks.js` |
 | Readable interpreter source | `src/tool-scripts/` |
 
-The current implementation remains JavaScript/ESM on Node.js 24+. The accepted
-language direction is incremental strict TypeScript. Runtime validation is
-still needed at model, filesystem, subprocess and extension boundaries.
-Rust is a possible narrow native worker later; no Rust rewrite is underway.
+The shipping runtime is ESM on Node.js 24+. Incremental strict TypeScript
+migration is active: `tsconfig.runtime.json` emits readable JavaScript beside
+strict TypeScript runtime modules, shared contracts live under `src/types/`,
+and retained JavaScript has a separately named migration ratchet. Session,
+plugin-skill, task-shape, delegated-agent, hook, approval-grant, plan-cache and
+MCP boundaries now compile from strict TypeScript.
+Runtime validation is still required at model, filesystem, subprocess and
+extension boundaries. Rust is reserved for a measured, narrow native worker;
+no Rust rewrite is underway.
 
 ## Tool and extension boundaries
 
@@ -54,11 +59,79 @@ the task shape or `tool_search` makes them relevant.
 Local plugins use a static `plugin.json` manifest. Creating a plugin leaves it
 disabled. Enabling it pins a digest of every file the plugin process may read;
 any later manifest, source, helper or asset change revokes trust. Discovery
-validates static manifests and hashes bytes without importing JavaScript, so code cannot run
-during pre-trust initialization. A plugin tool runs in a separate Node process
-with the permission model enabled and only its declared workspace, network, or
-subprocess capabilities. Plugin calls still pass through Causyne's sandbox and
-approval gates.
+validates static manifests and hashes bytes without importing JavaScript, so
+code cannot run during pre-trust initialization. Reviewed plugins may contribute
+namespaced, progressively disclosed Markdown skills; these remain inert data
+and disappear from the catalogue if the digest changes. A plugin tool runs in a
+separate Node process with the permission model enabled and only its declared
+workspace, network, or subprocess capabilities. Plugin calls still pass through
+Causyne's sandbox and approval gates.
+
+MCP uses the official Model Context Protocol client packages rather than a
+project-specific JSON-RPC implementation. It supports local stdio servers and
+remote Streamable HTTP servers, with legacy SSE fallback when configured for
+automatic negotiation. The SDK owns initialization, capability negotiation,
+protocol framing, request cancellation, and transport shutdown. Causyne adds
+connection timeouts, bounded output, current-workspace roots, concurrent
+discovery, `tools/list_changed` refresh, structured content handling, and
+namespaced access to server resources and prompts.
+
+Each MCP grant is bound to a SHA-256 digest of the complete server definition.
+Changing a command, URL, environment, header, working directory, timeout,
+protocol mode, or tool filter invalidates the old grant. Disconnect and revoke
+also invalidate an in-flight handshake so a stale connection cannot become
+active afterward. Per-server include and exclude patterns limit which
+capabilities enter the model's catalogue. Connection state distinguishes
+disabled, connecting, connected, failed, and authentication-required servers;
+one failing server does not prevent native tools or other MCP servers from
+loading. Static bearer or custom headers may be configured locally. Interactive
+browser OAuth is not implemented yet; an HTTP 401 is surfaced as
+`needs_auth` instead of being reported as a generic transport failure.
+
+## Agent browser boundary
+
+Causyne's web foundation has two layers. Lightweight TypeScript search and
+fetch clients work without a browser runtime. Rendered navigation uses a
+dedicated in-process Camoufox adapter derived from the locally reviewed Camofox
+Browser source. The adapter is deliberately smaller than the reference service:
+it does not import an HTTP server, inbound port, cloud deployment layer, VNC,
+telemetry, remote WebSocket control, or OpenClaw integration.
+
+Camoufox and Playwright are exact-pinned optional capability packages installed
+into the user's private Causyne capability directory only after an explicit
+browser capability grant. Causyne does not download a browser binary. Advanced
+rendered browsing requires a separately installed Camoufox bundle selected by
+`CAUSYNE_CAMOFOX_EXECUTABLE` or discovered from a standard system location.
+The main npm package therefore stays small and web search remains useful when
+the optional rendered browser is absent.
+
+The browser runs headless by default with WebRTC blocked and a Causyne-owned
+profile. It provides tabs, navigation, accessibility snapshots with bounded
+pagination, stable element references, form interaction, bounded extraction,
+and atomic downloads restricted to the selected workspace. Search first uses
+bounded DuckDuckGo HTML and Bing RSS providers, then uses rendered provider
+pages when the optional browser is available. Failures remain visible after
+every provider is exhausted instead of being replaced with fabricated results.
+
+Every top-level navigation and browser subresource passes through the public
+URL policy. The policy accepts only HTTP(S), rejects embedded credentials,
+resolves hostnames before access, and blocks loopback, private, link-local,
+multicast, reserved, local, internal, and metadata addresses. Redirects in the
+non-browser fetch path are revalidated one at a time. Responses and extracted
+text are bounded, and network downloads require the existing approval gate.
+These controls reduce SSRF and unbounded-output risk while preserving normal
+public-web use from the user's selected workspace.
+
+User-defined subagent profiles are static JSON manifests under the local Causyne
+state directory. A profile supplies bounded instructions, an allowlist of tools,
+and hard step/token ceilings. It cannot widen its own scope, cannot recursively
+delegate, and does not load executable project code. Calls may narrow a
+profile's tool scope or budgets, but cannot exceed them.
+
+Completed delegated runs write a separate append-only JSONL sidechain under the
+local Causyne state directory. The parent receives only the worker's final
+result, while the bounded sidechain retains its messages and outcome for local
+inspection. A torn final append preserves earlier complete events.
 
 Hooks are user-owned argv arrays stored in the local Causyne configuration.
 They never pass through a shell and project repositories are not searched for
@@ -66,10 +139,19 @@ startup hooks. `PreToolUse` runs after the built-in sandbox and before an
 approval prompt; exit code 2 denies, and any other failure fails closed.
 `PostToolUse` can annotate a result or reject it without rewriting history.
 
-Host execution remains the default because Causyne must work in the directory
-the user selected. Optional container isolation can be added as an execution
-profile later, but it must remain explicit: mounting a workspace into Docker is
-a different trust boundary and cannot silently replace native desktop access.
+Host execution remains the current architecture because Causyne must operate in
+the directory and desktop environment the user selected. Container work is
+deferred and is not part of the present implementation plan.
+
+## Durable sessions
+
+Each workspace-scoped conversation is stored as an append-only JSONL event
+journal. Reads project `session.created`, `messages.appended`,
+`messages.windowed`, and explicit replacement events into the current session.
+A torn final append preserves prior complete events, while complete corruption
+fails safely. Legacy per-session JSON and global history files migrate on read.
+The compatibility `sessionStore.js` entry keeps existing callers stable while
+the strict TypeScript journal emits the JavaScript used at runtime.
 
 ## Plan cache and context pressure
 
@@ -77,7 +159,9 @@ Completed multi-step runs teach argument-free plan templates. Lookup tries an
 indexed exact signature first, then bounded lexical similarity only for a task
 shape with enough confidence. Latency, hit type and recent hit rate are recorded;
 lookup temporarily cools down when a populated cache repeatedly misses while
-new successful plans may continue warming it. `/plans import` accepts sanitized
+new successful plans may continue warming it. Persisted plans and metrics are
+validated before entering the typed runtime; malformed entries are ignored.
+`/plans import` accepts sanitized
 offline samples for known workloads, and `/plans` exposes the measurements.
 `npm run benchmark:plan-cache` measures exact lookup, fuzzy lookup, misses and
 prewarming at bounded cache sizes in an isolated temporary state directory. It

package/docs/SECURITY_REVIEW.md

@@ -1,6 +1,6 @@
 # Security review and migration status
 
-Review date: 2026-10-19. This is a scoped source and package review, not a
+Review date: 2026-10-21. This is a scoped source and package review, not a
 claim that Causyne Agent is free from vulnerabilities.
 
 ## OpenSSF records
@@ -65,6 +65,18 @@ The active source takes a different architecture and distribution path:
 - `web_fetch` downloads and curated game-asset downloads require the highest
   approval class. Curated assets are size-limited, constrained to catalog URLs,
   protected from output path traversal, and are not automatically extracted.
+- Web search uses bounded HTTP providers without requiring a browser binary.
+  Interactive rendered browsing uses an outbound, in-process Camoufox adapter.
+  Causyne does not run Camofox Browser's server, inbound port, remote control,
+  VNC, telemetry, cloud deployment, or OpenClaw integration. Optional launcher
+  packages require an explicit capability grant. Causyne never downloads the
+  Camoufox browser binary; an existing external installation must be selected
+  through `CAUSYNE_CAMOFOX_EXECUTABLE` or a standard system location.
+- Browser navigation and subresources accept only public HTTP(S) destinations.
+  Hostnames are resolved and checked against private, loopback, link-local,
+  multicast, reserved, local, internal, and metadata ranges. Non-browser
+  redirects are checked at every hop. Downloads are bounded, atomic, restricted
+  to the selected workspace, and remain in the highest approval class.
 - The package allowlist excludes the legacy archive, Android source, private
   operating documents, credentials, installers, bytecode, and generated
   tarballs.

package/docs/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-party software review
 
-Review date: 2026-10-19.
+Review date: 2026-10-21.
 
 Causyne Agent's npm package declares third-party packages as dependencies; it
 does not bundle their source into the project tarball. Each dependency remains
@@ -9,22 +9,55 @@ license identifiers:
 
 | License expression | Lockfile package entries |
 | --- | ---: |
-| Apache-2.0 | 21 |
-| MIT | 9 |
+| Apache-2.0 | 25 |
+| MIT | 20 |
+| ISC | 2 |
 
-The lockfile contained 30 dependency entries in total. Three are production
-entries; development and platform-specific optional entries account for the
-rest. npm's audit metadata reported 12 installed packages.
+The lockfile contained 47 dependency entries in total. Development and
+platform-specific optional entries account for most of the graph.
 
-The direct runtime dependencies are `acorn-walk` and `commander`. Direct
-development dependencies are `@babel/parser`, `@types/node`, `acorn`, and
-`typescript`. Exact versions and integrity hashes are recorded in
-`package-lock.json`.
+The direct runtime dependencies are `@modelcontextprotocol/client`,
+`acorn-walk`, and `commander`. Direct development dependencies are
+`@babel/parser`, `@modelcontextprotocol/node`, `@modelcontextprotocol/server`,
+`@types/node`, `acorn`, `typescript`, and `zod`. The three direct MCP packages
+are licensed under Apache-2.0. Exact versions, transitive dependencies, license
+identifiers, and integrity hashes are recorded in `package-lock.json`.
 
 No dependency in the reviewed main lockfile was marked with an install script.
 Optional capability dependencies are installed only after approval into a
 separate local environment and are not covered by the main lockfile review.
 
+The optional browser capability installs `camoufox-js` 0.11.5 under MPL-2.0
+and `playwright-core` 1.58.0 under Apache-2.0. They remain separate packages in
+the user's local capability directory and are not copied into Causyne Agent's
+npm tarball. Causyne does not download or bundle the Camoufox browser runtime.
+
+The snapshot windowing and external executable bridge in `src/browser/` are
+adapted from the MIT-licensed Camofox Browser project at source commit
+`2c0036a8b18bf9cd983376751ff4d52dfd9add0f`. Its required notice is:
+
+> MIT License
+>
+> Copyright (c) 2025 Jo, Inc
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
+
 Repository scanning found no third-party copyright header or license marker in
 the project-authored source and skill files. That negative scan alone cannot
 establish authorship or permission. On 2026-10-19, the licensor confirmed that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causyne/agent",
-  "version": "1.10.13",
+  "version": "1.10.17",
   "description": "Agentic AI for software, tools, and computer workflows",
   "main": "bin/causyne.js",
   "type": "module",
@@ -23,13 +23,15 @@
   "scripts": {
     "start": "node ./bin/causyne.js",
     "test": "node --test --import ./tests/helpers/isolateState.js \"tests/**/*.test.js\"",
-    "build": "node scripts/compile_skills.js",
+    "build": "node scripts/compile_skills.js && tsc -p tsconfig.runtime.json",
     "benchmark:plan-cache": "node src/benchmarks/planCache.js",
     "check:release": "node scripts/check_release.js",
     "check:public": "npm run check:release && node scripts/check_public_release.js",
     "prepublishOnly": "npm run check:public && npm test && npm run typecheck:strict",
     "typecheck": "tsc -p tsconfig.json",
-    "typecheck:strict": "tsc -p tsconfig.strict.json"
+    "typecheck:ts": "tsc -p tsconfig.strict.json",
+    "typecheck:js-ratchet": "tsc -p tsconfig.js-ratchet.json",
+    "typecheck:strict": "npm run typecheck:ts && npm run typecheck:js-ratchet"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -51,14 +53,18 @@
     "url": "https://github.com/ikbal-causyne/causyne-agent/issues"
   },
   "dependencies": {
+    "@modelcontextprotocol/client": "2.3.1",
     "acorn-walk": "^8.3.5",
     "commander": "^11.1.0"
   },
   "devDependencies": {
     "@babel/parser": "^8.0.7",
+    "@modelcontextprotocol/node": "2.1.1",
+    "@modelcontextprotocol/server": "2.3.1",
     "@types/node": "^22.20.2",
     "acorn": "^8.18.0",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "zod": "4.6.7"
   },
   "private": false
 }

package/src/agentLoop.js

@@ -344,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();
@@ -719,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;
   }
 
@@ -1521,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.]`;
             }
 

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 };