Skip to content

Contracts and Boundaries

Prompts tell an agent how to reason. Contracts tell the runtime what may execute, what shape crosses a boundary, and what counts as complete. Production systems need both: a prompt can explain good judgment, but it cannot enforce authority, schema validity, durable identity, or completion state.

JarvisCore has several contracts at different boundaries. They are related, but not interchangeable.

Contract map

Boundary Framework surface What it controls
Agent identity role, capabilities, capability_descriptions How peers and planners discover the agent
Capability authority and artifact declaration capability_contracts Which effects and provider systems a capability may request, plus typed artifacts it produces or requires
Task execution context["execution_contract"] Whether work is a direct response, one artifact, or normal agentic execution
Kernel completion DONE plus RESULT Human-facing completion prose and machine-usable result data
Output validation output_schema or an application-owned validator Whether structured output matches the required schema
Agent result status, output, result_summary, telemetry, continuation metadata The stable boundary returned by execute_task()
Durable goal source obligations, revisions, step claims, attempts, interpretations What was requested, attempted, satisfied, blocked, or superseded

Capability contracts

A capability name says what an agent can own. Its contract states the authority available while performing that capability:

from jarviscore import AutoAgent


class RepositoryReviewer(AutoAgent):
    role = "repository_reviewer"
    capabilities = ["code_review"]
    capability_descriptions = {
        "code_review": "Inspect a change and propose evidence-backed findings.",
    }
    capability_contracts = {
        "code_review": {
            "effects": ["read", "propose"],
            "systems": ["github"],
            "produces": "ReviewReport(findings, inspected_revision)",
            "artifact_types": ["ReviewReport"],
            "requires_artifact_types": ["RepositorySnapshot"],
        },
    }

Distributed planning uses this catalog to create executable steps. Peer execution derives capability, effect, and systems from the published step; caller context cannot grant itself that authority. Credentials and provider policy remain separate enforcement boundaries. Optional produces metadata is human-readable. artifact_types and requires_artifact_types are stable type names: the compiler closes direct dependency edges to declared producers and rejects plans with no producer. They do not authorize effects or replace output validation.

When a composed work product must retain an upstream artifact exactly, declare artifact_reference_paths on the AutoAgent subclass and return an artifact_ref at each declared path. JarvisCore resolves the reference from direct dependency outputs before product validation. A copied or reconstructed artifact at a required path fails closed.

class ReliabilityStrategist(AutoAgent):
    artifact_reference_paths = (
        ("findings", "*", "candidate"),
        ("findings", "*", "verification"),
    )

# In RESULT:
{"artifact_ref": {"step_id": "verify", "path": ["reports", 0]}}

References can target an entire direct-dependency output or one nested path. They preserve the validated value exactly; they are not string interpolation or an instruction to the model to copy evidence.

Execution contracts

An execution contract travels in task context and selects the shape of one AutoAgent turn:

{
    "task": "Classify this incident and explain the decision.",
    "context": {
        "execution_contract": {
            "execution_shape": "single_response",
            "max_output_tokens": 4096,
        }
    },
}
Shape Behavior
omitted Normal Kernel OODA execution with tools and completion protocol
single_response One direct LLM completion; skips planning, tools, and code generation
single_artifact One bounded Kernel deliverable; a raw JSON object can satisfy completion

Use output_schema to validate data produced by CoderSubAgent execution. Other roles, or domains with stronger invariants than one schema, should validate in a shared application subclass and return only the validated work product.

Completion and result contracts

Where every provider in the fallback chain supports native tool calls, each sub-agent turn is a function call. The model calls one of the step's tools, or calls done with summary (the complete human answer) and result (the structured value for downstream work, typed from the step's output_schema). Any tool call may carry working_notes. The agent reads a note in the call that carried it while that call is in view, and in its notes once the call has left.

Otherwise, Kernel sub-agents use a provider-neutral text protocol:

THOUGHT: <reasoning>
DONE: <complete human answer>
RESULT: <JSON or structured value for downstream work>

Both forms carry the same answer and result, and only done (or DONE) completes a step. JarvisCore appends the protocol to the execution harness. Most application prompts should specify the semantics and shape of the deliverable, not redefine the parser syntax. A shared application subclass may reinforce RESULT when it validates a domain work product.

The coder path has one additional boundary: generated Python assigns its value to a variable named result. That sandbox convention is not required for single_response, and it should not be confused with the outer task envelope.

AutoAgent.execute_task() returns the outer envelope. Its stable display field is result_summary; structured data stays in output (and the standard Kernel payload alias). Status, errors, token use, cost, dispatches, continuation metadata, and goal metadata remain separate fields.

Application work-product contracts

JarvisCore does not know whether a qualified account, code-review finding, legal memo, or support resolution is valid. The application owns that domain truth. A production harness commonly defines Pydantic models and validates every agent handoff before it reaches memory, another peer, or a user interface.

For example, a code-review contract might require a file path, evidence span, severity, explanation, and actionable remediation. A GTM contract might require verified account evidence and explicitly forbid a ready outreach plan without a verified contact. Those rules belong to the application, not the framework.

This division is deliberate:

  • JarvisCore enforces execution, authority, lifecycle, and durable-state shapes.
  • The application enforces domain evidence and work-product validity.
  • The prompt explains how to reason toward a valid result.

Framework-owned evidence models are the exception to application-owned domain truth. CommandObservation and WorkspaceMutation bind claims to immutable tool receipts. Applications cite tool_receipt_id; JarvisCore replaces all execution or mutation fields with authoritative runtime values and fails closed on missing, foreign, stale, or incompatible receipts. See Execution and Evidence API.

Durable goal contracts

Mesh.execute_goal() adds a durable contract around the whole multi-agent goal:

  1. The source objective and obligation IDs are immutable.
  2. A temporary planning lease publishes a capability-addressed DAG.
  3. Eligible peers claim steps independently and append immutable attempts.
  4. Optional interpretations map evidence to the exact obligation IDs covered by a step.
  5. Reconciliation appends a new revision for unresolved obligations without erasing prior attempts or repeating satisfied effects.
  6. Execution, obligation, and response statuses are reported independently.

An interpretation is useful when successful execution does not prove the source requirement was satisfied. Its satisfied_requirements and unmet_requirements must use the stable IDs from the step's covers list. The framework reduces those IDs into current obligation truth; the agent remains responsible for the domain judgment.

Choose the right layer

Use a prompt for reasoning method, evidence standards, ownership, tone, and the meaning of the deliverable. Use a contract for permissions, schemas, terminal states, durable identity, and machine-readable handoffs. If downstream code must rely on it, do not leave it only in prose.

Continue with: