88 lines
3.6 KiB
Markdown
88 lines
3.6 KiB
Markdown
# 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
|
||
|
||
```ts
|
||
interface CoordinationScope {
|
||
readonly actorId: string;
|
||
readonly tenantId: string;
|
||
readonly correlationId: string;
|
||
readonly requesterAgentId: string; // trusted gateway/configuration data
|
||
}
|
||
|
||
interface HandoffRequest {
|
||
readonly idempotencyKey: string;
|
||
readonly summary: string;
|
||
readonly context?: string;
|
||
readonly missionId?: string;
|
||
}
|
||
|
||
interface HandoffReceipt {
|
||
readonly handoffId: string;
|
||
readonly targetAgentId: string;
|
||
readonly status: 'accepted' | 'queued';
|
||
readonly correlationId: string;
|
||
}
|
||
|
||
interface Handoff {
|
||
readonly handoffId: string;
|
||
readonly targetAgentId: string;
|
||
readonly request: HandoffRequest;
|
||
readonly scope: CoordinationScope;
|
||
}
|
||
|
||
interface InteractionCoordinationPort {
|
||
handoff(handoff: Handoff): Promise<HandoffReceipt>;
|
||
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 `InMemoryInteractionCoordinationPort` 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 `InteractionCoordinationPort`; no channel client or interaction
|
||
runtime calls a transport directly.
|
||
|
||
## Required tests
|
||
|
||
1. A configured non-default interaction identity can hand off work to a
|
||
configured non-default orchestration identity and receive its result.
|
||
2. The gateway passes only server-derived scope/identity to the adapter.
|
||
3. Self-targeting, target drift, and cross-tenant observe/result all fail closed
|
||
without invoking the adapter.
|
||
4. The exported public contract has no worker-dispatch, assignment, review,
|
||
merge, or cancellation capability.
|
||
5. The native adapter round-trips queued work, activity, and a host-recorded
|
||
terminal result without a live fleet dependency.
|