0.1.0 • Published 1 month ago

@octocodeai/agent-contracts

Licence

MIT

Version

0.1.0

Deps

Size

187 kB

Vulns

Weekly

Stars

Summary Dependency Versions

Octocode Agent

A self-working coding agent — the Pi runtime driven by the Octocode harness, with always-on multi-agent coordination.

octocode-agent is the agent slice of the Octocode platform. It packages three layers that turn Pi into an evidence-first, coordinated coding agent:

octocode-agent — the branded launcher CLI. One command, one update path.
@octocodeai/pi-extension — the harness: system prompt, MCP research bridge, support tools, skills, and Awareness wiring.
@octocodeai/octocode-awareness — the coordination layer: one package exposing the shared root library + octocode-awareness bin for Pi/external interoperability, and the advanced full runtime.

Pi runs the loop, Octocode owns the tools, Awareness coordinates. The launcher is thin on purpose — all behavior lives in the harness and coordination packages.

Quick Start
The Three Layers
Tool Ownership
Terminal Experience
Extending with MCP Servers and Skills
Architecture
Repository Layout
Developing
How the Pieces Wire Together
Verified Capabilities
Documentation

Quick Start

Run the agent — no clone required:

npm install -g octocode-agent
octocode-agent                 # launch the agent (Pi + Octocode harness)
octocode-agent --version       # launcher, core, and Pi host versions
octocode-agent update          # self-update the platform (pulls newest core)
octocode-agent update core     # update @octocodeai/pi-extension in place

Or use the harness inside an existing Pi install:

pi install npm:@octocodeai/pi-extension
/octocode                      # dashboard: status, agents, setup, skills, health

Authenticate GitHub-backed research once (optional, unlocks private repos + higher rate limits):

npx octocode auth login
npx octocode status

The branded entry point. It has a real dependency on @octocodeai/pi-extension, so npm install -g and npx always resolve the pinned harness. It launches Pi in octocode-first mode — the Octocode harness leads while Pi's runtime invariants stay underneath.

octocode-agent [agent args...]   # launch; Pi-compatible args are mapped by the launcher
octocode-agent update            # self-update the platform
octocode-agent update core       # refresh only @octocodeai/pi-extension in this install
octocode-agent --agent-help      # launcher help (reserved subcommands only)

Because the prompt, skills, tools, and memory all live in the core package, nothing is duplicated here — updating the core updates what the agent launches.

packages/octocode-agent · PI_INTEGRATION.md

2. Pi Extension — the harness

@octocodeai/pi-extension is where the agent gets its brain. Installing it into Pi loads:

Surface	Count	What it is
Octocode research tools via MCP	15	GitHub + local + LSP + npm evidence tools through the built-in `octocode` MCP server
Direct model tools	16	Guarded `bash` plus `file`, `web`, `chromeDebug`, `agent`, `callTool`, `skill`, `plan`, `localServer`, `MCPTool`, `askUser`, `memory`, `lock`, `message`, `readMedia`, and `media`
Bundled skill	1	`octocode-awareness`; the rest install on demand via `npx octocode skill --add`

On load it sets $OCTOCODE_CLI and $OCTOCODE_AWARENESS_CLI, injects the operating-model system prompt, registers edit-safety hooks, arms the session-scoped approval gate, and wires Awareness lifecycle automation. The full TUI layer it adds — banner, footer cockpit, permission levels, an RFC-backed plan gate + a live HTML plan/RFC page — is summarized in Terminal Experience.

$OCTOCODE_CLI            → node "$OCTOCODE_CLI" <command>
$OCTOCODE_AWARENESS_CLI  → node "$OCTOCODE_AWARENESS_CLI" <noun> <verb> --compact

Awareness is deliberately not exposed as Pi tools. Agents drive it through the bundled CLI under the octocode-awareness skill; in-process hooks automate file presence, exclusive-conflict checks, briefings, and finish warnings — one CLI/schema contract, no duplication.

packages/octocode-pi-extension · docs · TOOLS · AWARENESS flow

3. Awareness — CLI + Skill

@octocodeai/octocode-awareness gives any coding host one shared coordination contract:

The shared library (@octocodeai/octocode-awareness) used in-process by Pi.
The shared CLI bin (out/octocode-awareness.js, exposed at runtime as $OCTOCODE_AWARENESS_CLI) — the live-state engine over a local SQLite store (zero npm runtime deps, uses built-in node:sqlite, requires Node ≥ 22.13).
The octocode-awareness skill — the external-agent router that points at the shared bin.

