---
title: Entry points
description: Every import path of @venom/harness, what it is for and whether it loads pi, with the API of the modules that have no page of their own.
section: harness
order: 90
audience: [builder, agent]
sources: [packages/harness/package.json, packages/harness/src/index.ts, packages/harness/AGENTS.md]
features: [harness.actions, harness.browser, harness.decisions, harness.egress-map, harness.evidence, harness.flaky, harness.goalgate, harness.inbox, harness.injection, harness.intents, harness.longtask, harness.pi, harness.pi-path, harness.planexec, harness.provenance, harness.review, harness.risk, harness.schedules, harness.supplychain, harness.triage, harness.web]
---

The package has one root entry and many subpaths. Subpaths marked "no pi" do not load pi, so an app can use them (the permission engine, the review report, the inbox store) without the agent runtime. Most are also reachable from the root as a namespace: `import { review } from "@venom/harness"`.

## All entry points {#all}

| Import path | pi | What it is for | Documented in |
|---|---|---|---|
| `@venom/harness` | yes | sessions, harnesses, tools, events, re-exported pi and typebox types | [Embed](/docs/harness/embedding.md), [Sessions](/docs/harness/sessions.md) |
| `@venom/harness/permissions` | no | rules, modes, the policy engine, the sandbox, audit sinks, organisation policy | [The permission engine](/docs/harness/permissions.md) |
| `@venom/harness/provider` | no | provider options, model discovery, prices, error classification | [Model provider](/docs/harness/providers.md) |
| `@venom/harness/subagents` | no | task resolution, built-in agents, model tiers, task DAGs | [Subagents](/docs/harness/subagents.md) |
| `@venom/harness/workspaces` | no | git worktrees for sessions and subagents | [Subagents](/docs/harness/subagents.md#worktrees) |
| `@venom/harness/compat` | no | Claude Code file loaders | [Claude Code compatibility](/docs/harness/claude-code-compat.md#compat) |
| `@venom/harness/config` | no | `venom.yaml` discovery, validation, merge; gears | [Claude Code compatibility](/docs/harness/claude-code-compat.md#config) |
| `@venom/harness/plugin` | yes | the plugin SDK (`venom(pi, …)`) | [Claude Code compatibility](/docs/harness/claude-code-compat.md#plugins) |
| `@venom/harness/plugins` | no | plugin discovery, manifests, states, scaffolding | [Claude Code compatibility](/docs/harness/claude-code-compat.md#plugins) |
| `@venom/harness/library` | no | the team library sync and prompt expansion | [Claude Code compatibility](/docs/harness/claude-code-compat.md#library) |
| `@venom/harness/marketplace` | no | signed organisation plugin installs | [Claude Code compatibility](/docs/harness/claude-code-compat.md#marketplace) |
| `@venom/harness/init` | no | project detection and the `venom init` plan | [Claude Code compatibility](/docs/harness/claude-code-compat.md#init) |
| `@venom/harness/templates` | no | session templates and learned drafts | [Claude Code compatibility](/docs/harness/claude-code-compat.md#templates) |
| `@venom/harness/context` | no | token estimates and masking plans | [Context and memory](/docs/harness/context-and-memory.md#context) |
| `@venom/harness/memory` | no | memory-layer types: blob handles, pins, context descriptors | [Context and memory](/docs/harness/context-and-memory.md#context) |
| `@venom/harness/runtime` | no | agent process, signal and scheduler types | [Context and memory](/docs/harness/context-and-memory.md#runtime) |
| `@venom/harness/cost` | no | session cost and context breakdown | [Sessions](/docs/harness/sessions.md#cost) |
| `@venom/harness/checkpoints` | no | the shadow git store behind undo and restore | [Context and memory](/docs/harness/context-and-memory.md#checkpoints) |
| `@venom/harness/edit`, `/patch`, `/format`, `/lsp`, `/codeindex` | no | edit recovery, `apply_patch`, formatters, language servers, the code index | [Context and memory](/docs/harness/context-and-memory.md#edits) |
| `@venom/harness/guards` | no | runaway-loop trackers and limits | [Context and memory](/docs/harness/context-and-memory.md#guards) |
| `@venom/harness/todo` | no | the agent's checklist state | [Context and memory](/docs/harness/context-and-memory.md#todo) |
| `@venom/harness/lessons` | no | the evidence-gated lessons store | [Context and memory](/docs/harness/context-and-memory.md#memory) |
| `@venom/harness/review` | no | diff gathering and the `venom.review/v1` report | [below](#review) |
| `@venom/harness/injection` | no | prompt-injection detection and spotlighting | [below](#injection) |
| `@venom/harness/web` | no | `web_fetch` and `web_search` internals | [below](#web) |
| `@venom/harness/browser` | no | Chrome over the DevTools protocol | [below](#browser) |
| `@venom/harness/supplychain` | no | the dependency check on installs | [below](#supplychain) |
| `@venom/harness/egress-map` | no | the per-session network contact map | [below](#egress-map) |
| `@venom/harness/actions` | no | the signed action log | [below](#actions) |
| `@venom/harness/provenance` | no | signed receipts for commits | [below](#provenance) |
| `@venom/harness/evidence` | no | evidence bundles for a change | [below](#evidence) |
| `@venom/harness/risk` | no | risk tiers for a change | [below](#risk) |
| `@venom/harness/decisions` | no | advisory typed decisions from a decision model | [below](#decisions) |
| `@venom/harness/triage` | no | offline judgement of saved sessions | [below](#triage) |
| `@venom/harness/goalgate` | no | refuse vague goals before unattended work | [below](#goalgate) |
| `@venom/harness/flaky` | no | the flaky-test detector | [below](#flaky) |
| `@venom/harness/longtask` | no | task checkpoints and usage-limit waits | [below](#longtask) |
| `@venom/harness/planexec` | no | plan-then-execute data and engine | [below](#planexec) |
| `@venom/harness/schedules` | no | cron jobs for `venom serve` | [below](#schedules) |
| `@venom/harness/inbox` | no | the queue of decisions only a person can make | [below](#inbox) |
| `@venom/harness/intents` | no | the intent ledger | [below](#intents) |
| `@venom/harness/pi` | yes | the pinned pi exports | [below](#pi) |
| `@venom/harness/pi-path` | no | where pi is installed, without loading it | [below](#pi) |

## Review {#review}

`runReview({ harness, target, log?, maxUsd?, breaker? })` (root entry) reviews a diff read-only (no edits, no writes from bash, no network) and returns a `venom.review/v1` report: findings with severity, file, line and a suggested fix, plus a verdict. A model failure gives verdict `error`, never a throw; a bad target throws `ReviewTargetError`.

```ts
import { MemoryAuditSink, provider, runReview } from "@venom/harness";
import { exitCodeFor, type ReviewTarget } from "@venom/harness/review";

const target: ReviewTarget = { kind: "base", base: "origin/main" }; // also "working", "staged", "range"
const report = await runReview({
  harness: { cwd: repo, provider: provider.providerOptionsFromEnv(process.env), audit: new MemoryAuditSink(), compat: false },
  target,
});
process.exitCode = exitCodeFor(report); // 0 no blockers, 1 blockers, 2 error
```

`@venom/harness/review` has the pure parts: `gatherDiff`, `buildReport`, `validateReport`, `formatReport`, `REVIEW_SCHEMA`, `SEVERITIES`, `MIN_CONFIDENCE` (0.6). The CLI's `venom review` and the review action are in [the automation section](/docs/automation.md).

## Prompt injection {#injection}

Tool output (files, web pages, MCP and app tools) is wrapped in `<untrusted_…>` tags (spotlighting), the system prompt tells the model to treat it as data, and a detector flags instruction-like text with an `injection` event. `HarnessOptions.injection` turns each part off (`{ guidance, spotlight, detect }`). `@venom/harness/injection`: `detectInjection(text)` (`{ flagged, findings }`), `spotlight`, `scanScriptRequests` (text asking the agent to run a command); `firewall` (root entry) filters text that arrives from issues, PRs and comments for agents that take work from a tracker: untrusted authors' text is dropped, tool-call-shaped text is removed, and the rest is wrapped and tagged with its source. [More in the security section](/docs/security.md).

## Web {#web}

`web_fetch` turns a page into markdown (`htmlToMarkdown`), refuses private addresses unless allowed, follows at most 5 redirects, reads at most 5 MiB in 30 s and returns 16 000 characters by default (`DEFAULT_WEB_MAX_CHARS`). `web_search` tries the orchestrator's `POST /v1/search`, then SearxNG (`searchUrl`, `VENOM_SEARCH_URL`), Brave (`BRAVE_API_KEY`) or Tavily (`TAVILY_API_KEY`), then DuckDuckGo. `web.webOptionsFromEnv(env)` reads those variables plus `VENOM_SEARCH_ORCHESTRATOR` and `VENOM_SEARCH_RERANK`. `network: "offline"` or `web: false` removes both tools.

## Browser {#browser}

With `HarnessOptions.browser`, the agent gets browser tools driving Chrome: `launch` (a fresh profile), `attach` (a Chrome with a debugging port) or `extension` (the user's own Chrome through the venom extension and a local relay, `VENOM_BROWSER_RELAY`). Every action goes through the permission gate; the first action on a site, typing a credential and payments ask. `lazy: true` exposes only `browser_navigate` until first use. `@venom/harness/browser` has `CdpConnection`, `findChrome`, `launchChrome`, `attachChrome` and `BrowserSession`.

## Supply-chain check {#supplychain}

Before a bash install command or an edit of a manifest (`package.json`, `requirements.txt`, `go.mod`, …) is allowed, the gate checks each added dependency for typosquats of popular names and for registry facts from the project's own registry (`.npmrc`, `GOPROXY`, `PIP_INDEX_URL`), with a ten-minute in-memory cache. A finding turns the call into an ask that skips `auto` mode's classifier, or a deny when the organisation policy sets `supplyChain.action: "deny"`. `depsOfCall`, `checkDependencies`, `typosquatOf`, `registryFacts`.

## Egress map {#egress-map}

`EgressMap({ venomHome, session, repo })` collects every network contact of a session (sandboxed commands through the egress proxy, web tools) per host, with ports, request and denial counts and flags for hosts outside the allowlist or new to the repository, and saves `egress/<session>.json`. `readEgressMap`, `listEgressMaps`. CLI: `venom egress` ([security section](/docs/security.md)).

## Signed action log {#actions}

`ActionLog(venomHome, session)` appends each command and file write the agent made to `actions/<session>.jsonl` (mode 0600), each line chained to the previous by SHA-256, and `seal(key)` signs the head with an Ed25519 machine key (`machineSigningKey`, keystore chosen by `VENOM_KEYSTORE`). `verifyActionLog(file, { trustedKids? })` checks the chain and seal. CLI: `venom actions verify`.

## Provenance receipts {#provenance}

A receipt (`venom.provenance/v1`) records who made a commit and why: agent, model, a hash of the prompts (never their text), tools used, permission decisions and human approvals. It is Ed25519-signed, bound to the commit's tree and parents, stored in the git note `refs/notes/venom-provenance`, referenced by a `Venom-Receipt:` trailer, and chained to the signer's previous receipt. `signReceipt`, `writeNote`, `amendWithTrailer`, `readNote`, `checkSignature`.

## Evidence bundles {#evidence}

`buildEvidence(opts)` gathers the proof a change carries as one `venom.evidence/v1` JSON document: changed files, tests the change adds, the impacted-test selection and diff invariants, plus what the caller hands in (test runs, bench and eval deltas, a session reference, a risk score). `renderEvidenceMarkdown` makes the PR-comment form, marked `<!-- venom-evidence -->`. Nothing here runs a test or calls the network.

## Risk tiers {#risk}

`scoreRisk({ files, cochangeMisses?, plan?, policy? })` gives `{ tier: "low" | "medium" | "high", score, reasons }` from five signals: permission surface, size, co-change misses, test coverage and reversibility. Thresholds (medium 3, high 7) and extra sensitive paths come from the organisation policy's `risk` block. `assessChange(cwd, { base })` gathers the signals from git.

## Decisions {#decisions}

A typed question-and-answer interface to a decision model (yes/no probabilities, choices, scores). `SystemOneHttpProvider({ baseUrl, apiKey?, model: "venom-decide", timeoutMs: 3000 })` calls `POST <baseUrl>/systemone`; `LlmDecisionProvider` uses any chat model; `FallbackDecisionProvider` chains them; `decisionProviderFromEnv(env)` builds one from `VENOM_BASE_URL`, `VENOM_API_KEY` and `VENOM_DECISION_MODEL`. Decisions are advisory: a failed or slow one falls back to the behaviour without it, and none loosens a hard boundary.

## Session triage {#triage}

Which saved runs most likely went wrong, judged offline. `parseSessionJsonl(text)` reads a transcript's active branch (turns, tool calls, errors; no thinking or tool output), `buildTriageState` condenses it for a `DecisionProvider`, and the result ranks sessions. CLI: `venom triage`.

## Goal gate {#goalgate}

`checkGoal(goal)` refuses a goal for unattended work (schedules, `venom spec`) when it is shorter than 40 characters (`GOAL_MIN_LENGTH`) or names nothing concrete (a path, a symbol, a named test, a URL, an issue reference such as `#123`). A goal containing `[open-ended]` (`OPEN_ENDED_MARKER`) always passes. Interactive prompts are never gated.

## Flaky tests {#flaky}

The detector reads test output (vitest, go test, pytest) from tests the agent runs; a test that fails and then passes with no code change between is flaky. Records are kept per repository under `<venomHome>/flaky/`; after 3 occurrences (`FLAKY_DEFAULT_AFTER`) venom proposes an issue but never files one itself. `parseTestOutput`, `recordRun`, `loadFlaky`, `issueDraft`. CLI: `venom flaky`.

## Long tasks {#longtask}

A long task keeps a small checkpoint in `~/.venom/tasks/` (`TaskStore`), rewritten at each step boundary: where the session is, plan step state, the worktree's head and dirty files, in-flight tool calls. A task is resumable when it is waiting, paused, or running under a process that is gone. A 429 that names a reset time (`Retry-After`, `x-ratelimit-reset*`, or text like "try again in 2h 15m") parks the task until then (`parseUsageLimit`, `waitMs`; at most 7 days, at least 15 s). `resumableTasks`, `worktreeDrift`, `resumeNote`. CLI: `venom resume`.

## Plan-then-execute {#planexec}

The main model writes a plan (a fenced `plan-steps` JSON block in the plan file, at most 40 steps, each with an acceptance check), a person approves it, each step runs on a worker subagent, and the main model verifies it before the next starts; a failed check retries once on the escalation tier, then stops for the person. `parsePlan`, `newPlanRun`, `executePlan(run, deps)` (the worker, verifier and checkpoint write are injected, so you can drive it with your own models), `reopen`. CLI: `/plan-exec`.

## Schedules {#schedules}

`schedules:` in `venom.yaml` declares cron jobs that `venom serve` runs as background agents. `parseCron` (five fields), `nextFire`, `jobsFromConfig`, `planRun` (missed fire times collapse into one catch-up run; a new job never runs for the past) and `ScheduleStore`. Defaults: mode `default`, $1 per run (`DEFAULT_SCHEDULE_MAX_USD`), 120 minutes (`DEFAULT_SCHEDULE_MAX_MINUTES`); job names match `^[a-z0-9][a-z0-9._-]{0,63}$`. User guide: [automation section](/docs/automation.md).

## Inbox {#inbox}

One queue of the decisions only a person can make, shared by every local session. `InboxStore` keeps one JSON file per item in `<venomHome>/inbox/`, so separate processes need no server. A session `post`s an item (kind `approval`, `question`, `merge` or `lease`) and `wait`s; someone `resolve`s it with `approve`, `reject`, `redirect` or `take-over`. `list` ranks open items by blast radius × uncertainty × (1 + minutes blocked) and drops items whose owner process is gone. The inbox collects answers; it never decides. CLI: `venom inbox`.

```ts
import { inbox } from "@venom/harness";

const store = new inbox.InboxStore(inbox.inboxDir("/var/lib/myapp/venom"));
for (const item of store.list()) console.log(inbox.formatInbox([item], Date.now()));
```

## Intents {#intents}

A durable record of what is wanted: an intent has a goal, constraints, acceptance checks and an optional risk budget. `IntentStore` (one file per intent in `<venomHome>/intents/`) supports `create`, `claim(id, by)`, `release`, `addEvidence`, `close(id, { evidence })` and `close(id, { abandon: true })`; a parent cannot close while a sub-intent is open, and closing needs evidence. Errors are `IntentError` with a `code` (`not-found`, `claimed`, `open-children`, `evidence-required`, …).

## pi and pi-path {#pi}

`@venom/harness/pi` re-exports the pinned pi (`main`, `SessionManager`, `InteractiveMode`, `ProjectTrustStore`, `getAgentDir`, `VERSION`, TUI components and extension types), so a host loads exactly one copy of pi. Set pi's environment variables (`PI_PACKAGE_DIR`, `PI_OFFLINE`, …) before importing it or `@venom/harness`. `@venom/harness/pi-path` gives `piPackageDir()` and `piVersion()` without loading pi.

## Related {#related}

- [The harness library](/docs/harness.md)
- [Automation section](/docs/automation.md) and [Security section](/docs/security.md), for the CLI side of these modules
