Company Runtime
01 · Source of truth

Runtime Protocol

An open, vendor-neutral contract for asking a runtime to do something on someone's behalf — and getting back proof that it happened.

How to use itView on GitHub
At a glancePublic

github.com/Company-Runtime/runtime-protocol

Protocol
runtime/0.1
Maturity
Experimental
Registry
13 domains · 36 capabilities
Bindings
HTTP · MCP · Events
Tooling
Node.js ≥ 22.18
License
Apache-2.0
What it is

Source of truth.

A caller declares an intent — communication.send — never an implementation such as slack.send-message. The runtime validates the request, checks authority and policy, resolves a compatible provider, binds credentials by reference, executes, collects evidence and returns a canonical execution receipt.

This repository is the normative source of truth: the specification, the JSON Schemas, the semantic registry, the transport bindings and the conformance suite. Implementations follow what is written here, never the other way around, and nothing in it depends on a runtime product, vendor, model or transport.

Read it if you implement a runtime, write a provider or adapter, or need to audit what a runtime did on your behalf.

The processing flow
  1. Intent
  2. Capability request
  3. Semantic validation
  4. Authority
  5. Policy
  6. Provider resolution
  7. CredentialRef / BYOK
  8. Binding
  9. Execution
  10. Evidence
  11. Execution receipt
What's inside

Everything a third party needs to implement it.

A conforming implementation needs nothing but the specification, the schemas and the registry.

  • spec/0.1/

    The normative specification. Start with protocol.md — roles, the frozen primitive set, the processing flow — then semantics.md, the semantic constitution.

  • schemas/0.1/

    JSON Schemas (Draft 2020-12) for every exchanged document: requests, provider manifests, evidence, receipts, errors, events.

  • registry/

    The canonical vocabulary: 13 domains, canonical verbs, 36 capabilities, 7 profiles (email, chat, sms…) and 10 traits (attachments, idempotency, streaming…).

  • bindings/

    How the protocol travels: HTTP (http/0.1), MCP (mcp/0.1) and CloudEvents (events/0.1). A binding never changes what a document means.

  • conformance/

    A language-neutral suite: document cases, the execution state machine, provider resolution and the full pipeline, with scripted fixtures.

  • examples/

    Valid example documents for every primitive, from a capability request to an integrity-protected receipt.

  • recipes/

    Compositions of existing capabilities, such as employee.onboard and support.answer. Recipes are never primitives.

  • extensions/

    Registered experimental, community and vendor namespaces for what the core cannot express yet.

  • rfcs/

    Proposals that change the protocol, starting with 0001-runtime-protocol-v0.1.md.

  • tooling/

    Deterministic validators — schemas, registry, semantic lint, compatibility, docs. No network access and no language models.

How to use it

5 steps, from zero to running.

Commands and code come from the repository's own README and examples. Replace <commit> with the commit you pin.

  1. 01

    Read the specification

    Start with spec/0.1/protocol.md for roles, primitives and the processing flow, then semantics.md: the twelve principles every capability, profile, trait, binding and extension must respect.

  2. 02

    Express an intent

    A CapabilityRequest names a capability, an optional profile and traits, the actor, the input and the evidence it needs. It never names a provider, a transport or a key — only who owns the credential.

    examples/capability-request/communication-send-email.yaml
    protocol: runtime/0.1
request_id: req_01
capability: { id: communication.send, version: "^0.1" }
profile: email
traits: { required: [delivery_receipt] }
actor:
  ref: identity://agent/support-agent
  type: agent
  on_behalf_of: identity://user/42
authority: { ref: authority://company/support-manager }
input:
  recipients: [identity://customer/981]
  subject: Account update
  content: Your account has been updated.
constraints:
  timeout_ms: 30000
  max_cost: { amount: 0.05, currency: USD }
evidence: { require: [execution, delivery] }
credential: { owner: organization }
  3. 03

    Expect a receipt, not a boolean

    Every execution ends in a canonical receipt: who asked, under which authority and policy, which provider ran, with which evidence and at what cost. Its integrity is a SHA-256 digest over RFC 8785 canonical JSON.

    examples/execution-receipt/completed.yaml (excerpt)
    receipt:
  capability: { id: communication.send, version: 0.1.0 }
  provider: { id: example-provider, version: 1.0.0 }
  authority: { decision: allow, ref: authority://company/support-manager }
  policy: { decision: allow, refs: [policy://company/default] }
  credential_owner: organization
  status: completed
  evidence: [evidence://ev_01, evidence://ev_02]
integrity:
  canonicalization: RFC8785
  digest: sha256:e729721c…
  4. 04

    Validate documents locally

    The tooling checks schemas, the registry, examples, bindings, the semantic lint (SL001–SL020) and compatibility against main. Every result is reproducible from the repository alone.

    terminal
    git clone https://github.com/Company-Runtime/runtime-protocol
cd runtime-protocol
pnpm install
pnpm run ci                    # the full pipeline, as in CI
pnpm run validate:examples     # or one check at a time
pnpm run lint:semantic
  5. 05

    Propose vocabulary

    Open a capability proposal and answer its ten questions — why no existing capability, profile, trait or recipe serves, and which evidence proves completion. New experimental.* entries need no RFC; promotion to candidate needs an accepted RFC and two independent implementations passing conformance. Merges are always human.

Semantic constitution

Twelve principles keep the vocabulary small.

Vocabularies decay when every integration adds a word. Deterministic lint rules enforce these; a failure blocks the change.

  • 01

    Intent over implementation

    A capability names what the caller wants to happen, never how or where.

  • 02

    Semantics over endpoints

    A vendor endpoint does not become a capability without an observable difference for the caller.

  • 03

    Composition over proliferation

    What a sequence of existing capabilities can do is a recipe, not a new capability.

  • 04

    Profiles over specialization

    communication.send with profile email, never communication.send-email.

  • 05

    Traits over variants

    Attachments, streaming, threading and delivery receipts are optional traits, not new capabilities.

  • 06

    Evidence over assertion

    An execution is completed only when the required evidence exists; success: true proves nothing.

  • 07

    Authority before execution

    Deny by default, evaluated before any provider is invoked. Providers never widen it.

  • 08

    Policy outside capability

    A capability declares a default risk; only a policy decision can require approval.

  • 09

    Transport independence

    HTTP, MCP and event buses carry the protocol; they never define it.

  • 10

    Vendor neutrality

    No vendor or product name in the core. Vendor behaviour belongs to adapters or vendor.*.

  • 11

    Extensions before standardization

    New semantics start in an extension namespace or as experimental, and earn promotion through real use.

  • 12

    Stability over growth

    The core targets 30–50 capabilities. Silent synonyms are rejected.

Good to know
  • Every definition starts experimental: Extension → Experimental → RFC → Collision analysis → Independent implementations → Real usage → Semantic review → Candidate → Stable.
  • Language models may suggest collisions or summarize discussions; they never approve, merge, promote or decide conformance.
  • Out of scope for v0.1: marketplaces, billing, administrative UIs, a complete policy language, workflow engines and AI-driven provider ranking.
Next guideRuntime SDKReference implementationAll repositories