Commit message

[ajit-zer07]

Save as the GitHub PR body:

Summary

• Observer-only control-plane. Implements direct-agent-auth plan tasks CP-1..CP-13: POST /runs accepts a scenario-agnostic RunDescriptor, returns {runId, sessionId}; the control-plane polls GetSession until the initiator agent opens it, then subscribes to a read-only StreamSession. POST /runs/:id/{messages,signal,context} return 410 Gone. Agents authenticate to the runtime directly via macp-sdk-python / macp-sdk-typescript. RFC-MACP-0004 §4
  conformant.
• Quality cleanup. Implements plans/quality-cleanup.md (Phases 0–3): dead code purge, hardcoded sleeps → conditional waitFor() polling, instrumentation assertions
  tightened, conventions documented + enforced by grep, gRPC helpers extracted from the runtime provider.
• Two new invariant tests keep the boundaries from regressing: observer-invariant.spec.ts (no provider.send( / openSession( / chooseInitiator( / retryKickoff(
  in src/) and projection-coverage.spec.ts (every canonical event type has a reducer).

Behavioural changes (call out for reviewers)

Endpoint	Before	After
POST /runs	Accepted ExecutionRequest with kickoff[], participants[].role, policyHints, commitments[], initiatorParticipantId	Accepts RunDescriptor only
(forbidNonWhitelisted: true); returns sessionId
POST /runs/:id/messages	200 — control-plane forged envelope via provider.send	410 Gone (ENDPOINT_REMOVED)
POST /runs/:id/signal	200 — same	410 Gone
POST /runs/:id/context	200 — same	410 Gone
POST /runs/:id/cancel	Always called runtime.CancelSession with control-plane's identity	Option A (default): proxies to metadata.cancelCallback.url. Option B:
calls runtime.CancelSession only when metadata.cancellationDelegated === true

Examples-service and the SDKs landed their direct-agent-auth slices before this PR; they already produce RunDescriptor shapes against the new contract — see
ui-console/plans/direct-agent-auth.md.

Schema changes

• runs.runtime_session_id is now populated at INSERT (was set later via markBindingSession). GET /runs/:id returns the sessionId immediately.
• runtime_sessions.initiator_participant_id is populated from the runtime's GetSession snapshot (was forged by the deleted chooseInitiator). Still used by recovery.
• No new migrations.

Removed (deletion notice — coordinate with downstream consumers)

• RUNTIME_AGENT_TOKENS_JSON env var.
• KICKOFF_MAX_RETRIES env var.
• MockRuntimeProvider class (use ScriptedMockRuntimeProvider for tests).
• test-agents/ Python harness + scripts/run-e2e.sh.
• DTOs: send-run-message.dto.ts, send-signal.dto.ts, update-context.dto.ts.
• Integration specs: decision-mode, proposal-mode, task-mode, quorum-mode, handoff-mode, runs-messaging (replaced by consolidated
  observer-mode.integration.spec.ts).
• ExecutionRequest type alias (use RunDescriptor).
• encodeSessionContext / encodePayloadEnvelope / encodeMessage on ProtoRegistryService and their types (PayloadEnvelopeInput, ProtoPayload, PayloadEncoding).
• TestClient.sendMessage / sendSignal / updateContext helpers + ts-agent.ts.

New env vars

Var	Default	Purpose
SESSION_POLL_BASE_MS	100	Initial GetSession poll interval (observer mode)
SESSION_POLL_MAX_MS	1000	Capped backoff
SESSION_POLL_TIMEOUT_MS	60000	Give up waiting for initiator
CANCEL_CALLBACK_TIMEOUT_MS	5000	UI cancel → initiator agent (Option A)
THROTTLE_TTL_MS / THROTTLE_LIMIT	60000 / 100	Already used; now go through AppConfigService

Test plan

• npm run lint --max-warnings=0 — clean
• npm run build — clean
• npm test — 577/577 across 44 suites
• npm run test:integration — 59/59 across 14 suites
• Invariant lints (observer-mode, projection-coverage) green
• Convention grep rules (CLAUDE.md §Conventions) all clean
• Manual smoke (reviewer): point a local examples-service at this branch, launch a fraud scenario; verify POST /runs returns {runId, sessionId}, agents emit
  envelopes directly (runtime gRPC logs), control-plane shows zero Send RPCs, projection populates from runtime Proposal / Vote / Commitment events, UI cancel routes
  via the initiator's cancelCallback.
• Production runbook (reviewer): confirm RUNTIME_BEARER_TOKEN is set with a least-privilege identity (can_start_sessions: false); confirm
  RUNTIME_AGENT_TOKENS_JSON removed from Railway env; confirm dev-mode toggles (MACP_ALLOW_DEV_SENDER_HEADER, RUNTIME_USE_DEV_HEADER) are NOT set in prod.

Migration impact

• Examples-service: already uses RunDescriptor (compiler shipped 2026-04-15). Reading the response's sessionId and forwarding the initiator's cancelCallback URL
  into session.metadata.cancelCallback are the only follow-ups needed there.
• UI: POST /runs/:id/{messages,signal,context} callers need to be removed. Display sessionId in run details (already returned by GET /runs/:id).
• Railway / production: drop RUNTIME_AGENT_TOKENS_JSON. Set RUNTIME_BEARER_TOKEN to one least-privilege observer token. The runtime's MACP_AUTH_TOKENS_JSON entry
  for the control-plane must have can_start_sessions: false.

Net diff

80 files changed, 2,056 insertions, 7,605 deletions — net −5,549 LoC.