AGENTS

CortexPrism — Agent Orientation

CortexPrism is an open-source agentic harness system built on Deno 2.x + TypeScript strict mode. It hosts, orchestrates, and empowers AI agents with memory, tools, sandboxed code execution, a web UI, reflection, model routing, and layered security.

---

Build / Verify Commands

# Type-check — must exit 0 before any PR
deno task check

# Lint
deno task lint

# Format (auto-fixes)
deno task fmt

# Run all tests
deno task test

# Run a single test file
deno test --allow-all tests/<file>_test.ts

# Run check + lint + fmt in one shot
deno task check && deno task lint && deno task fmt

Runtime Commands

deno task dev          # Interactive chat (dev mode)
deno task serve        # HTTP + WebSocket server on :3000
deno task daemon       # Run background supervisor (foreground)
deno task migrate      # Apply all pending DB migrations

---

Project Layout

src/
  main.ts              # CLI entry point — all commands registered here
  cli/                 # One file per CLI sub-command
  agent/               # Agent loop, reflection, sub-agents, soul (system prompt)
  tools/               # Tool registry, executor, types
    builtin/           # All built-in tools (file ops, shell, web, code exec, etc.)
      workspace/       # File-system tools with undo/redo
  db/                  # DB client (libsql wrapper), migrations, session store
    migrations/        # NNN_description.sql — never edit applied migrations
  llm/                 # LLM provider adapters (one file per provider)
  memory/              # 5-tier memory: episodic, semantic, reflection
  security/            # Policy validator, vault (AES-256-GCM), CPL
  server/              # HTTP + WebSocket server, router, Web UI HTML
  channels/            # Channel adapters (Discord, etc.)
  plugins/             # Plugin loader, registry, sandbox, WASM runtime
  workflow/            # Workflow engine
  skills/              # Built-in skill definitions (Deno modules)
  scheduler/           # SQLite-persisted cron
  ipc/                 # Inter-process communication (validator ↔ executor)
  processes/           # Long-running process entry points (daemon workers)
  services/            # Micro-service registry + lifecycle
  workspace/           # Per-agent workspace paths + git integration
  config/              # PATHS constant, version, config schema
  model-quartermaster/ # Intelligent LLM selection (MQM)
  remote/              # Distributed node (Hub ↔ Node) infrastructure
  eval/                # Agent evaluation runner
  voice/               # TTS/STT voice pipeline
  sandbox/             # Code execution sandbox (Docker / subprocess)
  tui/                 # Terminal UI (ink-style)
  hub/                 # Hub coordination layer
  mcp/                 # MCP server (stdio)
  observability/       # Cortex Lens audit log
  quartermaster/       # Legacy model router
  triggers/            # Trigger system
  pipeline/            # Pipeline hook engine
  desktop/             # Tauri desktop app entry

tests/                 # Deno test files (*_test.ts)
docs/                  # Design specs and install guides
.kilo/                 # Kilo Code agent plans and specialist agent configs

---

Key Conventions

TypeScript

• Strict mode — no implicit any, no ! non-null assertions without a comment justifying why
• Async-first — prefer async/await over raw Promise chains
• Fire-and-forget — background tasks (memory write, reflection) use .catch(() => {}) and never block a response
• Error handling — catch at call-site boundaries; surface actionable error messages to the user

Paths

• Never hardcode paths — always import PATHS from src/config/paths.ts
• Data dir: ~/.cortex/data/ (override via CORTEX_DATA_DIR)
• Config dir: ~/.cortex/ (override via CORTEX_CONFIG_DIR)

Database

• SQL client: Db wrapper from src/db/client.ts (libsql)
• Migrations in src/db/migrations/NNN_description.sql — idempotent, never edit once applied
• Register new migrations in the targets array in src/db/migrate.ts

Secrets / Security

• No hardcoded credentials, API keys, or tokens anywhere in source
• Use CORTEX_VAULT_KEY env var; store secrets via the vault module (src/security/vault.ts)
• Every tool call is gated through the policy validator (src/security/validator.ts)

Adding a New CLI Command

1. Create src/cli/your-cmd.ts exporting a Command from @cliffy/command
2. Import and register it in src/main.ts
3. Document it in README.md and add a CHANGELOG.md entry

Adding a New Built-in Tool

1. Create src/tools/builtin/your_tool.ts implementing the Tool interface from src/tools/types.ts
2. Register it in src/tools/registry.ts
3. Add it to the WebSocket handler in src/server/ws.ts if needed
4. Add a policy rule if it executes shell commands or makes network requests

Adding a Database Migration

1. Create src/db/migrations/NNN_description.sql (next sequential number)
2. Add an entry to the targets array in src/db/migrate.ts
3. Never edit a migration that has already been applied — create a new one instead

Subprocess Spawning

• Use Deno.Command, never Deno.run (deprecated)

Commit Style

Conventional commits:

feat: add discord channel adapter
fix: handle empty response from Ollama
docs: update CLI reference for vault command
chore: bump deno.json dependencies
refactor: extract policy evaluation into pure function
test: add workspace path traversal cases

---

LLM Providers Supported

Anthropic, OpenAI, Google Gemini, Mistral, Groq, DeepSeek, OpenRouter, xAI, Together AI, AWS Bedrock, Cohere, Ollama (12 total). Provider adapters live in src/llm/.

Databases Used

File	Purpose
cortex.db	Core: sessions, jobs, policies, nodes, services
memory.db	5-tier memory (episodic, semantic, reflection, graph)
lens.db	Cortex Lens audit log
vault.db	Encrypted credential vault
plugins.db	Plugin registry

Deno Import Map

Dependencies are declared in deno.json under "imports". Key packages:

• @cliffy/command, @cliffy/prompt — CLI framework
• @std/assert, @std/path, @std/fs, @std/fmt, @std/datetime — Deno standard library
• npm:@anthropic-ai/sdk, npm:openai, npm:@google/generative-ai, npm:@aws-sdk/client-bedrock-runtime — LLM SDKs
• npm:@libsql/client — SQLite/libSQL client