Tess–Mos Coordination Contract Sketch

Task: TESS-M4-001 · PRD: TESS-MOS-001 / AC-TESS-04

Boundary

Agent identities are deployment data. A configured interaction agent may request Mos-owned work; the configured orchestration agent owns decomposition, worker assignment, reviews, and merge decisions. The interaction agent receives a correlated receipt, read-only activity projection, and terminal result. It has no dispatch, assignment, review, merge, or cancellation operation.

`@mosaicstack/coord` interface

interface CoordinationScope {
  readonly actorId: string;
  readonly tenantId: string;
  readonly correlationId: string;
  readonly requesterAgentId: string; // trusted gateway/configuration data
}

interface MosHandoffRequest {
  readonly idempotencyKey: string;
  readonly summary: string;
  readonly context?: string;
  readonly missionId?: string;
}

interface MosHandoffReceipt {
  readonly handoffId: string;
  readonly targetAgentId: string;
  readonly status: 'accepted' | 'queued';
  readonly correlationId: string;
}

interface MosHandoff {
  readonly handoffId: string;
  readonly targetAgentId: string;
  readonly request: MosHandoffRequest;
  readonly scope: CoordinationScope;
}

interface MosCoordinationPort {
  handoff(handoff: MosHandoff): Promise<MosHandoffReceipt>;
  observe(handoffId: string, scope: CoordinationScope): Promise<CoordinationObservation>;
  result(handoffId: string, scope: CoordinationScope): Promise<CoordinationResult>;
}

The port deliberately omits generic orchestrator verbs. It is tenant- and correlation-scoped; its gateway implementation obtains actorId, tenantId, and the requester agent from trusted authentication/configuration only.

HTTP routes

/api/coord/interaction is the canonical HTTP coordination prefix for handoff, observe, and result. /api/coord/mos remains a backward-compatible alias with the same handlers and DTOs; new integrations use the neutral canonical prefix.

Enforcement point

apps/gateway owns an InteractionCoordinationService (apps/gateway/src/coord/interaction-coordination.service.ts) boundary that compares the trusted configured requester/target identities and rejects all of the following before calling a transport: unconfigured requester, self-delegation, target identity drift, cross-tenant observe/result lookup, and attempts to observe or receive a result for a handoff outside the originating tenant. The service exposes handoff, observe, and result only, and delegates delivery to an injected adapter.

M4 ships a native in-process InMemoryMosCoordinationPort as the concrete, deterministic adapter. It preserves the immutable handoff ID, tenant, requester identity, and correlation ID while demonstrating the handoff → observe → result round trip. It is a queue/port adapter, not a Mos-side consumer.

A future fleet/tmux adapter is a documented M5 deployment seam and must implement the same MosCoordinationPort; no channel client or interaction runtime calls a transport directly.

Required tests

A configured non-default interaction identity can hand off work to a configured non-default orchestration identity and receive its result.
The gateway passes only server-derived scope/identity to the adapter.
Self-targeting, target drift, and cross-tenant observe/result all fail closed without invoking the adapter.
The exported public contract has no worker-dispatch, assignment, review, merge, or cancellation capability.
The native adapter round-trips queued work, activity, and a host-recorded terminal result without a live fleet dependency.

3.6 KiB Raw Blame History Unescape Escape