Multi-Agent Collaboration for Team and Friends
TypeScript agent-automationagent-orchestrationagent-workflowai-agentsai-collaborationai-memoryai-workforceautonomous-agentsclaude-codeclaude-code-skillscodexcoding-agentmulti-agentmultiple-agentone-person-businessone-person-companyone-person-teamopencodesolopreneur
/**
* Real-infra replacement for the deleted `controlPlane.e2e.test.ts` (which
* exercised `WsControlServer` against the in-memory `MockServer`). This
* suite instead drives the ACTUAL production path end to end:
*
* POST /api/community/channels/:id/messages (human, real HTTP)
* → committed message dispatcher → wake producer (dev HTTP transport)
* → alook-queue-worker (real process) → dispatchOneUnreadWake
* → sendWakeToMachine → alook-ws-do (real DO) → the daemon's real
* `WsControlChannel`, over a real WebSocket, receives `agent:wake`
* → the test (playing the "agent" — no CLI spawned) replies via the
* real `enroll-agent` → canonical pull/ack/send HTTP chain
* → the reply is visible via a real read of the channel.
*
* Requires `wrangler dev` (`@alook/web`), `@alook/ws-do dev`, and
* `@alook/queue-worker dev` all already running (same servers CI's `e2e`
* job boots for `@alook/cli`'s integration tests, plus `queue-worker`).
*/
import { describe, it, expect, beforeAll, afterAll } from "vitest"
import { WebSocket } from "ws"
import {
seedTestData,
cleanupTestData,
sessionRequest,
signIn,
fetchWithRetry,
seedCommunityBot,
cleanupCommunityBot,
type TestSeed,
type SeededCommunityBot,
} from "@alook/test-utils"
import { parseSeq } from "@alook/shared"
import { WsControlChannel } from "../../../src/daemon/src/server/wsControlChannel"
import type { HostCommand } from "../../../src/daemon/src/server/contract"
import { nanoid, seedPairedBot, cleanupPairedBot, type DaemonItFixture } from "./seed-helpers"
const APP_URL = process.env.APP_URL ?? "http://localhost:3000"
const WS_DO_URL = process.env.WS_DO_URL ?? "ws://localhost:8789"
// Assert a response is ok, but on failure surface the STATUS + body — a bare
// `expect(res.ok).toBe(true)` only tells you "false", which is undiagnosable in
// CI (is it a 401 key-timing? a 500 handler throw? a transport timeout?). This
// turns the opaque failure into an actionable signature.
async function assertResOk(res: Response, label: string): Promise<void> {
if (res.ok) return
let body = ""
try { body = (await res.text()).slice(0, 500) } catch { body = "<unreadable body>" }
throw new Error(`${label}: expected ok, got HTTP ${res.status} ${res.statusText} — body: ${body}`)
}
async function waitFor<T>(check: () => T | undefined, timeoutMs = 15_000, intervalMs = 200): Promise<T> {
const deadline = Date.now() + timeoutMs
for (; ;) {
const v = check()
if (v !== undefined) return v
if (Date.now() > deadline) throw new Error("waitFor: timed out")
await new Promise((r) => setTimeout(r, intervalMs))
}
}
async function waitForAsync<T>(
check: () => Promise<T | undefined>,
timeoutMs = 15_000,
intervalMs = 200,
): Promise<T> {
const deadline = Date.now() + timeoutMs
let lastDetail = "no attempt yet"
for (; ;) {
try {
const v = await check()
if (v !== undefined) return v
lastDetail = "check returned undefined"
} catch (err) {
lastDetail = err instanceof Error ? err.message : String(err)
}
if (Date.now() > deadline) throw new Error(`waitForAsync: timed out (${lastDetail})`)
await new Promise((r) => setTimeout(r, intervalMs))
}
}
async function waitForChannelReply(
channelId: string,
ownerCookie: string,
replyText: string,
timeoutMs = 15_000,
): Promise<void> {
await waitForAsync(async () => {
const readRes = await sessionRequest(`/api/community/channels/${channelId}/messages`, ownerCookie)
const raw = await readRes.text()
if (!readRes.ok) {
throw new Error(`channel read failed status=${readRes.status} body=${raw.slice(0, 200)}`)
}
if (!raw.trim()) {
throw new Error("channel read returned empty body")
}
const readBody = JSON.parse(raw) as { messages: Array<{ content: string }> }
return readBody.messages.some((m) => m.content === replyText) ? true : undefined
}, timeoutMs)
}
let seed: TestSeed
let cookie: string
let fixture: DaemonItFixture
let channel: WsControlChannel | undefined
beforeAll(async () => {
seed = seedTestData()
cookie = await signIn(seed.authEmail, seed.authPassword)
fixture = await seedPairedBot(seed, cookie)
}, 30_000)
afterAll(() => {
channel?.close()
if (fixture) cleanupPairedBot(seed, fixture)
cleanupTestData(seed)
})
describe("daemon control plane — real ws-do wake round-trip", () => {
it("delivers a real agent:wake HostCommand over a real WsControlChannel, and the agent's real HTTP reply lands in the channel", async () => {
const receivedCommands: HostCommand[] = []
channel = new WsControlChannel({
url: WS_DO_URL,
headers: { Authorization: `Bearer ${fixture.paired.credential}` },
webSocketFactory: (url, headers) => new WebSocket(url, { headers }) as never,
})
channel.onCommand((cmd) => {
receivedCommands.push(cmd)
})
channel.onResync(() => ({
ready: {
runtimeReport: [{ id: "claude" }],
runningAgents: [],
daemonVersion: "0.1.7",
capabilities: ["control-heartbeat-v1"],
},
sessions: [],
activities: [],
}))
// Step: connect and wait for the daemon's `ready` handshake to actually
// be sent — a wake with no ready daemon on the other end is recorded
// `delivered_nowhere` and step below would hang waiting for a frame
// that's never sent.
const opened = new Promise<void>((resolve) => channel!.onOpen(resolve))
channel.connect()
await opened
// Human owner posts a real message — exercises the real wake-producer
// path (committed dispatcher → wake producer → dev HTTP transport →
// queue-worker → forward-agent-wake → the DO → our open socket).
const postRes = await sessionRequest(`/api/community/channels/${fixture.channelId}/messages`, cookie, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ content: "hey bot, wake up" }),
})
await assertResOk(postRes, "owner message post (human→wake hop)")
const wake = await waitFor(
() => receivedCommands.find((c): c is HostCommand & { type: "agent:wake" } => c.type === "agent:wake"),
15_000,
)
expect(wake.type).toBe("agent:wake")
expect(wake.agentId).toBe(fixture.bot.botUserId)
// Acting as the "agent" (no CLI spawned): mint the runner key, then
// pull the backlog, ack it, and send a reply through the canonical HTTP
// resources exactly as a real agent's CLI would do.
const enrollRes = await fetchWithRetry(`${APP_URL}/api/community/daemon/enroll-agent`, {
method: "POST",
headers: { Authorization: `Bearer ${fixture.paired.credential}`, "content-type": "application/json" },
body: JSON.stringify({ agentId: fixture.bot.botUserId }),
})
expect(enrollRes.ok).toBe(true)
const { runnerKey } = (await enrollRes.json()) as { runnerKey: string; expiresAt: string | null }
expect(runnerKey.startsWith("crk_")).toBe(true)
const pullRes = await fetchWithRetry(`${APP_URL}/api/community/users/me/inbox/pull`, {
method: "POST",
headers: { Authorization: `Bearer ${runnerKey}`, "content-type": "application/json" },
body: JSON.stringify({}),
})
await assertResOk(pullRes, "inbox pull (enroll→pull hop)")
// Wire `seq` is formatted `"#N"` (see `formatSeq`/`toAgentMessages`) —
// the ack cursor schema wants the bare number back (`parseSeq`).
const pulled = (await pullRes.json()) as { messages: Array<{ seq: string; channel: string }> }
expect(pulled.messages.length).toBeGreaterThan(0)
const lastPulled = pulled.messages[pulled.messages.length - 1]!
const ackRes = await fetchWithRetry(`${APP_URL}/api/community/users/me/inbox/ack`, {
method: "POST",
headers: { Authorization: `Bearer ${runnerKey}`, "content-type": "application/json" },
body: JSON.stringify({ cursors: [{ channel: lastPulled.channel, seq: parseSeq(lastPulled.seq) }] }),
})
expect(ackRes.ok).toBe(true)
const replyText = `reply from the real credential chain ${nanoid()}`
const sendRes = await fetchWithRetry(`${APP_URL}/api/community/channels/resolve/messages`, {
method: "POST",
headers: { Authorization: `Bearer ${runnerKey}`, "content-type": "application/json" },
body: JSON.stringify({ channel: `/${fixture.serverHandle}/${fixture.channelName}`, content: { text: replyText } }),
})
expect(sendRes.ok).toBe(true)
const sendBody = (await sendRes.json()) as { state: string }
expect(sendBody.state).toBe("sent")
// The reply is now visible via a real owner-facing read of the channel.
// Poll: wrangler/dev can briefly return empty bodies under fan-out load.
await waitForChannelReply(fixture.channelId, cookie, replyText)
}, 30_000)
it("forwards the owner-scoped update API through the real ws-do as the exact machine:update command", async () => {
expect(channel).toBeDefined()
const received: HostCommand[] = []
channel!.onCommand((command) => received.push(command))
const response = await sessionRequest(
`/api/community/machines/${fixture.paired.machineId}/update`,
cookie,
{ method: "POST" },
)
await assertResOk(response, "machine update dispatch")
expect(await response.json()).toEqual({ dispatched: true })
const update = await waitFor(
() => received.find((command) => command.type === "machine:update"),
15_000,
)
expect(update).toEqual({ type: "machine:update" })
}, 30_000)
it("reports agent_activity over the real WsControlChannel and the profile route reflects running, then idle after the stub session ends its turn", async () => {
// Reuses the already-open `channel` from the first test — asserts the
// wire-level `agent_activity` frame this plan adds actually persists and
// is visible via the owner-facing /profile route (the read-side this
// plan's UI depends on for a fresh page load).
expect(channel).toBeDefined()
// Bot activity is stored on the same `statusEmoji`/`statusText` fields
// humans use — the WS DO translates the daemon's `agent_activity` frame
// into the appropriate preset and writes/broadcasts it as an ordinary
// status update.
await channel!.reportAgentActivity({ agentId: fixture.bot.botUserId, state: "running" })
const runningProfile = await waitForAsync(async () => {
const res = await sessionRequest(`/api/community/users/${fixture.bot.botUserId}/profile`, cookie)
if (!res.ok) return undefined
const body = (await res.json()) as { statusText: string | null }
// Any of the fun `running` variants counts — the WS DO picks one at random.
return typeof body.statusText === "string" && /Working on it|Cooking|Thinking hard|Tinkering|On it|In the zone/.test(body.statusText)
? body
: undefined
}, 15_000)
expect(runningProfile.statusText).toMatch(/Working on it|Cooking|Thinking hard|Tinkering|On it|In the zone/)
// Simulates the stub session's turn ending (the real daemon would derive
// this via `deriveActivity` — here we report the wire-level state
// directly since no CLI is spawned in this harness).
await channel!.reportAgentActivity({ agentId: fixture.bot.botUserId, state: "idle" })
const idleProfile = await waitForAsync(async () => {
const res = await sessionRequest(`/api/community/users/${fixture.bot.botUserId}/profile`, cookie)
if (!res.ok) return undefined
const body = (await res.json()) as { statusText: string | null }
return body.statusText === "Idle" ? body : undefined
}, 15_000)
expect(idleProfile.statusText).toBe("Idle")
}, 30_000)
it("fans out an independent agent:wake to each of several bots bound to the same machine, over the same socket", async () => {
// Reuses the already-open `channel` from the previous test — this is the
// scenario the deleted `controlPlane.e2e.test.ts`'s "multiple agents each
// reply" case covered: one control-plane connection correctly routes
// simultaneous wakes for several DIFFERENT bots, not just one.
expect(channel).toBeDefined()
const extraBots: SeededCommunityBot[] = [
seedCommunityBot({ ownerUserId: seed.userId, serverId: fixture.serverId, machineId: fixture.paired.machineId, runtime: "claude" }),
seedCommunityBot({ ownerUserId: seed.userId, serverId: fixture.serverId, machineId: fixture.paired.machineId, runtime: "claude" }),
]
try {
const receivedWakes: Array<HostCommand & { type: "agent:wake" }> = []
channel!.onCommand((cmd) => {
if (cmd.type === "agent:wake") receivedWakes.push(cmd)
})
const postRes = await sessionRequest(`/api/community/channels/${fixture.channelId}/messages`, cookie, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ content: "hey team, wake up" }),
})
expect(postRes.ok).toBe(true)
const targetIds = extraBots.map((b) => b.botUserId)
await waitFor(() => {
const seen = new Set(receivedWakes.map((c) => c.agentId))
return targetIds.every((id) => seen.has(id)) ? true : undefined
}, 15_000)
// Each bot replies independently through its own real credential chain
// — proves the wakes weren't just received, but are independently
// actionable per-agent over the one shared socket.
for (const bot of extraBots) {
const enrollRes = await fetchWithRetry(`${APP_URL}/api/community/daemon/enroll-agent`, {
method: "POST",
headers: { Authorization: `Bearer ${fixture.paired.credential}`, "content-type": "application/json" },
body: JSON.stringify({ agentId: bot.botUserId }),
})
await assertResOk(enrollRes, "agent enrollment (multi-bot wake→enroll)")
const { runnerKey } = (await enrollRes.json()) as { runnerKey: string }
const pullRes = await fetchWithRetry(`${APP_URL}/api/community/users/me/inbox/pull`, {
method: "POST",
headers: { Authorization: `Bearer ${runnerKey}`, "content-type": "application/json" },
body: JSON.stringify({}),
})
await assertResOk(pullRes, "inbox pull (multi-bot enroll→pull)")
const pulled = (await pullRes.json()) as { messages: Array<{ seq: string; channel: string }> }
expect(pulled.messages.length).toBeGreaterThan(0)
const lastPulled = pulled.messages[pulled.messages.length - 1]!
await fetchWithRetry(`${APP_URL}/api/community/users/me/inbox/ack`, {
method: "POST",
headers: { Authorization: `Bearer ${runnerKey}`, "content-type": "application/json" },
body: JSON.stringify({ cursors: [{ channel: lastPulled.channel, seq: parseSeq(lastPulled.seq) }] }),
})
const replyText = `reply from ${bot.botUserId} ${nanoid()}`
const sendRes = await fetchWithRetry(`${APP_URL}/api/community/channels/resolve/messages`, {
method: "POST",
headers: { Authorization: `Bearer ${runnerKey}`, "content-type": "application/json" },
body: JSON.stringify({ channel: `/${fixture.serverHandle}/${fixture.channelName}`, content: { text: replyText } }),
})
expect(sendRes.ok).toBe(true)
const sendBody = (await sendRes.json()) as { state: string }
expect(sendBody.state).toBe("sent")
await waitForChannelReply(fixture.channelId, cookie, replyText)
}
} finally {
for (const bot of extraBots) cleanupCommunityBot(bot)
}
}, 45_000)
})