@agentconnect/sdk 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# @agentconnect/sdk
+
+AgentConnect SDK for talking to a local AgentConnect host from browser or Node.
+
+## Install
+
+```bash
+bun add @agentconnect/sdk
+```
+
+```bash
+npm install @agentconnect/sdk
+```
+
+```bash
+pnpm add @agentconnect/sdk
+```
+
+## Quick start (browser)
+
+```ts
+import { AgentConnect } from '@agentconnect/sdk';
+
+const client = await AgentConnect.connect();
+const session = await client.sessions.create({ model: 'default' });
+
+let output = '';
+session.on('delta', (event) => {
+  output += event.text;
+});
+
+session.on('final', (event) => {
+  console.log('Final:', event.text);
+});
+
+session.on('error', (event) => {
+  console.error('Agent error:', event.message);
+});
+
+await session.send('Summarize this draft in 3 bullets.');
+```
+
+## Session context and resume
+
+```ts
+const session = await client.sessions.create({
+  model: 'codex',
+  cwd: '/path/to/project',
+  repoRoot: '/path/to/project',
+});
+
+session.on('final', (event) => {
+  console.log('Session id:', event.providerSessionId);
+});
+
+await session.send('Audit the README for clarity.', {
+  cwd: '/path/to/project/docs',
+});
+
+const resumed = await client.sessions.resume('sess_123', {
+  providerSessionId: 'provider-session-id',
+  cwd: '/path/to/project',
+});
+```
+
+## Additional session events
+
+```ts
+session.on('raw_line', (event) => {
+  console.log('CLI:', event.line);
+});
+
+session.on('provider_event', (event) => {
+  if (event.provider === 'codex') {
+    console.log('Codex event:', event.event);
+  }
+});
+```
+
+## Node usage
+
+```ts
+import { WebSocket } from 'ws';
+import { AgentConnect } from '@agentconnect/sdk';
+
+const client = await AgentConnect.connect({ webSocket: WebSocket });
+const session = await client.sessions.create({ model: 'codex', reasoningEffort: 'medium' });
+
+await session.send('Draft a product description for a local AI writing assistant.');
+await session.close();
+client.close();
+```
+
+## Provider and model helpers
+
+```ts
+const providers = await client.providers.list();
+const claude = await client.providers.status('claude');
+
+if (!claude.loggedIn) {
+  await client.providers.ensureInstalled('claude');
+  await client.providers.login('claude');
+}
+
+const models = await client.models.list('claude');
+const recent = await client.models.recent('claude');
+```
+
+## Requirements
+
+- Node 20+ for Node usage.
+- Browser usage relies on WebSocket support.
+
+## Docs
+
+See `docs/SDK.md` in the repo for the full SDK reference and `SPEC.md` for the protocol contract.

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+export type ProviderId = 'claude' | 'codex' | 'local';
+export type PackageManager = 'bun' | 'pnpm' | 'npm' | 'brew' | 'unknown';
+export type InstallResult = {
+    installed: boolean;
+    version?: string;
+    packageManager?: PackageManager;
+};
+export type ProviderInfo = {
+    id: ProviderId;
+    name?: string;
+    installed: boolean;
+    loggedIn: boolean;
+    version?: string;
+};
+export type ReasoningEffortOption = {
+    id: string;
+    label?: string;
+};
+export type ModelInfo = {
+    id: string;
+    provider: ProviderId;
+    displayName?: string;
+    contextWindow?: number;
+    maxOutputTokens?: number;
+    reasoningEfforts?: ReasoningEffortOption[];
+    defaultReasoningEffort?: string;
+};
+export type SessionEvent = {
+    type: 'delta';
+    text: string;
+} | {
+    type: 'final';
+    text: string;
+    providerSessionId?: string | null;
+} | {
+    type: 'usage';
+    usage: Record<string, number>;
+} | {
+    type: 'status';
+    status: 'thinking' | 'idle' | 'error';
+    error?: string;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'raw_line';
+    line: string;
+} | {
+    type: 'provider_event';
+    provider?: ProviderId;
+    event: Record<string, unknown>;
+};
+export type ProviderLoginOptions = {
+    baseUrl?: string;
+    apiKey?: string;
+    model?: string;
+    models?: string[];
+    loginMethod?: 'claudeai' | 'console';
+    loginExperience?: 'embedded' | 'terminal';
+};
+export type AgentConnectConnectOptions = {
+    host?: string;
+    preferInjected?: boolean;
+    timeoutMs?: number;
+    webSocket?: WebSocketConstructor;
+};
+export type SessionCreateOptions = {
+    model: string;
+    reasoningEffort?: string;
+    system?: string;
+    metadata?: Record<string, unknown>;
+    cwd?: string;
+    repoRoot?: string;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+};
+export type SessionSendOptions = {
+    metadata?: Record<string, unknown>;
+    cwd?: string;
+    repoRoot?: string;
+};
+export type SessionResumeOptions = {
+    model?: string;
+    reasoningEffort?: string;
+    providerSessionId?: string | null;
+    cwd?: string;
+    repoRoot?: string;
+};
+export interface AgentConnectSession {
+    id: string;
+    send(message: string, metadata?: Record<string, unknown>): Promise<void>;
+    send(message: string, options?: SessionSendOptions): Promise<void>;
+    cancel(): Promise<void>;
+    close(): Promise<void>;
+    on(type: SessionEvent['type'], handler: (ev: SessionEvent) => void): () => void;
+}
+export interface AgentConnectClient {
+    hello(): Promise<{
+        hostId: string;
+        hostName: string;
+        hostVersion: string;
+        protocolVersion: string;
+        mode: 'hosted' | 'local';
+        capabilities: string[];
+        providers: ProviderId[];
+        loginExperience?: 'embedded' | 'terminal';
+    }>;
+    close(): void;
+    providers: {
+        list(): Promise<ProviderInfo[]>;
+        status(provider: ProviderId): Promise<ProviderInfo>;
+        ensureInstalled(provider: ProviderId): Promise<InstallResult>;
+        login(provider: ProviderId, options?: ProviderLoginOptions): Promise<{
+            loggedIn: boolean;
+        }>;
+        logout(provider: ProviderId): Promise<{
+            loggedIn: boolean;
+        }>;
+    };
+    models: {
+        list(provider?: ProviderId): Promise<ModelInfo[]>;
+        recent(provider?: ProviderId): Promise<ModelInfo[]>;
+        info(model: string): Promise<ModelInfo>;
+    };
+    capabilities: {
+        observed(appId?: string): Promise<{
+            appId: string;
+            requested: string[];
+            observed: string[];
+            updatedAt: string;
+        }>;
+    };
+    sessions: {
+        create(options: SessionCreateOptions): Promise<AgentConnectSession>;
+        resume(sessionId: string, options?: SessionResumeOptions): Promise<AgentConnectSession>;
+    };
+    fs: {
+        read(path: string): Promise<{
+            content: string;
+        }>;
+        write(path: string, content: string): Promise<{
+            bytes: number;
+        }>;
+        list(path: string): Promise<{
+            entries: Array<{
+                name: string;
+                path: string;
+                type: string;
+            }>;
+        }>;
+        stat(path: string): Promise<{
+            type: string;
+            size: number;
+            mtime: string;
+        }>;
+    };
+    process: {
+        spawn(command: string, args?: string[]): Promise<{
+            pid: number;
+        }>;
+        kill(pid: number, signal?: string): Promise<{
+            success: boolean;
+        }>;
+    };
+    net: {
+        request(url: string, init?: {
+            method?: string;
+            headers?: Record<string, string>;
+            body?: string;
+        }): Promise<{
+            status: number;
+            headers: Record<string, string>;
+            body: string;
+        }>;
+    };
+    backend: {
+        start(appId: string): Promise<{
+            status: string;
+            url?: string;
+        }>;
+        stop(appId: string): Promise<{
+            status: string;
+        }>;
+        status(appId: string): Promise<{
+            status: string;
+            url?: string;
+        }>;
+    };
+}
+type WebSocketLike = {
+    addEventListener: (type: string, listener: (event: {
+        data?: unknown;
+    }) => void) => void;
+    removeEventListener: (type: string, listener: (event: {
+        data?: unknown;
+    }) => void) => void;
+    send: (data: string) => void;
+    close: () => void;
+};
+type WebSocketConstructor = new (url: string) => WebSocketLike;
+export declare class AgentConnect {
+    static connect(options?: AgentConnectConnectOptions): Promise<AgentConnectClient>;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,403 @@
+class WebSocketTransport {
+    socket;
+    pending = new Map();
+    notifyHandlers = new Set();
+    nextId = 1;
+    ready;
+    timeoutMs;
+    closed = false;
+    constructor(url, timeoutMs, webSocket) {
+        const WebSocketCtor = webSocket || globalThis.WebSocket;
+        if (!WebSocketCtor) {
+            throw new Error('WebSocket is not available in this environment. Provide AgentConnect.connect({ webSocket }) in Node.');
+        }
+        this.socket = new WebSocketCtor(url);
+        this.timeoutMs = timeoutMs;
+        const handleDisconnect = (message) => {
+            if (this.closed)
+                return;
+            this.closed = true;
+            for (const pending of this.pending.values()) {
+                pending.reject(new Error(message));
+            }
+            this.pending.clear();
+        };
+        this.ready = new Promise((resolve, reject) => {
+            const onOpen = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = () => {
+                cleanup();
+                reject(new Error('Failed to connect to AgentConnect host.'));
+            };
+            const onClose = () => {
+                cleanup();
+                reject(new Error('AgentConnect connection closed.'));
+            };
+            const cleanup = () => {
+                this.socket.removeEventListener('open', onOpen);
+                this.socket.removeEventListener('error', onError);
+                this.socket.removeEventListener('close', onClose);
+            };
+            this.socket.addEventListener('open', onOpen);
+            this.socket.addEventListener('error', onError);
+            this.socket.addEventListener('close', onClose);
+        });
+        this.socket.addEventListener('close', () => {
+            handleDisconnect('AgentConnect connection closed.');
+        });
+        this.socket.addEventListener('error', () => {
+            handleDisconnect('AgentConnect connection error.');
+        });
+        this.socket.addEventListener('message', (event) => {
+            const payload = typeof event.data === 'string' ? event.data : '';
+            if (!payload)
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(payload);
+            }
+            catch {
+                return;
+            }
+            if ('id' in msg && msg.result !== undefined) {
+                const pending = this.pending.get(msg.id);
+                if (pending) {
+                    this.pending.delete(msg.id);
+                    pending.resolve(msg.result);
+                }
+                return;
+            }
+            if ('id' in msg && msg.error) {
+                const pending = this.pending.get(msg.id);
+                if (pending) {
+                    this.pending.delete(msg.id);
+                    const err = msg.error;
+                    pending.reject(new Error(`${err.code}: ${err.message}`));
+                }
+                return;
+            }
+            if ('method' in msg && !('id' in msg)) {
+                for (const handler of this.notifyHandlers) {
+                    handler(msg);
+                }
+            }
+        });
+    }
+    async request(method, params) {
+        await this.ready;
+        if (this.closed) {
+            throw new Error('AgentConnect connection closed.');
+        }
+        const id = this.nextId++;
+        const payload = {
+            jsonrpc: '2.0',
+            id,
+            method,
+            params,
+        };
+        const timeout = this.timeoutMs;
+        return new Promise((resolve, reject) => {
+            const timer = timeout
+                ? setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(new Error('AgentConnect request timed out.'));
+                }, timeout)
+                : null;
+            this.pending.set(id, {
+                resolve: (value) => {
+                    if (timer)
+                        clearTimeout(timer);
+                    resolve(value);
+                },
+                reject: (err) => {
+                    if (timer)
+                        clearTimeout(timer);
+                    reject(err);
+                },
+            });
+            this.socket.send(JSON.stringify(payload));
+        });
+    }
+    onNotification(handler) {
+        this.notifyHandlers.add(handler);
+        return () => {
+            this.notifyHandlers.delete(handler);
+        };
+    }
+    close() {
+        this.socket.close();
+    }
+}
+class BridgeTransport {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    request(method, params) {
+        return this.bridge.request(method, params);
+    }
+    onNotification(handler) {
+        if (!this.bridge.onEvent) {
+            return () => { };
+        }
+        return this.bridge.onEvent(handler);
+    }
+}
+class AgentConnectSessionImpl {
+    id;
+    client;
+    listeners = new Map();
+    constructor(id, client) {
+        this.id = id;
+        this.client = client;
+    }
+    async send(message, options) {
+        const normalized = this.normalizeSendOptions(options);
+        await this.client.request('acp.sessions.send', {
+            sessionId: this.id,
+            message: { role: 'user', content: message },
+            metadata: normalized.metadata,
+            cwd: normalized.cwd,
+            repoRoot: normalized.repoRoot,
+        });
+    }
+    async cancel() {
+        await this.client.request('acp.sessions.cancel', { sessionId: this.id });
+    }
+    async close() {
+        try {
+            await this.client.request('acp.sessions.close', { sessionId: this.id });
+        }
+        finally {
+            this.client.dropSession(this.id);
+        }
+    }
+    on(type, handler) {
+        if (!this.listeners.has(type)) {
+            this.listeners.set(type, new Set());
+        }
+        const set = this.listeners.get(type);
+        if (set)
+            set.add(handler);
+        return () => {
+            set?.delete(handler);
+        };
+    }
+    emit(event) {
+        const handlers = this.listeners.get(event.type);
+        if (!handlers)
+            return;
+        for (const handler of handlers) {
+            handler(event);
+        }
+    }
+    normalizeSendOptions(options) {
+        if (!options)
+            return {};
+        const candidate = options;
+        if ('metadata' in candidate ||
+            'cwd' in candidate ||
+            'repoRoot' in candidate) {
+            return candidate;
+        }
+        return { metadata: options };
+    }
+}
+class AgentConnectClientImpl {
+    transport;
+    sessionStore = new Map();
+    constructor(transport) {
+        this.transport = transport;
+        this.transport.onNotification((notification) => {
+            if (notification.method !== 'acp.session.event')
+                return;
+            const params = notification.params ?? {};
+            const sessionId = String(params.sessionId ?? '');
+            if (!sessionId)
+                return;
+            const session = this.sessionStore.get(sessionId);
+            if (!session)
+                return;
+            const type = String(params.type ?? '');
+            const data = params.data;
+            const event = this.normalizeEvent(type, data);
+            if (event)
+                session.emit(event);
+        });
+    }
+    normalizeEvent(type, data) {
+        if (type === 'delta') {
+            return { type: 'delta', text: String(data?.text ?? '') };
+        }
+        if (type === 'final') {
+            const providerSessionId = typeof data?.providerSessionId === 'string'
+                ? data.providerSessionId
+                : typeof data?.sessionId === 'string'
+                    ? data.sessionId
+                    : undefined;
+            return { type: 'final', text: String(data?.text ?? ''), providerSessionId };
+        }
+        if (type === 'usage') {
+            return { type: 'usage', usage: data?.usage ?? {} };
+        }
+        if (type === 'status') {
+            const status = String(data?.status ?? 'idle');
+            const error = typeof data?.error === 'string' ? data.error : undefined;
+            return { type: 'status', status, error };
+        }
+        if (type === 'error') {
+            return { type: 'error', message: String(data?.message ?? 'Unknown error') };
+        }
+        if (type === 'raw_line') {
+            return { type: 'raw_line', line: String(data?.line ?? '') };
+        }
+        if (type === 'provider_event') {
+            const provider = typeof data?.provider === 'string' ? data.provider : undefined;
+            const event = data?.event && typeof data.event === 'object'
+                ? data.event
+                : {};
+            return { type: 'provider_event', provider, event };
+        }
+        return null;
+    }
+    request(method, params) {
+        return this.transport.request(method, params);
+    }
+    async hello() {
+        return (await this.request('acp.hello'));
+    }
+    close() {
+        this.transport.close?.();
+    }
+    providers = {
+        list: async () => {
+            const res = (await this.request('acp.providers.list'));
+            return res.providers ?? [];
+        },
+        status: async (provider) => {
+            const res = (await this.request('acp.providers.status', { provider }));
+            return res.provider;
+        },
+        ensureInstalled: async (provider) => {
+            return (await this.request('acp.providers.ensureInstalled', { provider }));
+        },
+        login: async (provider, options) => {
+            return (await this.request('acp.providers.login', { provider, options }));
+        },
+        logout: async (provider) => {
+            return (await this.request('acp.providers.logout', { provider }));
+        },
+    };
+    models = {
+        list: async (provider) => {
+            const res = (await this.request('acp.models.list', provider ? { provider } : undefined));
+            return res.models ?? [];
+        },
+        recent: async (provider) => {
+            const res = (await this.request('acp.models.recent', provider ? { provider } : undefined));
+            return res.models ?? [];
+        },
+        info: async (model) => {
+            const res = (await this.request('acp.models.info', { model }));
+            return res.model;
+        },
+    };
+    capabilities = {
+        observed: async (appId) => {
+            return (await this.request('acp.capabilities.observed', appId ? { appId } : undefined));
+        },
+    };
+    sessions = {
+        create: async (options) => {
+            const res = (await this.request('acp.sessions.create', options));
+            return this.getOrCreateSession(res.sessionId);
+        },
+        resume: async (sessionId, options) => {
+            await this.request('acp.sessions.resume', { sessionId, ...(options ?? {}) });
+            return this.getOrCreateSession(sessionId);
+        },
+    };
+    fs = {
+        read: async (path) => {
+            return (await this.request('acp.fs.read', { path }));
+        },
+        write: async (path, content) => {
+            return (await this.request('acp.fs.write', { path, content }));
+        },
+        list: async (path) => {
+            return (await this.request('acp.fs.list', { path }));
+        },
+        stat: async (path) => {
+            return (await this.request('acp.fs.stat', { path }));
+        },
+    };
+    process = {
+        spawn: async (command, args) => {
+            return (await this.request('acp.process.spawn', { command, args }));
+        },
+        kill: async (pid, signal) => {
+            return (await this.request('acp.process.kill', { pid, signal }));
+        },
+    };
+    net = {
+        request: async (url, init) => {
+            return (await this.request('acp.net.request', { url, ...init }));
+        },
+    };
+    backend = {
+        start: async (appId) => {
+            return (await this.request('acp.backend.start', { appId }));
+        },
+        stop: async (appId) => {
+            return (await this.request('acp.backend.stop', { appId }));
+        },
+        status: async (appId) => {
+            return (await this.request('acp.backend.status', { appId }));
+        },
+    };
+    getOrCreateSession(sessionId) {
+        const existing = this.sessionStore.get(sessionId);
+        if (existing)
+            return existing;
+        const session = new AgentConnectSessionImpl(sessionId, this);
+        this.sessionStore.set(sessionId, session);
+        return session;
+    }
+    dropSession(sessionId) {
+        this.sessionStore.delete(sessionId);
+    }
+}
+export class AgentConnect {
+    static async connect(options = {}) {
+        const { host, preferInjected = true, timeoutMs = 8000, webSocket } = options;
+        const injected = getInjectedBridge();
+        if (preferInjected && injected) {
+            return new AgentConnectClientImpl(new BridgeTransport(injected));
+        }
+        const target = host || resolveHostOverride() || 'ws://127.0.0.1:9630';
+        const transport = new WebSocketTransport(target, timeoutMs, webSocket);
+        return new AgentConnectClientImpl(transport);
+    }
+}
+function getInjectedBridge() {
+    const candidate = globalThis
+        .__AGENTCONNECT_BRIDGE__;
+    return candidate ?? null;
+}
+function resolveHostOverride() {
+    const location = globalThis.location;
+    if (location?.search) {
+        const params = new URLSearchParams(location.search);
+        const override = params.get('agentconnect');
+        if (override)
+            return override;
+    }
+    if (typeof process !== 'undefined' && typeof process.env !== 'undefined') {
+        const env = process.env.AGENTCONNECT_HOST;
+        if (env)
+            return env;
+    }
+    return null;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@agentconnect/sdk",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/rayzhudev/agent-connect",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rayzhudev/agent-connect.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/rayzhudev/agent-connect/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false
+}