agent-relay-server 0.42.0 → 0.43.0

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/teams.ts

@@ -0,0 +1,60 @@
+import { McpAuthError, McpNotFoundError } from "../mcp-errors";
+import { authContextFromRequest } from "../services/auth-context";
+import { ValidationError } from "../db";
+import { dissolveCallerTeam, getCallerTeam, setCallerTeamBrief, TeamAuthError, TeamNotFoundError } from "../services/team";
+import { cleanString, optionalEnum } from "../validation";
+import { error, json, parseBody, type Handler } from "./_shared";
+import type { Team } from "../types";
+
+const OUTCOME_STATUSES = ["success", "partial", "failed"] as const;
+
+function routeError(err: unknown): Response {
+  if (err instanceof TeamAuthError || err instanceof McpAuthError) return error(err.message, 403);
+  if (err instanceof TeamNotFoundError || err instanceof McpNotFoundError) return error(err.message, 404);
+  if (err instanceof Error) return error(err.message);
+  return error("team route failed");
+}
+
+export const getMyTeamRoute: Handler = (req) => {
+  try {
+    const channel = cleanString(new URL(req.url).searchParams.get("channel") ?? undefined, "channel", { max: 120 });
+    return json(getCallerTeam(authContextFromRequest(req), channel));
+  } catch (err) {
+    return routeError(err);
+  }
+};
+
+export const putMyTeamBriefRoute: Handler = async (req) => {
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const body = parsed.body ?? {};
+    return json(setCallerTeamBrief(authContextFromRequest(req), {
+      title: cleanString(body.title, "title", { max: 240 }),
+      brief: cleanString(body.brief, "brief", { max: 16_000 }),
+      definitionOfDone: cleanString(body.definitionOfDone, "definitionOfDone", { max: 4000 }),
+    }));
+  } catch (err) {
+    return routeError(err);
+  }
+};
+
+export const postMyTeamDissolveRoute: Handler = async (req) => {
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const body = parsed.body ?? {};
+    const landsClean = body.landsClean;
+    return json(dissolveCallerTeam(authContextFromRequest(req), {
+      outcomeStatus: optionalEnum(body.outcomeStatus, "outcomeStatus", OUTCOME_STATUSES) as Team["outcomeStatus"] | undefined,
+      outcomeSummary: cleanString(body.outcomeSummary, "outcomeSummary", { max: 4000 }),
+      landsClean: landsClean === undefined || landsClean === null
+        ? undefined
+        : typeof landsClean === "boolean"
+          ? landsClean
+          : (() => { throw new ValidationError("landsClean must be a boolean"); })(),
+    }));
+  } catch (err) {
+    return routeError(err);
+  }
+};

package/src/runtime-tokens.ts

@@ -10,9 +10,10 @@ import type { TokenRecord } from "./types";
 // purpose — that scope must stay for heartbeat/status without implying spawn rights.
 const SPAWN_SCOPES = ["command:spawn", "command:shutdown"] as const;
 