What it provides:

a live Plan → Task queue with reasons, acceptance criteria, paths, and dependencies;
advisory file presence — who is editing what and why;
optional exclusive locks for sensitive, non-mergeable changes;
durable memory, agent-to-agent messages, verification receipts, and an agent registry with presence counts.

# orient before any repo work (the extension sets $OCTOCODE_AWARENESS_CLI at load)
node "$OCTOCODE_AWARENESS_CLI" status --workspace "$PWD"

# core lifecycle
node "$OCTOCODE_AWARENESS_CLI" work start ...          # declare edited paths
node "$OCTOCODE_AWARENESS_CLI" task claim ...          # claim a ready task
node "$OCTOCODE_AWARENESS_CLI" memory recall ...       # surface prior verified learning
node "$OCTOCODE_AWARENESS_CLI" check mark ... && node "$OCTOCODE_AWARENESS_CLI" check audit

Commands: status · plan · task · lock · work · handoff · agent · message · check · memory · hooks (run … schema for exact shapes). SQLite is canonical; <workspace>/.octocode/ is a discovery shelf (authored plan docs), never a second database. No server, no daemon.

The same package's full octocode-awareness bin adds attend, reflection, projections, sessions, and maintenance in a separate advanced store; it is not the Pi-visible coordination ledger.

packages/octocode-awareness · HOW_IT_WORKS

Tool Ownership

The branded launcher starts Pi with all native Pi built-ins suppressed in both launch paths: the SDK session uses noTools: "builtin", and the subprocess uses --no-builtin-tools. There is no environment opt-out. The harness then supplies the complete public palette, including its guarded same-name bash implementation.

Pi native tool	Octocode route
`read`	`MCPTool` → `localGetFileContent`; local media uses `readMedia`
`edit`, `write`	`file` with `type:"edit"`, `"write"`, or `"delete"`
`grep`, `find`, `ls`	`MCPTool` → `localSearchCode`, `localFindFiles`, or `localViewStructure`
`bash`	Octocode's guarded same-name `bash` tool

Direct Pi users who install only the extension get the same effective palette: the extension removes replaced native names on load and again at session start as a defensive backstop. See OVERRIDES.md for the exact contract.

Terminal Experience

The harness ships a deliberate TUI design system — one palette, one copy source, and motion that always means something:

Surface	What you get
Startup banner	Branded OCTOCODE card (lens + octopus emblem, white→purple gradient with an animated gloss sweep) rendered once per fresh session as a transcript entry — zero prompt-token cost, re-renders on `/resume`.
Footer cockpit	Context gauge · merged turn timing (`turn 8 · 14s` live, `turns 7 · last 12s` idle) · session uptime · workers/awareness/peer state · effort dial · always-visible permission mode · prompt overhead · `branch* ΔN` changed files. `/octocode-footer legend` explains every segment; `compact`/`default`/`full` tune density.
Motion language	Wave (footer wordmark ripples) = working · glow (breathing ✗ and a ≥90% context gauge) = act on me · gloss sweep = brand splash. Deterministic, timer-free, test-pinned so status colors can never become decoration.
Approval gate	Sensitive bash (installs, git mutation, deletes, sudo, publish, system/infra, shell-rc persistence, backtick/`$()` evasion) prompts Yes / No / Always-allow. Session-scoped levels — `strict` / `default` / `relaxed` — via `/octocode-permissions`, a cycle shortcut (default `ctrl+shift+a`), or `OCTOCODE_PERMISSION_LEVEL`. Everything resets on a new session; headless hosts always deny rather than assume consent.
Plan workflow	A gated research → RFC → approve flow. `/octocode-plan new <goal>` enters plan mode (write tools blocked until approval); the agent orients, then `plan action:clarify` runs a bounded ≤3-question interview whose answers land in a durable decision log. Consequential work routes through the `octocode-rfc-generator` skill — and `plan action:propose` blocks a consequential plan that has no RFC. Propose sets the checklist and asks for sign-off inline (Approve / Reject; free-text = change request, echoed verbatim). `/octocode-plan html` opens a live local page — phase timeline, status checklist, mermaid dependency diagram, the rendered RFC, the decision log, and a shareable `plan.md` — rewriting on every change while you keep talking in the terminal.
Widgets	Unified below-editor status panel (model → plan → awareness → agents) with a live phase stepper (Research → RFC → Approve → Build → Verify), card-styled `askUser` prompts (72-col frame, quiet chrome, recommended-default + pros/cons), filter-preserving select overlays, worker inbox, command palette (default `ctrl+shift+k`).

