Merge pull request #61 from AgentWorkforce/feat-system-identity-first-class

Add first-class system identity support

Author: willwashburn

README.md

@@ -107,6 +107,7 @@ Relaycast is the messaging backbone:
 - Workspace: isolated environment for one project/team
 - Workspace key (`rk_live_*`): admin token for managing workspace resources
 - Agent token (`at_live_*`): token an individual agent uses to participate
+- Identity types: `agent` (AI worker), `human` (person), `system` (automation/service actor)
 - Channel: shared room for team/agent communication
 - Message: post in channel/DM/thread, with optional files and reactions
 
@@ -126,6 +127,9 @@ me.on.messageCreated((event) => {
 });
 
 await me.send('#general', 'Hello from Relaycast');
+
+// Convenience identity helpers
+const { token: systemToken } = await relay.system({ name: 'System' });
 ```
 
 Running locally:

openapi.yaml

@@ -59,6 +59,7 @@ components:
           type: string
         type:
           type: string
+          enum: [agent, human, system]
         persona:
           type: string
         status:
@@ -378,6 +379,7 @@ paths:
                   type: string
                 type:
                   type: string
+                  enum: [agent, human, system]
                 persona:
                   type: string
                 metadata:

packages/observer-dashboard/src/components/AgentPanel.tsx

@@ -50,6 +50,12 @@ export function AgentPanel({ agent, onClose }: AgentPanelProps) {
   const cli = (agent.metadata?.cli as string) || (agent.metadata?.spawn as Record<string, unknown>)?.cli as string || 'unknown';
   const model = (agent.metadata?.model as string) || '';
   const currentTask = (agent.metadata?.current_task as string) || '';
+  const identityLabel = agent.type === 'human' ? 'Human' : agent.type === 'system' ? 'System' : 'Agent';
+  const identityIcon = agent.type === 'human'
+    ? <User className="h-3.5 w-3.5" />
+    : agent.type === 'system'
+      ? <Sparkles className="h-3.5 w-3.5" />
+      : <Bot className="h-3.5 w-3.5" />;
 
   // Collect metadata entries to display (excluding known fields)
   const extraMeta = Object.entries(agent.metadata || {}).filter(
@@ -80,7 +86,7 @@ export function AgentPanel({ agent, onClose }: AgentPanelProps) {
             <span className={`text-xs ${status.color}`}>{status.text}</span>
             <span className="text-xs text-[var(--color-text-dim)] mx-1">&middot;</span>
             <span className="text-xs text-[var(--color-text-muted)]">
-              {agent.type === 'human' ? 'Human' : 'Agent'}
+              {identityLabel}
             </span>
           </div>
         </div>
@@ -123,7 +129,7 @@ export function AgentPanel({ agent, onClose }: AgentPanelProps) {
             value={relativeTime(agent.lastSeen)}
           />
           <InfoRow
-            icon={agent.type === 'human' ? <User className="h-3.5 w-3.5" /> : <Bot className="h-3.5 w-3.5" />}
+            icon={identityIcon}
             label="Created"
             value={formatDate(agent.createdAt ?? agent.lastSeen)}
           />

packages/react/src/__tests__/reducer.test.ts

@@ -36,7 +36,7 @@ function makeChannel(overrides: Partial<{ id: string; workspaceId: string; name:
   };
 }
 
-function makeAgent(overrides: Partial<{ id: string; workspaceId: string; name: string; type: 'agent' | 'human'; tokenHash: string; status: 'online' | 'offline' | 'away'; persona: string | null; metadata: Record<string, unknown>; createdAt: string; lastSeen: string }> = {}) {
+function makeAgent(overrides: Partial<{ id: string; workspaceId: string; name: string; type: 'agent' | 'human' | 'system'; tokenHash: string; status: 'online' | 'offline' | 'away'; persona: string | null; metadata: Record<string, unknown>; createdAt: string; lastSeen: string }> = {}) {
   return {
     id: 'ag1',
     workspaceId: 'ws1',

packages/sdk-python/src/relay_sdk/models.py

@@ -9,7 +9,7 @@
 
 # ── Enums / Literals ──────────────────────────────────────────────
 
-AgentType = Literal["agent", "human"]
+AgentType = Literal["agent", "human", "system"]
 AgentStatus = Literal["online", "offline", "away"]
 FileStatus = Literal["pending", "complete", "deleted"]
 DmType = Literal["1:1", "group"]

packages/sdk-rust/src/credentials.rs

@@ -66,7 +66,7 @@ pub struct AgentSession {
 pub struct BootstrapConfig {
     /// Preferred agent name. If not set, the server assigns one.
     pub preferred_name: Option<String>,
-    /// Agent type (e.g. "agent", "human"). Defaults to "agent".
+    /// Agent type (e.g. "agent", "human", "system"). Defaults to "agent".
     pub agent_type: Option<String>,
     /// Custom base URL. Defaults to https://api.relaycast.dev.
     pub base_url: Option<String>,

packages/sdk-typescript/src/__tests__/relay.test.ts

@@ -136,6 +136,19 @@ describe('RelayCast', () => {
       expect(init.body).toBe(JSON.stringify({ name: 'Worker' }));
     });
 
+    it('system() registers a system identity', async () => {
+      const { RelayCast } = await import('../relay.js');
+      const relay = new RelayCast({ apiKey: 'rk_live_test123' });
+
+      mockFetch.mockImplementation(() => mockResponse({ ok: true }));
+      await relay.system({ name: 'System' } as any);
+
+      const [url, init] = mockFetch.mock.calls[0]!;
+      expect(url).toBe('https://api.relaycast.dev/v1/agents');
+      expect(init.method).toBe('POST');
+      expect(init.body).toBe(JSON.stringify({ name: 'System', type: 'system' }));
+    });
+
     it('list() calls GET /v1/agents', async () => {
       const { RelayCast } = await import('../relay.js');
       const relay = new RelayCast({ apiKey: 'rk_live_test123' });

packages/sdk-typescript/src/relay.ts

@@ -81,6 +81,9 @@ interface WorkspaceDmMessage {
   createdAt: string;
 }
 
+type RegisterTypedIdentityInput = Omit<CreateAgentRequest, 'type'>;
+type RegisterIdentityType = NonNullable<CreateAgentRequest['type']>;
+
 export class RelayCast {
   private client: HttpClient;
   private identityHint: { agentId: string; name: string } | null = null;
@@ -198,6 +201,13 @@ export class RelayCast {
     throw new RelayError('transport_error', 'Failed to register agent identity after suffix retries');
   }
 
+  private registerTypedIdentity(
+    type: RegisterIdentityType,
+    data: RegisterTypedIdentityInput,
+  ): Promise<CreateAgentResponse> {
+    return this.agents.register({ ...data, type });
+  }
+
   async registerAgent(data: RegisterAgentInput): Promise<CreateAgentResponse> {
     const { strict, ...request } = data;
     if (strict) {
@@ -235,6 +245,18 @@ export class RelayCast {
     return this.resolveIdentityInternal();
   }
 
+  agent(data: RegisterTypedIdentityInput): Promise<CreateAgentResponse> {
+    return this.registerTypedIdentity('agent', data);
+  }
+
+  human(data: RegisterTypedIdentityInput): Promise<CreateAgentResponse> {
+    return this.registerTypedIdentity('human', data);
+  }
+
+  system(data: RegisterTypedIdentityInput): Promise<CreateAgentResponse> {
+    return this.registerTypedIdentity('system', data);
+  }
+
   workspace = {
     info: (): Promise<Workspace> => this.client.get('/v1/workspace'),
     update: (data: UpdateWorkspaceRequest): Promise<Workspace> =>

packages/server/src/routes/__tests__/agent.test.ts

@@ -77,6 +77,18 @@ describe('POST /v1/agents', () => {
     expect(body.error.code).toBe('invalid_request');
   });
 
+  it('returns 400 when type is invalid', async () => {
+    const res = await app.request('/v1/agents', {
+      method: 'POST',
+      headers: wsAuthHeaders(),
+      body: JSON.stringify({ name: 'CodeReviewer', type: 'robot' }),
+    }, bindings);
+
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.error.code).toBe('invalid_request');
+  });
+
   it('returns 409 for duplicate agent name', async () => {
     vi.mocked(agentEngine.registerAgent).mockRejectedValue(
       Object.assign(new Error('Agent "CodeReviewer" already exists'), {

packages/server/src/routes/agent.ts

@@ -1,5 +1,6 @@
 import { Hono } from 'hono';
 import { z } from 'zod';
+import { AgentTypeSchema } from '@relaycast/types';
 import type { AppEnv } from '../env.js';
 import { requireWorkspaceKey } from '../middleware/auth.js';
 import { rateLimit } from '../middleware/rateLimit.js';
@@ -12,7 +13,7 @@ export const agentRoutes = new Hono<AppEnv>();
 
 const registerAgentSchema = z.object({
   name: z.string().min(1),
-  type: z.string().optional(),
+  type: AgentTypeSchema.optional(),
   persona: z.string().optional(),
   metadata: z.record(z.string(), z.unknown()).optional(),
 });