-function runnerScopeWithSpawn(canSpawn: boolean): string[] | undefined {
-  if (!canSpawn) return undefined; // undefined → createToken falls back to the profile's scope
+function runnerScopeWithSpawn(canSpawn: boolean, agentInitiated?: boolean): string[] | undefined {
   const base = getTokenProfile("provider-agent")?.scope ?? [];
+  if (agentInitiated) return base.filter((scope) => scope !== "teams:write");
+  if (!canSpawn) return undefined; // undefined → createToken falls back to the profile's scope
   return [...base, ...SPAWN_SCOPES];
 }
 
@@ -101,6 +102,8 @@ export function issueRunnerRuntimeToken(input: {
   agentInitiated?: boolean;
   /** Parent agent id — stamped so the child registers with an authoritative `spawnedBy`. */
   spawnedBy?: string;
+  /** Durable team id — stamped so the child registers into the coordinator's team. */
+  teamId?: string;
 }): RuntimeTokenResult {
   const grant = spawnGrantForProfile(input.profile, input.agentInitiated);
   const subject = input.policyName
@@ -112,7 +115,7 @@ export function issueRunnerRuntimeToken(input: {
     profileId: "provider-agent",
     sub: subject,
     role: "provider",
-    scope: runnerScopeWithSpawn(grant.canSpawn),
+    scope: runnerScopeWithSpawn(grant.canSpawn, input.agentInitiated),
     constraints: {
       orchestrators: [input.orchestratorId],
       cwdPrefixes: [input.cwd],
@@ -120,6 +123,7 @@ export function issueRunnerRuntimeToken(input: {
       ...(input.spawnRequestId ? { spawnRequestIds: [input.spawnRequestId] } : {}),
       ...(grant.canSpawn && grant.maxSpawnedAgents ? { maxSpawnedAgents: grant.maxSpawnedAgents } : {}),
       ...(input.spawnedBy ? { spawnedBy: input.spawnedBy } : {}),
+      ...(input.teamId ? { teamId: input.teamId } : {}),
     },
     createdBy: input.createdBy ?? "runtime",
   });
@@ -133,6 +137,7 @@ function issueChildRunnerRuntimeToken(input: {
   label?: string;
   policyName?: string;
   spawnRequestId: string;
+  teamId?: string;
   createdBy?: string;
 }): RuntimeTokenResult {
   return createToken({
@@ -146,6 +151,7 @@ function issueChildRunnerRuntimeToken(input: {
       cwdPrefixes: [input.cwd],
       spawnRequestIds: [input.spawnRequestId],
       canDelegate: false,
+      ...(input.teamId ? { teamId: input.teamId } : {}),
       ...(input.policyName ? { policies: [input.policyName] } : {}),
     },
     createdBy: input.createdBy ?? input.parentAgentId,

package/src/security.ts

@@ -204,6 +204,7 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname.startsWith("/api/maintenance")) return "system:admin";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";
   if (pathname.startsWith("/api/pairs")) return method === "GET" ? "pairs:read" : "pairs:write";
+  if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
   // Insights config (the feature toggle) stays admin-only via the default; only the
   // mechanical observation feed is writable by lower-privilege callers.
   if (pathname === "/api/insights/observations") return method === "GET" ? "insights:read" : "insights:write";
@@ -278,6 +279,7 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";
   if (pathname.startsWith("/api/orchestrators")) return method === "GET" ? "agent:read" : "command:write";
   if (pathname.startsWith("/api/plans")) return method === "GET" ? "plans:read" : "plans:write";
+  if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
   // The Runner posts the #184 context-gathering signal here (source:"server") via its
   // provider token. Without this case the path fell through to the system:admin default
   // below and every observation was 403-dropped — the whole Insights feed stayed empty.
@@ -415,6 +417,10 @@ export function resolveSpawnLineage(constraints: TokenConstraints | undefined):
   return constraints?.spawnedBy ?? constraints?.parentAgents?.[0];
 }
 
+export function resolveTeamLineage(constraints: TokenConstraints | undefined): string | undefined {
+  return constraints?.teamId;
+}
+
 function constraintsAllow(constraints: TokenConstraints | undefined, resource: AuthorizationResource | undefined): boolean {
   if (!constraints || !resource) return true;
   const hasConstraints = Object.keys(constraints).length > 0;
@@ -462,7 +468,7 @@ function isTokenConstraints(value: unknown): value is TokenConstraints {
   for (const [key, item] of Object.entries(record)) {
     if (["terminalAttach", "logsRead", "canDelegate"].includes(key)) {
       if (typeof item !== "boolean") return false;
-    } else if (key === "cwd" || key === "spawnedBy") {
+    } else if (key === "cwd" || key === "spawnedBy" || key === "teamId") {
       if (typeof item !== "string") return false;
     } else if (key === "maxSpawnedAgents") {
       if (typeof item !== "number") return false;

package/src/services/plan-graph.ts

@@ -30,6 +30,7 @@ export interface PlanNodePatch {
 
 export interface PlanCreateInput {
   threadId: unknown;
+  teamId?: unknown;
   channel?: unknown;
   title?: unknown;
   objective?: unknown;
@@ -186,6 +187,7 @@ export function createPlan(input: PlanCreateInput, ctx: AuthContext): Plan {
   const actor = actorId(ctx);
   const plan = createPlanRow({
     threadId,
+    teamId: cleanString(input.teamId, "teamId", { max: 120 }),
     channel,
     title: cleanString(input.title, "title", { max: 240 }),
     objective: cleanString(input.objective, "objective", { max: 4000 }),

package/src/services/register-agent.ts

@@ -13,7 +13,7 @@ import { createActivityEvent, getAgent, upsertAgent } from "../db";
 import { emitAgentStatus } from "../sse";
 import { noteAgentTimelineEvent } from "../compaction-watch";
 import { notifyAgentReady } from "../agent-lifecycle-events";
-import { resolveSpawnLineage } from "../security";
+import { resolveSpawnLineage, resolveTeamLineage } from "../security";
 import { markManagedAgentRunning } from "./managed-running";
 import type { AuthContext } from "./auth-context";
 import type { AgentCard, RegisterAgentInput } from "../types";
@@ -28,6 +28,8 @@ export function registerAgent(input: RegisterAgentInput, ctx: AuthContext): Agen
   // the client-sent body (a child can't forge its own parent). Set by relay at spawn.
   const lineage = resolveSpawnLineage(ctx.constraints);
   if (lineage) input.spawnedBy = lineage;
+  const teamLineage = resolveTeamLineage(ctx.constraints);
+  if (teamLineage) input.teamId = teamLineage;
 
   const existing = getAgent(input.id);
   const agent = upsertAgent(input);

package/src/services/spawn-agent.ts

@@ -25,7 +25,7 @@
 // deliberately out of scope here — this slice converges the two external TRANSPORTS.
 import type { SpawnProvider } from "agent-relay-sdk";
 import { stringValue } from "agent-relay-sdk";
-import { countLiveSpawnedAgents, createActivityEvent, getAgent, listAgents, ValidationError } from "../db";
+import { countLiveSpawnedAgents, createActivityEvent, ensureTeam, getAgent, listAgents, setAgentTeam, ValidationError } from "../db";
 import { createCommand } from "../commands-db";
 import { emitCommandEvent } from "../command-events";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
@@ -178,6 +178,8 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // Provenance actor: the resolved caller agent when known, else the transport's label, else
   // the raw token actor. Recorded in the command payload, the token mint, and the audit row.
   const requestedBy = callerId ?? input.requestedBy ?? ctx.actor.id;
+  const callerTeam = callerId ? (caller?.teamId ? { id: caller.teamId } : ensureTeam(callerId)) : undefined;
+  if (callerId && callerTeam && !caller?.teamId) setAgentTeam(callerId, callerTeam.id);
 
   // Child runner token. `agentInitiated` (set whenever an agent is the caller) forces a
   // non-spawn-capable child (no grandchildren); `spawnedBy` stamps authoritative lineage the
@@ -197,6 +199,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
     // child regardless of profile (no grandchildren).
     profile: input.profile || undefined,
     ...(callerId ? { agentInitiated: true, spawnedBy: callerId } : {}),
+    ...(callerTeam ? { teamId: callerTeam.id } : {}),
   });
 
   const command = createCommand({

package/src/services/team.ts

@@ -0,0 +1,69 @@
+import { dissolveTeam, ensureTeam, getAgent, getPlanByTeam, getTeam, getTeamRoster, setTeamBrief } from "../db";
+import type { AuthContext } from "./auth-context";
+import type { Team } from "../types";
+
+export class TeamAuthError extends Error {}
+export class TeamNotFoundError extends Error {}
+
+export interface TeamPayload {
+  team: Team;
+  roster: ReturnType<typeof getTeamRoster>;
+  brief: string | null;
+  definitionOfDone: string | null;
+  plan: ReturnType<typeof getPlanByTeam>;
+}
+
+export interface TeamBriefInput {
+  title?: string;
+  brief?: string;
+  definitionOfDone?: string;
+}
+
+export interface TeamDissolveServiceInput {
+  outcomeStatus?: Team["outcomeStatus"];
+  outcomeSummary?: string;
+  landsClean?: boolean;
+}
+
+function requireCallerAgentId(ctx: AuthContext): string {
+  if (!ctx.callerAgentId) throw new TeamAuthError("team operations require a single caller agent identity");
+  return ctx.callerAgentId;
+}
+
+function payloadForAgent(agentId: string, channel?: string): TeamPayload {
+  const agent = getAgent(agentId);
+  const team = agent?.teamId ? getTeam(agent.teamId) : null;
+  if (!team) throw new TeamNotFoundError("caller has no team");
+  return {
+    team,
+    roster: getTeamRoster(team.id),
+    brief: team.brief ?? null,
+    definitionOfDone: team.definitionOfDone ?? null,
+    plan: getPlanByTeam(team.id, channel) ?? null,
+  };
+}
+
+export function getCallerTeam(ctx: AuthContext, channel?: string): TeamPayload {
+  return payloadForAgent(requireCallerAgentId(ctx), channel);
+}
+
+export function setCallerTeamBrief(ctx: AuthContext, input: TeamBriefInput): TeamPayload {
+  const agentId = requireCallerAgentId(ctx);
+  const team = ensureTeam(agentId);
+  setTeamBrief({ teamId: team.id, ...input });
+  return payloadForAgent(agentId);
+}
+
+export function dissolveCallerTeam(ctx: AuthContext, input: TeamDissolveServiceInput): TeamPayload {
+  const agentId = requireCallerAgentId(ctx);
+  const agent = getAgent(agentId);
+  if (!agent?.teamId) throw new TeamNotFoundError("caller has no team");
+  const team = dissolveTeam(agent.teamId, input);
+  return {
+    team,
+    roster: getTeamRoster(team.id),
+    brief: team.brief ?? null,
+    definitionOfDone: team.definitionOfDone ?? null,
+    plan: getPlanByTeam(team.id) ?? null,
+  };
+}

package/src/token-db.ts

@@ -57,7 +57,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Agent",
     description: "Coding-agent runtime access for messages, commands, tasks, and scoped memory reads.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "plans:read", "plans:write", "insights:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "plans:read", "plans:write", "teams:read", "teams:write", "insights:write"],
     ttlSeconds: 24 * 60 * 60,
     builtIn: true,
     createdBy: "system",
@@ -67,7 +67,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Child Agent",
     description: "Delegated child-agent runtime access, constrained to its parent and spawn request.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "insights:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "insights:write"],
     constraints: { canDelegate: false },
     ttlSeconds: 2 * 60 * 60,
     builtIn: true,
@@ -78,7 +78,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Interactive Agent",
     description: "User-launched provider runtime access constrained to its own agent and cwd for long interactive sessions.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "insights:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "insights:write"],
     constraints: { terminalAttach: false, logsRead: false, canDelegate: false },
     ttlSeconds: 30 * 24 * 60 * 60,
     builtIn: true,

package/src/validation.ts

@@ -122,6 +122,8 @@ export function cleanTokenConstraints(value: unknown): TokenConstraints | undefi
   }
   const cwd = cleanString(value.cwd, "constraints.cwd", { max: 500 });
   if (cwd) constraints.cwd = cwd;
+  const teamId = cleanString(value.teamId, "constraints.teamId", { max: 120 });
+  if (teamId) constraints.teamId = teamId;
   for (const key of ["terminalAttach", "logsRead", "canDelegate"] as const) {
     if (value[key] !== undefined) {
       if (typeof value[key] !== "boolean") throw new ValidationError(`constraints.${key} must be a boolean`);