Skip to content
Docs menu

Entry points

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.

View .md

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

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

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.

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.

Prompt 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.

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

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

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

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).

Signed action log

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

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

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

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

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

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

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

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

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

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: 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.

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 posts an item (kind approval, question, merge or lease) and waits; someone resolves 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.

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

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

@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.