Multi-Agent Collaboration Platform¶
- Product: Multi-Agent Collaboration Platform
- Family: Product and Engineering Toolkit
Objective¶
Enable multiple humans, each operating their own AI agents, to collaborate on shared investigations — pooling findings, sharing artifacts, building a collective knowledge graph, and producing a shared record that persists for future learning.
Context¶
Today, when multiple people use agentic tools (Kiro, Claude Code, etc.) on the same problem, each agent operates in isolation. Findings stay trapped in individual sessions. There's no shared memory, no coordination, no way for Agent A to know what Agent B already discovered. Humans resort to copy-pasting between Slack and agent sessions.
This project builds an AWS-native MCP server that gives all participating agents a shared collaboration surface — semantic memory, structured timeline, entity relationships, and artifact references — accessible through standard MCP tool calls.
Research Summary¶
The following tools were evaluated during design:
| Tool | What it does | Why not sufficient alone |
|---|---|---|
| MCP Agent Mail | Messaging + file reservations + Git audit trail | Optimized for code collaboration, not investigation. Complex (FastMCP + Git + SQLite). |
| Engram | Single-binary persistent memory with FTS5 | No semantic search, no entity relationships, single-machine without cloud sync |
| MACP | Shared SQLite bus for local agents | Single-machine only, no multi-user over network |
| Google A2A | Agent-to-agent interop protocol | Protocol only, no implementation of shared state |
| Neo4j Agent Memory | Graph-native memory with entities + reasoning traces | Requires Neo4j infrastructure, heavy for this use case |
| Amazon S3 Vectors | Managed vector store with strong consistency | Memory only — no coordination, no timeline, no entities |
| Bedrock AgentCore | Managed agent runtime with memory | Tied to Bedrock agent framework, not MCP-native |
| Centaur | Multiplayer agent runtime via Slack | One shared agent model, not multi-agent coordination |
| kiro-flock | Self-organizing agent clusters coordinating through append-only logs in S3 | Unstructured coordination — flat logs, no semantic search, no entity graph, no human attribution. Built for autonomous agent loops rather than humans each driving an agent, so its convergence and bounded-visibility mechanics do not transfer directly (see Out of scope). Its direction-file and iteration-loop patterns do. |
Conclusion: No single tool provides "shared memory + entity graph + timeline + artifacts + MCP interface" on AWS-managed infrastructure. A thin custom MCP server wrapping AWS services fills this gap with minimal code and zero ops burden.
(Bedrock AgentCore Gateway — distinct from AgentCore Runtime — was considered as a managed OAuth/MCP front door, but set aside for phase 1 because it is not yet fully working in our environment. The server self-hosts its own OAuth Resource Server instead.)
Tools In Use¶
Committed¶
- Amazon S3 Vectors — semantic search over findings (vector embeddings)
- Amazon DynamoDB — rooms, timeline events, entity graph, agent registry, coordination state
- Amazon S3 — artifact storage (logs, screenshots, metric graphs)
- Amazon Bedrock (Titan Text Embeddings V2) — embedding generation for semantic search
- OpenTofu — infrastructure deployment
- Python — MCP server implementation
- FastMCP — MCP server framework
- MCP (Streamable HTTP transport) — agent interface
Under Evaluation¶
- Amazon EventBridge — future push notifications when findings are posted
- Amazon Neptune — if entity relationship queries outgrow DynamoDB's adjacency list pattern
Scope¶
In scope¶
- MCP server exposing collaboration tools (rooms, findings, semantic search, timeline, entity graph, artifacts via presigned URLs)
- DynamoDB tables for rooms, findings (with timeline), entities + relationships, agent sessions
- S3 Vectors index for semantic search over findings
- S3 bucket for artifacts; agents upload directly via presigned URLs, then register metadata
- Auth via MCP OAuth 2.1 (auth-code + PKCE); self-hosted OAuth Resource Server; Cognito authorization server federated to our human IdP; no secrets in client config
- Private data plane (VPC + internal ALB); no public exposure of the MCP server
- Structured local (stdout) logging; observability stack left to the operator
visibility_modefield on rooms, with onlyfull(all agents see all findings) implemented in phase 1 — the field exists so alternative modes can be added without a schema change. Visibility is a coordination mechanism, not an access control: every authenticated user can still read every room throughget_timelineandsearch_findingsregardless of mode- OpenTofu module for all infrastructure
- Agent-facing documentation (SKILL.md or equivalent for Kiro)
- SKILL.md teaches the iteration loop pattern: read room context → check updates → decide contribution → post finding → declare status → repeat
- Advisory agent status (
active/idle/blocked) surfaced inget_room_summaryandget_room_context, so humans and peer agents can see who is working on what - Optional tags/labels on findings (triage, root-cause, remediation, etc.)
Out of scope¶
- Web UI or CLI viewer (future)
- Slack integration (future)
- Formal stage gating or workflow enforcement
- Push notifications / real-time reactivity (future via EventBridge)
- Bedrock agent or non-MCP agent integration (future phase)
- Multi-region replication
- Bounded and recency visibility modes. Bounded (ring/radius) visibility requires a stable agent-ordering mechanism that MACP does not have — agents join ad-hoc via
join_roomwith no assigned position. Adding it means adding ring assignment, which phase 1 does not need: at the documented 4–8 agents per room, full visibility is the appropriate topology (kiro-flock reports full-visibility mesh stays comfortable to roughly 30 agents) - Automated convergence detection. Deriving "the room is done" from all-agents-idle assumes agents run autonomous loops. MACP agents are driven by humans, so idle means "my operator stepped away" as often as "there is nothing left to contribute". Status stays advisory in phase 1
Architecture¶
graph TD
A[User A<br/>Kiro CLI] -->|MCP Streamable HTTP| S[MCP Server<br/>Python/FastMCP<br/>on EC2]
B[User B<br/>Kiro CLI] -->|MCP Streamable HTTP| S
C[User C<br/>Kiro CLI] -->|MCP Streamable HTTP| S
S --> SV[S3 Vectors<br/>semantic search]
S --> DDB[DynamoDB<br/>rooms, timeline,<br/>entities]
S --> S3[S3<br/>artifact bucket]
S --> BR[Bedrock<br/>Titan embeddings]
Auth flow: Kiro ↔ Cognito (OAuth 2.1 auth-code + PKCE, federated to our human IdP); Kiro presents the resulting Bearer JWT to the MCP server, which validates it as a self-hosted OAuth Resource Server. No secrets in client config — only a public client_id + loopback redirect.
MCP Tools Exposed¶
| Tool | Purpose |
|---|---|
create_room |
Start a new collaboration session with a stated objective |
join_room |
Register an agent's presence in a room (identity from IAM principal) |
close_room |
Mark a room closed; it remains fully queryable |
list_rooms |
List active/historical rooms |
get_room_summary |
Aggregated status: agent count (by declared status), finding count, entity count, latest activity |
get_room_context |
Bounded bootstrapping snapshot for a fresh agent session: objective, the N most recent findings, the top-K entities by relationship degree, and current agent statuses. Caps are server-configured and returned in the response alongside totals, so an agent knows what it did not see and can page deeper via get_timeline or search_findings |
declare_status |
Agent declares active, idle, or blocked with an optional reason. Advisory only — nothing in the server acts on it; it exists so humans and peer agents can see who is working on what |
post_finding |
Add a finding with optional tags, entity references, and evidence; auto-embeds and indexes |
search_findings |
Semantic search (S3 Vectors); returns finding IDs, hydrated from DynamoDB via BatchGetItem |
get_timeline |
Chronological findings, filterable by tag/agent/time range |
get_updates |
Findings since an opaque server cursor (polling); returns a new cursor; primary coordination primitive for the agent iteration loop |
add_entity |
Create or upsert an entity with typed identifiers[]; matches existing entities by shared identifier |
add_relationship |
Link two entities (depends_on, caused_by, changed_by, same_as, etc.) with evidence |
merge_entities |
Consolidate two entities into one canonical record (union of identifiers, relationships, evidence); old IDs become resolvable aliases |
get_entity_graph |
Query entities and relationships for a room |
request_artifact_upload |
Get a presigned S3 PUT URL + eventual object URL for direct agent upload |
register_artifact |
Record artifact metadata after upload; link to findings/entities |
list_artifacts |
List artifacts for a room |
DynamoDB Table Design¶
Rooms table:
- PK: room_id
- Attributes: name, objective (markdown — the stated goal agents self-organize around), visibility_mode (full only in phase 1; field reserved for future modes), created_at, created_by, tags, status (active/closed)
Findings table:
- PK: room_id, SK: finding_id (ULID — time-ordered)
- Attributes: content, agent_id, user_id, tags[], entity_refs[], evidence[], embedding_key (ref to S3 Vectors), index_status (pending|indexed), idempotency_key
- index_status supports the DynamoDB-first write protocol (write pending → embed via Bedrock → index in S3 Vectors → flip to indexed); a reconciler sweeps stale pending
- evidence[] items: { kind: artifact|url|cloudtrail|datadog|metric|log, ref, description, captured_at } — typed, free-form refs; artifact linkage not enforced
Entities table:
- PK: room_id, SK: entity_id
- Attributes: name, type (service, person, event, resource), identifiers[] (typed: {type, value} — e.g. ad_guid, sid, arn, hostname), properties{}, created_by, merged_into (alias pointer when merged)
- Identifier-claim items (same table, SK IDENT#type#value) map an identifier → entity_id. add_entity uses TransactWriteItems to create the entity and claim each identifier conditionally; a failed claim means an entity with that identifier already exists, so the caller attaches to it — making creation race-safe and idempotent
- Merge is lazy: merge_entities sets merged_into on the losing entity and unions its identifiers[] onto the winner; reads resolve merged_into, so stale entity_refs[] on findings resolve transparently with no bulk rewrite
Relationships table:
- PK: room_id#source_entity_id (composite is intentional — supports "get all edges of a node"), SK: relationship_type#target_entity_id
- Attributes: description, evidence[], created_at, agent_id, idempotency_key
Agent Sessions table:
- PK: room_id, SK: agent_id
- Attributes: user_id, joined_at, last_active, agent_type, agent_status (active|idle|blocked), status_reason, status_updated_at
Artifacts table:
- PK: room_id, SK: artifact_id
- Attributes: s3_key, content_type, size, uploaded_by, uploaded_at, description, linked_finding_ids[], linked_entity_ids[], idempotency_key
- Bucket is private; uploads via presigned PUT scoped to a per-room key prefix (content-length/type constrained); reads via presigned GET
All tables use on-demand (pay-per-request) capacity. Write tools (post_finding, add_entity, add_relationship, register_artifact) accept an optional idempotency_key and dedup on it so retries don't double-write.
Authentication & Access Control¶
Auth uses the MCP OAuth 2.1 authorization-code + PKCE flow — no secrets in client config.
- MCP server = self-hosted OAuth 2.1 Resource Server. On an unauthenticated call it returns
401with RFC 9728 protected-resource metadata pointing to the authorization server. It validates the Bearer JWT on every call (signature via JWKS, issuer, audience, expiry) and maps the token subject to a human user identity. - Authorization server = Amazon Cognito, federated to our upstream human IdP. Cognito runs the hosted-UI auth-code + PKCE flow and issues tokens. Because auth is interactive and human, actions map to people (attribution), and only identities in our federated IdP can obtain tokens — that membership is the access perimeter.
- No secret in client config. Kiro uses its native remote-MCP OAuth support —
url+oauth.clientId(a pre-registered public client) +oauth.redirectUri(loopback, e.g.http://127.0.0.1:8080). Kiro runs the browser flow (a browser is available on the EC2 host via virtual desktop / X-forwarding), caches tokens, and refreshes them. Confirmed against the existingemcpg-awsagent config. - Cognito DCR gap: Cognito does not support OAuth Dynamic Client Registration (RFC 7591), so a public client is pre-registered and its
client_iddistributed in agent config (public, not a secret). - Extensibility: the resource-server token-validation layer is abstracted behind an interface (configurable issuer / JWKS / audience), so a different authorization server or IdP can be swapped in by config.
Networking & Observability¶
- Networking: Private data plane. The self-hosted MCP server runs in a VPC behind an internal ALB; agents on EC2 within the controlled network reach it privately. The only public hop is the browser → Cognito hosted UI during login, which never exposes the MCP server. AWS service APIs (S3 Vectors, DynamoDB, Bedrock) are reached via VPC interface endpoints.
- Logging: Structured JSON logs to stdout / local files. The observability stack (log shipping, metrics, alarms) is left to the operator and not wired in phase 1.
Data Lifecycle¶
Phase 1 retains all data indefinitely (no TTL) to support postmortems and pattern recognition. Archival of old/closed rooms to cheaper storage is deferred to a later phase.
Risks¶
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Sensitive data (credentials, PII) posted as findings, evidence, or artifacts | High | High | Same exposure SIRIWAIT rates High/High for the same investigation content. Phase 1 compounds it: no per-room ACLs (any authenticated user reads any room) and indefinite retention. Decide among SKILL.md guidance against pasting raw secrets, redaction on write, per-room ACLs, and a retention TTL for rooms holding regulated data — currently none of these are in phase 1 |
| S3 Vectors is new (2026) — possible API changes or limitations | Medium | Medium | Abstract behind a repository interface; could swap to OpenSearch |
| DynamoDB entity graph queries become complex at scale | Low | Medium | Adjacency list pattern is well-understood; Neptune is the escape hatch |
| MCP Streamable HTTP + OAuth support in the client | Low | Low | Confirmed: Kiro supports remote Streamable HTTP MCP and native oauth (public client + loopback) per the existing emcpg-aws config |
| Embedding costs at high volume | Low | Low | Titan embeddings are cheap; findings are text-heavy, not high-volume |
| Agent prompt engineering — agents need to know when/how to use tools | Medium | Medium | Ship a SKILL.md with clear instructions; iterate on prompts |
| S3 Vectors only available in certain regions | Low | Low | Default to us-west-2 (supported, GA Dec 2025); region is a variable validated against the supported list |
| Multi-instance scale needs MCP session affinity | Low | Medium | Phase 1 runs a single instance; horizontal scale (Fargate) will require sticky sessions or externalized session state — don't bake in-memory session assumptions |
| Dual-write across DynamoDB + Bedrock + S3 Vectors | Medium | Medium | DynamoDB-first with index_status: pending and a reconciler; search tolerates brief indexing lag |
| Agent drift — a long-lived session carries a stale reading of the objective forward after peers have moved on | Medium | Medium | Unfixable from the server side: kiro-flock's control is a fresh session per iteration, and MACP does not own the client session lifecycle. get_room_context makes re-grounding cheap but cannot force it; SKILL.md must instruct agents to re-read context each iteration rather than trusting accumulated history |
Success Criteria¶
- 3+ Kiro CLI instances can join the same room and see each other's findings via
get_updates - Semantic search returns relevant findings across agents (not just keyword match)
- Entity graph correctly represents relationships discovered by different agents
- Artifacts uploaded by one agent are accessible (via presigned URL) to others
- Full investigation state persists and is queryable after the session ends
- A fresh agent session joining an in-progress room can orient from
get_room_contextalone and make a non-duplicative contribution, without its operator re-explaining the investigation get_room_contextstays within its configured caps and reports totals, so a large room does not exhaust the agent's context window- Infrastructure deploys cleanly via
tofu applyto any account and any S3 Vectors-supported region (default: us-west-2) - Agent SKILL.md enables Kiro to use the tools effectively without extensive prompting
Testing¶
- Unit / integration:
motoor DynamoDB Local for DynamoDB; mocked Bedrock and S3 Vectors clients; run viauvwithpytest. - Tool contract tests: each MCP tool tested for input validation, idempotency (
idempotency_key), and error paths (including dual-write partial failures andindex_statusreconciliation). - Entity-resolution tests: concurrent
add_entityrace (transactional claim), andmerge_entitieslazy-alias resolution on reads. - Context-bounding tests:
get_room_contextrespects its caps against a seeded large room, reports accurate totals alongside the truncated payload, and stays within a target token budget. - Status tests:
declare_statustransitions, and confirmation that no server behaviour is gated on declared status (status is advisory — a test asserts anidleagent still receives updates and can post). - Visibility tests: with
visibility_modeset tofull, assertget_timelineandsearch_findingsreturn the same result set for every member — guarding against visibility being mistaken for, or drifting into, an access control. - Multi-agent integration (milestone 7): 3+ Kiro instances against a deployed stack, exercising post → search → entity graph → artifact across agents.
Milestones¶
- Infrastructure — OpenTofu for DynamoDB tables, S3 artifact bucket, S3 Vectors index, VPC + internal ALB, Cognito user pool (federated to human IdP) + public client
- MCP server skeleton — OAuth Resource Server (401 + RFC 9728 metadata, JWT validation),
create_room(withobjective),join_room,list_rooms,close_room,get_room_summary,declare_status - Findings + search —
post_finding,search_findings,get_timeline,get_updates(cursor-based),get_room_context(bounded snapshot) - Entity graph —
add_entity(identifiers + auto-match),add_relationship,same_as,merge_entities,get_entity_graph - Artifacts —
request_artifact_upload,register_artifact,list_artifacts - Agent enablement — SKILL.md (iteration loop pattern, re-read context each iteration, objective-driven contribution selection) + prompt iteration for Kiro
- Multi-agent validation — 3+ Kiro instances collaborating in one room, including a fresh session joining mid-investigation and orienting from
get_room_contextalone
Open Questions¶
- The OAuth flow assumes an interactive browser is reachable wherever the agent runs (the plan cites virtual desktop / X-forwarding on the EC2 host). Does that hold for every intended operator? Cognito's hosted UI is browser-only, so if not, a device-authorization-style fallback would be needed — which changes the auth design, not just the UX.
- Which sensitive-data control lands in phase 1 (see Risks): SKILL.md guidance, redaction on write, per-room ACLs, or a retention TTL? Phase 1 currently has none, while SIRIWAIT rates the same data High/High.
- Milestones 1–7 have no owners or target dates.
- If bounded visibility is ever wanted, where does agent ordering come from? A ring needs stable positions, and
join_roomassigns none. Join order is the obvious candidate but is unstable across rejoins, and it couples topology to arrival timing rather than to the work. - Is a human-driven agent's
idledistinguishable from "operator stepped away"? If a future phase wants automated convergence, it needs a signal that separates the two — an explicit "nothing further to contribute toward this objective" assertion is not the same as absence of activity. - Does
objectiveneed to be mutable mid-investigation? kiro-flock supports steering a running cluster by updating the direction file. Allowing that here raises the question of whether findings posted against a superseded objective should be marked as such.
References¶
- Amazon S3 Vectors — managed vector store backing semantic search; region support is the basis of the us-west-2 default
- Amazon Titan Text Embeddings — embedding model invoked via Bedrock; requires model access to be enabled in the target account
- DynamoDB
TransactWriteItems— transactional identifier-claim mechanism for race-safe entity creation, and the 100-item limit that drove the lazy-merge design - MCP authorization specification — the OAuth 2.1 profile the server implements as a Resource Server
- RFC 9728 — OAuth 2.0 Protected Resource Metadata — the metadata returned on a 401
- RFC 7636 — PKCE — the auth-code flow extension used by the public client
- RFC 7591 — OAuth 2.0 Dynamic Client Registration — the standard Cognito does not implement, which is why a public client is pre-registered
- Amazon Cognito user pools — token endpoint reference — authorization server behaviour
- FastMCP — MCP server framework
- ULID specification — time-ordered identifiers used as finding sort keys
- moto — AWS mocking library used in the testing approach
- kiro-flock — open-source reference implementation of self-organizing multi-agent clusters on AWS; source of the direction-file and iteration-loop patterns adopted here, and of the bounded-visibility and convergence mechanics deferred as out of scope
- Scaling patterns for self-organizing multi-agent clusters with Kiro — AWS Architecture Blog post describing the amorphous/mesh/swarm coordination algorithms, the convergence math, and the four failure modes (groupthink, drift, hot spots, carry-over); the basis for the drift risk and the full-visibility choice at this cluster size
- SIRIWAIT plan and SAINT plan — the investigation workflows that consume this server
Decisions¶
| Date | Decision | Rationale |
|---|---|---|
| 2026-06-11 | Use S3 Vectors over OpenSearch or self-hosted vector DB | Fully managed, pay-per-use, strong consistency, no cluster management |
| 2026-06-11 | DynamoDB over RDS/Postgres | Serverless, schema-flexible, natural fit for time-series + adjacency patterns |
| 2026-06-11 | MCP Streamable HTTP over stdio | Enables multiple remote agents to connect to a single server instance |
| 2026-06-11 | Auth via MCP OAuth 2.1 (auth-code + PKCE), self-hosted Resource Server | No secrets in client config; Kiro native remote-MCP oauth support (public client_id + loopback redirect) confirmed against the existing emcpg-aws config |
| 2026-06-11 | Cognito as authorization server, federated to upstream human IdP | Interactive human auth maps actions to people; federated IdP membership is the access perimeter; pre-registered public client (Cognito lacks DCR) |
| 2026-06-11 | Self-host the MCP server (not AgentCore Gateway) | AgentCore Gateway not fully working yet in our environment; the self-hosted server acts as its own OAuth Resource Server |
| 2026-06-11 | Amazon Titan for embeddings | Fully managed via Bedrock, no API keys, stays within AWS ecosystem |
| 2026-06-11 | EC2 for phase 1, portable to Fargate later | Simpler HTTP handling, always-on; containerize so Fargate migration is straightforward |
| 2026-06-11 | Room IDs: auto-generated UUID + optional human-readable name | UUID is the primary key, name is a label for human convenience |
| 2026-06-11 | No enforced roles in phase 1 | Track created_by so roles can be added later without schema changes |
| 2026-06-11 | No conflict resolution in phase 1 | Store all assertions; each finding/relationship requires evidence (artifact references) so contradictions can be evaluated by looking at proof |
| 2026-06-11 | Findings are flat with tags + entity references | Findings point into the entity graph; graph traversal is at the entity layer, not the finding layer |
| 2026-06-11 | Findings and relationships require evidence | Each finding/relationship supports an evidence[] field — artifact URLs, Datadog links, CloudTrail event IDs, etc. |
| 2026-06-11 | Perimeter-based access control via federated IdP | Only humans in our federated IdP can obtain tokens; within that set, any authenticated user may access any room; no per-room ACLs in phase 1 |
| 2026-06-11 | Entity resolution: identifiers + auto-match + same_as + merge | Entities carry typed identifiers[]; shared-identifier creates converge automatically; later-discovered matches use evidence-backed same_as plus an explicit merge_entities |
| 2026-06-11 | Entities not semantically searchable in phase 1 | Found via identifier, graph traversal, and via searchable findings; embedding entities deferred |
| 2026-06-11 | Default region us-west-2 | Preferred region; confirmed S3 Vectors-supported (GA Dec 2025); region remains an OpenTofu variable |
| 2026-06-11 | Retain all data indefinitely in phase 1 | Supports postmortems/pattern recognition; archival deferred |
| 2026-06-11 | Private data plane, local logging | Self-hosted server in VPC behind internal ALB; AWS APIs via VPC endpoints; only public hop is browser↔Cognito login; structured stdout logs, observability stack operator's choice |
| 2026-06-11 | Artifacts via presigned S3 URLs | Agents upload directly to S3; server issues presigned URLs and stores metadata, never handles file bytes |
| 2026-06-11 | get_updates uses a server cursor | Server-authoritative cursor avoids client clock-skew in polling |
| 2026-06-11 | DynamoDB-first write protocol with index_status + reconciler | Avoids silently-unsearchable findings from dual-write partial failures |
| 2026-06-11 | Entity create via TransactWriteItems identifier claim | Race-safe, idempotent upsert; loser attaches to the existing entity |
| 2026-06-11 | Lazy entity merge (merged_into alias) | Avoids bulk rewrites and the 100-item transaction limit; references resolve at read time |
| 2026-06-11 | Multi-table DynamoDB, clean PK/SK | Simpler to operate at this scale; single-table design not warranted; composite PK kept only where it serves an access pattern (relationship adjacency) |
| 2026-06-11 | evidence[] is typed, free-form refs | {kind, ref, description, captured_at}; artifact linkage not enforced to avoid write-ordering constraints |
| 2026-06-11 | Search hydrates from DynamoDB | S3 Vectors returns IDs; BatchGetItem pulls bodies — keeps DynamoDB the single source of truth |
| 2026-06-11 | Single instance in phase 1 | 4-8 agents fit one instance; document session-affinity requirement for future horizontal scale |
| 2026-06-11 | idempotency_key on write tools | Network retries don't double-write |
| 2026-06-11 | ULID finding IDs | Time-ordered sort key; robust get_updates cursor |
| 2026-06-11 | On-demand DynamoDB; private artifact bucket | No capacity planning; all S3 access via presigned URLs scoped per room |
| 2026-06-11 | Titan Text Embeddings V2 confirmed in us-west-2 | Precondition: Bedrock model access for Titan must be enabled in the target account |
| 2026-08-11 | Room objective field |
Agents self-organize around a stated goal (the "direction file" pattern from kiro-flock) instead of each agent needing its operator to restate the goal |
| 2026-08-11 | Agent status is advisory, not actuating | declare_status records active/idle/blocked for human and peer visibility. No server behaviour is gated on it, because a human-driven agent's idle state does not distinguish "nothing left to contribute" from "operator stepped away" |
| 2026-08-11 | No automated convergence detection in phase 1 | Deriving "done" from all-agents-idle depends on autonomous agent loops; MACP agents are human-driven, so the signal would misfire. Deferred pending a signal that separates completion from inactivity |
| 2026-08-11 | get_room_context is explicitly bounded |
Caps on findings and entities returned, with totals reported alongside. An unbounded snapshot would exhaust the context window it exists to conserve |
| 2026-08-11 | Drift is mitigated by guidance, not enforcement | kiro-flock prevents drift with a fresh session per iteration. MACP does not own the client session lifecycle, so it cannot enforce that — get_room_context lowers the cost of re-grounding and SKILL.md instructs agents to do it each iteration. Recorded as a residual risk rather than a solved problem |
| 2026-08-11 | visibility_mode reserved, full only in phase 1 |
Bounded (ring/radius) visibility needs stable agent ordering MACP lacks, and full visibility is the right topology at the documented 4–8 agents per room. The field exists so modes can be added without a schema change |
| 2026-08-11 | Visibility is coordination, never access control | Whatever mode a room uses, every authenticated user can still reach every finding via get_timeline and search_findings. Keeping this explicit prevents visibility modes from being mistaken for the per-room ACLs phase 1 deliberately does not have |
| 2026-08-11 | SKILL.md teaches the iteration loop pattern | Read context → check updates → decide → contribute → declare status → repeat; the loop is the coordination mechanism, not just the tools |
Changelog¶
| Date | Status | Change |
|---|---|---|
| 2026-06-11 | draft | Initial draft |
| 2026-06-11 | draft | Review pass: resolved 15 issues — artifact flow, entity resolution, access model, networking, lifecycle, milestones |
| 2026-06-11 | draft | Auth design: MCP OAuth 2.1 (auth-code + PKCE), self-hosted Resource Server, Cognito federated to human IdP, no client secrets; AgentCore Gateway deferred |
| 2026-06-11 | draft | Architecture review fixes: dual-write protocol, transactional entity create + lazy merge, multi-table, evidence schema, search hydration, idempotency, ULID IDs, on-demand/private bucket, testing section, us-west-2 model confirmations |
| 2026-07-24 | planned | Status active → planned: the product is registered but no milestone has started |
| 2026-07-24 | planned | Review pass: added a High/High sensitive-data risk matching SIRIWAIT's assessment of the same investigation content, noting that phase 1 has neither per-room ACLs nor retention limits; replaced "(none remaining)" open questions with the browser dependency in the OAuth flow, the outstanding sensitive-data control choice, and missing milestone owners and dates; added References; corrected created to the first changelog date |
| 2026-08-11 | planned | Incorporated learnings from kiro-flock: added room objective, get_room_context (bounded snapshot), and advisory declare_status; documented the SKILL.md iteration-loop pattern. Deferred bounded/recency visibility (needs agent ordering MACP lacks) and automated convergence detection (idle is ambiguous for human-driven agents) to out-of-scope; recorded agent drift as a residual risk the server cannot enforce away; added kiro-flock to the research table and References |