J Jarvis protocol docs v0.1.0

Human-agent collaboration and learning loop

Jarvis Protocol Documentation

Jarvis defines how HumanWorkers and AgentWorkers collaborate inside governed WorkSessions, create scoped Requests when blocked, capture human Review and Takeover, record attributable Contribution, export portable EvidenceManifest records, and carry governed Learning into future work.

Jarvis is a protocol. Hosts own UI, auth, storage, execution, model calls, tool execution, monitoring, deployment, and host workflow.

Read v0.1 Spec OpenAPI Spec Conformance Guides Implementation Path Run Walkthrough GitHub
01

Read the protocol spine

Start with the v0.1 specification pages. They define the human-agent pair, WorkSession, policy gate, control plane, evidence, governed learning, and zero-trust rules.

Open v0.1 specification
02

Use the machine contract

OpenAPI 3.1 is the primary machine-readable communication binding for operations, headers, schemas, errors, and examples.

OpenAPI YAML
03

Prove compatibility

Compatible implementations pass the conformance checklist and fixture expectations without adopting a Jarvis-owned runtime.

Conformance docs
04

Run helper tooling

The SDK helper packages validate protocol records, headers, EvidenceManifest exports, event chains, and conformance fixtures.

Packages
Start Understand Jarvis in 10 minutes.

Read the thesis, boundary, core loop, and WorkSession record.

 Build Use the OpenAPI binding and SDK helpers.

Validate headers, records, event hashes, fixtures, and evidence exports.

 Prove Run conformance before claiming compatibility.

Compatible implementations prove behavior through records and fixtures.

 Extend Keep host implementation outside Jarvis.

Extensions add protocol fields. Extensions MUST NOT define runtime or workflow.

Protocol model

The unit is the human-agent team.

Jarvis does not define a personal agent, model runtime, planner, or workspace product. Jarvis defines the shared record that lets a human and an agent work together with policy, review, attribution, evidence, and learning.

HumanWorker + AgentWorker

Workers participate as protocol actors with authority and contribution scope.

WorkSession

The durable protocol record for goals, events, requests, reviews, evidence, and learning.

PolicyDecision

Every AgentWorker action that affects a WorkSession records policy state before acceptance.

Request, Review, ApprovalScope, and Takeover

Blocked scope routes to human judgment; authority stays bounded and attributable.

Contribution + EvidenceManifest

Jarvis records who did what and exports portable evidence without host-private fields.

LearningRecord + Proposals

Human, agent, and pair learning move forward only through governed protocol records.

Spec entry points

Read the contract from the same paths implementers use.

Introduction Protocol thesis, ownership boundary, and implementation path Terminology Worker, Actor, HumanWorker, AgentWorker, Host, and core terms Protocol Objects Required fields for the v0.1 object surface WorkSession Lifecycle Session states, JarvisEvent chain, and export readiness Policy and PolicyDecision Human-defined policy and required decision records Request, Review, ApprovalScope, and Takeover Scoped deferral, ApprovalScope, human judgment, and lock epochs Contribution and EvidenceManifest Attribution, EvidenceManifest export, and rejection rules LearningRecord, MemoryProposal, and SkillProposal LearningRecord, MemoryProposal, SkillProposal, and review gates OutcomeReport External feedback ingress and terminal-source requirements Versioning and Extensions Version negotiation, capabilities, namespaces, and extension limits Security and Zero Trust Mutation headers, Actor authority, revision, hash, and export safety Source: Protocol Lock Locked v0.1 protocol decisions and boundaries Source: Communication Binding HTTP operations, headers, versioning, and error envelope

OpenAPI 3.1 binding

The machine-readable contract starts here.

OpenAPI defines Jarvis v0.1.0 operations, schemas, parameters, headers, errors, and examples. Compatible implementations use the binding to exchange portable protocol records without adopting a Jarvis-owned runtime.

OpenAPI Reference OpenAPI README Raw YAML

WorkSession-scoped mutation headers

  • Jarvis-Protocol-Version
  • Jarvis-Actor-Id
  • Jarvis-Idempotency-Key
  • Jarvis-Request-Timestamp
  • Jarvis-Expected-WorkSession-Revision
  • Jarvis-Previous-Event-Hash

Non-WorkSession mutation headers are Jarvis-Protocol-Version, Jarvis-Actor-Id, Jarvis-Idempotency-Key, and Jarvis-Request-Timestamp. Worker registration, Actor registration, and OutcomeReport MUST NOT require fake revision or previous-hash values.

