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)

Before Committing

Always run all three verification steps before staging and committing:

deno task check && deno task lint && deno task fmt

• deno fmt auto-fixes formatting (including markdown in CHANGELOG.md).
• If deno fmt modified files, re-stage them before committing.
• Never skip deno fmt — CI will reject unformatted files.

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, Kilo, Cerebras, Fireworks, Perplexity, NVIDIA, Moonshot, Novita, LM Studio, LiteLLM, HuggingFace, Alibaba, Venice (24 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