Orivus Coding Agent

Apache-2.0 reference agent module for governed software mutation — technical preview.

Most AI coding tools interpret your intent and mutate your workspace in the same step.
Orivus separates those roles.

| Role | Package | License | |------|---------|---------| | Interpretation — risk, plan, preview, review, handoff preparation | @orivus-ai/coding-agent | Apache-2.0 | | Authority — sessions, attestation, apply, audit, replay | @orivus-ai/edge | BUSL-1.1 (source-available kernel) |

Proposal ≠ authority.
Agents interpret. The kernel authorizes mutation.

This repository is not the kernel. It is the first open reference agent built on Orivus Edge: a local, governance-first runtime where nothing governed touches disk until a human explicitly confirms and the kernel executes apply.

Requires: @orivus-ai/edge ^0.1.0 (peer). Not a standalone coding tool.

Why this exists

Today's AI coding stacks collapse two distinct responsibilities:

| Responsibility | Question it answers | Who should own it | |----------------|---------------------|-------------------| | Interpretation | What change is proposed, and is it reasonable? | Agent module | | Mutation authority | May this workspace change, now, on disk? | Kernel + explicit human confirm |

When both live in the same tool path, you get:

• patches applied while you are still reading the plan,
• no durable record of who authorized what,
• previews that silently go stale,
• sessions that cannot be replayed or audited,
• “the model decided” substituted for an authorization gate.

That is not only a model-quality problem. It is a systems architecture problem.

Proposal ≠ authority. An agent that can interpret and write production files without a separate authorization boundary is automation — not governance.

Orivus names the boundary and enforces it: agents prepare governed proposals in session; the kernel alone executes mutation after attestation, drift checks, and --confirm.

Who this is for

| You are… | Why this module matters | |----------|-------------------------| | Senior engineer | You want inspectable proposals, real previews, and explicit confirm before disk writes | | Platform / developer-experience team | You need a reference pattern for agent modules that cannot own final mutation authority | | Local-first / air-gapped environment | You run inference and governance on-machine; mutation stays session-gated until confirm | | AI-native workflow builder | You are composing agents on Edge, not wrapping another copilot SDK | | Team with mutation policy | You require audit trails, attestation, drift detection, and replayable sessions |

Not a fit if you want a chat-first copilot that edits files immediately, fully autonomous production apply, or a tool that works without the Edge kernel peer.

30-second mental model

Agent   → interpretation   (intent → risk → plan → preview → review)
Session → source of truth    (pendingMutation, hashes, stage seals)
Human   → authorization      (apply --confirm)
Kernel  → authority           (attest → drift check → write → audit)

orivus coding change              →  ready_for_confirm (workspace unchanged)
orivus coding apply               →  blocked (confirm required)
orivus coding apply --preview     →  unified diff only (still unchanged)
orivus coding apply --confirm     →  handoff → kernel apply → audit record

One sentence to remember:

Agents interpret. The kernel authorizes mutation.

Governed execution flow

Interpretation and authority are separate code paths. The agent never calls the kernel write API directly.

flowchart LR
  subgraph interpretation["Agent module (@orivus-ai/coding-agent)"]
    A[change pipeline]
  end
  subgraph session["Session (.orivus/session/)"]
    S[current_session.json<br/>pendingMutation · previewHash · seals]
  end
  subgraph authorization["Human gate"]
    H[apply --confirm]
  end
  subgraph authority["Kernel (@orivus-ai/edge)"]
    K[validate session + attestation]
    G[GovernedApplyService]
    W[workspace write]
    U[audit + archive]
  end

  A --> S
  S --> H
  H -->|handoff payload| K
  K --> G
  G --> W
  W --> U

| Step | Component | Disk under governed targets | |------|-----------|----------------------------| | coding change | Agent pipeline | Unchanged — proposal in session only | | coding apply | Kernel gate | Blocked without confirm | | coding apply --preview | Kernel gate | Diff only — still unchanged | | coding apply --confirm | Agent validates → handoff → kernel act | Written + audited |

