feat(shared): MS23-P1-001 IAgentProvider interface + agent types (#718)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

packages/shared/src/types/agent-provider.types.ts

@@ -0,0 +1,78 @@
+// Agent message roles
+export type AgentMessageRole = "user" | "assistant" | "system" | "tool";
+
+// A single message in an agent conversation
+export interface AgentMessage {
+  id: string;
+  sessionId: string;
+  role: AgentMessageRole;
+  content: string;
+  timestamp: Date;
+  metadata?: Record<string, unknown>;
+}
+
+// Session lifecycle status
+export type AgentSessionStatus = "active" | "paused" | "completed" | "failed" | "idle";
+
+// An agent session (conversation thread)
+export interface AgentSession {
+  id: string;
+  providerId: string; // which provider owns this session
+  providerType: string; // "internal" | "openclaw" | etc.
+  label?: string;
+  status: AgentSessionStatus;
+  parentSessionId?: string; // for subagent trees
+  createdAt: Date;
+  updatedAt: Date;
+  metadata?: Record<string, unknown>;
+}
+
+// Result of listing sessions
+export interface AgentSessionList {
+  sessions: AgentSession[];
+  total: number;
+  cursor?: string;
+}
+
+// Result of injecting a message
+export interface InjectResult {
+  accepted: boolean;
+  messageId?: string;
+}
+
+// The IAgentProvider interface — every provider (internal, OpenClaw, future) implements this
+export interface IAgentProvider {
+  readonly providerId: string;
+  readonly providerType: string;
+  readonly displayName: string;
+
+  // Session management
+  listSessions(cursor?: string, limit?: number): Promise<AgentSessionList>;
+  getSession(sessionId: string): Promise<AgentSession | null>;
+  getMessages(sessionId: string, limit?: number, before?: string): Promise<AgentMessage[]>;
+
+  // Control operations
+  injectMessage(sessionId: string, content: string): Promise<InjectResult>;
+  pauseSession(sessionId: string): Promise<void>;
+  resumeSession(sessionId: string): Promise<void>;
+  killSession(sessionId: string, force?: boolean): Promise<void>;
+
+  // SSE streaming — returns an AsyncIterable of AgentMessage events
+  streamMessages(sessionId: string): AsyncIterable<AgentMessage>;
+
+  // Health
+  isAvailable(): Promise<boolean>;
+}
+
+// Provider configuration stored in DB (AgentProviderConfig model from P0 schema)
+export interface AgentProviderConfig {
+  id: string;
+  providerId: string;
+  providerType: string;
+  displayName: string;
+  baseUrl?: string;
+  apiToken?: string;
+  enabled: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}

packages/shared/src/types/index.ts

@@ -134,3 +134,6 @@ export * from "./widget.types";
 
 // Export WebSocket types
 export * from "./websocket.types";
+
+// Export agent provider types
+export * from "./agent-provider.types";