All copy lives in one content module and all design constants (palette tokens, separators, brand marks, wave/glow painters) in one design module — wording and colors cannot drift between surfaces, and the test suite pins the rules (e.g. only warning/error states may glow).

Extending with MCP Servers and Skills

Use MCP servers to expose more tools. Use skills to teach the agent a reusable workflow. Most integrations only need MCP config — no code change, rebuild, or new skill.

MCP server config is read from:

Scope	Paths in precedence order	Loaded when
Built-in	pinned local `octocode-mcp` (`npx -y octocode-mcp@latest` fallback)	Always, as server `octocode`
Global	`~/.pi/mcp.json`; `$OCTOCODE_HOME/agent/mcp.json`; `~/.pi/agent/mcp.json`	When each file exists
Project	`<workspace>/.pi/mcp.json`; `<workspace>/.octocode/agent/mcp.json`; `<workspace>/.pi/agent/mcp.json`	Only after the project is trusted

A later definition of the same server name wins. Claude Code, Cursor, Codex, .agents, and compatibility .octocode/mcp.json files are discovery inventory only; copy a trusted stdio entry into an active path before the gateway can run it.

Minimal config:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@acme/mcp-server@latest"],
      "env": {},
      "cwd": ".",
      "timeoutMs": 30000
    }
  }
}

Inside a session, the agent can also add a trusted server live:

MCPTool({queries:[{
  reasoning: "Add the trusted external server.",
  action: "add",
  server: "my-server",
  scope: "project",
  config: { command: "npx", args: ["-y", "@acme/mcp-server@latest"] }
}]})

Discovery is automatic: MCPTool({queries:[{reasoning:"Inspect the server tools.", action:"list",server:"my-server"}]}) lists the server's tools and schemas; describe reads one exact tool schema; call invokes it. Config files are watched and hot-reloaded, so new tools apply on the next MCPTool call. You can also inspect or manage servers from /octocode-mcp.

Create or install a skill only when the integration needs operating guidance: when to use the tools, how to combine them, validation rules, pitfalls, or a multi-step workflow. For example, a docs-search MCP server can stand alone; a release-management workflow that uses several tools and requires checks is a skill.

More detail: packages/octocode-pi-extension/docs/TOOLS.md#MCP-Servers and packages/octocode-pi-extension/README.md.

Architecture

graph TD
    AGENT["octocode-agent<br/>branded launcher CLI"]
    PI["Pi runtime<br/>(shell, tool loop, providers)"]
    EXT["@octocodeai/pi-extension<br/>HARNESS: prompt · MCP research · support tools · skills · hooks"]
    AW["@octocodeai/octocode-awareness<br/>SHARED COORDINATION: plans/tasks · locks · memory · checks (SQLite)"]
    SKILL["octocode-awareness skill<br/>external-agent router"]
    BRAIN["External npm brain (sibling repos)<br/>octocode-tools-core · octocode-engine · @octocodeai/config"]

    AGENT -- launches --> PI
    PI -- loads --> EXT
    EXT -- bundles CLI + skill --> AW
    EXT -- injects --> SKILL
    SKILL -- drives --> AW
    EXT -- consumes --> BRAIN

    style EXT fill:#1a1a2e,stroke:#e75d2a,color:#fff
    style AW fill:#12233b,stroke:#4a9,color:#fff

This repo ships the agent, harness, and coordination layers. The tool-execution brain (@octocodeai/octocode-tools-core, @octocodeai/octocode-engine, @octocodeai/octocode-core), the config loader (@octocodeai/config), and the MCP / VS-Code interfaces are published from sibling repos and consumed here as npm dependencies. Never duplicate getOctocodeHome or .env parsing — always use @octocodeai/config.

Repository Layout

