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
import { describe, it, expect } from "vitest";
import {
parseRef,
formatRef,
formatCanonicalRef,
formatSeq,
parseSeq,
DM_SERVER,
AgentInterruptRequestSchema,
HostCommandSchema,
} from "../src/community-cli-contract";
import { CommunityAgentAttachmentUploadResponseSchema } from "../src/schemas";
describe("attachment thumbnail upload contract", () => {
it("accepts the optional server-confirmed hasThumbnail flag", () => {
expect(CommunityAgentAttachmentUploadResponseSchema.parse({
id: "a1", filename: "photo.png", contentType: "image/png", size: 10, hasThumbnail: true,
})).toMatchObject({ hasThumbnail: true });
});
});
describe("agent running-turn interrupt contract", () => {
it("accepts the exact one-way command", () => {
const request = { type: "agent:interrupt", agentId: "bot_1" };
expect(HostCommandSchema.parse(request)).toEqual(request);
expect(AgentInterruptRequestSchema.parse(request)).toEqual(request);
});
it("rejects missing, extra, empty, and overlong fields", () => {
expect(AgentInterruptRequestSchema.safeParse({ type: "agent:interrupt" }).success).toBe(false);
expect(AgentInterruptRequestSchema.safeParse({ type: "agent:interrupt", agentId: "bot_1", requestId: "x" }).success).toBe(false);
expect(AgentInterruptRequestSchema.safeParse({ type: "agent:interrupt", agentId: "" }).success).toBe(false);
expect(AgentInterruptRequestSchema.safeParse({ type: "agent:interrupt", agentId: "x".repeat(129) }).success).toBe(false);
});
});
describe("parseRef", () => {
it('parses "/studio#0042/general" as a plain channel ref', () => {
expect(parseRef("/studio#0042/general")).toEqual({ server: "studio#0042", channel: "general" });
});
it('parses "/studio#0042/general#42" as a pinned-message ref (seq)', () => {
expect(parseRef("/studio#0042/general#42")).toEqual({ server: "studio#0042", channel: "general", seq: 42 });
});
it('parses "/studio#0042/general/#42" as a thread ref (threadRootSeq)', () => {
expect(parseRef("/studio#0042/general/#42")).toEqual({
server: "studio#0042",
channel: "general",
threadRootSeq: 42,
});
});
it('parses "/.dm/user_123" as a DM ref (server === DM_SERVER)', () => {
// Legacy/no-discriminator id form: no "#" in the segment, so it round-trips
// through the PARSER unchanged — see Design §1. Resolution (not parsing) is
// what changes once `resolve-ref.ts` requires a `name#0042` handle; this
// parser-level case documents that the shape itself still parses fine.
const parsed = parseRef("/.dm/user_123");
expect(parsed).toEqual({ server: DM_SERVER, channel: "user_123" });
expect(parsed.server).toBe(".dm");
});
it('parses "/.dm/gusye#1231" as a bare handle (no seq stripped)', () => {
expect(parseRef("/.dm/gusye#1231")).toEqual({ server: DM_SERVER, channel: "gusye#1231" });
});
it('parses "/.dm/gusye#1231#42" as a pinned message on a handle peer', () => {
expect(parseRef("/.dm/gusye#1231#42")).toEqual({ server: DM_SERVER, channel: "gusye#1231", seq: 42 });
});
it('parses "/.dm/gusye#1231/#42" as a thread rooted on a handle peer', () => {
expect(parseRef("/.dm/gusye#1231/#42")).toEqual({
server: DM_SERVER,
channel: "gusye#1231",
threadRootSeq: 42,
});
});
it('parses "/.dm/a#b#0042" (name itself contains "#") with the documented ambiguity: peer="a#b", seq=42, NOT peer="a#b#0042"', () => {
// Known, accepted footgun from the Breaking Changes section — asserting
// it here means a future change to this behavior is a deliberate diff,
// not a silent regression.
expect(parseRef("/.dm/a#b#0042")).toEqual({ server: DM_SERVER, channel: "a#b", seq: 42 });
});
it("throws when the ref doesn't start with /", () => {
expect(() => parseRef("studio/general")).toThrow();
});
it("throws when the ref has fewer than 2 segments", () => {
expect(() => parseRef("/studio#0042")).toThrow();
});
it('falls back to a plain-channel result for a DM ref with a non-numeric tail after "#" — does NOT throw', () => {
// Regression guard: previously `parseRef("/.dm/foo#bar")` fell into
// the `parseSeq(tail)` path and threw `bad seq: bar`, crashing any
// caller not wrapped in try/catch. Now the whole segment is treated
// as the channel/handle and the resolution layer
// (`parseNameAndTag`) rejects the shape cleanly at its own boundary.
expect(() => parseRef("/.dm/foo#bar")).not.toThrow();
expect(parseRef("/.dm/foo#bar")).toEqual({ server: DM_SERVER, channel: "foo#bar" });
});
it('parses "/demo#0042/general/#5#42" as a thread-reply message ref', () => {
expect(parseRef("/demo#0042/general/#5#42")).toEqual({
server: "demo#0042",
channel: "general",
threadRootSeq: 5,
seq: 42,
});
});
it('parses "/demo#0042/general/#5" unchanged (regression)', () => {
expect(parseRef("/demo#0042/general/#5")).toEqual({
server: "demo#0042",
channel: "general",
threadRootSeq: 5,
});
});
it('throws on "/demo#0042/general/#5#" — empty seq tail (Number("") === 0 trap)', () => {
expect(() => parseRef("/demo#0042/general/#5#")).toThrow();
});
it('throws on "/demo#0042/general/##5" — empty root', () => {
expect(() => parseRef("/demo#0042/general/##5")).toThrow();
});
it('throws on "/demo#0042/general/#5#abc" — non-numeric seq', () => {
expect(() => parseRef("/demo#0042/general/#5#abc")).toThrow();
});
it('throws on "/demo#0042/general/#5#42#7" — three tails, not two', () => {
expect(() => parseRef("/demo#0042/general/#5#42#7")).toThrow();
});
it('parses "/demo#0042/general/#0#5" — parser stays permissive (server rejects root 0)', () => {
expect(parseRef("/demo#0042/general/#0#5")).toEqual({
server: "demo#0042",
channel: "general",
threadRootSeq: 0,
seq: 5,
});
});
it('parses "/demo#0042/general/#5#0" — parser stays permissive (server rejects seq 0)', () => {
expect(parseRef("/demo#0042/general/#5#0")).toEqual({
server: "demo#0042",
channel: "general",
threadRootSeq: 5,
seq: 0,
});
});
it('throws on "/demo#0042/general#5#42" — slashless form must NOT accept a trailing #M', () => {
// The thread form requires the explicit `/#` separator. This shape is
// ambiguous with the message form `/server/channel#N` and must be
// rejected so callers can't sneak past the grammar.
expect(() => parseRef("/demo#0042/general#5#42")).toThrow();
});
it('parses "/.dm/gusye#1231/#5#42" — parser is DM-agnostic on thread form', () => {
// Server rejects DM threads at resolve-ref.ts; the parser itself does
// not know DM rules.
expect(parseRef("/.dm/gusye#1231/#5#42")).toEqual({
server: DM_SERVER,
channel: "gusye#1231",
threadRootSeq: 5,
seq: 42,
});
});
it('the old forum-post ref shape "/studio#0042/ideas/my-post" no longer parses (no-compat, phase2 forum≡thread)', () => {
// A post is now addressed like any other thread (by-root-seq), never by
// its own child-name — the old 3-segment-no-hash form is GONE, not just
// unsupported. A ref-render layer that fails to parse this degrades to
// plain literal text (never a misresolved-to-wrong-target pill).
expect(() => parseRef("/studio#0042/ideas/my-post")).toThrow();
});
it("still parses the thread form (3rd segment starts with #) unaffected by the forum-post removal", () => {
expect(parseRef("/studio#0042/ideas/#5")).toEqual({ server: "studio#0042", channel: "ideas", threadRootSeq: 5 });
});
it("throws on any 3+ segment ref whose last segment doesn't start with # (the old forum-post ref's territory)", () => {
expect(() => parseRef("/studio#0042/ideas/notes")).toThrow();
expect(() => parseRef("/studio#0042/ideas/post/extra")).toThrow();
expect(() => parseRef("/studio#0042/ideas/post#3")).toThrow();
});
});
describe("formatRef", () => {
it("formats a plain channel", () => {
expect(formatRef({ server: "studio#0042", channel: "general" })).toBe("/studio#0042/general");
});
it("formats a thread ref with threadRootSeq", () => {
expect(formatRef({ server: "studio#0042", channel: "general", threadRootSeq: 42 })).toBe(
"/studio#0042/general/#42"
);
});
it("round-trips through parseRef for the thread form", () => {
const ref = formatRef({ server: "studio#0042", channel: "general", threadRootSeq: 7 });
expect(parseRef(ref)).toEqual({ server: "studio#0042", channel: "general", threadRootSeq: 7 });
});
it("formats a thread-reply message ref (threadRootSeq + seq)", () => {
expect(
formatRef({ server: "studio#0042", channel: "general", threadRootSeq: 5, seq: 42 }),
).toBe("/studio#0042/general/#5#42");
});
it("round-trips through parseRef for the thread-reply form", () => {
const input = { server: "studio#0042", channel: "general", threadRootSeq: 5, seq: 42 };
expect(parseRef(formatRef(input))).toEqual(input);
});
it("throws when seq is provided without threadRootSeq", () => {
expect(() =>
formatRef({ server: "studio#0042", channel: "general", seq: 42 }),
).toThrow();
});
it("formats a plain thread ref unchanged (regression)", () => {
expect(formatRef({ server: "studio#0042", channel: "general", threadRootSeq: 5 })).toBe(
"/studio#0042/general/#5",
);
});
});
describe("formatSeq / parseSeq", () => {
it("formatSeq prefixes with #", () => {
expect(formatSeq(12)).toBe("#12");
});
it("parseSeq strips a leading # if present", () => {
expect(parseSeq("#12")).toBe(12);
});
it("parseSeq accepts a bare number string too", () => {
expect(parseSeq("12")).toBe(12);
});
it("parseSeq throws on a non-numeric value", () => {
expect(() => parseSeq("#abc")).toThrow();
});
});
// The single canonical-ref emitter (B1 trait model, red-line ①). Dispatches the
// ref SHAPE off the channel type's addressing trait so every emit site (agent
// inbox, wake notice, listChannels) produces one addressing identity per type.
describe("formatCanonicalRef", () => {
it("by-server-name (text): /server/name", () => {
expect(formatCanonicalRef({ type: "text", serverHandle: "studio#0042", name: "general" })).toBe("/studio#0042/general");
});
it("by-server-name (forum): /server/name", () => {
expect(formatCanonicalRef({ type: "forum", serverHandle: "studio#0042", name: "ideas" })).toBe("/studio#0042/ideas");
});
it("by-root-seq (thread): /server/channel/#rootSeq", () => {
expect(
formatCanonicalRef({ type: "thread", serverHandle: "studio#0042", parentName: "general", rootSeq: 42 }),
).toBe("/studio#0042/general/#42");
});
it("by-peer-identity (dm): /.dm/peer", () => {
expect(formatCanonicalRef({ type: "dm", peerSegment: "gusye#1231" })).toBe("/.dm/gusye#1231");
});
// Round-trip: every emitted canonical ref must parse back to a ref that
// resolves the same scope — the emitter and parser share the addressing model
// so a ref a bot receives is one it can send/read/ack against (red-line ①).
it("round-trips through parseRef for every addressing trait", () => {
expect(parseRef(formatCanonicalRef({ type: "text", serverHandle: "studio#0042", name: "general" })!)).toEqual({
server: "studio#0042",
channel: "general",
});
expect(
parseRef(formatCanonicalRef({ type: "thread", serverHandle: "studio#0042", parentName: "general", rootSeq: 7 })!),
).toEqual({ server: "studio#0042", channel: "general", threadRootSeq: 7 });
expect(parseRef(formatCanonicalRef({ type: "dm", peerSegment: "gusye#1231" })!)).toEqual({
server: DM_SERVER,
channel: "gusye#1231",
});
});
// Missing-field → null (not a bogus ref): a caller that can't resolve the
// context an addressing value needs keeps its own fallback/skip handling
// rather than emitting a ref that won't round-trip.
it("returns null when a required addressing field is absent", () => {
expect(formatCanonicalRef({ type: "text", serverHandle: "studio#0042" })).toBeNull(); // no name
expect(formatCanonicalRef({ type: "thread", serverHandle: "studio#0042", parentName: "g" })).toBeNull(); // no rootSeq
expect(formatCanonicalRef({ type: "dm" })).toBeNull(); // no peerSegment
});
});
describe("HostCommand nap contract", () => {
const command = { type: "agent:nap", agentId: "bot_1", config: {}, launchId: "launch_1" };
it("accepts an omitted handoff and preserves a supplied note verbatim", () => {
expect(HostCommandSchema.parse(command)).toEqual(command);
const handoff = " Next step\n第二行\n";
expect(HostCommandSchema.parse({ ...command, handoff })).toEqual({ ...command, handoff });
});
it.each(["", " \n\t", null])("rejects an explicit invalid handoff: %j", (handoff) => {
expect(HostCommandSchema.safeParse({ ...command, handoff }).success).toBe(false);
});
});
describe("HostCommand diagnostics contract", () => {
it("accepts the diagnostics arm in the runtime command union", () => {
type DiagnosticCommand = {
type: "diagnostics:collect";
reportId: string;
agentId: string;
fromMs: number;
deadlineAt: number;
};
const command: DiagnosticCommand = {
type: "diagnostics:collect",
reportId: "dbr_0123456789abcdef",
agentId: "bot_1",
fromMs: 1_700_000_000_000,
deadlineAt: 1_700_087_000_000,
};
expect(HostCommandSchema.safeParse(command)).toEqual(
expect.objectContaining({ success: true }),
);
});
});
describe("HostCommand control heartbeat contract", () => {
it("keeps a strict nonce-only arm", () => {
expect(HostCommandSchema.parse({ type: "machine:heartbeat", nonce: "nonce_1" }))
.toEqual({ type: "machine:heartbeat", nonce: "nonce_1" });
expect(HostCommandSchema.safeParse({
type: "machine:heartbeat",
nonce: "nonce_1",
machineId: "injected",
}).success).toBe(false);
});
});
describe("HostCommand runtime config update contract", () => {
it("accepts the revisioned config arm in the runtime command union", () => {
const config = {
version: 1,
runtime: "codex",
model: { kind: "default" as const },
mode: { kind: "default" as const },
reasoningEffort: "xhigh",
runtimeConfigRevision: 8,
};
expect(HostCommandSchema.parse({
type: "agent:runtime_config_update",
agentId: "bot_1",
config,
})).toEqual({ type: "agent:runtime_config_update", agentId: "bot_1", config });
});
});
describe("HostCommand machine update contract", () => {
it("accepts the payload-free update arm in the strict runtime schema", () => {
expect(HostCommandSchema.safeParse({ type: "machine:update" })).toEqual(
expect.objectContaining({ success: true }),
);
});
it.each(["package", "version", "url", "command"])(
"rejects an extra %s field instead of stripping it",
(field) => {
expect(HostCommandSchema.safeParse({ type: "machine:update", [field]: "attacker" }).success)
.toBe(false);
},
);
});
describe("HostCommand machine stop contract", () => {
it("accepts only the payload-free stop command", () => {
expect(HostCommandSchema.parse({ type: "machine:stop" })).toEqual({ type: "machine:stop" });
for (const field of ["machineId", "command", "force", "delete", "credential"]) {
expect(HostCommandSchema.safeParse({ type: "machine:stop", [field]: "extra" }).success).toBe(false);
}
});
});