macro-agent 0.0.14 → 0.0.16

package/references/multi-agent-protocol/docs-site/sdk/api/agent.md

@@ -0,0 +1,357 @@
+---
+title: Agent API
+parent: API Reference
+grand_parent: SDK
+nav_order: 3
+description: "AgentConnection methods and properties"
+---
+
+# Agent API
+{: .no_toc }
+
+AgentConnection class for building MAP agents.
+{: .fs-6 .fw-300 }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## AgentConnection
+
+### Constructor
+
+```typescript
+const agent = new AgentConnection(stream: Stream, options: AgentOptions);
+
+interface AgentOptions {
+  name: string;
+  role?: string;
+  metadata?: Record<string, unknown>;
+  auth?: AuthCredentials;
+  reconnect?: ReconnectOptions;
+}
+```
+
+---
+
+## Properties
+
+| Property | Type | Description |
+|:---------|:-----|:------------|
+| `state` | `ConnectionState` | Current connection state |
+| `id` | `string \| undefined` | Registered agent ID |
+| `sessionId` | `string \| undefined` | Current session ID |
+| `resumeToken` | `string \| undefined` | Token for session resume |
+
+---
+
+## Connection Methods
+
+### connect()
+
+Connect and register the agent:
+
+```typescript
+const result = await agent.connect(options?: ConnectOptions): Promise<AgentConnectResult>;
+
+interface ConnectOptions {
+  resumeToken?: string;
+}
+
+interface AgentConnectResult {
+  agent: RegisteredAgent;
+  connection: {
+    sessionId: string;
+    resumed: boolean;
+  };
+}
+```
+
+### disconnect()
+
+Gracefully disconnect and unregister:
+
+```typescript
+await agent.disconnect(): Promise<void>;
+```
+
+---
+
+## Message Handling
+
+### onMessage()
+
+Register a message handler:
+
+```typescript
+agent.onMessage(handler: MessageHandler): void;
+
+type MessageHandler = (message: IncomingMessage) => void | Promise<void>;
+
+interface IncomingMessage {
+  id: string;
+  from: string;
+  payload: unknown;
+  meta?: MessageMeta;
+  timestamp: number;
+}
+```
+
+Multiple handlers can be registered and are called in order:
+
+```typescript
+agent.onMessage((message) => {
+  console.log(`Received: ${message.id}`);
+});
+
+agent.onMessage(async (message) => {
+  if (message.payload.type === "task") {
+    await processTask(message.payload);
+  }
+});
+```
+
+---
+
+## Messaging Methods
+
+### send()
+
+Send a message to another agent or scope:
+
+```typescript
+const result = await agent.send(params: SendParams): Promise<SendResult>;
+
+interface SendParams {
+  to: Address;
+  payload: unknown;
+  meta?: {
+    priority?: "low" | "normal" | "high" | "urgent";
+    ttl?: number;
+    requireAck?: boolean;
+  };
+}
+
+type Address =
+  | { agentId: string }
+  | { scopeId: string }
+  | { role: string }
+  | { parent: true }
+  | { children: true };
+
+interface SendResult {
+  messageId: string;
+  delivered: number;
+}
+```
+
+---
+
+## Agent State Methods
+
+### update()
+
+Update agent state or metadata:
+
+```typescript
+await agent.update(updates: AgentUpdates): Promise<RegisteredAgent>;
+
+interface AgentUpdates {
+  state?: "running" | "busy" | "suspended";
+  metadata?: Record<string, unknown>;
+}
+```
+
+---
+
+## Scope Methods
+
+### createScope()
+
+Create a new scope:
+
+```typescript
+const scope = await agent.createScope(params: CreateScopeParams): Promise<Scope>;
+
+interface CreateScopeParams {
+  name: string;
+  parentId?: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+### joinScope()
+
+Join an existing scope:
+
+```typescript
+await agent.joinScope(scopeId: string): Promise<void>;
+```
+
+### leaveScope()
+
+Leave a scope:
+
+```typescript
+await agent.leaveScope(scopeId: string): Promise<void>;
+```
+
+### listScopes()
+
+List available scopes:
+
+```typescript
+const { scopes } = await agent.listScopes(): Promise<ListScopesResult>;
+```
+
+---
+
+## Query Methods
+
+### listAgents()
+
+List other agents:
+
+```typescript
+const { agents } = await agent.listAgents(filter?: AgentFilter): Promise<ListAgentsResult>;
+
+interface AgentFilter {
+  role?: string;
+  state?: string;
+  scopeId?: string;
+}
+```
+
+### getAgent()
+
+Get details for a specific agent:
+
+```typescript
+const { agent: otherAgent } = await agent.getAgent(agentId: string): Promise<GetAgentResult>;
+```
+
+---
+
+## Subscription Methods
+
+### subscribe()
+
+Subscribe to system events:
+
+```typescript
+const subscription = await agent.subscribe(params: SubscribeParams): Promise<Subscription>;
+
+interface SubscribeParams {
+  eventTypes: string[];
+  scopeIds?: string[];
+}
+```
+
+---
+
+## State Management
+
+### onStateChange()
+
+Listen for connection state changes:
+
+```typescript
+agent.onStateChange(handler: (state: ConnectionState) => void): void;
+```
+
+---
+
+## Event Handlers
+
+### onError()
+
+Handle errors:
+
+```typescript
+agent.onError(handler: (error: Error) => void): void;
+```
+
+### onReconnecting()
+
+Handle reconnection attempts:
+
+```typescript
+agent.onReconnecting(handler: (attempt: number) => void): void;
+```
+
+### onReconnected()
+
+Handle successful reconnection:
+
+```typescript
+agent.onReconnected(handler: () => void): void;
+```
+
+---
+
+## Types
+
+### RegisteredAgent
+
+```typescript
+interface RegisteredAgent {
+  id: string;
+  name: string;
+  role?: string;
+  state: AgentState;
+  parentId?: string;
+  scopeIds: string[];
+  metadata?: Record<string, unknown>;
+  registeredAt: number;
+}
+
+type AgentState = "registered" | "running" | "busy" | "suspended" | "stopped";
+```
+
+---
+
+## Example
+
+```typescript
+import { AgentConnection } from "@multi-agent-protocol/sdk";
+
+const agent = new AgentConnection(stream, {
+  name: "TaskProcessor",
+  role: "worker",
+  metadata: {
+    capabilities: ["text-analysis"],
+  },
+  reconnect: { enabled: true },
+});
+
+// Connect and register
+const { agent: registered } = await agent.connect();
+console.log(`Registered as ${registered.id}`);
+
+// Join a scope
+await agent.joinScope("task-queue");
+
+// Handle messages
+agent.onMessage(async (message) => {
+  console.log(`Received task from ${message.from}`);
+
+  await agent.update({ state: "busy" });
+
+  try {
+    const result = await processTask(message.payload);
+
+    await agent.send({
+      to: { agentId: message.from },
+      payload: { type: "result", data: result },
+    });
+  } finally {
+    await agent.update({ state: "running" });
+  }
+});
+
+console.log("Ready to process tasks");
+```

package/references/multi-agent-protocol/docs-site/sdk/api/client.md

@@ -0,0 +1,380 @@
+---
+title: Client API
+parent: API Reference
+grand_parent: SDK
+nav_order: 2
+description: "ClientConnection methods and properties"
+---
+
+# Client API
+{: .no_toc }
+
+ClientConnection class for observing MAP systems.
+{: .fs-6 .fw-300 }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## ClientConnection
+
+### Constructor
+
+```typescript
+const client = new ClientConnection(stream: Stream, options: ClientOptions);
+
+interface ClientOptions {
+  name: string;
+  auth?: AuthCredentials;
+  reconnect?: ReconnectOptions;
+}
+
+interface AuthCredentials {
+  method: "bearer" | "api-key" | "none";
+  credential?: string;
+}
+
+interface ReconnectOptions {
+  enabled: boolean;
+  maxAttempts?: number;     // Default: 5
+  baseDelayMs?: number;     // Default: 1000
+  maxDelayMs?: number;      // Default: 30000
+}
+```
+
+---
+
+## Properties
+
+| Property | Type | Description |
+|:---------|:-----|:------------|
+| `state` | `ConnectionState` | Current connection state |
+| `sessionId` | `string \| undefined` | Current session ID |
+| `resumeToken` | `string \| undefined` | Token for session resume |
+
+```typescript
+type ConnectionState = "initial" | "connecting" | "connected" | "reconnecting" | "closed";
+```
+
+---
+
+## Connection Methods
+
+### connect()
+
+Establish connection to the server:
+
+```typescript
+const result = await client.connect(options?: ConnectOptions): Promise<ConnectResult>;
+
+interface ConnectOptions {
+  resumeToken?: string;  // Resume previous session
+}
+
+interface ConnectResult {
+  sessionId: string;
+  participantId: string;
+  systemInfo?: {
+    name: string;
+    version: string;
+  };
+  serverCapabilities: ServerCapabilities;
+  principal?: Principal;
+  resumed?: boolean;
+}
+```
+
+### disconnect()
+
+Gracefully disconnect:
+
+```typescript
+await client.disconnect(): Promise<void>;
+```
+
+### updateAuth()
+
+Update authentication credentials:
+
+```typescript
+client.updateAuth(credentials: AuthCredentials): void;
+```
+
+---
+
+## Query Methods
+
+### listAgents()
+
+List registered agents:
+
+```typescript
+const { agents } = await client.listAgents(filter?: AgentFilter): Promise<ListAgentsResult>;
+
+interface AgentFilter {
+  role?: string;
+  state?: string;
+  scopeId?: string;
+}
+
+interface ListAgentsResult {
+  agents: Agent[];
+}
+```
+
+### getAgent()
+
+Get a specific agent:
+
+```typescript
+const { agent } = await client.getAgent(agentId: string): Promise<GetAgentResult>;
+
+interface GetAgentResult {
+  agent: Agent | null;
+}
+```
+
+### listScopes()
+
+List available scopes:
+
+```typescript
+const { scopes } = await client.listScopes(filter?: ScopeFilter): Promise<ListScopesResult>;
+
+interface ListScopesResult {
+  scopes: Scope[];
+}
+```
+
+### getScope()
+
+Get a specific scope:
+
+```typescript
+const { scope } = await client.getScope(scopeId: string): Promise<GetScopeResult>;
+
+interface GetScopeResult {
+  scope: Scope | null;
+}
+```
+
+---
+
+## Subscription Methods
+
+### subscribe()
+
+Subscribe to events:
+
+```typescript
+const subscription = await client.subscribe(params: SubscribeParams): Promise<Subscription>;
+
+interface SubscribeParams {
+  eventTypes: string[];      // e.g., ["agent.*", "message.sent"]
+  scopeIds?: string[];       // Filter by scopes
+  options?: {
+    bufferSize?: number;
+    overflowStrategy?: "drop" | "error" | "block";
+  };
+}
+```
+
+### Subscription Object
+
+```typescript
+interface Subscription {
+  id: string;
+
+  // Async iterator for events
+  [Symbol.asyncIterator](): AsyncIterator<Event>;
+
+  // Control methods
+  pause(): Promise<void>;
+  resume(): Promise<void>;
+  unsubscribe(): Promise<void>;
+
+  // Backpressure
+  ack(eventId: string): Promise<void>;
+}
+
+// Usage
+for await (const event of subscription) {
+  console.log(event.type, event.data);
+}
+```
+
+---
+
+## Messaging Methods
+
+### send()
+
+Send a message:
+
+```typescript
+const result = await client.send(params: SendParams): Promise<SendResult>;
+
+interface SendParams {
+  to: Address;
+  payload: unknown;
+  meta?: {
+    priority?: "low" | "normal" | "high" | "urgent";
+    ttl?: number;
+    requireAck?: boolean;
+  };
+}
+
+type Address =
+  | { agentId: string }
+  | { scopeId: string }
+  | { role: string };
+
+interface SendResult {
+  messageId: string;
+  delivered: number;
+}
+```
+
+---
+
+## Replay Methods
+
+### replay()
+
+Replay missed events:
+
+```typescript
+const events = await client.replay(params: ReplayParams): Promise<Event[]>;
+
+interface ReplayParams {
+  afterEventId?: string;
+  fromTimestamp?: number;
+  toTimestamp?: number;
+  eventTypes?: string[];
+  limit?: number;
+}
+```
+
+---
+
+## State Management
+
+### onStateChange()
+
+Listen for connection state changes:
+
+```typescript
+client.onStateChange(handler: (state: ConnectionState) => void): void;
+```
+
+### Current State
+
+```typescript
+if (client.state === "connected") {
+  // Safe to make requests
+}
+```
+
+---
+
+## Event Handlers
+
+### onError()
+
+Handle connection errors:
+
+```typescript
+client.onError(handler: (error: Error) => void): void;
+```
+
+### onReconnecting()
+
+Handle reconnection attempts:
+
+```typescript
+client.onReconnecting(handler: (attempt: number) => void): void;
+```
+
+### onReconnected()
+
+Handle successful reconnection:
+
+```typescript
+client.onReconnected(handler: () => void): void;
+```
+
+---
+
+## Types
+
+### Agent
+
+```typescript
+interface Agent {
+  id: string;
+  name: string;
+  role?: string;
+  state: string;
+  parentId?: string;
+  scopeIds: string[];
+  metadata?: Record<string, unknown>;
+}
+```
+
+### Scope
+
+```typescript
+interface Scope {
+  id: string;
+  name: string;
+  parentId?: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+### Event
+
+```typescript
+interface Event {
+  id: string;
+  type: string;
+  data: unknown;
+  timestamp: number;
+  agentId?: string;
+  scopeId?: string;
+}
+```
+
+---
+
+## Example
+
+```typescript
+import { ClientConnection } from "@multi-agent-protocol/sdk";
+
+const client = new ClientConnection(stream, {
+  name: "Dashboard",
+  reconnect: { enabled: true },
+});
+
+// Connect
+const { sessionId, systemInfo } = await client.connect();
+console.log(`Connected to ${systemInfo?.name}`);
+
+// Query agents
+const { agents } = await client.listAgents({ role: "worker" });
+console.log(`Found ${agents.length} workers`);
+
+// Subscribe to events
+const subscription = await client.subscribe({
+  eventTypes: ["agent.*"],
+});
+
+for await (const event of subscription) {
+  console.log(`${event.type}: ${JSON.stringify(event.data)}`);
+}
+```