Workflow

The skill and workflow authority system extends the Chio capability model with multi-step tool compositions, I/O contracts between steps, budget envelopes, and signed workflow receipts. Implementations MUST follow the grant, manifest, receipt, and authority lifecycle described here.

Source

This page normatively reflects spec/WORKFLOW.md in the chio repository. Status: Normative. Version 1.0.

Purpose

A skill is an ordered sequence of tool invocations that composes multiple tools into a single authorized unit of work. The workflow system provides four primitives:

• SkillGrant. Extends the capability model for ordered tool sequences with budget envelopes and execution limits.
• SkillManifest. Declares tool dependencies, I/O contracts between steps, and budget requirements.
• WorkflowReceipt. Captures the complete execution trace as a single signed artifact.
• WorkflowAuthority. Validates each step against declared scope, ordering, budget, and time constraints.

SkillGrant

A SkillGrant authorizes an agent to execute a named skill. Unlike individual tool grants, a skill grant binds an entire tool sequence under a single authorization with a shared budget envelope.

Schema

Step Authorization

A step is authorized if "server_id:tool_name" appears in the authorized_steps list. Invocations of tools not in the list MUST be rejected.

Ordering Modes

When strict_ordering is true (the default), each step MUST execute at index equal to the number of previously completed steps. A step submitted out of order MUST be rejected with StepOutOfOrder.

When strict_ordering is false (relaxed mode), steps may execute in any order. All steps MUST still be in the authorized_steps list.

SkillManifest

A SkillManifest is authored by the skill developer and declares the full execution plan for a skill.

Schema

SkillStep

IoContract

The IoContract type describes data flow between steps.

I/O Contract Validation

Implementations MUST validate that I/O contracts form a consistent data flow:

• For each step after the first, every field in input_contract.required_fields MUST appear in the output_contract.produced_fields of some preceding step.
• The first step's input requirements come from the caller, not from preceding steps, and are therefore not validated against the manifest.
• Violations MUST be reported with the step index, tool name, and missing field name.

Tool Dependencies

The manifest's tool dependencies are the list of "server_id:tool_name" strings derived from each step. The workflow authority uses this list to verify the grant covers all required tools.

WorkflowReceipt

A WorkflowReceipt captures the complete execution of a skill as a single signed artifact.

WorkflowReceiptBody

WorkflowReceipt (Signed)

The signed WorkflowReceipt inlines all fields from WorkflowReceiptBody and adds a signature field (Ed25519 signature over canonical JSON of the body). The signature MUST be computed over canonical_json_bytes(body) using RFC 8785 canonical JSON.

WorkflowOutcome

StepRecord

StepOutcome

Signature Verification

Verification reconstructs the WorkflowReceiptBody from the receipt fields and verifies the Ed25519 signature over its canonical JSON serialization using the embedded kernel_key. A tampered receipt (any field modified after signing) MUST fail verification.

WorkflowAuthority Lifecycle

The WorkflowAuthority manages the lifecycle of skill executions. It holds the kernel signing key and tracks execution counts for limit enforcement.

begin

begin(manifest, grant, agent_id, capability_id, session_id)
  -> Result<WorkflowExecution, WorkflowError>

Preconditions, all of which MUST be checked:

• grant.skill_id == manifest.skill_id and grant.skill_version == manifest.version. Fail: UnauthorizedSkill.
• If grant.max_executions is set, execution_count < limit. Fail: ExecutionLimitReached.
• Every step in the manifest MUST be authorized by the grant. For each step, grant.authorized_steps MUST contain "step.server_id:step.tool_name". Fail: UnauthorizedStep.

On success, returns a WorkflowExecution with:

• Budget limit from grant.budget_envelope or manifest.budget_envelope (grant takes precedence).
• Time limit from grant.max_duration_secs or manifest.max_duration_secs (grant takes precedence).
• active set to true.
• Empty step_records and zero budget_spent.

validate_step

validate_step(execution, step, grant) -> Result<(), WorkflowError>

Preconditions, checked in order:

• execution.active MUST be true. Fail: InvalidState.
• The step MUST be authorized by the grant. Fail: UnauthorizedStep.
• If strict ordering is enabled, step.index == execution.completed_steps(). Fail: StepOutOfOrder.
• If a time limit is set, elapsed time MUST be less than the limit. Fail: TimeLimitExceeded.

record_step

record_step(execution, step, outcome, duration_ms, cost, tool_receipt_id, output_hash)
  -> Result<(), WorkflowError>

Behavior:

• If execution.active is false, return InvalidState.
• Add cost.units (if present) to execution.budget_spent using saturating addition.
• Append a StepRecord to execution.step_records. The record is always appended, even if the budget is about to be exceeded, so the audit trail includes the offending step.
• After recording, check the budget envelope. If budget_spent > budget_limit.units, set active to false and return BudgetExceeded.
• If outcome is Failed or Denied, set active to false.

finalize

finalize(execution) -> Result<WorkflowReceipt, WorkflowError>

Behavior:

• Set execution.active to false.
• Determine the WorkflowOutcome by inspecting step records and budget. If any step has outcome == Failed or outcome == Denied, the outcome is StepFailed. If budget_spent > budget_limit.units, the outcome is BudgetExceeded. Otherwise the outcome is Completed.
• Construct WorkflowReceiptBody with all execution data.
• Sign the body: keypair.sign_canonical(body).
• Increment the authority's execution_count.
• Return the signed WorkflowReceipt.

WorkflowError

Example

A two-step search-and-summarize skill:

schema: chio.skill-manifest.v1
skill_id: search-and-summarize
version: "1.0.0"
name: Search and Summarize
steps:
  - index: 0
    server_id: search-srv
    tool_name: search
    label: Search
    output_contract:
      produced_fields: [results]
  - index: 1
    server_id: llm-srv
    tool_name: summarize
    label: Summarize
    input_contract:
      required_fields: [results]
    output_contract:
      produced_fields: [summary]
budget_envelope:
  units: 1000
  currency: USD

schema: chio.skill-grant.v1
skill_id: search-and-summarize
skill_version: "1.0.0"
authorized_steps:
  - search-srv:search
  - llm-srv:summarize
budget_envelope:
  units: 1000
  currency: USD
max_executions: 10
strict_ordering: true

Execution flow:

• authority.begin(manifest, grant, agent, capability, session). Validates grant matches manifest, creates execution.
• authority.validate_step(execution, step_0, grant). Checks authorization, ordering, time.
• Invoke search-srv:search, collect result.
• authority.record_step(execution, step_0, Success, 100ms, $0.50). Records cost, checks budget.
• authority.validate_step(execution, step_1, grant).
• Invoke llm-srv:summarize, collect result.
• authority.record_step(execution, step_1, Success, 200ms, $1.00).
• authority.finalize(execution). Signs receipt, increments count.

Related

• Guard pipelines
• The Guard trait
• Receipt Format
• Metering Spec