agent-relay-server 0.42.0 → 0.44.0

package/src/db/delivery.ts

@@ -174,6 +174,10 @@ export function matchingDeliveryAgents(target: string): AgentCard[] {
     const label = target.slice(6);
     return candidates.filter((agent) => agent.label === label);
   }
+  if (target.startsWith("team:")) {
+    const teamId = target.slice(5);
+    return candidates.filter((agent) => agent.teamId === teamId);
+  }
   return [];
 }
 
@@ -392,4 +396,3 @@ export function expireQueuedMessages(now: number = Date.now()): Message[] {
   })();
   return ids.map((id) => getMessage(id)).filter((message): message is Message => Boolean(message));
 }
-

package/src/db/index.ts

@@ -24,3 +24,4 @@ export * from "./merge-lease.ts";
 export * from "./continuations.ts";
 export * from "./continuation-archives.ts";
 export * from "./plans.ts";
+export * from "./teams.ts";

package/src/db/mappers.ts

@@ -130,6 +130,7 @@ export function rowToAgent(row: any): AgentCard {
     context: parseJson<ContextState | undefined>(row.context_state, undefined),
     meta: parseJson(row.meta, {}),
     spawnedBy: row.spawned_by ?? undefined,
+    teamId: row.team_id ?? undefined,
     lastSeen: row.last_seen,
     createdAt: row.created_at,
   };
@@ -394,4 +395,3 @@ export const MSG_SELECT = `SELECT m.*, (
 ) AS reactions_json FROM messages m`;
 
 // --- Agents ---
-

package/src/db/message-reads.ts

