Implement RFC 001: RunInvocation companion schema and MAG tool_calls

[brettin]

Summary

Implements the normative contract changes proposed in RFC 001 (PR #2) for run invocation I/O and MAG tool_calls.

• Adds optional companion schema RunInvocation (run-invocation.schema.json) capturing literal inputs, parameters, and outputs.tool_calls as [{ id, name, input }] behind a spine ExecutionContext hash — without widening the mandatory spine.
• Adds example fixture, registers the schema in core-v3-companion, and wires validator coverage.
• Documents OpenAI/Anthropic interop and MAG normalization in run-invocation-interop.md.

Gap IDs: xrun-execution-context-io, xrun-outputs-tool-calls

Test plan

• make validate-v3-contracts passes
• Review run-invocation.schema.json against platform ExecutionContextSubmit, MagToolCall, and RunOutputs
• Confirm companion profile registration and fixture mapping are correct
• Review interop doc for OpenAI/Anthropic normalization rules

Made with Cursor

[Oaklight]

The implementation direction looks good: RunInvocation as an optional companion artifact is a better fit than widening the mandatory spine. I do see a contract-strength issue around contextHash, though.

The new doc says RunInvocation.contextHash may equal ExecutionContext.configHash, but the core schema requires ExecutionContext.configHash to be 64 hex chars. ARIAPlatform v0 currently computes context_hash as a truncated 32-hex SHA256 digest in aria_server/api/routes/runs.py:

context_hash = hashlib.sha256(context_data.encode()).hexdigest()[:32]

Meanwhile the new schema only requires minLength: 1, so it neither enforces the core hash shape nor documents the platform-v0 32-hex digest as a profile-specific/opaque value.

I think this needs one explicit choice:

• make contextHash an opaque platform digest and document that it is not necessarily ExecutionContext.configHash; or
• align it with the core 64-hex configHash; or
• allow both with a clear rule for when each appears.

Right now the text suggests stronger linkage than the schema and platform implementation actually provide.

[Oaklight]

The outputs.tool_calls schema is looser than the interop doc says it is.

The doc defines the normative MAG shape as:

[{ "id": "...", "name": "...", "input": { ... } }]

and says input is the decoded arguments object, with id preserved for later tool_call_id correlation. But the schema only requires name; id and input are optional, and input has no type constraint.

That means all of these validate even though they do not satisfy the documented canonical shape:

{ "name": "run_simulation" }
{ "name": "run_simulation", "input": "not decoded object" }

I would make id, name, and input required, and set input to type: "object" unless there is a specific provider case where decoded tool arguments can be non-object. If non-object inputs are intentionally allowed, the interop doc should say that explicitly.

[Oaklight]

The lifecycle semantics of RunInvocation need one more sentence, because this matters for ReAct loops and for RFC002.

As written, outputs.tool_calls captures model-requested tool invocations. ARIAPlatform's client-side agent then executes those tools locally and appends role: "tool" messages into the next turn. The new schema supports inputs.messages[].role = "tool" and tool_call_id, but it does not say whether a RunInvocation is:

• a single MAG invoke record, where tool results appear as inputs to a later invocation; or
• a whole multi-turn ReAct transcript; or
• also expected to include executed-tool results.

I think the cleanest rule is: RunInvocation records MAG/model turns; executed-tool telemetry/results belong either in subsequent inputs.messages or in tool.call events covered by RFC002. Stating that here would keep the RFC001 implementation from absorbing RFC002's event semantics by accident.

[Oaklight]

Because this companion artifact can persist literal prompts, parameters, messages, and decoded tool inputs, it should probably include some redaction / retention guidance.

inputs, parameters, and outputs.tool_calls[].input can contain secrets, data identifiers, local paths, proprietary prompts, PHI/PII, or facility-specific operational details. I do not think that means the schema should avoid literal payloads entirely; the companion artifact is useful exactly because it can preserve them. But the doc should say whether deployments may/should store redacted payloads, references, or digests instead of raw values.

Possible lightweight additions:

• document that raw RunInvocation records are sensitive audit artifacts;
• allow or recommend inputRef / inputDigest / redacted forms for tool inputs when raw parameters cannot be stored;
• mention that retention/access policy is deployment-owned.

This will matter once RunInvocation is used together with event provenance and budget/accounting logs.

[Oaklight]

A few smaller consistency nits:

• run-invocation-interop.md says maxToolCalls counts model-returned tool_calls "batches" per MAG invoke, then defines it as len(outputs.tool_calls). That is an item count, not a batch count. I would say "tool call items" to avoid suggesting one model response counts as 1 regardless of how many calls it contains.
• RunInvocation currently only requires contextHash, so { "contextHash": "x" } validates. If the schema is meant to describe an invocation record, consider requiring at least inputs for request-side records and/or outputs for completed records, or add an explicit phase/status field.
• core-v3-companion.json now includes run-invocation.schema.json, but the profile description still only names CampaignPlan / DataMovementIntent / EvalPublication. It should mention RunInvocation too, and consider whether the profile patch version should move with the added required companion schema.

[Oaklight]

Follow-up after #9 was merged: this looks good to me now.

The implementation now makes the RunInvocation companion contract much tighter while preserving the original design choice not to widen the mandatory spine:

• contextHash is now explicitly constrained to documented 32/64-hex digest forms instead of accepting any string.
• outputs.tool_calls now matches the documented MAG shape more closely by requiring id, name, and decoded object input.
• The interop note now draws the right boundary: RunInvocation records MAG/model turns, while executed-tool telemetry stays in the event stream.
• The docs now call out sensitivity/retention concerns for literal prompts, parameters, messages, and tool inputs.

I think this is a good contract-level landing point for RFC001. The remaining questions around executed tool events should be handled in RFC002 rather than folded back into this companion schema.

[brettin]

reviewed, updated, implemented, and tested

[Oaklight]

Approved.

I rechecked the current PR head after #9 was merged. The RunInvocation companion contract now addresses the issues I raised earlier:

• contextHash is constrained to documented 32/64-hex digest forms instead of accepting arbitrary strings.
• outputs.tool_calls[] now matches the documented MAG shape with required id, name, and decoded object input.
• The interop note clearly separates MAG/model-turn records from executed-tool telemetry, which should remain in the event stream / RFC002 scope.
• The docs now call out sensitivity and retention concerns for literal prompts, parameters, messages, and decoded tool inputs.

From my side, this is a good contract-level landing point for RFC001. Any remaining executed-tool event questions should be handled in RFC002 rather than folded back into this companion schema.