Yarn 4 workspaces monorepo (packages/*), Node ≥ 22 (Awareness runtime needs ≥ 22.13).

Package	npm name	Role	Deep dive
`packages/octocode-agent`	`octocode-agent`	Branded launcher — one command, one update path.	docs
`packages/octocode-pi-extension`	`@octocodeai/pi-extension`	The Pi harness: native tools, CLIs, system prompt, skills, Awareness wiring.	docs
`packages/octocode-awareness`	`@octocodeai/octocode-awareness`	Shared root coordination used by Pi/external agents plus advanced reflection/query/session runtime. Canonical skill source.	docs

Agent guides: AGENTS.md (repo) · packages/octocode-awareness/AGENTS.md (package). Internals: each package's ARCHITECTURE.md where present.

Developing

yarn install

# root: fans out to every workspace
yarn build        # build all packages
yarn test         # run all test suites
yarn lint         # lint all
yarn typecheck    # typecheck all

Per-package verification (no root verify):

yarn workspace @octocodeai/octocode-awareness verify
yarn workspace @octocodeai/pi-extension verify
yarn workspace octocode-agent verify

Local end-to-end after changing a local package — rebuild in dependency order, then exercise the real CLI / harness path (don't claim done from a compile alone):

yarn workspace @octocodeai/octocode-awareness build
yarn workspace @octocodeai/pi-extension build
yarn workspace octocode-agent build

Conventions. Plan → TDD → yarn workspace <pkg> test → yarn lint → verify. Coverage target ≥ 90% branch (Vitest + v8). No backward-compat by default — refactor freely; add shims only when asked.

Build outputs (do not hand-edit): packages/octocode-awareness/out/** (separate CLI + import-only library/schema API + bundled skills), extension dist/**, and any .agents/skills/** / out/skills/** mirrors. Edit source in src/**, bin/**, and the canonical skill under packages/octocode-awareness/skills/octocode-awareness/**, then rebuild.

How the Pieces Wire Together

octocode-agent launches Pi with @octocodeai/pi-extension loaded as the harness.
On load the extension sets $OCTOCODE_CLI + $OCTOCODE_AWARENESS_CLI, registers support tools, injects the operating-model system prompt, and installs edit-safety + Awareness lifecycle hooks.
For non-trivial repository work the agent activates the octocode-awareness skill and runs status, then claims work, declares edited files, coordinates with peers, records verified memory, and gates on verification.
Research runs through MCPTool and the built-in octocode MCP server (GitHub / local / LSP / npm), backed by the external Rust engine + tools-core packages.

Config is a single source: all env/config flows through @octocodeai/config (getOctocodeHome, propagateOctocodeEnv, parseEnv, loadOctocoderc). Skills use the injected ./octocode-config.mjs; packages import from @octocodeai/config or a package-local re-export.

Verified Capabilities

Every surface below is exercised end-to-end (live smoke runs + the package test suites), not just compiled.

Tools

Surface	What's verified
`bash` / `file`	Path-guarded shell plus preflighted edit/write/delete batches with stale/lost-update checks and diffs
Octocode research (via MCP)	`localSearchCode` · `localViewStructure` · `localGetFileContent` · `localFindFiles` · `localFindDeadCode` · `npmSearch` · `ghSearchCode` · `ghViewRepoStructure` with `next.*` chaining
`lspGetSemantics`	Live LSP definitions/references/callers with exact file:line anchors
`web`	Search (provider chain Tavily → Serper → Exa → DuckDuckGo), URL fetch with pagination
`readMedia` / `media`	Perceives images, video, and audio; authors images/PDFs and transforms media through a separate write boundary
`chromeDebug` / `agent`	Direct CDP operations plus browser-profile routing and multi-turn worker lifecycle
`agent`	Typed/custom/browser worker spawn plus inspect/wait/message/steer/abort/kill lifecycle operations
Awareness (Lite)	`status`, plan/task queue, verification gates (`verify audit`/`mark`), exclusive file locks with the full contention cycle (acquire → conflict → release → re-acquire), agent presence counts

Skills

Pi owns Awareness instructions in its prompt. External agents can install octocode-awareness from the canonical repo-root source skills/octocode-awareness. Other workflow skills remain installable with npx octocode skill --add.

Test surface

Package	Suite
`@octocodeai/pi-extension`	Vitest suites across 73 test files (1,200+ tests) — tools, prompts, CDP schemes, subagents, approval gate + permission levels, footer/widgets/animation, the plan/RFC surface (clarify interview, decision log, consequential gate, phase stepper)
`@octocodeai/octocode-awareness`	Shared SQLite coordination/library/CLI tests, advanced runtime tests, and zero-dependency pack verification

Documentation

Area	Links
Agent / launcher	`octocode-agent` docs · PI_INTEGRATION
Harness (Pi extension)	docs index · TOOLS · AWARENESS flow · REFLECT · OVERRIDES
Awareness	docs index · HOW_IT_WORKS · HOOKS · VERIFY · LOCKS · MEMORY_NAVIGATION
Platform	Website octocode.ai · Pi

The full Octocode platform — MCP server, the octocode CLI, the Rust engine, and the VS Code extension — lives in the sibling bgauryy/octocode monorepo and is consumed here as npm dependencies.