Core protocol flow

  • create WorkSession
  • record PolicyDecision
  • create Request
  • record Review or Takeover
  • export EvidenceManifest
  • submit OutcomeReport

The full operation matrix lives in the OpenAPI YAML.

Error envelope

  • error_id
  • protocol_version
  • object_type
  • field
  • reason
  • remediation

Examples

Map real work into protocol records.

Examples show how existing agents and hosts participate through Jarvis records without becoming Jarvis-owned agents, adapters, or runtimes.

Protocol Records

Concrete Worker, Actor, WorkSession, Request, Review, Contribution, EvidenceManifest, and LearningRecord examples.

Read record examples

Existing Agent Compatibility

How an existing agent participates through Jarvis records without being rewritten as a Jarvis agent.

Read compatibility guide

Compatible Host Mapping

How a host maps native collaboration events into Jarvis protocol records while keeping implementation private.

Read host mapping

Evidence Packs

Machine-checkable protocol records for existing-agent Review and Takeover loops, validated without host runtime code.

Open evidence packs

Implementer guides

Implementer guides define protocol obligations.

Implementer guides define what compatible implementations MUST store, emit, validate, reject, export, and preserve. They do not define host UI, auth, storage, runtime behavior, model routing, tool execution, billing, scoring, payment, deployment, monitoring, or host workflow.

Implementer guide Store, emit, validate, reject, and export protocol records. Existing-agent compatibility Map native agent work into Jarvis records without rewriting the agent. Request, Review, ApprovalScope, and Takeover Use scoped blockers, human judgment, ApprovalScope, and takeover lock epochs. Evidence and Learning Record contribution, export evidence, and carry governed learning forward. Extensions Use version, capability, and namespace rules without overriding core fields. Protocol errors Return stable error ids and portable error envelopes.

Conformance

Compatibility is proven through records.

A compatible implementation proves required headers, Actor authority, WorkSession revision, previous event hash, PolicyDecision preconditions, Request resolution, Takeover lock epochs, Contribution attribution, EvidenceManifest export safety, and governed learning.

Open conformance pages Claim format Fixture list 
npm run test:cli
node packages/cli/src/index.js validate fixtures docs/conformance/fixtures
node packages/cli/src/index.js list rejection-ids
python3 scripts/check_example_evidence_packs.py

SDK helper tooling

Helpers implement the protocol contract. They do not run agents.

Jarvis helper packages provide generated OpenAPI surfaces, validators, event helpers, hash-chain helpers, header checks, EvidenceManifest checks, protocol errors, fixture snapshots, and a conformance runner CLI.

TypeScript

Protocol types, validators, event helpers, header checks, and fixture snapshots.

Read TypeScript package

Python

Protocol models, validators, hash-chain helpers, and fixture validation.

Read Python package

CLI

Conformance fixture runner and protocol helper commands for local checks.

Read CLI package

Real implementation path

Existing agents remain host-owned.

Compatible implementations record Jarvis protocol state around native work. The agent keeps native execution. The host records Worker, Actor, WorkSession, PolicyDecision, Request, Review, Takeover, Contribution, EvidenceManifest, LearningRecord, proposals, and OutcomeReport records.

Read Implementation Proof Proof Validator
01

Host-owned execution

Native coding-agent sessions, workspace apps, and agent platforms stay outside Jarvis.

02

Add protocol recording

Emit Jarvis records at WorkSession start, policy checks, requests, reviews, takeovers, contribution, evidence, and learning.

03

Validate every record

Run SDK helpers, conformance fixtures, event hash-chain checks, and EvidenceManifest export checks.

04

Publish compatibility proof

Export an evidence pack and implementation proof without claiming certification or official-host status.

Release status

Jarvis v0.1.0 is Protocol Alpha.

Protocol Alpha defines the v0.1.0 contract and helper tooling. It does not certify implementations, designate an official host, claim production adoption, establish foundation governance, or create long-term support.

Read Release Notes
Current phase

Mutation Headers

01 / 12 created Ready 01 item
HumanWorker goals + judgment review, approve, teach
AgentWorker autonomous worker plan, research, learn
Jarvis protocol WorkSession policy requests review evidence
Host owns implementation UI, storage, tool execution
Request record human gate approve narrow deny takeover

The WorkSession-scoped mutation enters through required Jarvis headers.

    Jarvis owns

    protocol records, lifecycle rules, OpenAPI binding, errors, conformance, evidence, and governed learning.

    Hosts own

    UI, identity, auth, storage, runtime, tools, models, monitoring, deployment, and workflow.

    Alpha limit

    v0.1.0 does not certify implementations, designate an official host, or claim production adoption.