agent-relay 4.0.2 → 4.0.3

package/packages/sdk/src/provisioner/types.ts

@@ -0,0 +1,188 @@
+import type {
+  AccessPreset,
+  AgentPermissions,
+  CompiledAgentPermissions,
+  FilePermissions,
+  PermissionSource,
+} from '../workflows/types.js';
+import type { MountHandle } from './mount.js';
+
+// ── Input Configuration ────────────────────────────────────────────────────
+
+/** Configuration for provisioning workflow agents. */
+export interface WorkflowProvisionConfig {
+  /** HMAC secret used to sign JWT tokens. */
+  secret: string;
+
+  /** Workspace identifier (e.g. 'my-project'). */
+  workspace: string;
+
+  /** Absolute path to the project directory. */
+  projectDir: string;
+
+  /** Base URL of the relayfile server (e.g. 'http://127.0.0.1:4080'). */
+  relayfileBaseUrl: string;
+
+  /**
+   * Agents to provision, keyed by agent name.
+   * Each entry carries the AgentPermissions from relay.yaml.
+   * When empty/undefined, agents are auto-discovered from dotfiles.
+   */
+  agents?: Record<string, AgentPermissions>;
+
+  /** JWT token TTL in seconds. Default: 7200 (2 hours). */
+  tokenTtlSeconds?: number;
+
+  /**
+   * Directories to exclude from workspace seeding.
+   * Defaults: ['.relay', '.git', 'node_modules'].
+   */
+  excludeDirs?: string[];
+
+  /**
+   * When true, skip workspace creation and file seeding.
+   * Useful when only tokens/ACL are needed.
+   */
+  skipSeeding?: boolean;
+
+  /**
+   * Admin scopes for the workspace management token.
+   * Uses DEFAULT_ADMIN_SCOPES when omitted.
+   */
+  adminScopes?: string[];
+
+  /** Optional explicit relayfile-mount binary path. */
+  mountBinaryPath?: string;
+
+  /** Base directory for per-agent mount points. Defaults to <projectDir>/.relay. */
+  mountBaseDir?: string;
+
+  /** When true, skip starting relayfile mount processes. */
+  skipMount?: boolean;
+
+  /** When true, print a short audit summary to stdout after provisioning. */
+  verbose?: boolean;
+}
+
+// ── Output ─────────────────────────────────────────────────────────────────
+
+/** Aggregate counts for compiled permissions across provisioned agents. */
+export interface ProvisionSummary {
+  readonly: number;
+  readwrite: number;
+  denied: number;
+  customScopes: number;
+}
+
+/** Convenience shape for a single agent's compiled scopes. */
+export interface CompiledAgentScopes {
+  /** Agent name. */
+  agentName: string;
+
+  /** Workspace identifier. */
+  workspace: string;
+
+  /** Final token scopes after compilation. */
+  scopes: string[];
+
+  /** Directory ACL rules derived from the compiled permissions. */
+  acl: Record<string, string[]>;
+
+  /** Counts for the compiled access model. */
+  summary: ProvisionSummary;
+}
+
+/** Result of a single agent's provisioning. */
+export interface AgentProvisionResult {
+  /** Agent name. */
+  name: string;
+
+  /** Absolute path to the written JWT file (.relay/tokens/<name>.jwt). */
+  tokenPath: string;
+
+  /** The raw JWT string. */
+  token: string;
+
+  /** Scopes baked into the token. */
+  scopes: string[];
+
+  /** Full compiled permissions (for audit / dry-run output). */
+  compiled: CompiledAgentPermissions;
+
+  /** Absolute path to the mounted relayfile workspace for this agent, when active. */
+  mountPoint?: string;
+}
+
+/** Map of agent names to minted JWT strings. */
+export type AgentTokenMap = Record<string, string>;
+
+/** Map of agent names to their provisioning result. */
+export type AgentProvisionMap = Record<string, AgentProvisionResult>;
+
+/** Aggregate result of provisionWorkflowAgents(). */
+export interface ProvisionResult {
+  /** Per-agent results, keyed by agent name. */
+  agents: AgentProvisionMap;
+
+  /** Ordered list of agent names (matches iteration order). */
+  agentNames: string[];
+
+  /** Workspace-level admin token (used for seeding). */
+  adminToken: string;
+
+  /** Number of files seeded to the relayfile workspace. */
+  seededFileCount: number;
+
+  /** Number of ACL directory rules seeded. */
+  seededAclCount: number;
+
+  /** Aggregate summary across all agents. */
+  summary: ProvisionSummary;
+
+  /** Per-agent mounted workspace handles. */
+  mounts: Map<string, MountHandle>;
+
+  /** Per-agent minted JWT strings. */
+  tokens: Map<string, string>;
+
+  /** Per-agent compiled token scopes. */
+  scopes: Map<string, string[]>;
+}
+
+// ── Compiler Types ─────────────────────────────────────────────────────────
+
+/** Input to the permission compiler for a single agent. */
+export interface CompileInput {
+  agentName: string;
+  workspace: string;
+  projectDir: string;
+  permissions: AgentPermissions;
+}
+
+// ── Seeder Types ───────────────────────────────────────────────────────────
+
+/** Options for the ACL seeder. */
+export interface SeedAclOptions {
+  relayfileBaseUrl: string;
+  token: string;
+  workspace: string;
+  aclRules: Record<string, string[]>;
+}
+
+/** Options for workspace file seeding. */
+export interface SeedWorkspaceOptions {
+  relayfileBaseUrl: string;
+  token: string;
+  workspace: string;
+  projectDir: string;
+  excludeDirs: string[];
+}
+
+/** Minimal debug summary written alongside compiled ACL output. */
+export interface AgentAclSummary {
+  name: string;
+  summary: Pick<ProvisionSummary, 'readonly' | 'readwrite' | 'denied'>;
+}
+
+// Re-export upstream types for convenience.
+export type { AccessPreset, AgentPermissions, CompiledAgentPermissions, FilePermissions, PermissionSource };

