agent-relay-sdk 0.2.7 → 0.2.9

package/src/types.ts

@@ -450,6 +450,9 @@ export interface Message {
   reactions?: MessageReaction[];
   readBy: string[];
   createdAt: number;
+  // True event time (#196). Equals createdAt for messages posted live; differs only when a
+  // Runner backfilled a message queued during an outage. Read `occurredAt ?? createdAt`.
+  occurredAt?: number;
 }
 
 export interface ReplyObligation {
@@ -537,6 +540,10 @@ export interface SendMessageInput {
   attachments?: AttachmentRef[];
   payload?: Record<string, unknown>;
   meta?: Record<string, unknown>;
+  // Epoch-ms event time, stamped when the event actually occurred (#196). When a Runner
+  // queues a message through its durable outbox during a server outage, this preserves the
+  // true time rather than the (later) server receive time. Defaults server-side to created_at.
+  occurredAt?: number;
 }
 
 export type ConnectorKind = "channel" | "event" | "provider" | "orchestrator";
@@ -1123,10 +1130,29 @@ export interface ActivityEventInput {
 // --- Orchestrators ---
 
 export type OrchestratorStatus = "online" | "offline";
-export type SpawnProvider = "claude" | "codex";
-export type SpawnApprovalMode = "open" | "guarded" | "read-only";
+
+/** 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 {
+  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 {
+  return typeof value === "string" && (APPROVAL_MODES as readonly string[]).includes(value);
+}
+
 export type SpawnEffort = "low" | "medium" | "high" | "xhigh" | "max";
-export type WorkspaceMode = "isolated" | "shared" | "inherit";
+
+/** Workspace modes — runtime tuple + derived type + guard. */
+export const VALID_WORKSPACE_MODES = ["isolated", "shared", "inherit"] as const;
+export type WorkspaceMode = (typeof VALID_WORKSPACE_MODES)[number];
+export function isWorkspaceMode(value: unknown): value is WorkspaceMode {
+  return typeof value === "string" && (VALID_WORKSPACE_MODES as readonly string[]).includes(value);
+}
 export type WorkspaceStatus = "active" | "ready" | "conflict" | "review_requested" | "merge_planned" | "merged" | "abandoned" | "cleanup_requested" | "cleaned";
 
 /** How a workspace's work is integrated back into its base branch. */
@@ -1187,6 +1213,8 @@ export interface WorkspaceGitState {
   lastCommit?: WorkspaceGitCommit;
   /** Ref/sha the ahead/behind counts were computed against. */
   baseRef?: string;
+  /** Branch currently checked out in the worktree (for recorded-vs-live mismatch). */
+  branch?: string;
   /** Set when the worktree path no longer exists on disk. */
   missing?: boolean;
   /** Populated when git interrogation failed. */
@@ -1255,12 +1283,44 @@ export interface WorkspaceMergeResult {
   mergedSha?: string;
   branchDeleted?: boolean;
   worktreeRemoved?: boolean;
+  /** Fresh branch the worktree was recycled onto after a land-and-continue merge
+   * (#206) — the relay repoints the workspace row at it. Absent for terminal lands. */
+  newBranch?: string;
+  /** True when the landed base branch was pushed to its upstream (origin). */
+  pushed?: boolean;
   /** Resulting workspace status the relay should record. */
   status: WorkspaceStatus;
   /** Populated when the merge could not complete. */
   error?: string;
 }
 
+/**
+ * Joined steward briefing for one workspace (#208): the row, owner + orchestrator
+ * liveness, live git state, recorded-vs-live branch mismatch, any active steward
+ * claim, and a recommended next action — so a steward (or release agent) doesn't
+ * reconstruct it from ad-hoc shell + API calls.
+ */
+export interface WorkspaceDiagnostics {
+  workspaceId: string;
+  status: WorkspaceStatus;
+  mode: WorkspaceMode;
+  repoRoot: string;
+  worktreePath?: string;
+  recordedBranch?: string;
+  liveBranch?: string;
+  baseRef?: string;
+  branchMismatch?: boolean;
+  owner?: { id?: string; status?: string; online: boolean };
+  orchestrator?: { id?: string; online: boolean };
+  /** Active claim that auto-merge yields to (#208), if held and unexpired. */
+  claim?: { by?: string; purpose?: string; expiresAt?: number };
+  /** Live worktree git state (proxied from the host); absent when unavailable. */
+  gitState?: WorkspaceGitState;
+  /** Why git state is absent (host offline, no worktree, …). */
+  gitStateUnavailable?: string;
+  recommendation: { action: "merge" | "rebase" | "cleanup" | "review" | "wait" | "none"; confidence: "high" | "medium" | "low"; reason: string };
+}
+
 /** One changed file in a workspace diff against its base. */
 export interface WorkspaceDiffFile {
   path: string;
@@ -1313,6 +1373,14 @@ export interface WorkspaceDepsProvision {
   error?: string;
 }
 
+/** Result of symlinking configured untracked files/dirs from main into an isolated worktree. */
+export interface WorkspaceSymlinkProvision {
+  /** Relative paths (from repo root) that were symlinked from the main checkout. */
+  linked: string[];
+  /** Per-pattern failures, if any (best-effort: a failure never blocks the spawn). */
+  errors?: string[];
+}
+
 export interface WorkspaceMetadata {
   id?: string;
   mode: WorkspaceMode;
@@ -1326,6 +1394,8 @@ export interface WorkspaceMetadata {
   status?: WorkspaceStatus;
   stewardAgentId?: string;
   deps?: WorkspaceDepsProvision;
+  /** Configured untracked files/dirs symlinked from main (see WorkspaceConfig.symlinkPaths). */
+  symlinks?: WorkspaceSymlinkProvision;
   probe?: WorkspaceProbe;
 }
 
@@ -1521,6 +1591,21 @@ export interface StewardConfig {
   keepaliveSeconds: number;
 }
 
+/**
+ * Global workspace provisioning config for isolated worktrees (the dashboard "Workspace"
+ * spawn option). A fresh git worktree only contains git-tracked files; node_modules are
+ * symlinked from main automatically, and these additional untracked paths are too.
+ */
+export interface WorkspaceConfig {
+  /**
+   * Files or filename patterns to symlink from the main checkout into each isolated
+   * worktree. Plain names ("AGENTS.md", ".claude-rig") match files and directories;
+   * entries containing glob metacharacters (*?[]{}) are expanded against main. A path
+   * is only linked if it actually exists in main — missing entries are ignored.
+   */
+  symlinkPaths: string[];
+}
+
 /**
  * Continuous self-improvement ("Insights") module config — feature toggles for the
  * dogfooding flywheel (see docs/self-improvement.md, epic #183). Everything here is
@@ -2062,3 +2147,33 @@ export interface HealthReport {
   generatedAt: number;
   checks: HealthCheck[];
 }
+
+// --- Shared micro-helpers (single source of truth; do not re-declare per file) ---
+
+/** True for a non-null, non-array object. The canonical type guard for the whole repo. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Narrow `unknown` to a non-empty trimmed string, else `undefined`.
+ * Settled semantics: whitespace-only is treated as empty (returns `undefined`).
+ */
+export function stringValue(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/** Extract a human-readable message from any thrown value. */
+export function errMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// --- Relay connection defaults ---
+
+/** Default port the relay server listens on. */
+export 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}`;