feat(runtime): unify lifecycle observability across Harnesses

[Yevanchen]

Area

Runtime

Problem

A unified API is only the first layer of runtime portability. Builders need two stronger guarantees:

1. they can change the selected Runtime/Harness for a new execution without rewriting Session/Thread, file, permission, cancellation, or event handling; and
2. when an execution fails, they can reconstruct the failure down to the concrete Agent step instead of falling through to unrelated runtime-specific logs.

Mosoo already exposes normalized Run events, stable toolCallId values, Thread files, permission requests, cancellation, runtime diagnostics, and W3C trace context. The current docs describe these capabilities, but do not make their end-to-end correlation and cross-Harness parity one explicit acceptance boundary. A Harness can therefore satisfy the top-level API while lifecycle semantics or diagnostic depth still drift.

Public events should remain safe and stable, and private runtime diagnostics should remain access-controlled. The missing piece is a shared identity and correlation contract between them, not exposing raw logs through the public API.

Proposal

Treat each Run as one observable boundary across every admitted Harness:

• Every lifecycle event, permission request/decision, file or artifact created or consumed by the Run, cancellation transition, terminal result, and attributable diagnostic record carries the Run identity.
• Agent steps use stable correlation identities and causal ordering. Reuse existing identities such as toolCallId, file IDs, and trace context where they already cover the boundary.
• Given a Run, an authorized Builder can inspect one ordered activity timeline and follow a failure from the public-safe step to the relevant private diagnostic/log context.
• Record the resolved Runtime/Harness/version and frozen execution inputs needed to compare two executions.
• Add one cross-Harness conformance scenario that keeps the task, Environment, resources, and permissions fixed while changing only the Runtime/Harness selection.

This should extend the existing event and observability substrate rather than introduce a second tracing system.

Acceptance criteria

• A caller can run the same supported task on at least two admitted Harnesses and change only the Runtime/Harness selector; Session/Thread, file, permission, cancellation, and event handling remain unchanged.
• Every Run exposes its requested and resolved Runtime/Harness/version and frozen Environment/resource identity.
• Tool activity, permission requests and decisions, file/artifact records, cancellation, failures, and terminal state can be correlated to the Run and, when applicable, a stable Agent step.
• Cancellation shows both the request and the observed terminal outcome; uncertain external side effects remain explicit rather than being reported as safely rolled back.
• An authorized Builder can reconstruct an ordered causal timeline for a failed Run and navigate from a normalized activity to the relevant redacted diagnostic context.
• Public events do not expose raw provider credentials, secrets, private runtime payloads, or unrestricted logs.
• A conformance test proves lifecycle and observability parity across at least two Harnesses, including success, permission, file output, cancellation, and failure paths.
• A Harness that cannot meet a required capability fails readiness before execution with an actionable gap.

Non-goals

• Deterministic re-execution or replaying side effects.
• Switching Harnesses mid-Run or resuming one Harness's native state in another.
• Turning operational visibility into a compliance audit log.
• Publishing raw runtime logs through the public API.
• Building a new general-purpose tracing platform.

Related

• feat(runtime): allow explicit runtime and model selection for Cattle threads #530 — explicit Runtime/model selection
• feat(platform): pivot Mosoo to an API-first managed Agent runtime #546 — environment-first Harness Run API
• feat(driver): define community-contributed Harness packages #566 — Harness package and Driver conformance
• fix(runtime): persist uncertainty for external tool effects #412 — uncertainty for external tool effects

Alternatives considered

• Normalize only the top-level API: simpler, but leaves lifecycle drift and runtime-specific incident diagnosis to every integrator.
• Keep one observability view per Runtime: preserves native detail, but makes painless Runtime switching and comparable operations impossible.

Compatibility and migration

This is additive. Existing public event shapes remain compatible; privileged diagnostic details stay behind existing owner authorization and redaction boundaries.

Contribution

I can provide product feedback.

Checklist

• I searched existing issues before opening this request.
• I described the problem before the proposed solution.
• I kept this request focused on one improvement.

[FradSer]

A complementary idea for the proposed Run timeline: make it possible for a trusted Tool or Skill to contribute scoped context for a subsequent model step, without giving arbitrary tool output the ability to write system instructions.

The underlying distinction matters:

• Model weights / provider behavior are outside Mosoo's runtime learning loop.
• Agent policy (prompt, Skills, Environment, approval and network policy) is versioned, control-plane-owned configuration.
• Tool observations are concrete, time-bound facts or effects; they need provenance, scope, freshness, and an explicit projection rule before they influence another model call.

Rather than an injectPrompt() escape hatch, a Harness could expose a controlled ContextContribution / ContextProjection contract:

Tool or Skill result
  -> fact/effect record with provenance
  -> Host policy validates source, capability, scope, size, and expiry
  -> timeline records accept/reject/redact/project decision
  -> approved projection is included in the next model step

Suggested contribution categories:

• fact: a structured observation backed by a tool result or artifact;
• guidance: bounded, non-authoritative task guidance from a reviewed Skill;
• warning: a risk or freshness caveat;
• constraint: reserved for the Mosoo control plane only (for example, a resolved approval policy, network boundary, an unknown external effect, or a blocked continuation).

A useful invariant is that an MCP server, web page, or ordinary tool output can contribute evidence but cannot promote itself to a higher-priority instruction slot. Only reviewed Skills can propose guidance, and only the control plane can emit enforceable constraints. This prevents prompt-injection in external content from silently becoming runtime policy.

For #574's ordered causal timeline, each projection should make these fields visible to an authorized Builder:

• runId, model-step identity, and originating toolCallId / Skill version;
• evidence or artifact reference, rather than an untraceable text blob;
• contribution category, requested and admitted scope (next-step, run, or explicitly bounded thread), expiry, and rendered context slot;
• policy decision: accepted, rejected, redacted, truncated, or awaiting user acknowledgement;
• the subsequent tool calls / output causally associated with that projection.

This is not a request for automatic long-term memory. The safe promotion path is deliberately separate:

tool observation -> scoped context projection -> reviewed reusable resource ->
human- or eval-approved Agent/Skill revision

That boundary complements the issue's existing requirement to freeze execution inputs and correlate normalized public events with redacted diagnostics. It would make "what did the model know, and why did it act on it?" reconstructible across Harnesses while preserving Mosoo's existing distinction between configuration, session history, files/artifacts, sandbox state, and external effects.