@causyne/agent 1.10.12 → 1.10.17

package/LICENSE

@@ -9,7 +9,7 @@ Parameters
 
 Licensor:             Ikbal Fadilah
 
-Licensed Work:        Causyne Agent 1.10.1
+Licensed Work:        Causyne Agent 1.10.13
                       The Licensed Work is (c) 2026 Ikbal Fadilah.
 
 Additional Use Grant: You may make use of the Licensed Work, provided that

package/docs/ARCHITECTURE.md

@@ -31,18 +31,147 @@ 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 | `mcpClient.js`, `skillsManager.js`, `toolPacks.js`, user skills and Tool Forge |
+| 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
+
+Tool schemas are assembled once from native tools, explicitly enabled plugins,
+and granted MCP servers. Denied tools are removed before the model sees them,
+native names win collisions, and large capability groups remain deferred until
+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. 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
+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 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
+
+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. 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
+is a synthetic cache microbenchmark, not evidence for model accuracy, token
+cost, or end-to-end latency claims from the research paper.
+
+Context uses per-tool result budgets, oversized-result snipping, decay, a bounded
+sliding window, and structural summaries. Full tool output is spilled before it
+is shortened. Material compaction is recorded in the audit log, and summary
+collapse emits a quiet terminal notice so context loss is visible.
 
 ## Removed boundaries
 

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.12",
+  "version": "1.10.17",
   "description": "Agentic AI for software, tools, and computer workflows",
   "main": "bin/causyne.js",
   "type": "module",
@@ -23,12 +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"
@@ -50,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
 }