@@ -162,6 +162,7 @@ export function pollMessages(query: PollQuery): Message[] {
   const agentTags = agent?.tags ?? [];
   const agentCaps = agent?.capabilities ?? [];
   const agentLabel = agent?.label;
+  const agentTeamId = agent?.teamId;
   const agentLegacyChannelTargets = legacyChannelTargets(agent);
 
   const conditions: string[] = [];
@@ -186,11 +187,19 @@ export function pollMessages(query: PollQuery): Message[] {
     targetClauses.push("to_target = ?");
     params.push(`label:${agentLabel}`);
   }
+  if (agentTeamId) {
+    targetClauses.push("to_target = ?");
+    params.push(`team:${agentTeamId}`);
+  }
   for (const target of agentLegacyChannelTargets) {
     targetClauses.push("to_target = ?");
     params.push(target);
   }
   conditions.push(`(${targetClauses.join(" OR ")})`);
+  if (agentTeamId) {
+    conditions.push("(from_agent != ? OR to_target != ?)");
+    params.push(query.for, `team:${agentTeamId}`);
+  }
   conditions.push("delivery_status != 'queued' AND delivery_status NOT IN ('failed', 'dead')");
 
   // Hide active claims held by someone else, but let expired claims surface so
@@ -323,7 +332,7 @@ export function markRead(messageId: number, agentId: string): boolean {
         delivery_next_retry_at = NULL,
         delivery_poison_reason = NULL,
         delivery_updated_at = ?
-    WHERE id = ? AND (to_target = ? OR resolved_to_agent = ? OR to_target = 'broadcast' OR to_target LIKE 'tag:%' OR to_target LIKE 'cap:%' OR to_target LIKE 'label:%')
+    WHERE id = ? AND (to_target = ? OR resolved_to_agent = ? OR to_target = 'broadcast' OR to_target LIKE 'tag:%' OR to_target LIKE 'cap:%' OR to_target LIKE 'label:%' OR to_target LIKE 'team:%')
   `).run(Date.now(), messageId, agentId, agentId);
   return true;
 }

package/src/db/migrations.ts

@@ -279,22 +279,70 @@ export function applyMigrations(): void {
   // which runs per persisted session step. Added here (not the base schema) because the column
   // is migration-added for pre-hardening DBs. Without it that lookup full-scans messages.
   getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_idempotency ON messages(from_agent, idempotency_key)");
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS teams (
+      id TEXT PRIMARY KEY,
+      coordinator_id TEXT,
+      root_coordinator_id TEXT,
+      title TEXT,
+      brief TEXT,
+      definition_of_done TEXT,
+      status TEXT NOT NULL DEFAULT 'active',
+      outcome_status TEXT,
+      outcome_summary TEXT,
+      composition TEXT,
+      cost_tokens INTEGER,
+      cost_usd REAL,
+      wall_clock_ms INTEGER,
+      lands_clean INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      dissolved_at INTEGER
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_teams_coordinator ON teams(coordinator_id)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_teams_status ON teams(status)");
   getDb().run(`
     CREATE TABLE IF NOT EXISTS plans (
-      id TEXT PRIMARY KEY, thread_id INTEGER NOT NULL, channel TEXT, version INTEGER NOT NULL DEFAULT 1,
+      id TEXT PRIMARY KEY, thread_id INTEGER NOT NULL, team_id TEXT, channel TEXT, version INTEGER NOT NULL DEFAULT 1,
       title TEXT, objective TEXT, nodes TEXT NOT NULL DEFAULT '[]', edges TEXT NOT NULL DEFAULT '[]',
       created_by TEXT NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
     )
   `);
+  const planCols = getDb().query("PRAGMA table_info(plans)").all() as any[];
+  const planColNames = planCols.map((c: any) => c.name);
+  if (!planColNames.includes("team_id")) {
+    getDb().run("ALTER TABLE plans ADD COLUMN team_id TEXT");
+  }
   getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_plans_thread_channel ON plans(thread_id, coalesce(channel, ''))");
   getDb().run("CREATE INDEX IF NOT EXISTS idx_plans_updated ON plans(updated_at)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_plans_team ON plans(team_id)");
   getDb().run(`
     CREATE TABLE IF NOT EXISTS plan_versions (
-      id INTEGER PRIMARY KEY AUTOINCREMENT, plan_id TEXT NOT NULL REFERENCES plans(id) ON DELETE CASCADE,
+      id INTEGER PRIMARY KEY AUTOINCREMENT, plan_id TEXT NOT NULL,
       version INTEGER NOT NULL, title TEXT, objective TEXT, nodes TEXT NOT NULL, edges TEXT NOT NULL,
       changed_by TEXT, changed_at INTEGER NOT NULL
     )
   `);
+  const planVersionFks = getDb().query("PRAGMA foreign_key_list(plan_versions)").all() as any[];
+  if (planVersionFks.some((fk) => fk.table === "plans" && String(fk.on_delete).toUpperCase() === "CASCADE")) {
+    getDb().transaction(() => {
+      getDb().run("ALTER TABLE plan_versions RENAME TO plan_versions_old");
+      getDb().run(`
+        CREATE TABLE plan_versions (
+          id INTEGER PRIMARY KEY AUTOINCREMENT, plan_id TEXT NOT NULL,
+          version INTEGER NOT NULL, title TEXT, objective TEXT, nodes TEXT NOT NULL, edges TEXT NOT NULL,
+          changed_by TEXT, changed_at INTEGER NOT NULL
+        )
+      `);
+      getDb().run(`
+        INSERT INTO plan_versions (id, plan_id, version, title, objective, nodes, edges, changed_by, changed_at)
+        SELECT id, plan_id, version, title, objective, nodes, edges, changed_by, changed_at
+        FROM plan_versions_old
+      `);
+      getDb().run("DROP TABLE plan_versions_old");
+    })();
+  }
   getDb().run("CREATE INDEX IF NOT EXISTS idx_plan_versions_plan ON plan_versions(plan_id, version DESC)");
 
   // Backfill thread_id for pre-migration rows (self-threaded).
@@ -372,6 +420,10 @@ export function applyMigrations(): void {
   if (!agentColNames.includes("spawned_by")) {
     getDb().run("ALTER TABLE agents ADD COLUMN spawned_by TEXT");
   }
+  if (!agentColNames.includes("team_id")) {
+    getDb().run("ALTER TABLE agents ADD COLUMN team_id TEXT");
+  }
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_agents_team ON agents(team_id)");
   getDb().run(`
     CREATE TABLE IF NOT EXISTS context_snapshots (
       id INTEGER PRIMARY KEY AUTOINCREMENT,

package/src/db/plans.ts

@@ -6,6 +6,7 @@ import type { Plan, PlanEdge, PlanNode } from "../types";
 interface PlanRow {
   id: string;
   thread_id: number;
+  team_id: string | null;
   channel: string | null;
   version: number;
   title: string | null;
@@ -49,6 +50,7 @@ function rowToPlan(row: PlanRow): Plan {
   return {
     id: row.id,
     threadId: String(row.thread_id),
+    ...(row.team_id ? { teamId: row.team_id } : {}),
     ...(row.channel ? { channel: row.channel } : {}),
     version: row.version,
     ...(row.title ? { title: row.title } : {}),
@@ -82,6 +84,7 @@ export function planThreadExists(threadId: number): boolean {
 export function createPlanRow(input: {
   id?: string;
   threadId: number;
+  teamId?: string;
   channel?: string;
   title?: string;
   objective?: string;
@@ -93,11 +96,12 @@ export function createPlanRow(input: {
   const now = Date.now();
   try {
     getDb().query(`
-      INSERT INTO plans (id, thread_id, channel, version, title, objective, nodes, edges, created_by, created_at, updated_at)
-      VALUES (?, ?, ?, 1, ?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO plans (id, thread_id, team_id, channel, version, title, objective, nodes, edges, created_by, created_at, updated_at)
+      VALUES (?, ?, ?, ?, 1, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       id,
       input.threadId,
+      input.teamId ?? null,
       input.channel ?? null,
       input.title ?? null,
       input.objective ?? null,
@@ -128,6 +132,17 @@ export function getPlanByThread(threadId: number, channel?: string): Plan | null
   return row ? rowToPlan(row) : null;
 }
 
+export function getPlanByTeam(teamId: string, channel?: string): Plan | null {
+  const row = channel === undefined
+    ? getDb()
+      .query("SELECT * FROM plans WHERE team_id = ? ORDER BY updated_at DESC LIMIT 1")
+      .get(teamId) as PlanRow | undefined
+    : getDb()
+      .query("SELECT * FROM plans WHERE team_id = ? AND coalesce(channel, '') = ? ORDER BY updated_at DESC LIMIT 1")
+      .get(teamId, channel) as PlanRow | undefined;
+  return row ? rowToPlan(row) : null;
+}
+
 export function replacePlan(input: Plan, changedBy?: string): Plan {
   const existing = getPlan(input.id);
   if (!existing) throw new ValidationError(`plan ${input.id} not found`);

package/src/db/schema.ts

@@ -106,10 +106,10 @@ export function initDb(path: string = "agent-relay.db"): Database {
       context_state TEXT,
       meta TEXT NOT NULL DEFAULT '{}',
       spawned_by TEXT,
+      team_id TEXT,
       last_seen INTEGER NOT NULL,
       created_at INTEGER NOT NULL
     );
-
     CREATE TABLE IF NOT EXISTS messages (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       from_agent TEXT NOT NULL,
@@ -150,15 +150,36 @@ export function initDb(path: string = "agent-relay.db"): Database {
     -- per candidate row (O(n^2)): ~8.6s at 4k rows, which blew the 5s Stop-hook
     -- timeout and wedged turns in "busy" (#199).
     CREATE INDEX IF NOT EXISTS idx_msg_reply_to ON messages(reply_to, from_agent);
+    CREATE TABLE IF NOT EXISTS teams (
+      id TEXT PRIMARY KEY,
+      coordinator_id TEXT,
+      root_coordinator_id TEXT,
+      title TEXT,
+      brief TEXT,
+      definition_of_done TEXT,
+      status TEXT NOT NULL DEFAULT 'active',
+      outcome_status TEXT,
+      outcome_summary TEXT,
+      composition TEXT,
+      cost_tokens INTEGER,
+      cost_usd REAL,
+      wall_clock_ms INTEGER,
+      lands_clean INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      dissolved_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_teams_coordinator ON teams(coordinator_id);
+    CREATE INDEX IF NOT EXISTS idx_teams_status ON teams(status);
     CREATE TABLE IF NOT EXISTS plans (
-      id TEXT PRIMARY KEY, thread_id INTEGER NOT NULL, channel TEXT, version INTEGER NOT NULL DEFAULT 1,
+      id TEXT PRIMARY KEY, thread_id INTEGER NOT NULL, team_id TEXT, channel TEXT, version INTEGER NOT NULL DEFAULT 1,
       title TEXT, objective TEXT, nodes TEXT NOT NULL DEFAULT '[]', edges TEXT NOT NULL DEFAULT '[]',
       created_by TEXT NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
     );
     CREATE UNIQUE INDEX IF NOT EXISTS idx_plans_thread_channel ON plans(thread_id, coalesce(channel, ''));
     CREATE INDEX IF NOT EXISTS idx_plans_updated ON plans(updated_at);
     CREATE TABLE IF NOT EXISTS plan_versions (
-      id INTEGER PRIMARY KEY AUTOINCREMENT, plan_id TEXT NOT NULL REFERENCES plans(id) ON DELETE CASCADE,
+      id INTEGER PRIMARY KEY AUTOINCREMENT, plan_id TEXT NOT NULL,
       version INTEGER NOT NULL, title TEXT, objective TEXT, nodes TEXT NOT NULL, edges TEXT NOT NULL,
       changed_by TEXT, changed_at INTEGER NOT NULL
     );

package/src/db/teams.ts

@@ -0,0 +1,151 @@
+import { randomUUID } from "node:crypto";
+import { getAgent, setAgentTeam } from "./agents.ts";
+import { getDb, ValidationError } from "./connection.ts";
+import { rowToAgent } from "./mappers.ts";
+import type { AgentCard, Team } from "../types";
+
+interface TeamRow {
+  id: string;
+  coordinator_id: string | null;
+  root_coordinator_id: string | null;
+  title: string | null;
+  brief: string | null;
+  definition_of_done: string | null;
+  status: Team["status"];
+  outcome_status: Team["outcomeStatus"] | null;
+  outcome_summary: string | null;
+  composition: string | null;
+  cost_tokens: number | null;
+  cost_usd: number | null;
+  wall_clock_ms: number | null;
+  lands_clean: number | null;
+  created_at: number;
+  updated_at: number;
+  dissolved_at: number | null;
+}
+
+export interface TeamDissolveInput {
+  outcomeStatus?: Team["outcomeStatus"];
+  outcomeSummary?: string;
+  landsClean?: boolean;
+}
+
+export function teamId(): string {
+  return `team_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+}
+
+function rowToTeam(row: TeamRow): Team {
+  return {
+    id: row.id,
+    ...(row.coordinator_id ? { coordinatorId: row.coordinator_id } : {}),
+    ...(row.root_coordinator_id ? { rootCoordinatorId: row.root_coordinator_id } : {}),
+    ...(row.title ? { title: row.title } : {}),
+    ...(row.brief ? { brief: row.brief } : {}),
+    ...(row.definition_of_done ? { definitionOfDone: row.definition_of_done } : {}),
+    status: row.status,
+    ...(row.outcome_status ? { outcomeStatus: row.outcome_status } : {}),
+    ...(row.outcome_summary ? { outcomeSummary: row.outcome_summary } : {}),
+    ...(row.composition ? { composition: row.composition } : {}),
+    ...(row.cost_tokens !== null ? { costTokens: row.cost_tokens } : {}),
+    ...(row.cost_usd !== null ? { costUsd: row.cost_usd } : {}),
+    ...(row.wall_clock_ms !== null ? { wallClockMs: row.wall_clock_ms } : {}),
+    ...(row.lands_clean !== null ? { landsClean: row.lands_clean === 1 } : {}),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    ...(row.dissolved_at !== null ? { dissolvedAt: row.dissolved_at } : {}),
+  };
+}
+
+export function getTeam(id: string): Team | null {
+  const row = getDb().query("SELECT * FROM teams WHERE id = ?").get(id) as TeamRow | undefined;
+  return row ? rowToTeam(row) : null;
+}
+
+export function getTeamRoster(teamId: string): AgentCard[] {
+  const rows = getDb()
+    .query("SELECT * FROM agents WHERE team_id = ? ORDER BY created_at ASC, id ASC")
+    .all(teamId) as any[];
+  return rows.map(rowToAgent);
+}
+
+export function ensureTeam(coordinatorId: string): Team {
+  const coordinator = getAgent(coordinatorId);
+  if (!coordinator) throw new ValidationError(`coordinator agent ${coordinatorId} not found`);
+  if (coordinator.teamId) {
+    const existing = getTeam(coordinator.teamId);
+    if (existing) return existing;
+  }
+
+  const id = teamId();
+  const now = Date.now();
+  getDb().transaction(() => {
+    getDb().query(`
+      INSERT INTO teams (id, coordinator_id, root_coordinator_id, status, created_at, updated_at)
+      VALUES (?, ?, ?, 'active', ?, ?)
+    `).run(id, coordinatorId, coordinatorId, now, now);
+    setAgentTeam(coordinatorId, id);
+  })();
+  return getTeam(id)!;
+}
+
+export function setTeamBrief(input: {
+  teamId: string;
+  title?: string;
+  brief?: string;
+  definitionOfDone?: string;
+}): Team {
+  const existing = getTeam(input.teamId);
+  if (!existing) throw new ValidationError(`team ${input.teamId} not found`);
+  const now = Date.now();
+  getDb().query(`
+    UPDATE teams
+    SET title = ?, brief = ?, definition_of_done = ?, updated_at = ?
+    WHERE id = ?
+  `).run(
+    input.title ?? null,
+    input.brief ?? null,
+    input.definitionOfDone ?? null,
+    now,
+    input.teamId,
+  );
+  return getTeam(input.teamId)!;
+}
+
+function compositionForMembers(members: AgentCard[]): string {
+  return JSON.stringify(members.map((agent) => ({
+    id: agent.id,
+    label: agent.label,
+    role: typeof agent.meta?.role === "string" ? agent.meta.role : undefined,
+    provider: agent.providerCapabilities?.model?.provider,
+    model: agent.providerCapabilities?.model?.id ?? agent.providerCapabilities?.model?.alias,
+  })));
+}
+
+export function dissolveTeam(teamId: string, input: TeamDissolveInput = {}): Team {
+  const existing = getTeam(teamId);
+  if (!existing) throw new ValidationError(`team ${teamId} not found`);
+  const members = getTeamRoster(teamId);
+  const now = Date.now();
+  getDb().query(`
+    UPDATE teams
+    SET status = 'dissolved',
+        outcome_status = ?,
+        outcome_summary = ?,
+        composition = ?,
+        wall_clock_ms = ?,
+        lands_clean = ?,
+        dissolved_at = ?,
+        updated_at = ?
+    WHERE id = ?
+  `).run(
+    input.outcomeStatus ?? null,
+    input.outcomeSummary ?? null,
+    compositionForMembers(members),
+    Math.max(0, now - existing.createdAt),
+    input.landsClean === undefined ? null : input.landsClean ? 1 : 0,
+    now,
+    now,
+    teamId,
+  );
+  return getTeam(teamId)!;
+}

package/src/mcp-plan-tools.ts

@@ -5,6 +5,7 @@ import {
   addPlanEdge,
   addPlanNode,
   createPlan,
+  deletePlanGraph,
   getPlanGraph,
   removePlanEdge,
   removePlanNode,
@@ -47,6 +48,7 @@ export const PLAN_TOOLS = [
       type: "object",
       properties: {
         threadId: { oneOf: [{ type: "string" }, { type: "integer", minimum: 1 }] },
+        teamId: { type: "string" },
         channel: { type: "string" },
         title: { type: "string" },
         objective: { type: "string" },
@@ -81,13 +83,14 @@ export const PLAN_TOOLS = [
   { name: "relay_plan_add_edge", description: "Add a dependency edge to a plan DAG; rejects cycles.", requiredScopes: ["plans:write"], inputSchema: { type: "object", properties: { planId: { type: "string" }, from: { type: "string" }, to: { type: "string" } }, required: ["planId", "from", "to"], additionalProperties: false } },
   { name: "relay_plan_remove_node", description: "Remove a node and its connected edges from a plan DAG.", requiredScopes: ["plans:write"], inputSchema: { type: "object", properties: { planId: { type: "string" }, nodeId: { type: "string" } }, required: ["planId", "nodeId"], additionalProperties: false } },
   { name: "relay_plan_remove_edge", description: "Remove a dependency edge from a plan DAG.", requiredScopes: ["plans:write"], inputSchema: { type: "object", properties: { planId: { type: "string" }, from: { type: "string" }, to: { type: "string" } }, required: ["planId", "from", "to"], additionalProperties: false } },
+  { name: "relay_plan_delete", description: "Delete a persisted plan DAG and archive its latest version.", requiredScopes: ["plans:write"], inputSchema: { type: "object", properties: { planId: { type: "string" } }, required: ["planId"], additionalProperties: false } },
   {
     name: "relay_plan_get",
-    description: "Fetch a plan by planId or by threadId/channel.",
+    description: "Fetch a plan by planId, teamId, or by threadId/channel.",
     requiredScopes: ["plans:read"],
     inputSchema: {
       type: "object",
-      properties: { planId: { type: "string" }, threadId: { oneOf: [{ type: "string" }, { type: "integer", minimum: 1 }] }, channel: { type: "string" } },
+      properties: { planId: { type: "string" }, teamId: { type: "string" }, threadId: { oneOf: [{ type: "string" }, { type: "integer", minimum: 1 }] }, channel: { type: "string" } },
       additionalProperties: false,
     },
   },
@@ -111,8 +114,9 @@ export function relayPlanTool(auth: McpAuthLike, name: string, args: Record<stri
   if (name === "relay_plan_add_edge") return addPlanEdge(stringArg(args.planId, "planId"), { from: args.from, to: args.to }, ctx) as unknown as Record<string, unknown>;
   if (name === "relay_plan_remove_node") return removePlanNode(stringArg(args.planId, "planId"), stringArg(args.nodeId, "nodeId"), ctx) as unknown as Record<string, unknown>;
   if (name === "relay_plan_remove_edge") return removePlanEdge(stringArg(args.planId, "planId"), { from: args.from, to: args.to }, ctx) as unknown as Record<string, unknown>;
+  if (name === "relay_plan_delete") return deletePlanGraph(stringArg(args.planId, "planId"), ctx);
   if (name === "relay_plan_get") {
-    const plan = getPlanGraph({ planId: args.planId, threadId: args.threadId, channel: args.channel });
+    const plan = getPlanGraph({ planId: args.planId, teamId: args.teamId, threadId: args.threadId, channel: args.channel });
     if (!plan) throw new McpNotFoundError("plan not found");
     return plan as unknown as Record<string, unknown>;
   }

package/src/mcp-team-tools.ts

@@ -0,0 +1,87 @@
+import { McpAuthError, McpNotFoundError } from "./mcp-errors";
+import { authContextFromMcp } from "./services/auth-context";
+import { ValidationError } from "./db";
+import { dissolveCallerTeam, getCallerTeam, setCallerTeamBrief, TeamAuthError, TeamNotFoundError } from "./services/team";
+import { cleanString, optionalEnum } from "./validation";
+import type { Team } from "./types";
+
+const OUTCOME_STATUSES = ["success", "partial", "failed"] as const;
+
+export const TEAM_TOOLS = [
+  {
+    name: "relay_team_get",
+    description: "Return the caller's team row, live roster, shared brief/definition of done, and any bound plan.",
+    requiredScopes: ["teams:read"],
+    inputSchema: {
+      type: "object",
+      properties: { channel: { type: "string" } },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_team_set_brief",
+    description: "Create/update the caller's team brief, title, and definition of done. Lazily mints a team when needed.",
+    requiredScopes: ["teams:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string" },
+        brief: { type: "string" },
+        definitionOfDone: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_team_dissolve",
+    description: "Dissolve the caller's team and freeze the composition/outcome snapshot. Does not kill members.",
+    requiredScopes: ["teams:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        outcomeStatus: { type: "string", enum: OUTCOME_STATUSES },
+        outcomeSummary: { type: "string" },
+        landsClean: { type: "boolean" },
+      },
+      additionalProperties: false,
+    },
+  },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type McpAuthLike = Parameters<typeof authContextFromMcp>[0];
+
+function mapTeamError(error: unknown): never {
+  if (error instanceof TeamAuthError) throw new McpAuthError(error.message);
+  if (error instanceof TeamNotFoundError) throw new McpNotFoundError(error.message);
+  throw error;
+}
+
+export function relayTeamTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Record<string, unknown> {
+  const ctx = authContextFromMcp(auth);
+  try {
+    if (name === "relay_team_get") {
+      return getCallerTeam(ctx, cleanString(args.channel, "channel", { max: 120 })) as unknown as Record<string, unknown>;
+    }
+    if (name === "relay_team_set_brief") {
+      return setCallerTeamBrief(ctx, {
+        title: cleanString(args.title, "title", { max: 240 }),
+        brief: cleanString(args.brief, "brief", { max: 16_000 }),
+        definitionOfDone: cleanString(args.definitionOfDone, "definitionOfDone", { max: 4000 }),
+      }) as unknown as Record<string, unknown>;
+    }
+    if (name === "relay_team_dissolve") {
+      return dissolveCallerTeam(ctx, {
+        outcomeStatus: optionalEnum(args.outcomeStatus, "outcomeStatus", OUTCOME_STATUSES) as Team["outcomeStatus"] | undefined,
+        outcomeSummary: cleanString(args.outcomeSummary, "outcomeSummary", { max: 4000 }),
+        landsClean: args.landsClean === undefined || args.landsClean === null
+          ? undefined
+          : typeof args.landsClean === "boolean"
+            ? args.landsClean
+            : (() => { throw new ValidationError("landsClean must be a boolean"); })(),
+      }) as unknown as Record<string, unknown>;
+    }
+  } catch (error) {
+    mapTeamError(error);
+  }
+  throw new ValidationError(`unknown tool: ${name}`);
+}

package/src/mcp.ts

@@ -47,6 +47,7 @@ import {
 import { sendMessageService } from "./services/send-message";
 import { ServiceAuthError } from "./services/errors";
 import { PLAN_TOOLS, relayPlanTool } from "./mcp-plan-tools";
+import { TEAM_TOOLS, relayTeamTool } from "./mcp-team-tools";
 import type { ActivityKind, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
 import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
 import { AUTO_MERGE_POLICIES } from "./workspace-merge";
@@ -101,7 +102,7 @@ const TOOLS: ToolDefinition[] = [
       type: "object",
       properties: {
         from: { type: "string", description: "Deprecated/optional. Your identity is taken from your auth token; ignored for managed agents. You never need to set this." },
-        to: { type: "string", description: "Target: an agent id, label, name, or a unique id segment (e.g. the number part) — resolved automatically. Or a fan-out selector: tag:, cap:, label:, policy:, or broadcast." },
+        to: { type: "string", description: "Target: an agent id, label, name, or a unique id segment (e.g. the number part) — resolved automatically. Or a fan-out selector: tag:, cap:, label:, team:, policy:, or broadcast." },
         body: { type: "string" },
         subject: { type: "string" },
         channel: { type: "string" },
@@ -232,6 +233,7 @@ const TOOLS: ToolDefinition[] = [
         kind: { type: ["string", "array"], items: { type: "string" } },
         status: { type: ["string", "array"], items: { type: "string" }, description: "online/idle/busy/offline/stale, the 'running' shorthand, or 'all'. Default 'running'." },
         spawnedBy: { type: "string", description: "Parent agent id, or 'me' for your own spawned children (#221)." },
+        teamId: { type: "string", description: "Durable team id for roster filtering." },
         sortBy: { type: "string", enum: ["lastActive", "created", "label"] },
         order: { type: "string", enum: ["asc", "desc"] },
         limit: { type: "integer", minimum: 1, maximum: 200 },
@@ -456,6 +458,7 @@ const TOOLS: ToolDefinition[] = [
       additionalProperties: false,
     },
   },
+  ...TEAM_TOOLS,
   ...PLAN_TOOLS,
 ];
 
@@ -568,6 +571,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_workspace_claim") result = relayWorkspaceMutation(auth, "claim", args);
     else if (name === "relay_workspace_release") result = relayWorkspaceMutation(auth, "release-claim", args);
     else if (name === "relay_workspace_land") result = relayWorkspaceMutation(auth, "merge", args);
+    else if (name.startsWith("relay_team_")) result = relayTeamTool(auth, name, args);
     else if (name.startsWith("relay_plan_")) result = relayPlanTool(auth, name, args);
     else throw new ValidationError(`unknown tool: ${name}`);
 
@@ -831,6 +835,7 @@ function relayFindAgents(auth: McpAuthContext, args: Record<string, unknown>): R
     machine: optionalStringOrArray(args.machine, "machine"),
     kind: optionalStringOrArray(args.kind, "kind"),
     spawnedBy,
+    teamId: optionalString(args.teamId, "teamId", 120),
     // Default to running — you can only act on a live agent (consistent with #218).
     status: optionalStringOrArray(args.status, "status") ?? "running",
   };

package/src/routes/index.ts

@@ -30,6 +30,7 @@ import { getPlanByIdRoute, getPlansRoute } from "./plans";
 import { getRecipeByName, getRecipeInstanceArtifacts, getRecipeInstanceById, getRecipeInstances, getRecipes, postRecipeInstanceArtifacts, postRecipeStart, postRecipeStop } from "./recipes";
 import { getStewardConfigRoute, getWorkspaceConfigRoute, putStewardConfigRoute, putWorkspaceConfigRoute } from "./steward";
 import { getTaskById, getTaskEvents, getTasks, patchTaskStatus, postClaimTask, postRenewTaskClaim } from "./tasks";
+import { getMyTeamRoute, postMyTeamDissolveRoute, putMyTeamBriefRoute } from "./teams";
 import { postMcp } from "../mcp";
 import { postOrchestratorBootstrap, postOrchestratorBootstrapExchange } from "./orchestrator-bootstrap";
 
@@ -135,6 +136,9 @@ const routes: Route[] = [
   route("DELETE", "/api/workspaces/:id", deleteWorkspaceById),
 
   route("POST", "/api/system/broadcast", postSystemBroadcast),
+  route("GET", "/api/teams/me", getMyTeamRoute),
+  route("PUT", "/api/teams/me/brief", putMyTeamBriefRoute),
+  route("POST", "/api/teams/me/dissolve", postMyTeamDissolveRoute),
   route("GET", "/api/recipes", getRecipes),
   route("POST", "/api/recipes/start", postRecipeStart),
   route("GET", "/api/recipes/instances", getRecipeInstances),

package/src/routes/integrations.ts

@@ -9,7 +9,7 @@ import { isRecord } from "agent-relay-sdk";
 import { parseChannelRouteTarget } from "../channel-target.ts";
 import { type ChannelBinding, type ChannelBindingMode, type ChannelRouteTarget, type ChannelSummary, type IntegrationEventInput, type IntegrationSummary } from "../types";
 
-const VALID_CHANNEL_BINDING_TARGET_TYPES = ["agent", "label", "tag", "capability", "broadcast", "orchestrator", "pool", "policy"] as const;
+const VALID_CHANNEL_BINDING_TARGET_TYPES = ["agent", "label", "team", "tag", "capability", "broadcast", "orchestrator", "pool", "policy"] as const;
 
 const VALID_CHANNEL_BINDING_MODES = ["exclusive", "broadcast"] as const;
 
@@ -59,6 +59,7 @@ function messageTargetForChannelTarget(target: ChannelRouteTarget, binding?: Cha
     return binding.poolAgentId;
   }
   if (target.type === "label") return `label:${target.id}`;
+  if (target.type === "team") return `team:${target.id}`;
   if (target.type === "tag") return `tag:${target.id}`;
   if (target.type === "capability") return `cap:${target.id}`;
   if (target.type === "broadcast") return "broadcast";

package/src/routes/messages.ts

@@ -66,7 +66,7 @@ function normalizeMessageInput(body: unknown): SendMessageInput {
   return input;
 }
 
-const FANOUT_PREFIXES = ["tag:", "cap:", "label:"];
+const FANOUT_PREFIXES = ["tag:", "cap:", "label:", "team:"];
 
 function isDirectTarget(to: string): boolean {
   return to !== "broadcast" && !FANOUT_PREFIXES.some((p) => to.startsWith(p));

package/src/routes/plans.ts

@@ -5,10 +5,16 @@ import { error, json, parseQueryInt, type Handler } from "./_shared";
 
 export const getPlansRoute: Handler = (req) => {
   const url = new URL(req.url);
-  const threadId = parseQueryInt(url.searchParams.get("threadId"), { min: 1, max: Number.MAX_SAFE_INTEGER });
-  if (threadId === null) return error("threadId required");
-  if (Number.isNaN(threadId)) return error("threadId must be a positive integer");
   const channel = cleanString(url.searchParams.get("channel") ?? undefined, "channel", { max: 120 });
+  const teamId = cleanString(url.searchParams.get("teamId") ?? undefined, "teamId", { max: 120 });
+  if (teamId) {
+    const plan = getPlanGraph({ teamId, channel });
+    return plan ? json(plan) : error("plan not found", 404);
+  }
+  const rawThreadId = url.searchParams.get("threadId");
+  if (rawThreadId === null) return error("threadId or teamId required");
+  const threadId = parseQueryInt(rawThreadId, { min: 1, max: Number.MAX_SAFE_INTEGER });
+  if (Number.isNaN(threadId)) return error("threadId must be a positive integer");
   const plan = getPlanGraph({ threadId, channel });
   return plan ? json(plan) : error("plan not found", 404);
 };