RFC 001: Run invocation I/O and MAG tool_calls

[brettin]

Summary

Adds contracts/rfcs/ with an index and RFC 001, proposing how core-v3 should represent run invocation inputs/outputs (including MAG tool_calls) beyond execution-context hashes alone.

Gap IDs

• xrun-execution-context-io
• xrun-outputs-tool-calls

Tracking

Part of #1 (platform v0 alignment RFC series). Merge before RFC 002.

Test plan

• Review RFC 001 against execution-context.schema.json and run.schema.json
• No contract validator changes until normative schema/OpenAPI updates land in follow-up PRs

Made with Cursor

[brettin]

Review: RFC 001 — Run invocation I/O and MAG tool_calls

Overall this is a well-motivated RFC that correctly identifies two real gaps between the core-v3 spec and the ARIAPlatform_v0 wire format. The scaffolding (RFC index, merge-order table, cross-link from contracts/README.md) is clean and makes the process discoverable. A few observations and suggestions below.

---

✅ What works well

1. Gap identification is accurate. The spec's execution-context.schema.json is strictly reproducibility-oriented (configHash, environmentHash, seedList, dataVersion) with additionalProperties: false. The platform's ExecutionContext (in both server runs.py and client common.py) carries inputs, parameters, environment, artifacts, and datasets — none of which the spec accommodates. This RFC correctly calls that out.

2. tool_calls shape is documented. The MAG service (mag.py) normalizes all provider responses to [{ id, name, input }] via normalize_openai_tool_calls(). The RFC captures that canonical shape.

3. Dual-path proposal (companion schema vs. x-gmp extension block) is pragmatic — it acknowledges the spine-vs-companion tension without prematurely committing.

4. The RFC index and merge-order table in rfcs/README.md give good visibility into the full alignment series.

---

🔍 Suggestions

1. Pick a recommended disposition. The RFC presents companion schema vs. x-gmp but doesn't stake a recommendation. Given the GAP_DISPOSITION_REGISTER.md pattern of routing invocation-level concerns to "companion" disposition, a companion schema (run-invocation.schema.json) seems more aligned with the spine philosophy. Consider adding a "Recommended approach" subsection with a rationale.

2. The gap is wider than described. Cross-referencing the platform code reveals additional wire-format fields not mentioned in the RFC:

   • Server-side RunResponse (in aria-server) includes inputs, parameters, outputs, artifacts, and error — all absent from the spec's run.schema.json.
   • Client-side ExecutionContext (in aria-client) has context_hash, inputs, parameters, environment, artifacts, datasets — substantially richer than the spec's four required fields.
   • The RFC focuses on inputs/parameters and outputs.tool_calls. Should artifacts, datasets, environment, and error be in-scope here, or are they intentionally deferred? A one-line "Out of scope" note would clarify.

3. Flesh out the interop section. The proposal says "Document OpenAI/Anthropic interop and MAG normalization" but doesn't elaborate. The MAG service already handles this: OpenAI tool calls use arguments (JSON string), Anthropic uses input (object), MAG normalizes to {id, name, input}. Even a brief mapping table would strengthen the RFC:

   Provider	Field	Type	MAG normalized
   OpenAI	arguments	JSON string	input (parsed object)
   Anthropic	input	object	input (pass-through)

4. Add a concrete schema sketch. A draft JSON Schema fragment — even a few lines showing the inputs, parameters, and outputs.tool_calls shape — would make the RFC much easier to evaluate and would give downstream RFC authors (002–006) something concrete to reference.

5. Status enum heads-up. While reviewing platform code for context, I noticed the spec's Run status enum is ["queued", "running", "succeeded", "failed", "cancelled"] but the platform uses ["pending", "planning", "running", "paused", "completed", "failed", "cancelled"]. This is presumably RFC 003's territory, but worth a cross-reference note in RFC 001 since the Run schema is touched by both.

6. Broken reference? The RFC index links to spec-implementation-gap-register.json in ARIAPlatform_v0's reference/ directory, but that file doesn't appear to exist at that path currently. Worth verifying the link is still valid.

---

Summary

Strong start — the gap analysis is correct and the RFC addresses a real alignment need. Main suggestions: (a) add an "out of scope" note for the fields not covered, (b) flesh out the interop/normalization section, (c) include a draft schema sketch, and (d) recommend a disposition (companion schema vs. x-gmp).