The agent's apply --confirm does not write your source tree. It validates integrity and returns a handoff. Only the kernel apply path mutates reality.

60-second demo

Reproducible golden path from Orivus Edge (certification/fixtures/v1-golden-path):

# 0. Prerequisites: @orivus-ai/edge installed globally (see Install)
cd certification/fixtures/v1-golden-path

orivus init --yes
orivus index

# 1. Interpretation — full pipeline, session only
orivus coding change --contract contracts/golden-path.orivus.yaml

# 2. Authority check — workspace still clean
git diff    # expect: empty (pending work lives under .orivus/session/)

# 3. Gate — confirm required
orivus coding apply
# expect: blocked, no file mutation

# 4. Inspect — real unified diff, still no write
orivus coding apply --preview
# expect: diff output; git diff still empty

# 5. Authorize — kernel write + audit
orivus coding apply --confirm
# expect: governed target changed; session archived; audit trail updated

What proves governance: after step 1, git diff is empty. After step 5, only then does the governed file change.

Full narrative: Orivus Edge — demo release v0.1.

Contract-driven change (deterministic)

For demos without free-form intent (explicit symbol — no guessed edit locus):

orivus coding change --contract examples/contracts/safe-null-guard.orivus.yaml

See examples/contracts/README.md.

Install

From npm (recommended)

npm install -g @orivus-ai/edge
cd your-project
orivus init    # registers @orivus-ai/coding-agent when configured

You do not need to clone this repository for normal use.
@orivus-ai/[email protected] is on registry.npmjs.org.

Local development (both repos)

git clone https://github.com/orivus/orivus-edge.git
git clone https://github.com/orivus/orivus-coding-agent.git
cd orivus-edge && pnpm install && pnpm run build
cd ../orivus-coding-agent && pnpm install && pnpm run build
orivus init --yes --agent-path /absolute/path/to/orivus-coding-agent

What changes on disk (v0.1)

| Phase | Actor | Governed source files | |-------|-------|------------------------| | Risk → review pipeline | Coding agent | Unchanged | | apply (no flags) | Kernel | Blocked | | apply --preview | Kernel | Preview only | | apply --confirm | Kernel GovernedApplyService | Written + audited |

Guarantees in this preview:

• Session-only proposals — pending work under .orivus/session/, not your tree
• Pipeline attestation — incomplete or tampered pipelines cannot apply
• Preview before review — reviewer sees real proposed content, not summaries
• Drift detection — stale preview vs on-disk file blocks apply
• Syntax verification — structural validation before write
• Kernel-owned audit — apply and block paths recorded

Core law: Agents propose. The kernel governs. The runtime observes.

What this package does

Governed single-file change pipeline (v0.1):

| Stage | Purpose | |-------|---------| | risk | Analyze change risk; abort on CRITICAL | | plan | Build plan from intent + structural context | | preview | Proposed file content in memory | | adversarial_review | Adversarial pass on preview | | review | Reviewer evaluates real preview vs original | | ready_for_confirm | pendingMutation with previewHash + targetFingerprint |

CLI (via orivus coding …):

| Command | Purpose | |---------|---------| | change | Full pipeline + session persistence; normal CLI shows a concise governed mission report (use --verbose for contract envelopes) | | apply --preview | Unified diff; disk unchanged | | apply --confirm | Session validation → handoff to kernel | | risk / plan / review / run | Partial paths — not the certified golden path |

What this package must never do

| Prohibited | Enforcement | |------------|-------------| | Write governed target source files | ApplyCommand returns handoff only (CERT-SOV-001) | | Direct apply via --target / --content | UNSUPPORTED_DIRECT_HANDOFF | | Skip preview-before-review | Fixed stage order in CodingChangePipeline | | Bypass session on governed apply | Requires current_session.json | | Import Edge kernel internals | @orivus-ai/edge/sdk only; pnpm run certify | | Raw filesystem I/O in commands | Workspace reads via granted storage capability |

No final mutation authority — by design.

Integration with Edge

