agent-relay-sdk 0.2.17 → 0.2.18

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

@@ -26,8 +26,8 @@ export interface AgentCard {
 
 export type AgentStatus = "online" | "idle" | "busy" | "stale" | "offline";
 
-export type CapabilitySource = "catalog" | "provider" | "runtime" | "override" | "estimate";
-export type CapabilityConfidence = "declared" | "reported" | "verified" | "estimated" | "unknown";
+type CapabilitySource = "catalog" | "provider" | "runtime" | "override" | "estimate";
+type CapabilityConfidence = "declared" | "reported" | "verified" | "estimated" | "unknown";
 
 export interface ProviderCapabilities {
   lifecycle: {
@@ -99,7 +99,7 @@ export interface ProviderCapabilities {
   lastUpdatedAt: number;
 }
 
-export type ContextLifecycleState =
+type ContextLifecycleState =
   | "fresh"
   | "primed"
   | "working"
@@ -249,7 +249,7 @@ export interface ContextBudget {
   priorityCutoff: 1 | 2 | 3;
 }
 
-export interface TaskHistorySummary {
+interface TaskHistorySummary {
   taskId: number;
   agentId: string;
   status: string;
@@ -303,7 +303,7 @@ export interface MemoryBrokerContext {
 
 export type MemoryBrokerKind = "sqlite" | "http" | "command";
 
-export interface SqliteMemoryBrokerConfig {
+interface SqliteMemoryBrokerConfig {
   type: "sqlite";
 }
 
@@ -332,6 +332,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 +367,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 +1175,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 +1228,7 @@ export interface WorkspaceProbe {
   error?: string;
 }
 
-export interface WorkspaceGitCommit {
+interface WorkspaceGitCommit {
   sha: string;
   message: string;
   at?: number;
@@ -1548,7 +1573,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 +1946,7 @@ export interface OrchestratorRuntimeInput {
   providerCatalog?: ProviderCatalogSummary[];
 }
 
-export interface OrchestratorSpawnInput {
+interface OrchestratorSpawnInput {
   provider: SpawnProvider;
   model?: string;
   effort?: SpawnEffort;
@@ -2016,7 +2041,7 @@ export interface ProviderCatalogSummary {
   }>;
 }
 
-export interface OrchestratorSpawnResult {
+interface OrchestratorSpawnResult {
   orchestratorId: string;
   provider: SpawnProvider;
   sessionName?: string;
@@ -2057,19 +2082,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 +2211,7 @@ export interface TokenConstraints {
   canDelegate?: boolean;
 }
 
-export type TokenScope =
+type TokenScope =
   | "system:admin"
   | "token:read"
   | "token:write"
@@ -2291,7 +2316,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}`;