agent-relay-sdk 0.2.17 → 0.2.19

package/src/protocol.ts

@@ -24,7 +24,7 @@ export interface RegisterFrame extends BusFrame {
   };
 }
 
-export interface HeartbeatFrame extends BusFrame {
+interface HeartbeatFrame extends BusFrame {
   type: "heartbeat";
   payload: {
     status: Exclude<BusAgentStatus, "offline">;
@@ -32,7 +32,7 @@ export interface HeartbeatFrame extends BusFrame {
   };
 }
 
-export interface CommandFrame extends BusFrame {
+interface CommandFrame extends BusFrame {
   type: "command";
   id: string;
   payload: {
@@ -42,7 +42,7 @@ export interface CommandFrame extends BusFrame {
   };
 }
 
-export interface SubscribeFrame extends BusFrame {
+interface SubscribeFrame extends BusFrame {
   type: "subscribe";
   id: string;
   payload: {
@@ -51,7 +51,7 @@ export interface SubscribeFrame extends BusFrame {
   };
 }
 
-export interface StatusFrame extends BusFrame {
+interface StatusFrame extends BusFrame {
   type: "status";
   payload: {
     agentStatus: BusAgentStatus;
@@ -60,14 +60,14 @@ export interface StatusFrame extends BusFrame {
   };
 }
 
-export interface AckFrame extends BusFrame {
+interface AckFrame extends BusFrame {
   type: "ack";
   payload: {
     frameId: string;
   };
 }
 
-export interface ResumeFrame extends BusFrame {
+interface ResumeFrame extends BusFrame {
   type: "resume";
   id: string;
   payload: {
@@ -87,7 +87,7 @@ export interface RegisteredFrame extends BusFrame {
   };
 }
 
-export interface EventPayload {
+interface EventPayload {
   seq: number;
   eventType: string;
   source: string;
@@ -102,7 +102,7 @@ export interface EventFrame extends BusFrame {
   payload: EventPayload;
 }
 
-export interface CommandResultFrame extends BusFrame {
+interface CommandResultFrame extends BusFrame {
   type: "command.result";
   payload: {
     commandId: string;
@@ -118,7 +118,7 @@ export interface CommandStatusUpdateParams {
   error?: string;
 }
 
-export interface ResumedFrame extends BusFrame {
+interface ResumedFrame extends BusFrame {
   type: "resumed";
   payload: {
     events: EventPayload[];
@@ -136,7 +136,7 @@ export interface ErrorFrame extends BusFrame {
   };
 }
 
-export type ClientBusFrame =
+type ClientBusFrame =
   | RegisterFrame
   | HeartbeatFrame
   | CommandFrame
@@ -162,13 +162,13 @@ export class BusProtocolError extends Error {
   }
 }
 
-export function isRegisterFrame(f: BusFrame): f is RegisterFrame { return f.type === "register"; }
-export function isHeartbeatFrame(f: BusFrame): f is HeartbeatFrame { return f.type === "heartbeat"; }
-export function isCommandFrame(f: BusFrame): f is CommandFrame { return f.type === "command"; }
-export function isSubscribeFrame(f: BusFrame): f is SubscribeFrame { return f.type === "subscribe"; }
-export function isStatusFrame(f: BusFrame): f is StatusFrame { return f.type === "status"; }
-export function isAckFrame(f: BusFrame): f is AckFrame { return f.type === "ack"; }
-export function isResumeFrame(f: BusFrame): f is ResumeFrame { return f.type === "resume"; }
+function isRegisterFrame(f: BusFrame): f is RegisterFrame { return f.type === "register"; }
+function isHeartbeatFrame(f: BusFrame): f is HeartbeatFrame { return f.type === "heartbeat"; }
+function isCommandFrame(f: BusFrame): f is CommandFrame { return f.type === "command"; }
+function isSubscribeFrame(f: BusFrame): f is SubscribeFrame { return f.type === "subscribe"; }
+function isStatusFrame(f: BusFrame): f is StatusFrame { return f.type === "status"; }
+function isAckFrame(f: BusFrame): f is AckFrame { return f.type === "ack"; }
+function isResumeFrame(f: BusFrame): f is ResumeFrame { return f.type === "resume"; }
 
 export function parseBusFrame(data: string | ArrayBuffer | Uint8Array): BusFrame {
   const text = typeof data === "string" ? data : new TextDecoder().decode(data);

package/src/provider-base.ts

@@ -11,7 +11,7 @@ export interface ProviderAdapter {
   formatDelivery?(messages: Message[]): string;
 }
 
-export interface SpawnConfig {
+interface SpawnConfig {
   cwd: string;
   label?: string;
   approvalMode?: string;
@@ -19,13 +19,13 @@ export interface SpawnConfig {
   env?: Record<string, string>;
 }
 
-export interface SpawnResult {
+interface SpawnResult {
   agentId: string;
   pid?: number;
   sessionId?: string;
 }
 
-export interface ProviderBaseOptions {
+interface ProviderBaseOptions {
   relayUrl: string;
   adapter: ProviderAdapter;
   agentId: string;
@@ -36,7 +36,7 @@ export interface ProviderBaseOptions {
   token?: string;
 }
 
-export class ProviderBase {
+class ProviderBase {
   readonly client: RelayBusClient;
   private running = false;
   private readonly pending = new Map<number, Message>();

package/src/provider-catalog.ts

@@ -3,25 +3,25 @@ import type { SpawnProvider } from "./types.js";
 /** Valid reasoning-effort levels — runtime tuple is the single source of truth. */
 export const VALID_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
 export type ProviderEffort = (typeof VALID_EFFORTS)[number];
-export function isProviderEffort(value: unknown): value is ProviderEffort {
+function isProviderEffort(value: unknown): value is ProviderEffort {
   return typeof value === "string" && (VALID_EFFORTS as readonly string[]).includes(value);
 }
-export type ProviderCatalogValueSource = "catalog" | "provider" | "runtime" | "override";
-export type ProviderCatalogConfidence = "declared" | "verified" | "estimated" | "unknown";
+type ProviderCatalogValueSource = "catalog" | "provider" | "runtime" | "override";
+type ProviderCatalogConfidence = "declared" | "verified" | "estimated" | "unknown";
 
-export interface ProviderCatalogValue<T> {
+interface ProviderCatalogValue<T> {
   value: T;
   source: ProviderCatalogValueSource;
   confidence: ProviderCatalogConfidence;
   lastUpdatedAt?: number;
 }
 
-export interface ProviderModelLimits {
+interface ProviderModelLimits {
   contextWindowTokens?: ProviderCatalogValue<number>;
   maxOutputTokens?: ProviderCatalogValue<number>;
 }
 
-export interface ProviderModelModalities {
+interface ProviderModelModalities {
   input: {
     text: boolean;
     image?: boolean;
@@ -37,7 +37,7 @@ export interface ProviderModelModalities {
   };
 }
 
-export interface ProviderModelToolCapabilities {
+interface ProviderModelToolCapabilities {
   code?: boolean;
   review?: boolean;
   debug?: boolean;
@@ -50,7 +50,7 @@ export interface ProviderModelToolCapabilities {
   imageEditing?: boolean;
 }
 
-export interface ProviderModelCapabilities {
+interface ProviderModelCapabilities {
   modalities: ProviderModelModalities;
   tools?: ProviderModelToolCapabilities;
   source: ProviderCatalogValueSource;
@@ -75,13 +75,13 @@ export interface ProviderCatalogEntry {
   models: ProviderModelCatalogEntry[];
 }
 
-export interface ProviderSelection {
+interface ProviderSelection {
   provider: SpawnProvider;
   model?: string;
   effort?: ProviderEffort;
 }
 
-export interface ResolvedProviderSelection {
+interface ResolvedProviderSelection {
   provider: SpawnProvider;
   modelAlias?: string;
   providerModel?: string;

package/src/reconnect.ts

@@ -1,6 +1,6 @@
 import { setTimeout as delay } from "node:timers/promises";
 
-export interface ReconnectOptions {
+interface ReconnectOptions {
   initialMs: number;
   maxMs: number;
   jitterMs: number;

package/src/speech-text.ts

@@ -111,7 +111,7 @@ function collapseTables(text: string): string {
  * by appending an entry. Order matters: earlier rules see the raw text, later
  * rules see the output of earlier ones (see the ordering notes in SPEECH_RULES).
  */
-export interface SpeechRule {
+interface SpeechRule {
   readonly name: string
   readonly pattern: RegExp
   readonly replace: string | ((substring: string, ...args: string[]) => string)

package/src/sse.ts

@@ -3,7 +3,7 @@
 // (voice connector). One home for the `event:`/`data:`/`retry:` field parse
 // that was hand-rolled in connectors/voice and dashboard/src/lib/api.ts.
 
-export interface ParsedSseFrame {
+interface ParsedSseFrame {
   /** Event name; defaults to "message" per the SSE spec when no `event:` field. */
   event: string;
   /** Each `data:` line, in order. Join with "\n" to reconstruct the payload. */

package/src/types.ts

@@ -20,14 +20,36 @@ export interface AgentCard {
    * signed runner token at registration). Absent for top-level/user/system agents. Powers
    * spawn quotas, the `spawnedBy:` search filter, scoped shutdown, and the no-grandchild gate. */
   spawnedBy?: string;
+  /** Branch-workspace lifecycle state, server-derived from the agent's owned isolated
+   * worktree (#236). Absent for non-branch agents (no live isolated workspace). Lets the
+   * dashboard show a "where is this in the merge-back" badge without recomputing it. */
+  branchState?: BranchState;
+  /** Id of the live isolated workspace this agent owns — populated whenever `branchState`
+   * is, so the dashboard can deep-link the badge to that workspace row (#236). */
+  branchWorkspaceId?: string;
   lastSeen: number;
   createdAt: number;
 }
 
 export type AgentStatus = "online" | "idle" | "busy" | "stale" | "offline";
 
-export type CapabilitySource = "catalog" | "provider" | "runtime" | "override" | "estimate";
-export type CapabilityConfidence = "declared" | "reported" | "verified" | "estimated" | "unknown";
+/**
+ * At-a-glance branch-workspace state for an isolated-workspace owner (#236). One
+ * server-derived projection of `WorkspaceStatus` + claim + git ahead/dirty, so the
+ * human can answer "does this agent have unlanded work, and where is it in the
+ * merge-back lifecycle" from the agent card alone.
+ * - `idle`     ⚪ active worktree, nothing to land (0 ahead, clean tree)
+ * - `changes`  🟡 active worktree with commits/dirty work — human can mark it ready
+ * - `ready`    🔵 handed off; the relay auto-merge will land it (~2 min sweep)
+ * - `steward`  🟠 under reconciliation (a steward holds it, or conflict/merge in flight)
+ * - `blocked`  🔴 escalated/failed — needs human attention
+ */
+export type BranchState = "idle" | "changes" | "ready" | "steward" | "blocked";
+/** All BranchState values, for exhaustive UI maps and validation. */
+export const BRANCH_STATE_VALUES = ["idle", "changes", "ready", "steward", "blocked"] as const satisfies readonly BranchState[];
+
+type CapabilitySource = "catalog" | "provider" | "runtime" | "override" | "estimate";
+type CapabilityConfidence = "declared" | "reported" | "verified" | "estimated" | "unknown";
 
 export interface ProviderCapabilities {
   lifecycle: {
@@ -99,7 +121,7 @@ export interface ProviderCapabilities {
   lastUpdatedAt: number;
 }
 
-export type ContextLifecycleState =
+type ContextLifecycleState =
   | "fresh"
   | "primed"
   | "working"
@@ -249,7 +271,7 @@ export interface ContextBudget {
   priorityCutoff: 1 | 2 | 3;
 }
 
-export interface TaskHistorySummary {
+interface TaskHistorySummary {
   taskId: number;
   agentId: string;
   status: string;
@@ -303,7 +325,7 @@ export interface MemoryBrokerContext {
 
 export type MemoryBrokerKind = "sqlite" | "http" | "command";
 
-export interface SqliteMemoryBrokerConfig {
+interface SqliteMemoryBrokerConfig {
   type: "sqlite";
 }
 
@@ -332,6 +354,31 @@ export type MessageKind =
   | "system"
   | "session";
 
+/**
+ * Mechanical message kinds: the relay's own lifecycle/observability lane, not
+ * agent-directed messaging. They bypass delivery resolution (never re-delivered
+ * into a session) and — when targeting a reserved sink — the recipient-constraint
+ * auth check (a managed token's `targets`/`policies`/`agents` constraints gate which
+ * *agents* it may message, not a session-mirror capture to the reserved sink; #284).
+ * Keep in sync with the `MessageKind` union.
+ */
+export const MECHANICAL_MESSAGE_KINDS: readonly MessageKind[] = ["system", "control", "session"];
+
+export function isMechanicalMessageKind(kind: string | undefined): boolean {
+  return MECHANICAL_MESSAGE_KINDS.includes((kind ?? "") as MessageKind);
+}
+
+/**
+ * Reserved built-in identities that are not real agents: the `user` chat/mirror sink
+ * and the `system` lifecycle sender. They are never registered, polled, or delivered to
+ * like agents, so recipient constraints don't apply to mechanical posts addressed to them.
+ */
+export const RESERVED_AGENT_IDS: readonly string[] = ["user", "system"];
+
+export function isReservedAgentId(id: string | undefined): boolean {
+  return id === "user" || id === "system";
+}
+
 /**
  * Session-mirror event taxonomy. Every `kind: "session"` message carries a
  * `payload.session` of this shape so the dashboard can render the live provider
@@ -342,9 +389,9 @@ export type MessageKind =
  * and `notice` render discreetly (collapsed/inline activity, never bubbles).
  * A legacy session message with no `payload.session` is treated as a `response`.
  */
-export type SessionEventType = "prompt" | "response" | "narration" | "reasoning" | "tool" | "notice";
+type SessionEventType = "prompt" | "response" | "narration" | "reasoning" | "tool" | "notice";
 
-export type SessionEventOrigin = "chat" | "terminal" | "provider";
+type SessionEventOrigin = "chat" | "terminal" | "provider";
 
 export interface MessageSessionMeta {
   type: SessionEventType;
@@ -1150,14 +1197,14 @@ export type OrchestratorStatus = "online" | "offline";
 /** Spawn providers — the runtime tuple is the single source of truth; the type derives from it. */
 export const SPAWN_PROVIDERS = ["claude", "codex"] as const;
 export type SpawnProvider = (typeof SPAWN_PROVIDERS)[number];
-export function isSpawnProvider(value: unknown): value is SpawnProvider {
+function isSpawnProvider(value: unknown): value is SpawnProvider {
   return typeof value === "string" && (SPAWN_PROVIDERS as readonly string[]).includes(value);
 }
 
 /** Approval modes — runtime tuple + derived type. */
 export const APPROVAL_MODES = ["open", "guarded", "read-only"] as const;
 export type SpawnApprovalMode = (typeof APPROVAL_MODES)[number];
-export function isApprovalMode(value: unknown): value is SpawnApprovalMode {
+function isApprovalMode(value: unknown): value is SpawnApprovalMode {
   return typeof value === "string" && (APPROVAL_MODES as readonly string[]).includes(value);
 }
 
@@ -1203,7 +1250,7 @@ export interface WorkspaceProbe {
   error?: string;
 }
 
-export interface WorkspaceGitCommit {
+interface WorkspaceGitCommit {
   sha: string;
   message: string;
   at?: number;
@@ -1311,8 +1358,16 @@ export interface WorkspaceMergeResult {
   prUrl?: string;
   branch?: string;
   baseRef?: string;
-  /** SHA base now points at after a successful rebase-ff. */
+  /** SHA of the landed commit — the agent branch's tip, preserved verbatim (#287).
+   *  This is the SHA reported in the `branch.landed` notice, so it exists on base
+   *  exactly as the agent produced it (no rebase rewrite). On a clean fast-forward
+   *  it equals {@link baseSha}; on a no-ff merge it's the merge's second parent. */
   mergedSha?: string;
+  /** SHA base points at after the land (#287): equals {@link mergedSha} on a
+   *  fast-forward, or the merge commit on a no-ff merge when base had advanced. The
+   *  relay records this as the recycled workspace's new base_sha. Absent on older
+   *  orchestrators — consumers fall back to {@link mergedSha}. */
+  baseSha?: string;
   /** Subject line of the landed commit (git log -1 --format=%s of mergedSha), for
    *  the `branch.landed` notification body (#239). Best-effort; absent on older
    *  orchestrators or when the subject can't be read. */
@@ -1548,7 +1603,7 @@ export interface ManagedAgentState {
   updatedAt: number;
 }
 
-export type SpawnPolicyMode = "always-on" | "on-demand";
+type SpawnPolicyMode = "always-on" | "on-demand";
 
 export type AgentProfileProvider = SpawnProvider | "any";
 export type AgentProfileBase = "host" | "minimal" | "isolated";
@@ -1921,7 +1976,7 @@ export interface OrchestratorRuntimeInput {
   providerCatalog?: ProviderCatalogSummary[];
 }
 
-export interface OrchestratorSpawnInput {
+interface OrchestratorSpawnInput {
   provider: SpawnProvider;
   model?: string;
   effort?: SpawnEffort;
@@ -2016,7 +2071,7 @@ export interface ProviderCatalogSummary {
   }>;
 }
 
-export interface OrchestratorSpawnResult {
+interface OrchestratorSpawnResult {
   orchestratorId: string;
   provider: SpawnProvider;
   sessionName?: string;
@@ -2057,19 +2112,19 @@ export interface RecipeAgent {
   env?: Record<string, string>;
 }
 
-export interface RecipeWorkflow {
+interface RecipeWorkflow {
   trigger?: string;
   fanOut?: "all" | "first";
   collect?: string;
   routing?: RecipeRoute[];
 }
 
-export interface RecipeRoute {
+interface RecipeRoute {
   pattern: string;
   pipeline: string[];
 }
 
-export interface RecipeLifecycle {
+interface RecipeLifecycle {
   mode?: "persistent" | "ephemeral";
   idleTimeoutMs?: number;
   memory?: RecipeMemoryPolicy;
@@ -2186,7 +2241,7 @@ export interface TokenConstraints {
   canDelegate?: boolean;
 }
 
-export type TokenScope =
+type TokenScope =
   | "system:admin"
   | "token:read"
   | "token:write"
@@ -2291,7 +2346,7 @@ export function errMessage(error: unknown): string {
 // --- Relay connection defaults ---
 
 /** Default port the relay server listens on. */
-export const DEFAULT_RELAY_PORT = 4850;
+const DEFAULT_RELAY_PORT = 4850;
 
 /** Default relay base URL. Loopback spelling settled on `127.0.0.1` (not `localhost`). */
 export const DEFAULT_RELAY_URL = `http://127.0.0.1:${DEFAULT_RELAY_PORT}`;