package/packages/sdk/src/relay.ts

@@ -29,11 +29,7 @@ import path from 'node:path';
 
 import { RelayCast } from '@relaycast/sdk';
 
-import {
-  AgentRelayClient,
-  type AgentRelayBrokerInitArgs,
-  type AgentRelaySpawnOptions,
-} from './client.js';
+import { AgentRelayClient, type AgentRelayBrokerInitArgs, type AgentRelaySpawnOptions } from './client.js';
 import { AgentRelayProtocolError } from './transport.js';
 import type { SendMessageInput, SpawnPtyInput } from './types.js';
 import type {
@@ -220,6 +216,9 @@ export interface SpawnOptions extends SpawnLifecycleHooks {
   shadowMode?: string;
   idleThresholdSecs?: number;
   restartPolicy?: RestartPolicy;
+  /** JWT token for relayauth/relayfile permissions. When set, the broker
+   *  injects RELAY_AGENT_TOKEN into the agent's environment. */
+  agentToken?: string;
   /** When true, skip injecting the relay MCP configuration and protocol prompt into the spawned agent.
    *  Useful for minor tasks where relay messaging is not needed, saving tokens. */
   skipRelayPrompt?: boolean;
@@ -298,6 +297,9 @@ export interface SpawnerSpawnOptions extends SpawnLifecycleHooks {
   task?: string;
   model?: string;
   cwd?: string;
+  /** JWT token for relayauth/relayfile permissions. When set, the broker
+   *  injects RELAY_AGENT_TOKEN into the agent's environment. */
+  agentToken?: string;
   /** When true, skip injecting the relay MCP configuration and protocol prompt into the spawned agent.
    *  Useful for minor tasks where relay messaging is not needed, saving tokens. */
   skipRelayPrompt?: boolean;
@@ -584,6 +586,7 @@ export class AgentRelay {
         model: input.model,
         cwd: input.cwd,
         team: input.team,
+        agentToken: input.agentToken,
         shadowOf: input.shadowOf,
         shadowMode: input.shadowMode,
         idleThresholdSecs: input.idleThresholdSecs,
@@ -626,6 +629,7 @@ export class AgentRelay {
       model: options?.model,
       cwd: options?.cwd,
       team: options?.team,
+      agentToken: options?.agentToken,
       shadowOf: options?.shadowOf,
       shadowMode: options?.shadowMode,
       idleThresholdSecs: options?.idleThresholdSecs,
@@ -1124,7 +1128,11 @@ export class AgentRelay {
       const workspaceId = this.getResolvedWorkspaceId();
       if (workspaceId) {
         this.applyWorkspaceEnv(workspaceId, this.relayApiKey);
-        try { this.persistWorkspaceMapping(workspaceId, this.relayApiKey); } catch { /* non-critical */ }
+        try {
+          this.persistWorkspaceMapping(workspaceId, this.relayApiKey);
+        } catch {
+          /* non-critical */
+        }
       } else {
         this.wireRelaycastBaseUrl();
       }
@@ -1141,7 +1149,11 @@ export class AgentRelay {
       this.relayApiKey = resolvedKey;
       this.resolvedWorkspaceId = requestedWorkspaceId;
       this.applyWorkspaceEnv(requestedWorkspaceId, resolvedKey);
-      try { this.persistWorkspaceMapping(requestedWorkspaceId, resolvedKey); } catch { /* non-critical */ }
+      try {
+        this.persistWorkspaceMapping(requestedWorkspaceId, resolvedKey);
+      } catch {
+        /* non-critical */
+      }
       return;
     }
 
@@ -1153,7 +1165,11 @@ export class AgentRelay {
     this.relayApiKey = resolvedKey;
     this.resolvedWorkspaceId = resolvedWorkspaceId;
     this.applyWorkspaceEnv(resolvedWorkspaceId, resolvedKey);
-    try { this.persistWorkspaceMapping(resolvedWorkspaceId, resolvedKey); } catch { /* non-critical */ }
+    try {
+      this.persistWorkspaceMapping(resolvedWorkspaceId, resolvedKey);
+    } catch {
+      /* non-critical */
+    }
   }
 
   /** Inject relaycastBaseUrl into broker env. Explicit option wins over inherited env. */
@@ -1190,7 +1206,11 @@ export class AgentRelay {
           const workspaceId = this.getResolvedWorkspaceId();
           if (workspaceId) {
             this.applyWorkspaceEnv(workspaceId, c.workspaceKey);
-            try { this.persistWorkspaceMapping(workspaceId, c.workspaceKey); } catch { /* non-critical */ }
+            try {
+              this.persistWorkspaceMapping(workspaceId, c.workspaceKey);
+            } catch {
+              /* non-critical */
+            }
           }
         }
         this.wireEvents(c);
@@ -1582,6 +1602,7 @@ export class AgentRelay {
             task,
             model: options?.model,
             cwd: options?.cwd,
+            agentToken: options?.agentToken,
             skipRelayPrompt: options?.skipRelayPrompt,
             onStart: options?.onStart,
             onSuccess: options?.onSuccess,
@@ -1606,6 +1627,7 @@ export class AgentRelay {
             args,
             channels,
             task,
+            agentToken: options?.agentToken,
             skipRelayPrompt: options?.skipRelayPrompt,
           });
         } catch (error) {

package/packages/sdk/src/types.ts

@@ -19,6 +19,9 @@ export interface SpawnPtyInput {
   restartPolicy?: RestartPolicy;
   continueFrom?: string;
   skipRelayPrompt?: boolean;
+  /** JWT token for relayauth/relayfile permissions. When set, the broker
+   *  injects RELAY_AGENT_TOKEN into the agent's environment. */
+  agentToken?: string;
 }
 
 export interface SpawnHeadlessInput {
@@ -28,6 +31,9 @@ export interface SpawnHeadlessInput {
   channels?: string[];
   task?: string;
   skipRelayPrompt?: boolean;
+  /** JWT token for relayauth/relayfile permissions. When set, the broker
+   *  injects RELAY_AGENT_TOKEN into the agent's environment. */
+  agentToken?: string;
 }
 
 export type AgentTransport = 'pty' | 'headless';
@@ -48,6 +54,9 @@ export interface SpawnProviderInput {
   restartPolicy?: RestartPolicy;
   continueFrom?: string;
   skipRelayPrompt?: boolean;
+  /** JWT token for relayauth/relayfile permissions. When set, the broker
+   *  injects RELAY_AGENT_TOKEN into the agent's environment. */
+  agentToken?: string;
 }
 
 export interface SendMessageInput {