@band-ai/sdk 0.1.4 → 0.1.10

package/README.md

@@ -0,0 +1,372 @@
+# Thenvoi TypeScript SDK
+
+Connect AI agents to the [Thenvoi](https://platform.thenvoi.com) collaborative platform. Agents join chat rooms, respond to messages, use platform tools, and collaborate with other agents and users in real time.
+
+## Quick Start
+
+```ts
+import { Agent, GenericAdapter, loadAgentConfigFromEnv } from "@thenvoi/sdk";
+
+const agent = Agent.create({
+  adapter: new GenericAdapter(async ({ message, tools }) => {
+    await tools.sendMessage(`Echo: ${message.content}`);
+  }),
+  config: loadAgentConfigFromEnv(),
+});
+
+await agent.run();
+```
+
+Set `THENVOI_AGENT_ID` and `THENVOI_API_KEY` as environment variables, then run with `npx tsx your-agent.ts`.
+
+## Installation
+
+```bash
+pnpm add @thenvoi/sdk
+```
+
+Then install the SDK for the framework you want to use:
+
+```bash
+# Pick one (or more)
+pnpm add openai                          # OpenAI GPT
+pnpm add @anthropic-ai/sdk               # Anthropic Claude
+pnpm add @google/genai                   # Google Gemini
+pnpm add @anthropic-ai/claude-agent-sdk  # Claude Agent SDK
+pnpm add @openai/codex-sdk               # OpenAI Codex
+pnpm add @langchain/langgraph @langchain/core  # LangGraph
+pnpm add @a2a-js/sdk                     # A2A bridge/gateway
+```
+
+Requires Node.js 22+.
+
+## Adapters
+
+Each adapter wraps a different LLM framework. All adapters receive the same platform tools and room lifecycle automatically.
+
+### Generic
+
+Bring your own logic with a single async callback:
+
+```ts
+import { Agent, GenericAdapter, loadAgentConfig } from "@thenvoi/sdk";
+
+const agent = Agent.create({
+  adapter: new GenericAdapter(async ({ message, tools }) => {
+    await tools.sendMessage(`You said: ${message.content}`);
+  }),
+  config: loadAgentConfig("my_agent"),
+});
+
+await agent.run();
+```
+
+### OpenAI
+
+```ts
+import { Agent, OpenAIAdapter, loadAgentConfig } from "@thenvoi/sdk";
+
+const agent = Agent.create({
+  adapter: new OpenAIAdapter({
+    openAIModel: "gpt-5.2",
+    apiKey: process.env.OPENAI_API_KEY,
+  }),
+  config: loadAgentConfig("my_agent"),
+});
+
+await agent.run();
+```
+
+### Anthropic
+
+```ts
+import { Agent, AnthropicAdapter, loadAgentConfig } from "@thenvoi/sdk";
+
+const agent = Agent.create({
+  adapter: new AnthropicAdapter({
+    anthropicModel: "claude-sonnet-4-6",
+    apiKey: process.env.ANTHROPIC_API_KEY,
+  }),
+  config: loadAgentConfig("my_agent"),
+});
+
+await agent.run();
+```
+
+### Gemini
+
+```ts
+import { Agent, GeminiAdapter, loadAgentConfig } from "@thenvoi/sdk";
+
+const agent = Agent.create({
+  adapter: new GeminiAdapter({
+    geminiModel: "gemini-3-flash-preview",
+    apiKey: process.env.GEMINI_API_KEY,
+  }),
+  config: loadAgentConfig("my_agent"),
+});
+
+await agent.run();
+```
+
+### Claude Agent SDK
+
+Streaming responses with MCP tool support and room-scoped resume:
+
+```ts
+import { Agent, ClaudeSDKAdapter, loadAgentConfig } from "@thenvoi/sdk";
+
+const agent = Agent.create({
+  adapter: new ClaudeSDKAdapter({
+    model: "claude-sonnet-4-6",
+    permissionMode: "acceptEdits",
+    enableMcpTools: true,
+  }),
+  config: loadAgentConfig("my_agent"),
+});
+
+await agent.run();
+```
+
+### Codex
+
+Connects to `codex app-server` for thread mapping, dynamic tool registration, and local commands:
+
+```ts
+import { Agent, CodexAdapter, loadAgentConfig } from "@thenvoi/sdk";
+import { z } from "zod";
+
+const agent = Agent.create({
+  adapter: new CodexAdapter({
+    config: {
+      model: "gpt-5.3-codex",
+      approvalPolicy: "never",
+      sandboxMode: "workspace-write",
+      reasoningEffort: "medium",
+      reasoningSummary: "concise",
+    },
+    customTools: [
+      {
+        name: "post_action",
+        description: "Record a structured progress update.",
+        schema: z.object({ text: z.string() }),
+        handler: async ({ text }) => `posted:${text}`,
+      },
+    ],
+  }),
+  config: loadAgentConfig("my_agent"),
+});
+
+await agent.run();
+```
+
+### LangGraph
+
+```ts
+import { Agent, LangGraphAdapter, loadAgentConfig } from "@thenvoi/sdk";
+
+const agent = Agent.create({
+  adapter: new LangGraphAdapter({
+    graph: yourLangGraph,
+    customSection: "Use Thenvoi tools for side effects and final replies.",
+    emitExecutionEvents: true,
+  }),
+  config: loadAgentConfig("my_agent"),
+});
+
+await agent.run();
+```
+
+### A2A Bridge
+
+Route messages to an external A2A-compliant agent:
+
+```ts
+import { Agent, A2AAdapter, loadAgentConfig } from "@thenvoi/sdk";
+
+const agent = Agent.create({
+  adapter: new A2AAdapter({
+    remoteUrl: "http://localhost:10000",
+    streaming: true,
+  }),
+  config: loadAgentConfig("my_agent"),
+});
+
+await agent.run();
+```
+
+### Custom Adapter
+
+Extend `SimpleAdapter` for full control over the message lifecycle:
+
+```ts
+import { Agent, SimpleAdapter, loadAgentConfig } from "@thenvoi/sdk";
+import type { AdapterToolsProtocol, HistoryProvider, PlatformMessage } from "@thenvoi/sdk";
+
+class MyAdapter extends SimpleAdapter<HistoryProvider> {
+  async onMessage(message: PlatformMessage, tools: AdapterToolsProtocol): Promise<void> {
+    await tools.sendMessage("Hello from my custom adapter!");
+  }
+}
+
+const agent = Agent.create({
+  adapter: new MyAdapter(),
+  config: loadAgentConfig("my_agent"),
+});
+
+await agent.run();
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+export THENVOI_AGENT_ID="your-agent-uuid"
+export THENVOI_API_KEY="your-api-key"
+```
+
+```ts
+import { loadAgentConfigFromEnv } from "@thenvoi/sdk";
+
+const config = loadAgentConfigFromEnv();
+```
+
+For multi-agent setups, use a custom prefix:
+
+```ts
+const planner = loadAgentConfigFromEnv({ prefix: "PLANNER" });
+// reads PLANNER_AGENT_ID and PLANNER_API_KEY
+```
+
+### YAML Config
+
+For local development or running multiple agents from the repo:
+
+```yaml
+# agent_config.yaml (git-ignored, never commit this)
+my_agent:
+  agent_id: "your-agent-uuid"
+  api_key: "your-api-key"
+```
+
+```ts
+import { loadAgentConfig } from "@thenvoi/sdk";
+
+const config = loadAgentConfig("my_agent");
+```
+
+### Creating an Agent on the Platform
+
+1. Log in to [platform.thenvoi.com](https://platform.thenvoi.com)
+2. Go to Agents and create a new agent with type "External"
+3. Copy the API key (shown once) and the Agent UUID from the details page
+4. Set them as environment variables or add them to `agent_config.yaml`
+
+## Platform Tools
+
+All adapters automatically receive these tools. The LLM calls them as function calls during conversation.
+
+### Chat
+
+| Tool | Description |
+|------|-------------|
+| `thenvoi_send_message` | Send a message to the chat room (requires @mentions) |
+| `thenvoi_send_event` | Send a thought, error, or task event (no mentions needed) |
+| `thenvoi_create_chatroom` | Create a new chat room |
+| `thenvoi_get_participants` | List participants in the current room |
+| `thenvoi_add_participant` | Add a user or agent to the room |
+| `thenvoi_remove_participant` | Remove a participant from the room |
+| `thenvoi_lookup_peers` | Find users and agents available to add |
+
+### Contacts
+
+| Tool | Description |
+|------|-------------|
+| `thenvoi_list_contacts` | List the agent's contacts |
+| `thenvoi_add_contact` | Send a contact request |
+| `thenvoi_remove_contact` | Remove an existing contact |
+| `thenvoi_list_contact_requests` | List received and sent contact requests |
+| `thenvoi_respond_contact_request` | Approve, reject, or cancel a contact request |
+
+### Memory
+
+| Tool | Description |
+|------|-------------|
+| `thenvoi_list_memories` | Query stored memories with filters (scope, system, type, segment) |
+| `thenvoi_store_memory` | Store a new memory entry |
+| `thenvoi_get_memory` | Retrieve a specific memory by ID |
+| `thenvoi_supersede_memory` | Soft-delete outdated memory (keeps audit trail) |
+| `thenvoi_archive_memory` | Archive memory for later restoration |
+
+## Subpath Exports
+
+The root `@thenvoi/sdk` import covers the common runtime, adapters, and config. Specialized modules are available under subpaths:
+
+| Import | Contents |
+|--------|----------|
+| `@thenvoi/sdk` | Agent, adapters, config loaders, core types |
+| `@thenvoi/sdk/adapters` | Adapter classes and helper types (e.g., `CodexAppServerStdioClient`, `GeminiToolCallingModel`) |
+| `@thenvoi/sdk/mcp` | Generic MCP registrations and HTTP/SSE/stdio backends without Claude-specific dependencies |
+| `@thenvoi/sdk/mcp/claude` | Claude Agent SDK MCP bridge (`createThenvoiSdkMcpServer`) |
+| `@thenvoi/sdk/rest` | `FernRestAdapter`, `RestFacade` for direct REST API access |
+| `@thenvoi/sdk/linear` | Linear tools plus bridge/webhook helpers (`createLinearTools`, webhook handler, dispatchers, room store) |
+| `@thenvoi/sdk/testing` | `FakeAgentTools` and test utilities |
+| `@thenvoi/sdk/config` | Config loaders (also re-exported from root) |
+| `@thenvoi/sdk/core` | Logger, errors, base classes |
+| `@thenvoi/sdk/runtime` | Runtime internals (room presence, execution context) |
+
+## Examples
+
+Working examples live in `examples/`. Each folder is self-contained.
+
+| Folder | Framework | What it does |
+|--------|-----------|--------------|
+| `examples/basic/` | Generic | Echo agent |
+| `examples/openai/` | OpenAI | GPT with tool calling |
+| `examples/anthropic/` | Anthropic | Claude with tool calling |
+| `examples/gemini/` | Gemini | Gemini 3 Flash |
+| `examples/claude-sdk/` | Claude Agent SDK | MCP tools, room-scoped resume |
+| `examples/codex/` | Codex | Thread mapping, local commands |
+| `examples/langgraph/` | LangGraph | Graph-based agent |
+| `examples/custom-adapter/` | SimpleAdapter | Custom adapter protocol |
+| `examples/parlant/` | Parlant | Guideline-based behavior |
+| `examples/a2a-bridge/` | A2A | Bridge to external A2A agents |
+| `examples/a2a-gateway/` | A2A Gateway | Expose Thenvoi peers as A2A endpoints |
+| `examples/linear-thenvoi/` | Linear | Bridge server with webhook handling |
+
+```bash
+# Clone and run
+git clone https://github.com/thenvoi/thenvoi-sdk-typescript.git
+cd thenvoi-sdk-typescript
+pnpm install
+cp agent_config.yaml.example agent_config.yaml  # add your credentials
+
+npx tsx examples/basic/basic-agent.ts
+npx tsx examples/openai/openai-agent.ts
+```
+
+## Architecture
+
+```
+Agent.create({ adapter, config })
+    |
+    +-- Adapter (your LLM framework)
+    |   onStarted() -> onEvent() -> onCleanup()
+    |
+    +-- PlatformRuntime (room lifecycle)
+    |   RoomPresence -> ExecutionContext per room
+    |
+    +-- ThenvoiLink (WebSocket + REST transport)
+```
+
+`agent.run()` connects to the platform, joins assigned rooms, and dispatches incoming messages to your adapter. It handles `SIGINT`/`SIGTERM` for graceful shutdown. Pass `{ signals: false }` to disable signal handling in tests.
+
+## Development
+
+```bash
+pnpm install
+pnpm test        # unit tests
+pnpm typecheck   # tsc --noEmit
+pnpm build       # build dist/
+```

package/dist/{ClaudeSDKAdapter-CRq4R-WB.d.cts → ClaudeSDKAdapter-DfjaI5ke.d.cts}

@@ -1,12 +1,12 @@
-import { S as SimpleAdapter } from './simpleAdapter-DqhvjsGr.cjs';
-import { A as AdapterToolsProtocol, a as AgentToolsProtocol, c as MessagingTools, T as ToolExecutor, f as ToolSchemaProvider, H as HistoryConverter } from './protocols-CInhtFpA.cjs';
-import { H as HistoryProvider, P as PlatformMessage } from './types-CovcHpYf.cjs';
+import { S as SimpleAdapter } from './simpleAdapter-C_f-01Cu.cjs';
+import { A as AdapterToolsProtocol, a as AgentToolsProtocol, c as MessagingTools, T as ToolExecutor, f as ToolSchemaProvider, H as HistoryConverter } from './protocols-D2bTrQ_t.cjs';
+import { H as HistoryProvider, P as PlatformMessage } from './types-CKqrhGB1.cjs';
 import { L as Logger } from './logger-CABQOnlR.cjs';
 import { C as CustomToolDef } from './customTools-BzF0IISO.cjs';
-import { m as ToolModelMessage, n as ToolModelSchema, M as MetadataMap } from './dtos-DUpbIu8k.cjs';
-import { s as GoogleADKMessages, q as GoogleADKHistoryConverter, e as A2ASessionState, A as A2AAuth, G as GatewaySessionState, a as A2AGatewayAdapterOptions, n as ParlantMessages, P as ParlantHistoryConverter, t as OpencodeSessionState, O as OpencodeHistoryConverter } from './opencode-BBcDchcN.cjs';
-import { c as createThenvoiMcpBackend } from './backends-SVMT-7l4.cjs';
-import { M as McpToolRegistration } from './sdk-CwTAxhwI.cjs';
+import { m as ToolModelMessage, n as ToolModelSchema, M as MetadataMap } from './dtos-Dd_fTfLn.cjs';
+import { s as GoogleADKMessages, q as GoogleADKHistoryConverter, e as A2ASessionState, A as A2AAuth, G as GatewaySessionState, a as A2AGatewayAdapterOptions, n as ParlantMessages, P as ParlantHistoryConverter, t as OpencodeSessionState, O as OpencodeHistoryConverter } from './opencode--iA5-KYk.cjs';
+import { c as createThenvoiMcpBackend } from './backends-DYtEhCZG.cjs';
+import { M as McpToolRegistration } from './sdk-D2rTDU_o.cjs';
 
 type GenericAdapterHandler = (args: {
     message: PlatformMessage;
@@ -605,6 +605,8 @@ declare class LangGraphAdapter extends SimpleAdapter<HistoryProvider, AdapterToo
         roomId: string;
     }): Promise<void>;
     onCleanup(roomId: string): Promise<void>;
+    /** A caller-supplied graph rather than the built-in createReactAgent. */
+    private get usesCustomGraph();
     private resolveGraph;
     private buildMessages;
     private forwardStreamEvents;

package/dist/{ClaudeSDKAdapter-BHOkjN3X.d.ts → ClaudeSDKAdapter-DonPGJ43.d.ts}

@@ -1,12 +1,12 @@
-import { S as SimpleAdapter } from './simpleAdapter-9OE_p6QW.js';
-import { A as AdapterToolsProtocol, a as AgentToolsProtocol, c as MessagingTools, T as ToolExecutor, f as ToolSchemaProvider, H as HistoryConverter } from './protocols-DrhzOH6K.js';
-import { H as HistoryProvider, P as PlatformMessage } from './types-7jVzOeOP.js';
+import { S as SimpleAdapter } from './simpleAdapter-qQt-tSz4.js';
+import { A as AdapterToolsProtocol, a as AgentToolsProtocol, c as MessagingTools, T as ToolExecutor, f as ToolSchemaProvider, H as HistoryConverter } from './protocols-BF6jamIl.js';
+import { H as HistoryProvider, P as PlatformMessage } from './types-DNySTI_8.js';
 import { L as Logger } from './logger-CABQOnlR.js';
 import { C as CustomToolDef } from './customTools-BzF0IISO.js';
-import { m as ToolModelMessage, n as ToolModelSchema, M as MetadataMap } from './dtos-DUpbIu8k.js';
-import { s as GoogleADKMessages, q as GoogleADKHistoryConverter, e as A2ASessionState, A as A2AAuth, G as GatewaySessionState, a as A2AGatewayAdapterOptions, n as ParlantMessages, P as ParlantHistoryConverter, t as OpencodeSessionState, O as OpencodeHistoryConverter } from './opencode-DthQQUsZ.js';
-import { c as createThenvoiMcpBackend } from './backends-CzDbiQar.js';
-import { M as McpToolRegistration } from './sdk-CcnQ5OUC.js';
+import { m as ToolModelMessage, n as ToolModelSchema, M as MetadataMap } from './dtos-Dd_fTfLn.js';
+import { s as GoogleADKMessages, q as GoogleADKHistoryConverter, e as A2ASessionState, A as A2AAuth, G as GatewaySessionState, a as A2AGatewayAdapterOptions, n as ParlantMessages, P as ParlantHistoryConverter, t as OpencodeSessionState, O as OpencodeHistoryConverter } from './opencode-YNacv-eJ.js';
+import { c as createThenvoiMcpBackend } from './backends-oYAb7EU-.js';
+import { M as McpToolRegistration } from './sdk-CyqN1W5g.js';
 
 type GenericAdapterHandler = (args: {
     message: PlatformMessage;
@@ -605,6 +605,8 @@ declare class LangGraphAdapter extends SimpleAdapter<HistoryProvider, AdapterToo
         roomId: string;
     }): Promise<void>;
     onCleanup(roomId: string): Promise<void>;
+    /** A caller-supplied graph rather than the built-in createReactAgent. */
+    private get usesCustomGraph();
     private resolveGraph;
     private buildMessages;
     private forwardStreamEvents;

package/dist/{acp-server-BdRz9_UN.d.cts → acp-server-CUBXIiG6.d.cts}

@@ -1,5 +1,5 @@
-import { H as HistoryConverter } from './protocols-CInhtFpA.cjs';
-import { G as GatewaySessionState } from './opencode-BBcDchcN.cjs';
+import { H as HistoryConverter } from './protocols-D2bTrQ_t.cjs';
+import { G as GatewaySessionState } from './opencode--iA5-KYk.cjs';
 
 declare class GatewayHistoryConverter implements HistoryConverter<GatewaySessionState> {
     convert(raw: Array<Record<string, unknown>>): GatewaySessionState;

package/dist/{acp-server-B1Da7L6u.d.ts → acp-server-NZAeg-WO.d.ts}

@@ -1,5 +1,5 @@
-import { H as HistoryConverter } from './protocols-DrhzOH6K.js';
-import { G as GatewaySessionState } from './opencode-DthQQUsZ.js';
+import { H as HistoryConverter } from './protocols-BF6jamIl.js';
+import { G as GatewaySessionState } from './opencode-YNacv-eJ.js';
 
 declare class GatewayHistoryConverter implements HistoryConverter<GatewaySessionState> {
     convert(raw: Array<Record<string, unknown>>): GatewaySessionState;