Happy to discuss any of these points.

[brettin]

Recommended approach

Disposition: companion_spec — add companion/schemas/run-invocation.schema.json and link it from spine Run / submitRun via invocationRef and invocationDigest (same pattern as planRef / planDigest for CampaignPlan).

Rationale: Invocation I/O (inputs, parameters, outputs.tool_calls) is portable interchange data for agent/LLM runs, not spine infrastructure. Keeping execution-context.schema.json hash-only preserves reproducibility semantics; optional adoption via core-v3-companion avoids widening mandatory GA for non-agent deployments.

Not chosen: x-gmp inline fields are a possible short-term bridge for platform v0, but execution-context.schema.json and run.schema.json use additionalProperties: false, so experimental extensions still require a schema change and do not graduate cleanly to interop. A direct spine patch would make LLM payloads mandatory core surface — out of step with the spine charter.

[brettin]

Out of scope

Should artifacts, datasets, environment, and error be in-scope here, or are they intentionally deferred?

They should be intentionally deferred from RFC 001. That matches the PR’s gap IDs (xrun-execution-context-io, xrun-outputs-tool-calls) and keeps the RFC focused on one alignment problem: what you send to invoke an LLM run and what MAG returns as model-requested tool calls.

[brettin]

RFC 001 scope: in-scope vs deferred

RFC 001 should own "invoke the model" (prompt/messages, tools, model params → tool_calls). The following table clarifies what belongs here vs what is intentionally deferred (per gap IDs xrun-execution-context-io and xrun-outputs-tool-calls).

Field	In RFC 001?	Why
inputs / parameters	In scope	Core of the execution-context I/O gap; MAG submit payload.
outputs.tool_calls	In scope	Core of the outputs gap; canonical [{ id, name, input }].
artifacts	Defer	Spine already models artifacts on Capability (artifact.schema.json), not on Run submit/response. Platform run-level artifacts are execution results / provenance, not invocation interchange. Belongs in a later run-outputs or events/provenance RFC (or capability_profile read models per GAP-012).
datasets	Defer	Spine has dataset-ref.schema.json under artifacts. Platform inline datasets on submit mixes data staging/access with LLM invocation. That tracks data-plane / companion concerns (see GAP-004), not run-invocation.
environment	Defer	Spec executionContext uses environmentHash (reproducibility), not a rich env blob. Platform environment is runtime/config context — a different layer than messages, tools, and model params. Can be added to run-invocation later as an optional block without blocking RFC 001.
error	Defer	Spine Run already has failureClass (F0–F8); HTTP errors use StructuredError. Platform's embedded error on RunResponse is run lifecycle reporting, not MAG invocation I/O. Fits a small spine patch or RFC adjacent to 003 (status vocabulary), not 001.

Optional later: if platform environment is truly part of every MAG submit, a follow-up amendment to run-invocation.schema.json can add it without reopening the disposition debate.

[Oaklight]

I think RFC001 identifies the right gap and the companion-schema direction is the right split: literal invocation I/O should not widen the core spine Run / ExecutionContext contract.

One thing I would tighten before treating the RFC as accepted: it should explicitly define the boundary between three records that are easy to conflate:

• RunInvocation: one MAG/model invocation record, including model-requested outputs.tool_calls[].input.
• tool.call events: executed-tool telemetry, not the model request itself.
• budget maxToolCalls: the count of model-returned tool call items, not necessarily the count of locally executed tools.

That distinction is mostly implied by RFC001 + the implementation PR, but spelling it out in RFC001 would make RFC002 much cleaner and avoid another round of ambiguity around where arguments/results belong.

[Oaklight]

Approved.

RFC001 correctly identifies the run invocation I/O gap, and the companion-schema disposition has now been implemented concretely in #8 as RunInvocation.

The remaining details that were open in the RFC discussion are addressed by the implementation PR:

• literal invocation payloads stay outside the mandatory spine;
• outputs.tool_calls[] is defined as { id, name, input };
• MAG/model-turn records are separated from executed-tool telemetry, leaving the latter for RFC002;
• sensitivity/retention guidance is included in the companion interop note.

I think this PR is useful to merge as the RFC record before #8, since #8 links back to contracts/rfcs/001-run-invocation-and-tool-use.md.