agent-relay-server 0.44.0 → 0.46.0

package/src/db/blackboard.ts

@@ -0,0 +1,171 @@
+import { randomUUID } from "node:crypto";
+import { getDb, ValidationError } from "./connection.ts";
+import { parseJson } from "../utils";
+import type { BlackboardEntry, BlackboardEntryKind, BlackboardEntryStatus } from "../types";
+
+const BLACKBOARD_KINDS = ["decision", "fact", "ruled_out"] as const;
+const BLACKBOARD_STATUSES = ["active", "superseded", "retracted"] as const;
+
+interface BlackboardEntryRow {
+  id: string;
+  team_id: string;
+  kind: BlackboardEntryKind;
+  title: string;
+  body: string | null;
+  status: BlackboardEntryStatus;
+  supersedes: string | null;
+  tags: string | null;
+  author_id: string;
+  created_at: number;
+  updated_at: number;
+}
+
+interface WriteBlackboardEntryInput {
+  teamId: string;
+  kind: BlackboardEntryKind;
+  title: string;
+  body?: string;
+  tags?: string[];
+  authorId: string;
+  supersedes?: string;
+}
+
+function blackboardId(): string {
+  return `bb_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+}
+
+function rowToEntry(row: BlackboardEntryRow): BlackboardEntry {
+  const tags = parseJson<string[]>(row.tags, []).filter((tag) => typeof tag === "string");
+  return {
+    id: row.id,
+    teamId: row.team_id,
+    kind: row.kind,
+    title: row.title,
+    ...(row.body ? { body: row.body } : {}),
+    status: row.status,
+    ...(row.supersedes ? { supersedes: row.supersedes } : {}),
+    tags,
+    authorId: row.author_id,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function assertKind(kind: BlackboardEntryKind): void {
+  if (!BLACKBOARD_KINDS.includes(kind)) {
+    throw new ValidationError(`kind must be one of: ${BLACKBOARD_KINDS.join(", ")}`);
+  }
+}
+
+function assertStatus(status: BlackboardEntryStatus): void {
+  if (!BLACKBOARD_STATUSES.includes(status)) {
+    throw new ValidationError(`status must be one of: ${BLACKBOARD_STATUSES.join(", ")}`);
+  }
+}
+
+function escapeLike(value: string): string {
+  return value.replace(/[\\%_]/g, (char) => `\\${char}`);
+}
+
+export function writeEntry(input: WriteBlackboardEntryInput): BlackboardEntry {
+  assertKind(input.kind);
+  const id = blackboardId();
+  const now = Date.now();
+  getDb().transaction(() => {
+    if (input.supersedes) {
+      const previous = getEntry(input.supersedes);
+      if (!previous) throw new ValidationError(`blackboard entry ${input.supersedes} not found`);
+      if (previous.teamId !== input.teamId) throw new ValidationError("superseded entry belongs to another team");
+      if (previous.status === "retracted") throw new ValidationError("cannot supersede a retracted entry");
+      getDb().query("UPDATE blackboard_entries SET status = 'superseded', updated_at = ? WHERE id = ?")
+        .run(now, input.supersedes);
+    }
+    getDb().query(`
+      INSERT INTO blackboard_entries (id, team_id, kind, title, body, status, supersedes, tags, author_id, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?)
+    `).run(
+      id,
+      input.teamId,
+      input.kind,
+      input.title,
+      input.body ?? null,
+      input.supersedes ?? null,
+      input.tags?.length ? JSON.stringify([...new Set(input.tags)]) : null,
+      input.authorId,
+      now,
+      now,
+    );
+  })();
+  return getEntry(id)!;
+}
+
+export function getEntry(id: string): BlackboardEntry | null {
+  const row = getDb().query("SELECT * FROM blackboard_entries WHERE id = ?").get(id) as BlackboardEntryRow | undefined;
+  return row ? rowToEntry(row) : null;
+}
+
+export function getEntryChain(id: string): BlackboardEntry[] {
+  const chain: BlackboardEntry[] = [];
+  const seen = new Set<string>();
+  let current = getEntry(id);
+  while (current && !seen.has(current.id)) {
+    chain.push(current);
+    seen.add(current.id);
+    current = current.supersedes ? getEntry(current.supersedes) : null;
+  }
+  return chain;
+}
+
+export function listEntries(
+  teamId: string,
+  opts: { kind?: BlackboardEntryKind; includeInactive?: boolean } = {},
+): BlackboardEntry[] {
+  if (opts.kind) assertKind(opts.kind);
+  const conditions = ["team_id = ?"];
+  const params: string[] = [teamId];
+  if (opts.kind) {
+    conditions.push("kind = ?");
+    params.push(opts.kind);
+  }
+  if (!opts.includeInactive) conditions.push("status = 'active'");
+  const rows = getDb().query(`
+    SELECT * FROM blackboard_entries
+    WHERE ${conditions.join(" AND ")}
+    ORDER BY updated_at DESC, created_at DESC, id DESC
+  `).all(...params) as BlackboardEntryRow[];
+  return rows.map(rowToEntry);
+}
+
+export function searchEntries(
+  teamId: string,
+  query: string,
+  opts: { kind?: BlackboardEntryKind } = {},
+): BlackboardEntry[] {
+  if (opts.kind) assertKind(opts.kind);
+  const like = `%${escapeLike(query)}%`;
+  const conditions = [
+    "team_id = ?",
+    "status = 'active'",
+    "(title LIKE ? ESCAPE '\\' OR body LIKE ? ESCAPE '\\' OR tags LIKE ? ESCAPE '\\')",
+  ];
+  const params: string[] = [teamId, like, like, like];
+  if (opts.kind) {
+    conditions.push("kind = ?");
+    params.push(opts.kind);
+  }
+  const rows = getDb().query(`
+    SELECT * FROM blackboard_entries
+    WHERE ${conditions.join(" AND ")}
+    ORDER BY updated_at DESC, created_at DESC, id DESC
+  `).all(...params) as BlackboardEntryRow[];
+  return rows.map(rowToEntry);
+}
+
+export function retractEntry(id: string): BlackboardEntry | null {
+  const existing = getEntry(id);
+  if (!existing) return null;
+  assertStatus("retracted");
+  getDb().query("UPDATE blackboard_entries SET status = 'retracted', updated_at = ? WHERE id = ?")
+    .run(Date.now(), id);
+  return getEntry(id);
+}

package/src/db/index.ts

@@ -25,3 +25,4 @@ export * from "./continuations.ts";
 export * from "./continuation-archives.ts";
 export * from "./plans.ts";
 export * from "./teams.ts";
+export * from "./blackboard.ts";

package/src/db/migrations.ts

@@ -302,6 +302,23 @@ export function applyMigrations(): void {
   `);
   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 blackboard_entries (
+      id TEXT PRIMARY KEY,
+      team_id TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT,
+      status TEXT NOT NULL DEFAULT 'active',
+      supersedes TEXT,
+      tags TEXT,
+      author_id TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_blackboard_team ON blackboard_entries(team_id)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_blackboard_team_kind ON blackboard_entries(team_id, kind)");
   getDb().run(`
     CREATE TABLE IF NOT EXISTS plans (
       id TEXT PRIMARY KEY, thread_id INTEGER NOT NULL, team_id TEXT, channel TEXT, version INTEGER NOT NULL DEFAULT 1,

package/src/db/schema.ts

@@ -171,6 +171,21 @@ export function initDb(path: string = "agent-relay.db"): Database {
     );
     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 blackboard_entries (
+      id TEXT PRIMARY KEY,
+      team_id TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT,
+      status TEXT NOT NULL DEFAULT 'active',
+      supersedes TEXT,
+      tags TEXT,
+      author_id TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_blackboard_team ON blackboard_entries(team_id);
+    CREATE INDEX IF NOT EXISTS idx_blackboard_team_kind ON blackboard_entries(team_id, kind);
     CREATE TABLE IF NOT EXISTS plans (
       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 '[]',

package/src/mcp-blackboard-tools.ts

@@ -0,0 +1,131 @@
+import { getAgent, getEntry, getEntryChain, listEntries, retractEntry, searchEntries, ValidationError, writeEntry } from "./db";
+import { McpNotFoundError } from "./mcp-errors";
+import { authContextFromMcp } from "./services/auth-context";
+import { cleanString, cleanStringArray, optionalEnum } from "./validation";
+import type { BlackboardEntryKind } from "./types";
+
+const BLACKBOARD_KINDS = ["decision", "fact", "ruled_out"] as const;
+
+export const BLACKBOARD_TOOLS = [
+  {
+    name: "relay_blackboard_write",
+    description: "Create a team-scoped blackboard entry. The caller's token identity determines the team and author.",
+    requiredScopes: ["blackboard:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: BLACKBOARD_KINDS },
+        title: { type: "string" },
+        body: { type: "string" },
+        tags: { type: "array", items: { type: "string" } },
+        supersedes: { type: "string" },
+      },
+      required: ["kind", "title"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_blackboard_get",
+    description: "Fetch one blackboard entry and its supersession chain for the caller's team.",
+    requiredScopes: ["blackboard:read"],
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_blackboard_read",
+    description: "Read the caller team's active blackboard working set, optionally filtered by kind.",
+    requiredScopes: ["blackboard:read"],
+    inputSchema: {
+      type: "object",
+      properties: { kind: { type: "string", enum: BLACKBOARD_KINDS } },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_blackboard_search",
+    description: "Search active blackboard entries for the caller's team by title, body, or tags.",
+    requiredScopes: ["blackboard:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        kind: { type: "string", enum: BLACKBOARD_KINDS },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_blackboard_retract",
+    description: "Retract a blackboard entry for the caller's team without deleting its ledger row.",
+    requiredScopes: ["blackboard:write"],
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type McpAuthLike = Parameters<typeof authContextFromMcp>[0];
+
+function callerTeam(auth: McpAuthLike): { agentId: string; teamId: string } {
+  const ctx = authContextFromMcp(auth);
+  if (!ctx.callerAgentId) throw new ValidationError("blackboard operations require a single caller agent identity");
+  const agent = getAgent(ctx.callerAgentId);
+  if (!agent?.teamId) throw new ValidationError("caller has no team");
+  return { agentId: ctx.callerAgentId, teamId: agent.teamId };
+}
+
+function cleanKind(value: unknown): BlackboardEntryKind | undefined {
+  return optionalEnum(value, "kind", BLACKBOARD_KINDS) as BlackboardEntryKind | undefined;
+}
+
+function ensureSameTeam(entryId: string, teamId: string): void {
+  const entry = getEntry(entryId);
+  if (!entry) throw new McpNotFoundError("blackboard entry not found");
+  if (entry.teamId !== teamId) throw new McpNotFoundError("blackboard entry not found");
+}
+
+export function relayBlackboardTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Record<string, unknown> {
+  const { agentId, teamId } = callerTeam(auth);
+  if (name === "relay_blackboard_write") {
+    const supersedes = cleanString(args.supersedes, "supersedes", { max: 120 });
+    const kind = cleanKind(args.kind);
+    if (!kind) throw new ValidationError("kind required");
+    if (supersedes) ensureSameTeam(supersedes, teamId);
+    return writeEntry({
+      teamId,
+      authorId: agentId,
+      kind,
+      title: cleanString(args.title, "title", { required: true, max: 240 })!,
+      body: cleanString(args.body, "body", { max: 16_000 }),
+      tags: cleanStringArray(args.tags, "tags", { itemMax: 80, maxItems: 32 }),
+      supersedes,
+    }) as unknown as Record<string, unknown>;
+  }
+  if (name === "relay_blackboard_get") {
+    const id = cleanString(args.id, "id", { required: true, max: 120 })!;
+    ensureSameTeam(id, teamId);
+    return { entry: getEntry(id), chain: getEntryChain(id) };
+  }
+  if (name === "relay_blackboard_read") {
+    return { entries: listEntries(teamId, { kind: cleanKind(args.kind) }) };
+  }
+  if (name === "relay_blackboard_search") {
+    return { entries: searchEntries(teamId, cleanString(args.query, "query", { required: true, max: 240 })!, { kind: cleanKind(args.kind) }) };
+  }
+  if (name === "relay_blackboard_retract") {
+    const id = cleanString(args.id, "id", { required: true, max: 120 })!;
+    ensureSameTeam(id, teamId);
+    const entry = retractEntry(id);
+    if (!entry) throw new McpNotFoundError("blackboard entry not found");
+    return entry as unknown as Record<string, unknown>;
+  }
+  throw new ValidationError(`unknown tool: ${name}`);
+}

package/src/mcp-plan-tools.ts

@@ -28,6 +28,7 @@ const PLAN_NODE_SCHEMA = {
     lane: { type: "string" },
     status: { type: "string", enum: PLAN_STATUSES },
     statusSource: { type: "string", enum: ["manual", "bound"] },
+    blackboardRefs: { type: "array", items: { type: "string" } },
   },
   required: ["id", "label"],
   additionalProperties: false,
@@ -75,6 +76,7 @@ export const PLAN_TOOLS = [
         lane: { oneOf: [{ type: "string" }, { type: "null" }] },
         status: { type: "string", enum: PLAN_STATUSES },
         statusSource: { type: "string", enum: ["manual", "bound"] },
+        blackboardRefs: { oneOf: [{ type: "array", items: { type: "string" } }, { type: "null" }] },
       },
       required: ["planId", "nodeId"],
       additionalProperties: false,

package/src/mcp.ts

@@ -48,6 +48,7 @@ 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 { BLACKBOARD_TOOLS, relayBlackboardTool } from "./mcp-blackboard-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";
@@ -460,6 +461,7 @@ const TOOLS: ToolDefinition[] = [
   },
   ...TEAM_TOOLS,
   ...PLAN_TOOLS,
+  ...BLACKBOARD_TOOLS,
 ];
 
 export async function postMcp(req: Request): Promise<Response> {
@@ -573,6 +575,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     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 if (name.startsWith("relay_blackboard_")) result = relayBlackboardTool(auth, name, args);
     else throw new ValidationError(`unknown tool: ${name}`);
 
     auditToolCall(auth, name, "ok", result);

package/src/routes/blackboard.ts

@@ -0,0 +1,54 @@
+import { getAgent, getEntry, getEntryChain, listEntries } from "../db";
+import { authContextFromRequest } from "../services/auth-context";
+import { cleanString, optionalEnum } from "../validation";
+import { error, json, type Handler } from "./_shared";
+import type { BlackboardEntryKind } from "../types";
+
+const BLACKBOARD_KINDS = ["decision", "fact", "ruled_out"] as const;
+
+function isAdminContext(ctx: ReturnType<typeof authContextFromRequest>): boolean {
+  return ctx.scopes.includes("*") || ctx.scopes.includes("admin:*");
+}
+
+function routeTeamId(req: Request): string | Response {
+  const ctx = authContextFromRequest(req);
+  if (ctx.component && ctx.callerAgentId) {
+    const callerId = ctx.callerAgentId;
+    const agent = getAgent(callerId);
+    return agent?.teamId ?? error("caller has no team", 403);
+  }
+  if (ctx.component && !isAdminContext(ctx)) return error("caller has no team", 403);
+  const teamId = cleanString(new URL(req.url).searchParams.get("team") ?? undefined, "team", { required: true, max: 120 });
+  return teamId!;
+}
+
+function routeKind(req: Request): BlackboardEntryKind | undefined {
+  return optionalEnum(new URL(req.url).searchParams.get("kind") ?? undefined, "kind", BLACKBOARD_KINDS) as BlackboardEntryKind | undefined;
+}
+
+export const getBlackboardRoute: Handler = (req) => {
+  try {
+    const teamId = routeTeamId(req);
+    if (teamId instanceof Response) return teamId;
+    return json({ entries: listEntries(teamId, { kind: routeKind(req) }) });
+  } catch (err) {
+    return error(err instanceof Error ? err.message : "blackboard route failed");
+  }
+};
+
+export const getBlackboardEntryRoute: Handler = (req, params) => {
+  try {
+    const id = cleanString(params.id, "id", { required: true, max: 120 })!;
+    const entry = getEntry(id);
+    if (!entry) return error("blackboard entry not found", 404);
+    const ctx = authContextFromRequest(req);
+    if (ctx.component && ctx.callerAgentId) {
+      const agent = getAgent(ctx.callerAgentId);
+      if (!agent?.teamId || agent.teamId !== entry.teamId) return error("blackboard entry not found", 404);
+    }
+    if (ctx.component && !ctx.callerAgentId && !isAdminContext(ctx)) return error("blackboard entry not found", 404);
+    return json({ entry, chain: getEntryChain(id) });
+  } catch (err) {
+    return error(err instanceof Error ? err.message : "blackboard route failed");
+  }
+};

package/src/routes/index.ts

@@ -27,6 +27,7 @@ import { getInsightsConfigRoute, getInsightsObservationsRoute, postInsightsObser
 import { getOrchestratorDirectories, getOrchestratorFileRead, getOrchestratorFileStat, getOrchestratorFilesList, getOrchestratorLogs, getOrchestratorProviders, getOrchestratorSessions, getOrchestratorTerminal, getOrchestratorVersion, getOrchestratorWorkspaceProbe, postOrchestratorCreateDirectory, postOrchestratorTerminalInput, postOrchestratorTerminalResize } from "./orchestrator-proxy";
 import { getPairById, getPairs, postAcceptPair, postHangupPair, postPair, postPairMessage, postRejectPair } from "./pairs";
 import { getPlanByIdRoute, getPlansRoute } from "./plans";
+import { getBlackboardEntryRoute, getBlackboardRoute } from "./blackboard";
 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";
@@ -267,6 +268,8 @@ const routes: Route[] = [
   route("POST", "/api/pairs/:id/messages", postPairMessage),
   route("GET", "/api/plans", getPlansRoute),
   route("GET", "/api/plans/:id", getPlanByIdRoute),
+  route("GET", "/api/blackboard", getBlackboardRoute),
+  route("GET", "/api/blackboard/:id", getBlackboardEntryRoute),
 
   route("GET", "/api/spec", getApiSpec),
   route("GET", "/api/docs", getApiDocs),

package/src/security.ts

@@ -205,6 +205,7 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   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";
+  if (pathname.startsWith("/api/blackboard")) return method === "GET" ? "blackboard:read" : "blackboard: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";
@@ -280,6 +281,7 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   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";
+  if (pathname.startsWith("/api/blackboard")) return method === "GET" ? "blackboard:read" : "blackboard: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.

package/src/services/plan-graph.ts

@@ -1,7 +1,7 @@
 import { isRecord } from "agent-relay-sdk";
-import { createPlanRow, deletePlan, getAgent, getPlan, getPlanByTeam, getPlanByThread, planThreadExists, replacePlan, ValidationError } from "../db";
+import { createPlanRow, deletePlan, getAgent, getEntry, getPlan, getPlanByTeam, getPlanByThread, planThreadExists, replacePlan, ValidationError } from "../db";
 import { emitRelayEvent } from "../events";
-import { cleanString, optionalEnum } from "../validation";
+import { cleanString, cleanStringArray, optionalEnum } from "../validation";
 import type { AuthContext } from "./auth-context";
 import type { Plan, PlanEdge, PlanNode, PlanOwnerRef, PlanStatus } from "../types";
 
@@ -16,6 +16,7 @@ export interface PlanNodeInput {
   status?: unknown;
   statusSource?: unknown;
   refs?: unknown;
+  blackboardRefs?: unknown;
 }
 
 export interface PlanNodePatch {
@@ -26,6 +27,7 @@ export interface PlanNodePatch {
   status?: unknown;
   statusSource?: unknown;
   refs?: unknown;
+  blackboardRefs?: unknown;
 }
 
 export interface PlanCreateInput {
@@ -73,30 +75,47 @@ function cleanRefs(value: unknown): PlanNode["refs"] | undefined {
   throw new ValidationError("refs are populated by live binding in slice c");
 }
 
+function cleanBlackboardRefs(value: unknown, planTeamId?: string): string[] | undefined {
+  const refs = cleanStringArray(value, "node.blackboardRefs", { itemMax: 120, maxItems: 100 });
+  if (!refs?.length) return refs;
+  if (!planTeamId) throw new ValidationError("plan has no team; cannot reference blackboard entries");
+  for (const ref of refs) {
+    const entry = getEntry(ref);
+    if (!entry || entry.teamId !== planTeamId) throw new ValidationError(`blackboard entry not found for plan team: ${ref}`);
+  }
+  return refs;
+}
+
 function cleanStatusSource(value: unknown): "manual" {
   const statusSource = optionalEnum(value, "statusSource", ["manual", "bound"] as const, "manual");
   if (statusSource !== "manual") throw new ValidationError("statusSource must be manual in this slice");
   return "manual";
 }
 
-function cleanNode(input: PlanNodeInput): PlanNode {
+function cleanNode(input: PlanNodeInput, planTeamId?: string): PlanNode {
   if (!isRecord(input)) throw new ValidationError("node must be an object");
+  const scopeBlurb = cleanString(input.scopeBlurb, "node.scopeBlurb", { max: 2000 });
+  const ownerRef = cleanOwnerRef(input.ownerRef);
+  const lane = cleanString(input.lane, "node.lane", { max: 120 });
+  const refs = cleanRefs(input.refs);
+  const blackboardRefs = cleanBlackboardRefs(input.blackboardRefs, planTeamId);
   return {
     id: cleanString(input.id, "node.id", { required: true, max: 120 })!,
     label: cleanString(input.label, "node.label", { required: true, max: 240 })!,
-    ...(cleanString(input.scopeBlurb, "node.scopeBlurb", { max: 2000 }) ? { scopeBlurb: cleanString(input.scopeBlurb, "node.scopeBlurb", { max: 2000 }) } : {}),
-    ...(cleanOwnerRef(input.ownerRef) ? { ownerRef: cleanOwnerRef(input.ownerRef) } : {}),
-    ...(cleanString(input.lane, "node.lane", { max: 120 }) ? { lane: cleanString(input.lane, "node.lane", { max: 120 }) } : {}),
+    ...(scopeBlurb ? { scopeBlurb } : {}),
+    ...(ownerRef ? { ownerRef } : {}),
+    ...(lane ? { lane } : {}),
     status: optionalEnum(input.status, "node.status", PLAN_STATUSES, "pending") as PlanStatus,
     statusSource: cleanStatusSource(input.statusSource),
-    ...(cleanRefs(input.refs) ? { refs: cleanRefs(input.refs) } : {}),
+    ...(refs ? { refs } : {}),
+    ...(blackboardRefs ? { blackboardRefs } : {}),
   };
 }
 
-function cleanNodes(value: unknown): PlanNode[] {
+function cleanNodes(value: unknown, planTeamId?: string): PlanNode[] {
   if (value === undefined || value === null) return [];
   if (!Array.isArray(value)) throw new ValidationError("nodes must be an array");
-  const nodes = value.map((item) => cleanNode(item as PlanNodeInput));
+  const nodes = value.map((item) => cleanNode(item as PlanNodeInput, planTeamId));
   assertUnique(nodes.map((node) => node.id), "node id");
   return nodes;
 }
@@ -181,12 +200,12 @@ export function createPlan(input: PlanCreateInput, ctx: AuthContext): Plan {
   const threadId = cleanThreadId(input.threadId);
   if (!planThreadExists(threadId)) throw new ValidationError(`thread ${threadId} not found`);
   const channel = cleanString(input.channel, "channel", { max: 120 });
-  const nodes = cleanNodes(input.nodes);
-  const edges = cleanEdges(input.edges);
-  validateEdges(nodes, edges);
   const actor = actorId(ctx);
   const explicitTeamId = cleanString(input.teamId, "teamId", { max: 120 });
   const teamId = explicitTeamId ?? (input.teamId === undefined || input.teamId === null ? getAgent(actor)?.teamId : undefined);
+  const nodes = cleanNodes(input.nodes, teamId);
+  const edges = cleanEdges(input.edges);
+  validateEdges(nodes, edges);
   const plan = createPlanRow({
     threadId,
     teamId,
@@ -203,7 +222,7 @@ export function createPlan(input: PlanCreateInput, ctx: AuthContext): Plan {
 
 export function addPlanNode(planId: string, nodeInput: PlanNodeInput, ctx: AuthContext): Plan {
   const plan = existingPlan(planId);
-  const node = cleanNode(nodeInput);
+  const node = cleanNode(nodeInput, plan.teamId);
   if (plan.nodes.some((item) => item.id === node.id)) throw new ValidationError(`node ${node.id} already exists`);
   const updated = replacePlan({ ...plan, nodes: [...plan.nodes, node] }, actorId(ctx));
   emitPlan("plan.changed", updated, actorId(ctx));
@@ -223,6 +242,7 @@ export function updatePlanNode(planId: string, nodeId: string, patch: PlanNodePa
     ...(patch.lane !== undefined ? optionalProp("lane", cleanString(patch.lane, "lane", { max: 120 })) : {}),
     ...(patch.status !== undefined ? { status: optionalEnum(patch.status, "status", PLAN_STATUSES) as PlanStatus } : {}),
     ...(patch.refs !== undefined ? optionalProp("refs", cleanRefs(patch.refs)) : {}),
+    ...(patch.blackboardRefs !== undefined ? optionalProp("blackboardRefs", cleanBlackboardRefs(patch.blackboardRefs, plan.teamId)) : {}),
     statusSource: "manual",
   };
   const updated = replacePlan({ ...plan, nodes: plan.nodes.map((node) => node.id === nodeId ? next : node) }, actorId(ctx));

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", "teams:read", "teams: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", "blackboard:read", "blackboard: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", "teams:read", "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", "blackboard:read", "blackboard:write", "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", "teams:read", "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", "blackboard:read", "blackboard:write", "insights:write"],
     constraints: { terminalAttach: false, logsRead: false, canDelegate: false },
     ttlSeconds: 30 * 24 * 60 * 60,
     builtIn: true,