agent-relay-server 0.28.0 → 0.30.0

package/src/runtime-tokens.ts

@@ -118,7 +118,7 @@ export function issueRunnerRuntimeToken(input: {
   });
 }
 
-export function issueChildRunnerRuntimeToken(input: {
+function issueChildRunnerRuntimeToken(input: {
   parentAgentId: string;
   orchestratorId: string;
   cwd: string;
@@ -239,7 +239,7 @@ export function runnerRuntimeTokenEnv(input: {
   };
 }
 
-export function childRunnerRuntimeTokenEnv(input: {
+function childRunnerRuntimeTokenEnv(input: {
   parentAgentId: string;
   orchestratorId: string;
   cwd: string;

package/src/security.ts

@@ -200,6 +200,9 @@ 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";
+  // 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";
   if (pathname.startsWith("/api/system/")) return "system:admin";
   return null;
 }
@@ -268,6 +271,11 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname.startsWith("/api/agent-profiles")) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";
   if (pathname.startsWith("/api/orchestrators")) return method === "GET" ? "agent:read" : "command: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.
+  // Config (the feature toggle) intentionally keeps falling through to system:admin.
+  if (pathname === "/api/insights/observations") return method === "GET" ? "insights:read" : "insights:write";
   if (pathname.startsWith("/api/system/")) return "system:admin";
   return "system:admin";
 }

package/src/spawn-command.ts

@@ -17,7 +17,7 @@ export function generateSpawnRequestId(): string {
   return `sp_${randomUUID()}`;
 }
 
-export interface ResolveSpawnModelParamsOptions {
+interface ResolveSpawnModelParamsOptions {
   /**
    * What to do when provider-catalog resolution throws (e.g. unknown model, or
    * effort without a model):
@@ -69,7 +69,7 @@ export function resolveSpawnModelParams(
  * Every field that can appear in a spawn command-bus payload.
  * Optional fields are omitted from the result when undefined.
  */
-export interface BuildSpawnCommandOptions {
+interface BuildSpawnCommandOptions {
   provider: SpawnProvider | string;
   cwd: string;
   /** Correlation id; omitted from the payload when absent (e.g. automation spawns use automationRunId instead). */

package/src/sse.ts

@@ -1,5 +1,7 @@
-import { getAgent, getOrchestrator } from "./db";
+import { getAgent, getOrchestrator, onWorkspaceChange } from "./db";
+import { attachBranchState } from "./agent-branch-state";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
+import { messageMatchesAgent, targetMatchesAgent } from "./agent-ref";
 import type { ActivityEvent, AgentCard, Message, RelayNotification, Task } from "./types";
 import { isRecord } from "agent-relay-sdk";
 
@@ -68,18 +70,6 @@ function send(conn: Connection, event: string, data: unknown) {
   }
 }
 
-function messageMatchesAgent(msg: Message, agentId: string): boolean {
-  const agent = getAgent(agentId);
-  if (!agent) return false;
-  if (msg.resolvedToAgent === agentId) return true;
-  if (msg.to === agentId || msg.from === agentId) return true;
-  if (msg.to === "broadcast") return true;
-  if (msg.to.startsWith("tag:") && agent.tags.includes(msg.to.slice(4))) return true;
-  if (msg.to.startsWith("cap:") && agent.capabilities.includes(msg.to.slice(4))) return true;
-  if (msg.to.startsWith("label:") && agent.label === msg.to.slice(6)) return true;
-  return false;
-}
-
 function fanout(event: RelayEvent): void {
   if (event.type === "message.new") {
     sendNewMessage(event.data as unknown as Message);
@@ -100,8 +90,7 @@ function sendNewMessage(msg: Message): void {
       send(conn, "message.new", msg);
       continue;
     }
-    if (!messageMatchesAgent(msg, conn.agentId)) continue;
-    if (msg.claimable && msg.claimedBy && msg.claimedBy !== conn.agentId) continue;
+    if (!messageMatchesAgent(msg, conn.agentId, getAgent(conn.agentId))) continue;
     send(conn, "message.new", msg);
   }
 }
@@ -114,12 +103,21 @@ export function emitNewMessage(msg: Message) {
 
 export function emitAgentStatus(agentId: string) {
   const agent = getAgent(agentId);
-  const data = agent ?? { id: agentId, status: "offline" };
+  // Enrich with the branch-state badge fields (#236) so the dashboard's live agent
+  // updates carry the same projection as GET /api/agents.
+  const data = agent ? attachBranchState(agent) : { id: agentId, status: "offline" };
   emitRelayEvent({ type: "agent.status", source: "server", subject: agentId, data: data as unknown as Record<string, unknown> });
   const notification = agent ? notificationForAgentStatus(agent) : undefined;
   if (notification) emitNotificationCreated(notification);
 }
 
+// A workspace row changed (status transition or an idle↔changes git snapshot) →
+// re-emit its owner's agent.status so the branch-state badge updates live (#236).
+// Registered against the db hook to avoid a db→sse import cycle.
+onWorkspaceChange((workspace) => {
+  if (workspace.ownerAgentId) emitAgentStatus(workspace.ownerAgentId);
+});
+
 export function emitAgentRemoved(agentId: string) {
   emitRelayEvent({ type: "agent.removed", source: "server", subject: agentId, data: { id: agentId } });
 }
@@ -165,7 +163,7 @@ export function emitMessageReactionUpdated(msg: Message) {
 
 function sendTaskChanged(task: Task, eventType = "task.updated"): void {
   for (const conn of connections.values()) {
-    if (conn.agentId && !targetMatchesAgent(task.target, conn.agentId)) continue;
+    if (conn.agentId && !targetMatchesAgent(task.target, conn.agentId, getAgent(conn.agentId))) continue;
     send(conn, eventType, task);
   }
 }
@@ -194,16 +192,6 @@ export function getConnectionCount(): number {
   return connections.size;
 }
 
-function targetMatchesAgent(target: string, agentId: string): boolean {
-  const agent = getAgent(agentId);
-  if (!agent) return false;
-  if (target === agentId || target === "broadcast") return true;
-  if (target.startsWith("tag:") && agent.tags.includes(target.slice(4))) return true;
-  if (target.startsWith("cap:") && agent.capabilities.includes(target.slice(4))) return true;
-  if (target.startsWith("label:") && agent.label === target.slice(6)) return true;
-  return false;
-}
-
 export function emitOrchestratorStatus(orchestratorId: string) {
   const orch = getOrchestrator(orchestratorId);
   const data = orch ?? { id: orchestratorId, status: "offline" };

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

package/src/upgrade.ts

@@ -249,7 +249,7 @@ export function createUpgradePlan(snapshot: UpgradeSnapshot, options: UpgradeOpt
   };
 }
 
-export type ExecuteUpgradeOptions = {
+type ExecuteUpgradeOptions = {
   dryRun?: boolean;
   runner?: Runner;
   /** Re-register grace window for post-restart version checks (default 30s). */

package/src/workspace-actions.ts

@@ -41,7 +41,7 @@ export const WORKSPACE_ACTIONS = [
 ] as const;
 export type WorkspaceAction = (typeof WORKSPACE_ACTIONS)[number];
 
-export interface ApplyWorkspaceActionInput {
+interface ApplyWorkspaceActionInput {
   action: WorkspaceAction;
   agentId?: string;
   detail?: string;
@@ -62,7 +62,7 @@ export interface ApplyWorkspaceActionInput {
   auditMetadata?: Record<string, unknown>;
 }
 
-export type WorkspaceActionResult =
+type WorkspaceActionResult =
   | {
       ok: true;
       httpStatus: number;
@@ -320,10 +320,10 @@ export function buildWorkspaceDepsRefreshCommand(
   return { ok: true, command };
 }
 
-export const DEFAULT_WORKSPACE_WAIT_MS = 300_000;
-export const MAX_WORKSPACE_WAIT_MS = 600_000;
+const DEFAULT_WORKSPACE_WAIT_MS = 300_000;
+const MAX_WORKSPACE_WAIT_MS = 600_000;
 
-export interface WaitForWorkspaceResult {
+interface WaitForWorkspaceResult {
   workspace: WorkspaceRecord | null;
   /** The status when the wait began. */
   fromStatus?: WorkspaceStatus;

package/src/workspace-claim.ts

@@ -4,9 +4,9 @@ import type { WorkspaceRecord } from "./types";
 // auto-merge (Layer 0) doesn't race it (#208 / steward report §1). The claim is a
 // TTL'd lease stored in row metadata, so a dead steward can't block the workspace
 // forever — it expires and auto-merge resumes. Renew by re-claiming.
-export const STEWARD_CLAIM_TTL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_CLAIM_TTL_MS) || 15 * 60_000;
+const STEWARD_CLAIM_TTL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_CLAIM_TTL_MS) || 15 * 60_000;
 
-export interface WorkspaceClaim {
+interface WorkspaceClaim {
   by?: string;
   purpose?: string;
   claimedAt?: number;

package/src/workspace-merge.ts

@@ -10,7 +10,7 @@ import {
 import type { Command, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
 import { isPathWithinBase } from "./utils";
 
-export interface RequestWorkspaceMergeOptions {
+interface RequestWorkspaceMergeOptions {
   /** Who asked for the merge (lease holder + audit). e.g. an agent id, "dashboard", "auto-merge". */
   requestedBy: string;
   /** Merge strategy; "auto" lets the host pick pr-vs-rebase-ff. Defaults to "auto". */
@@ -26,7 +26,7 @@ export interface RequestWorkspaceMergeOptions {
   metadata?: Record<string, unknown>;
 }
 
-export type RequestWorkspaceMergeResult =
+type RequestWorkspaceMergeResult =
   | { ok: true; command: Command; workspace: WorkspaceRecord }
   | { ok: false; status: number; error: string };
 

package/src/workspace-orphans.ts

@@ -141,7 +141,7 @@ function knownRepoRoots(workspaces: WorkspaceRecord[]): string[] {
   return [...new Set(workspaces.map((ws) => ws.repoRoot).filter(Boolean))];
 }
 
-export interface CollectOrphansResult {
+interface CollectOrphansResult {
   orphans: WorkspaceOrphan[];
   /** Live isolated rows whose worktree is missing on disk (DB→disk drift). */
   missingWorktrees: Array<{

package/src/workspace-phase.ts

@@ -15,13 +15,23 @@
 // anti-panic signal.
 
 import { TERMINAL_WORKSPACE_STATUS_VALUES } from "agent-relay-sdk";
-import type { WorkspaceRecord, WorkspaceStatus } from "./types";
+import type { BranchState, WorkspaceRecord, WorkspaceStatus } from "./types";
+import { workspaceActiveClaim } from "./workspace-claim";
 
 // Statuses where the worktree's lifecycle is over — landed or torn down. Single
 // home; imported by maintenance (stale reap), routes (orphan scan), and the MCP
 // initialize primer (don't brief an agent on a dead workspace). Was duplicated.
 export const TERMINAL_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(TERMINAL_WORKSPACE_STATUS_VALUES);
 
+// The "this is the worktree the agent is actively branch-working in" predicate:
+// isolated mode and not yet landed/torn down. SINGLE HOME — the MCP owner-workspace
+// resolver, the db owner lookup, and the #236 badge enrichment all mean the same
+// thing; they drifted into private copies before. listWorkspaces is ORDER BY
+// updated_at DESC, so the first match per owner is the most recent live worktree.
+export function isLiveIsolatedWorkspace(ws: Pick<WorkspaceRecord, "mode" | "status">): boolean {
+  return ws.mode === "isolated" && !TERMINAL_WORKSPACE_STATUSES.has(ws.status);
+}
+
 // The "handed off, waiting to land" statuses — an agent has finished and the
 // auto-merge-back is responsible for getting the branch onto base. SINGLE HOME:
 // the auto-land consumer (maintenance `autoMergeCleanFastForwards`) and the
@@ -71,7 +81,7 @@ export function worktreeReapable(state: WorktreeReapState | null | undefined): b
 // instead of the old behavior where it looked healthy for 90 minutes.
 export const LAND_PENDING_STALL_MS = 15 * 60 * 1000;
 
-export type WorkspacePhase =
+type WorkspacePhase =
   | "working" // active — your turn: commit, then mark ready
   | "land-pending" // ready | review_requested — handed off; auto-merge will land it
   | "landing" // merge_planned — merge dispatched, in progress
@@ -79,7 +89,7 @@ export type WorkspacePhase =
   | "landed" // merged — on the base; a fresh rebased branch is coming
   | "closed"; // abandoned | cleanup_requested | cleaned — torn down
 
-export interface WorkspaceNextAction {
+interface WorkspaceNextAction {
   /** MCP tool to call (when the agent is on the MCP surface). */
   tool?: string;
   /** Equivalent CLI invocation (when the agent is on the shell surface). */
@@ -209,6 +219,64 @@ export function describeWorkspacePhase(
   }
 }
 
+function metaNumber(meta: Record<string, unknown> | undefined, key: string): number | undefined {
+  const v = meta?.[key];
+  return typeof v === "number" ? v : undefined;
+}
+
+// THE branch-state projection for the human (#236) — the sibling of
+// describeWorkspacePhase, which targets the agent. Maps a workspace to one compact
+// state for the agent-card/chat badge, so the recurring "does this agent have
+// unlanded work, and where is it in the merge-back" question is answered at a
+// glance. SINGLE HOME (server-side); the dashboard never recomputes it.
+//
+// idle/changes need the worktree's ahead/dirty counts, which the relay isn't in the
+// git path to know live — the ~2 min conflict scan stashes them in metadata
+// (`gitAhead`/`gitDirtyCount`). Until the first scan they're absent, so an active
+// worktree shows the optimistic `changes` (the high-value "mark ready" affordance);
+// the scan then settles it to `idle` when genuinely empty (#236 v1 option a).
+//
+// Returns undefined for non-branch / torn-down workspaces (no badge).
+export function deriveBranchState(
+  workspace: Pick<WorkspaceRecord, "status" | "metadata" | "readyAt"> | null | undefined,
+  opts: { now?: number; stallMs?: number } = {},
+): BranchState | undefined {
+  if (!workspace) return undefined;
+  const now = opts.now ?? Date.now();
+  switch (workspace.status) {
+    case "active": {
+      const meta = workspace.metadata as Record<string, unknown> | undefined;
+      const ahead = metaNumber(meta, "gitAhead");
+      const dirty = metaNumber(meta, "gitDirtyCount");
+      if (ahead === undefined && dirty === undefined) return "changes";
+      return (ahead ?? 0) > 0 || (dirty ?? 0) > 0 ? "changes" : "idle";
+    }
+    case "ready":
+    case "review_requested":
+      // Handed off, waiting for the auto-merge. A steward holding the claim means a
+      // human-out-of-loop reconciliation is underway → 🟠, otherwise the robot has it → 🔵.
+      return workspaceActiveClaim(workspace, now)?.purpose === "steward" ? "steward" : "ready";
+    case "merge_planned":
+      // Merge dispatched / under reconciliation — robot-or-steward, either way not the human's move.
+      return "steward";
+    case "conflict": {
+      // Held by a steward → reconciling (🟠). Past the stall window with nobody
+      // holding it → the steward path isn't progressing → escalate to the human (🔴).
+      if (workspaceActiveClaim(workspace, now)?.purpose === "steward") return "steward";
+      const stallMs = opts.stallMs ?? LAND_PENDING_STALL_MS;
+      const since = typeof workspace.readyAt === "number" ? now - workspace.readyAt : undefined;
+      if (since !== undefined && since > stallMs) return "blocked";
+      return "steward";
+    }
+    case "merged":
+    case "abandoned":
+    case "cleanup_requested":
+    case "cleaned":
+      // Terminal/torn down: the owner lookup filters these out, so the badge clears.
+      return undefined;
+  }
+}
+
 // Plain-language contract printed/returned right when an agent marks a workspace
 // ready, so the whole "what happens next" is stated up front instead of being
 // decoded from status enums over the following minutes (#235).