sequenceDiagram
  participant User
  participant EdgeCLI as orivus CLI
  participant Agent as @orivus-ai/coding-agent
  participant Kernel as GovernedApplyService

  User->>EdgeCLI: coding change
  EdgeCLI->>Agent: run pipeline
  Agent->>Agent: session metadata only
  EdgeCLI->>EdgeCLI: SessionPipelineSealer

  User->>EdgeCLI: coding apply --confirm
  EdgeCLI->>Agent: apply
  Agent-->>EdgeCLI: handoff
  EdgeCLI->>Kernel: execute(authorization)
  Kernel->>Kernel: write file + audit

1. orivus init registers module id: coding.
2. CapabilityBroker grants declared capabilities at activation.
3. On confirm, Edge forwards authorization to GovernedApplyService — the only legal workspace write path.

Capabilities required (src/agent.manifest.ts):

INFERENCE_EXECUTE · TOPOLOGY_READ · INDEX_READ · GIT_SIGNALS_READ · SOURCE_PARSE · LOGGER_WRITE · STORAGE_WORKSPACE_READ · STORAGE_SESSION_WRITE

Session files (agent scope):

| File | Writer | Content | |------|--------|---------| | .orivus/session/current_session.json | change | Pipeline state, pendingMutation, stages | | .orivus/session/last_session.json | Edge after apply | Archived session | | .orivus/session/last_plan.json | plan only | Standalone plan artifact |

The agent never writes governed paths under your workspace source tree.

Handoff on apply --confirm:

{
  status: 'success',
  handoff: {
    ready: true,
    payload: {
      type: 'file_mutation',
      file,
      content,
      previewHash,
      // …
    },
    sessionRef: session.sessionId,
  },
}

Kernel semantics: Orivus Edge — governance.

Build another agent

Orivus agents are EdgeAgentModule packages: declare capabilities, run a governed pipeline, persist proposals in session, return handoff on apply — never invoke kernel apply from agent code.

• Minimal pattern: docs/examples/simple-agent.md
• Reference: src/agent.manifest.ts, src/agent.module.ts

Honest limits (v0.1)

Technical preview — not a finished platform.

| Area | Reality | |------|---------| | Scope | Single-file governed mutation only | | Autonomy | Human confirm required — not certified for unattended production apply | | Sandbox | Trusted binary — no VM isolation for agent code | | Inference | Local-first — first model download can be slow; live LLM behavior varies | | Context | Structural (index, topology) — not a deep semantic call graph | | Commands | change + apply are certified; run and partial commands are secondary |

We block apply rather than guess when attestation, hash, or drift checks fail.

Kernel limits: known limitations v0.1.

What we are not claiming

| Narrative | Status | |-----------|--------| | “Another AI coding assistant” | No — mutation authority is separated and kernel-governed | | “LangChain / copilot wrapper” | No — Edge kernel + agent module architecture | | “Fully autonomous coding” | No — explicit --confirm is mandatory | | “Fully open-source platform” | No — kernel is BUSL-1.1; this agent is Apache-2.0 | | “AI OS” | No — governed local coding runtime preview |

Develop and certify

pnpm install
pnpm run build
pnpm run check      # typecheck + lint + test + build
pnpm run certify    # boundary scan + behavioral certification

| Suite | Proves | |-------|--------| | certification.sovereignty.test.ts | No disk write on agent apply confirm | | ApplyCommand.test.ts | Drift, hash mismatch, blocked direct handoff | | CodingChangePipeline.test.ts | Stage ordering, retries |

docs/certification.md · docs/release-checklist-v0.1.md

Documentation

| Doc | Topic | |-----|-------| | Orivus Edge README | Kernel, CLI, runtime | | Governance | Attestation, drift, audit, replay | | CLI reference | Full commands | | Certification | pnpm run certify | | Contributing | PR rules, governance laws | | Security | Reporting, threat model | | Changelog | Releases |

License

Apache License 2.0 — LICENSE, NOTICE.

• Runtime peer: @orivus-ai/edge (BUSL-1.1). Commercial kernel use may require a separate license — Edge licensing.
• Mutation authority: Edge kernel only. This agent proposes; it does not own the write path.