cccc-sdk 0.1.0 → 0.1.1

package/dist/client.js

@@ -1,536 +1,499 @@
 /**
- * CCCC Client SDK
- *
- * High-level API for interacting with CCCC daemon
+ * CCCC SDK client
  */
-import { callDaemon, pingDaemon } from './transport.js';
-import { createRequest } from './types/ipc.js';
-import { CCCCError } from './errors.js';
+import { DaemonAPIError, IncompatibleDaemonError, } from './errors.js';
+import { discoverEndpoint, callDaemon, openEventsStream, readLines, } from './transport.js';
 /**
- * Handle daemon response, throwing on error
+ * CCCC client
  */
-function handleResponse(response) {
-    if (!response.ok) {
-        if (response.error) {
-            throw CCCCError.fromDaemonError(response.error);
-        }
-        throw new CCCCError('DAEMON_ERROR', 'Unknown daemon error');
-    }
-    return response.result;
-}
-/**
- * Groups API
- */
-class GroupsAPI {
-    client;
-    constructor(client) {
-        this.client = client;
+export class CCCCClient {
+    constructor(endpoint, timeoutMs) {
+        this._endpoint = endpoint;
+        this._timeoutMs = timeoutMs;
     }
     /**
-     * List all groups
+     * Async factory method: create a client instance
      */
-    async list() {
-        const response = await this.client.call('groups', {});
-        return (handleResponse(response)).groups;
+    static async create(options = {}) {
+        const endpoint = options.endpoint ?? await discoverEndpoint(options.ccccHome);
+        const timeoutMs = options.timeoutMs ?? 30000;
+        return new CCCCClient(endpoint, timeoutMs);
     }
     /**
-     * Get group info
+     * Get the current endpoint
      */
-    async get(groupId) {
-        const response = await this.client.call('group_show', { group_id: groupId });
-        return handleResponse(response);
+    get endpoint() {
+        return this._endpoint;
     }
+    // ============================================================
+    // Low-level API
+    // ============================================================
     /**
-     * Create a new group
+     * Send raw IPC request and return the full response
      */
-    async create(options) {
-        const response = await this.client.call('group_create', {
-            title: options.title,
-            topic: options.topic ?? '',
-            url: options.url ?? '',
-        });
-        return handleResponse(response);
-    }
-    /**
-     * Set group state
-     */
-    async setState(groupId, state, by) {
-        const response = await this.client.call('group_set_state', {
-            group_id: groupId,
-            state,
-            by,
-        });
-        handleResponse(response);
+    async callRaw(op, args) {
+        const request = {
+            v: 1,
+            op,
+            args: args ?? {},
+        };
+        const response = await callDaemon(this._endpoint, request, this._timeoutMs);
+        if (!response.ok && response.error) {
+            throw new DaemonAPIError(response.error.code, response.error.message, response.error.details, response);
+        }
+        return response;
     }
     /**
-     * Start group (activate all enabled actors)
+     * Send IPC request and return only result payload
      */
-    async start(groupId) {
-        const response = await this.client.call('group_start', { group_id: groupId });
-        handleResponse(response);
+    async call(op, args) {
+        const response = await this.callRaw(op, args);
+        return response.result ?? {};
     }
     /**
-     * Stop group (stop all actors)
+     * Compatibility check
      */
-    async stop(groupId) {
-        const response = await this.client.call('group_stop', { group_id: groupId });
-        handleResponse(response);
+    async assertCompatible(options = {}) {
+        const pingResult = await this.ping();
+        const ipcV = pingResult['ipc_v'] ?? 0;
+        const capabilities = pingResult['capabilities'] ?? {};
+        // Check IPC version
+        const requiredV = options.requireIpcV ?? 1;
+        if (ipcV < requiredV) {
+            throw new IncompatibleDaemonError(`IPC version ${ipcV} < required ${requiredV}`);
+        }
+        // Check capabilities
+        for (const [cap, required] of Object.entries(options.requireCapabilities ?? {})) {
+            if (required && !capabilities[cap]) {
+                throw new IncompatibleDaemonError(`Missing capability: ${cap}`);
+            }
+        }
+        // Check operation support by probing
+        const reservedOps = new Set(['ping', 'shutdown', 'events_stream', 'term_attach']);
+        for (const op of options.requireOps ?? []) {
+            if (reservedOps.has(op))
+                continue;
+            try {
+                await this.callRaw(op, {});
+            }
+            catch (e) {
+                if (e instanceof DaemonAPIError && e.code === 'unknown_op') {
+                    throw new IncompatibleDaemonError(`Operation not supported: ${op}`);
+                }
+                // Other errors (e.g. missing_group_id) imply the operation exists.
+            }
+        }
+        return pingResult;
     }
+    // ============================================================
+    // Convenience methods: diagnostics
+    // ============================================================
     /**
-     * Update group
+     * Ping daemon
      */
-    async update(groupId, patch) {
-        const response = await this.client.call('group_update', {
-            group_id: groupId,
-            patch,
-        });
-        handleResponse(response);
+    async ping() {
+        return this.call('ping');
     }
+    // ============================================================
+    // Convenience methods: group operations
+    // ============================================================
     /**
-     * Delete group
+     * List all groups
      */
-    async delete(groupId) {
-        const response = await this.client.call('group_delete', { group_id: groupId });
-        handleResponse(response);
-    }
-}
-/**
- * Actors API
- */
-class ActorsAPI {
-    client;
-    constructor(client) {
-        this.client = client;
+    async groups() {
+        return this.call('groups');
     }
     /**
-     * List actors in a group
+     * Show group details
      */
-    async list(groupId) {
-        const response = await this.client.call('actor_list', { group_id: groupId });
-        return (handleResponse(response)).actors;
+    async groupShow(groupId) {
+        return this.call('group_show', { group_id: groupId });
     }
     /**
-     * Add an actor to a group
+     * Create group
      */
-    async add(groupId, by, options) {
-        const response = await this.client.call('actor_add', {
-            group_id: groupId,
-            by,
-            actor_id: options.actor_id,
-            runtime: options.runtime ?? 'claude',
-            runner: options.runner ?? 'pty',
+    async groupCreate(options = {}) {
+        return this.call('group_create', {
             title: options.title ?? '',
-            command: options.command ?? [],
-            env: options.env ?? {},
+            topic: options.topic ?? '',
+            by: options.by ?? 'user',
         });
-        return handleResponse(response).actor;
     }
     /**
-     * Start an actor
+     * Update group
      */
-    async start(groupId, actorId, by) {
-        const response = await this.client.call('actor_start', {
-            group_id: groupId,
-            actor_id: actorId,
-            by,
+    async groupUpdate(options) {
+        return this.call('group_update', {
+            group_id: options.groupId,
+            patch: options.patch,
+            by: options.by ?? 'user',
         });
-        handleResponse(response);
     }
     /**
-     * Stop an actor
+     * Delete group
      */
-    async stop(groupId, actorId, by) {
-        const response = await this.client.call('actor_stop', {
-            group_id: groupId,
-            actor_id: actorId,
-            by,
-        });
-        handleResponse(response);
+    async groupDelete(groupId, by = 'user') {
+        return this.call('group_delete', { group_id: groupId, by });
     }
     /**
-     * Restart an actor
+     * Use group (set active scope)
      */
-    async restart(groupId, actorId, by) {
-        const response = await this.client.call('actor_restart', {
-            group_id: groupId,
-            actor_id: actorId,
-            by,
-        });
-        handleResponse(response);
+    async groupUse(groupId, path, by = 'user') {
+        return this.call('group_use', { group_id: groupId, path, by });
     }
     /**
-     * Remove an actor
+     * Set group state
      */
-    async remove(groupId, actorId, by) {
-        const response = await this.client.call('actor_remove', {
-            group_id: groupId,
-            actor_id: actorId,
-            by,
-        });
-        handleResponse(response);
+    async groupSetState(groupId, state, by = 'user') {
+        return this.call('group_set_state', { group_id: groupId, state, by });
     }
-}
-/**
- * Messages API
- */
-class MessagesAPI {
-    client;
-    constructor(client) {
-        this.client = client;
+    /**
+     * Update group settings
+     */
+    async groupSettingsUpdate(groupId, patch, by = 'user') {
+        return this.call('group_settings_update', { group_id: groupId, patch, by });
     }
     /**
-     * Send a message
+     * Read group-level automation state (rules, snippets, next run, ...)
      */
-    async send(groupId, by, options) {
-        const response = await this.client.call('send', {
-            group_id: groupId,
-            by,
-            text: options.text,
-            to: options.to ?? [],
-            format: options.format ?? 'plain',
-        });
-        return handleResponse(response).event;
+    async groupAutomationState(groupId, by = 'user') {
+        return this.call('group_automation_state', { group_id: groupId, by });
     }
     /**
-     * Reply to a message
+     * Replace group-level automation (rules + snippets)
      */
-    async reply(groupId, by, options) {
-        const response = await this.client.call('reply', {
-            group_id: groupId,
-            by,
-            event_id: options.event_id,
-            text: options.text,
-            to: options.to ?? [],
-        });
-        return handleResponse(response).event;
+    async groupAutomationUpdate(options) {
+        const args = {
+            group_id: options.groupId,
+            by: options.by ?? 'user',
+            ruleset: options.ruleset,
+        };
+        if (options.expectedVersion !== undefined) {
+            args['expected_version'] = options.expectedVersion;
+        }
+        return this.call('group_automation_update', args);
     }
-}
-/**
- * Inbox API
- */
-class InboxAPI {
-    client;
-    constructor(client) {
-        this.client = client;
+    /**
+     * Incrementally manage group-level automation (actions[])
+     */
+    async groupAutomationManage(options) {
+        const actions = options.actions;
+        if (actions.length === 0) {
+            throw new Error('groupAutomationManage requires a non-empty actions array');
+        }
+        const args = {
+            group_id: options.groupId,
+            by: options.by ?? 'user',
+            actions,
+        };
+        if (options.expectedVersion !== undefined)
+            args['expected_version'] = options.expectedVersion;
+        return this.call('group_automation_manage', args);
+    }
+    /**
+     * Reset group-level automation to baseline
+     */
+    async groupAutomationResetBaseline(options) {
+        const args = {
+            group_id: options.groupId,
+            by: options.by ?? 'user',
+        };
+        if (options.expectedVersion !== undefined) {
+            args['expected_version'] = options.expectedVersion;
+        }
+        return this.call('group_automation_reset_baseline', args);
     }
     /**
-     * List inbox messages
+     * Start group
      */
-    async list(groupId, actorId, options = {}) {
-        const response = await this.client.call('inbox_list', {
-            group_id: groupId,
-            actor_id: actorId,
-            kind_filter: options.kind_filter ?? 'all',
-            limit: options.limit ?? 50,
-        });
-        return (handleResponse(response)).messages;
+    async groupStart(groupId, by = 'user') {
+        return this.call('group_start', { group_id: groupId, by });
     }
     /**
-     * Mark messages as read up to event_id
+     * Stop group
      */
-    async markRead(groupId, actorId, eventId) {
-        const response = await this.client.call('inbox_mark_read', {
-            group_id: groupId,
-            actor_id: actorId,
-            event_id: eventId,
-        });
-        handleResponse(response);
+    async groupStop(groupId, by = 'user') {
+        return this.call('group_stop', { group_id: groupId, by });
     }
     /**
-     * Mark all messages as read
+     * Attach path to group
      */
-    async markAllRead(groupId, actorId) {
-        const response = await this.client.call('inbox_mark_all_read', {
-            group_id: groupId,
-            actor_id: actorId,
-        });
-        handleResponse(response);
+    async attach(path, groupId = '', by = 'user') {
+        const args = { path, by };
+        if (groupId)
+            args['group_id'] = groupId;
+        return this.call('attach', args);
     }
-}
-/**
- * Context API
- */
-class ContextAPI {
-    client;
-    constructor(client) {
-        this.client = client;
+    // ============================================================
+    // Convenience methods: actor operations
+    // ============================================================
+    /**
+     * List actors in group
+     */
+    async actorList(groupId) {
+        return this.call('actor_list', { group_id: groupId });
     }
     /**
-     * Get project context
+     * Add actor
      */
-    async get(groupId) {
-        const response = await this.client.call('context_get', { group_id: groupId });
-        return handleResponse(response);
+    async actorAdd(options) {
+        const args = {
+            group_id: options.groupId,
+            by: options.by ?? 'user',
+        };
+        if (options.actorId)
+            args['actor_id'] = options.actorId;
+        if (options.title)
+            args['title'] = options.title;
+        if (options.runtime)
+            args['runtime'] = options.runtime;
+        if (options.runner)
+            args['runner'] = options.runner;
+        if (options.command)
+            args['command'] = options.command;
+        if (options.env)
+            args['env'] = options.env;
+        if (options.envPrivate)
+            args['env_private'] = options.envPrivate;
+        if (options.defaultScopeKey)
+            args['default_scope_key'] = options.defaultScopeKey;
+        if (options.submit)
+            args['submit'] = options.submit;
+        return this.call('actor_add', args);
     }
     /**
-     * Sync context with batch operations
+     * Update actor
      */
-    async sync(groupId, ops, dryRun = false) {
-        const response = await this.client.call('context_sync', {
-            group_id: groupId,
-            ops,
-            dry_run: dryRun,
+    async actorUpdate(options) {
+        return this.call('actor_update', {
+            group_id: options.groupId,
+            actor_id: options.actorId,
+            patch: options.patch,
+            by: options.by ?? 'user',
         });
-        return handleResponse(response);
     }
-}
-/**
- * Tasks API
- */
-class TasksAPI {
-    client;
-    constructor(client) {
-        this.client = client;
+    /**
+     * Remove actor
+     */
+    async actorRemove(groupId, actorId, by = 'user') {
+        return this.call('actor_remove', { group_id: groupId, actor_id: actorId, by });
     }
     /**
-     * List tasks
+     * Start actor
      */
-    async list(groupId, includeArchived = false) {
-        const response = await this.client.call('task_list', {
-            group_id: groupId,
-            include_archived: includeArchived,
-        });
-        return (handleResponse(response)).tasks;
+    async actorStart(groupId, actorId, by = 'user') {
+        return this.call('actor_start', { group_id: groupId, actor_id: actorId, by });
     }
     /**
-     * Create a task
+     * Stop actor
      */
-    async create(groupId, options) {
-        const response = await this.client.call('context_sync', {
-            group_id: groupId,
-            ops: [
-                {
-                    op: 'task.create',
-                    name: options.name,
-                    goal: options.goal,
-                    steps: options.steps,
-                    milestone_id: options.milestone_id,
-                    assignee: options.assignee,
-                },
-            ],
-        });
-        const result = handleResponse(response);
-        return result.results[0].task;
+    async actorStop(groupId, actorId, by = 'user') {
+        return this.call('actor_stop', { group_id: groupId, actor_id: actorId, by });
     }
     /**
-     * Update a task
+     * Restart actor
      */
-    async update(groupId, options) {
-        const response = await this.client.call('context_sync', {
-            group_id: groupId,
-            ops: [
-                {
-                    op: 'task.update',
-                    task_id: options.task_id,
-                    name: options.name,
-                    goal: options.goal,
-                    status: options.status,
-                    assignee: options.assignee,
-                    milestone_id: options.milestone_id,
-                    step_id: options.step_id,
-                    step_status: options.step_status,
-                },
-            ],
-        });
-        const result = handleResponse(response);
-        return result.results[0].task;
+    async actorRestart(groupId, actorId, by = 'user') {
+        return this.call('actor_restart', { group_id: groupId, actor_id: actorId, by });
     }
-}
-/**
- * Milestones API
- */
-class MilestonesAPI {
-    client;
-    constructor(client) {
-        this.client = client;
+    /**
+     * List actor private env keys (without values)
+     */
+    async actorEnvPrivateKeys(groupId, actorId, by = 'user') {
+        return this.call('actor_env_private_keys', { group_id: groupId, actor_id: actorId, by });
     }
     /**
-     * Create a milestone
+     * Update actor private env vars (runtime-only; values are never echoed)
      */
-    async create(groupId, options) {
-        const response = await this.client.call('context_sync', {
-            group_id: groupId,
-            ops: [
-                {
-                    op: 'milestone.create',
-                    name: options.name,
-                    description: options.description,
-                    status: options.status ?? 'planned',
-                },
-            ],
+    async actorEnvPrivateUpdate(options) {
+        return this.call('actor_env_private_update', {
+            group_id: options.groupId,
+            actor_id: options.actorId,
+            by: options.by ?? 'user',
+            set: options.set ?? undefined,
+            unset: options.unset ?? undefined,
+            clear: options.clear ?? false,
         });
-        const result = handleResponse(response);
-        return result.results[0].milestone;
     }
+    // ============================================================
+    // Convenience methods: messaging
+    // ============================================================
     /**
-     * Complete a milestone
+     * Send message
      */
-    async complete(groupId, milestoneId, outcomes) {
-        const response = await this.client.call('context_sync', {
-            group_id: groupId,
-            ops: [
-                {
-                    op: 'milestone.complete',
-                    milestone_id: milestoneId,
-                    outcomes,
-                },
-            ],
-        });
-        handleResponse(response);
+    async send(options) {
+        const args = {
+            group_id: options.groupId,
+            text: options.text,
+            by: options.by ?? 'user',
+            priority: options.priority ?? 'normal',
+            reply_required: options.replyRequired ?? false,
+        };
+        if (options.to)
+            args['to'] = options.to;
+        if (options.path)
+            args['path'] = options.path;
+        return this.call('send', args);
+    }
+    /**
+     * Send message across groups
+     */
+    async sendCrossGroup(options) {
+        const args = {
+            group_id: options.groupId,
+            dst_group_id: options.dstGroupId,
+            text: options.text,
+            by: options.by ?? 'user',
+            priority: options.priority ?? 'normal',
+            reply_required: options.replyRequired ?? false,
+        };
+        if (options.to)
+            args['to'] = options.to;
+        return this.call('send_cross_group', args);
     }
-}
-/**
- * Vision API
- */
-class VisionAPI {
-    client;
-    constructor(client) {
-        this.client = client;
+    /**
+     * Reply message
+     */
+    async reply(options) {
+        const args = {
+            group_id: options.groupId,
+            reply_to: options.replyTo,
+            text: options.text,
+            by: options.by ?? 'user',
+            priority: options.priority ?? 'normal',
+            reply_required: options.replyRequired ?? false,
+        };
+        if (options.to)
+            args['to'] = options.to;
+        return this.call('reply', args);
     }
     /**
-     * Update project vision
+     * Acknowledge chat message
      */
-    async update(groupId, vision) {
-        const response = await this.client.call('context_sync', {
+    async chatAck(groupId, actorId, eventId, by) {
+        return this.call('chat_ack', {
             group_id: groupId,
-            ops: [{ op: 'vision.update', vision }],
+            actor_id: actorId,
+            event_id: eventId,
+            by: by ?? actorId,
         });
-        handleResponse(response);
-    }
-}
-/**
- * Sketch API
- */
-class SketchAPI {
-    client;
-    constructor(client) {
-        this.client = client;
     }
+    // ============================================================
+    // Convenience methods: inbox
+    // ============================================================
     /**
-     * Update execution sketch
+     * List inbox
      */
-    async update(groupId, sketch) {
-        const response = await this.client.call('context_sync', {
-            group_id: groupId,
-            ops: [{ op: 'sketch.update', sketch }],
+    async inboxList(options) {
+        return this.call('inbox_list', {
+            group_id: options.groupId,
+            actor_id: options.actorId,
+            by: options.by ?? 'user',
+            limit: options.limit ?? 50,
+            kind_filter: options.kindFilter ?? 'all',
         });
-        handleResponse(response);
-    }
-}
-/**
- * Headless API for MCP-driven actors
- */
-class HeadlessAPI {
-    client;
-    constructor(client) {
-        this.client = client;
     }
     /**
-     * Get headless session status
+     * Mark message as read
      */
-    async status(groupId, actorId) {
-        const response = await this.client.call('headless_status', {
+    async inboxMarkRead(groupId, actorId, eventId, by = 'user') {
+        return this.call('inbox_mark_read', {
             group_id: groupId,
             actor_id: actorId,
+            event_id: eventId,
+            by,
         });
-        return handleResponse(response);
     }
     /**
-     * Set headless session status
+     * Mark all messages as read
      */
-    async setStatus(groupId, actorId, status, taskId) {
-        const response = await this.client.call('headless_set_status', {
+    async inboxMarkAllRead(groupId, actorId, by = 'user', kindFilter = 'all') {
+        return this.call('inbox_mark_all_read', {
             group_id: groupId,
             actor_id: actorId,
-            status,
-            task_id: taskId,
+            by,
+            kind_filter: kindFilter,
         });
-        handleResponse(response);
     }
+    // ============================================================
+    // Convenience methods: notifications
+    // ============================================================
     /**
-     * Acknowledge processed message
+     * Acknowledge notification
      */
-    async ackMessage(groupId, actorId, messageId) {
-        const response = await this.client.call('headless_ack_message', {
+    async notifyAck(groupId, actorId, notifyEventId, by) {
+        return this.call('notify_ack', {
             group_id: groupId,
             actor_id: actorId,
-            message_id: messageId,
+            notify_event_id: notifyEventId,
+            by: by ?? actorId,
         });
-        handleResponse(response);
-    }
-}
-/**
- * CCCC Client
- *
- * Main entry point for SDK
- *
- * @example
- * ```typescript
- * const client = new CCCCClient();
- *
- * // List all groups
- * const groups = await client.groups.list();
- *
- * // Add an actor
- * await client.actors.add(groupId, 'user', {
- *   actor_id: 'agent-1',
- *   runtime: 'claude',
- *   runner: 'pty'
- * });
- *
- * // Send a message
- * await client.messages.send(groupId, 'user', {
- *   text: 'Hello agents!',
- *   to: ['agent-1']
- * });
- * ```
- */
-export class CCCCClient {
-    options;
-    // API namespaces
-    groups;
-    actors;
-    messages;
-    inbox;
-    context;
-    tasks;
-    milestones;
-    vision;
-    sketch;
-    headless;
-    constructor(options = {}) {
-        this.options = options;
-        // Initialize API namespaces
-        this.groups = new GroupsAPI(this);
-        this.actors = new ActorsAPI(this);
-        this.messages = new MessagesAPI(this);
-        this.inbox = new InboxAPI(this);
-        this.context = new ContextAPI(this);
-        this.tasks = new TasksAPI(this);
-        this.milestones = new MilestonesAPI(this);
-        this.vision = new VisionAPI(this);
-        this.sketch = new SketchAPI(this);
-        this.headless = new HeadlessAPI(this);
-    }
-    /**
-     * Ping daemon to check if it's running
-     */
-    async ping() {
-        return pingDaemon(this.options);
     }
+    // ============================================================
+    // Convenience methods: context
+    // ============================================================
     /**
-     * Low-level daemon call
+     * Get group context
      */
-    async call(op, args) {
-        const request = createRequest(op, args);
-        return callDaemon(request, this.options);
+    async contextGet(groupId) {
+        return this.call('context_get', { group_id: groupId });
     }
     /**
-     * Shutdown the daemon
+     * Sync context
      */
-    async shutdown() {
-        const response = await this.call('shutdown', {});
-        handleResponse(response);
+    async contextSync(options) {
+        return this.call('context_sync', {
+            group_id: options.groupId,
+            ops: options.ops,
+            by: options.by ?? 'system',
+            dry_run: options.dryRun ?? false,
+        });
+    }
+    // ============================================================
+    // Event stream
+    // ============================================================
+    /**
+     * Subscribe to event stream
+     */
+    async *eventsStream(options) {
+        const args = {
+            group_id: options.groupId,
+            by: options.by ?? 'user',
+        };
+        if (options.kinds) {
+            args['kinds'] = options.kinds instanceof Set
+                ? Array.from(options.kinds)
+                : options.kinds;
+        }
+        if (options.sinceEventId) {
+            args['since_event_id'] = options.sinceEventId;
+        }
+        if (options.sinceTs) {
+            args['since_ts'] = options.sinceTs;
+        }
+        const request = {
+            v: 1,
+            op: 'events_stream',
+            args,
+        };
+        const { socket, handshake, initialBuffer } = await openEventsStream(this._endpoint, request, options.timeoutMs ?? this._timeoutMs);
+        if (!handshake.ok) {
+            socket.destroy();
+            throw new DaemonAPIError(handshake.error?.code ?? 'unknown', handshake.error?.message ?? 'Handshake failed', handshake.error?.details, handshake);
+        }
+        try {
+            for await (const line of readLines(socket, initialBuffer)) {
+                try {
+                    yield JSON.parse(line);
+                }
+                catch {
+                    // Skip invalid JSON lines.
+                }
+            }
+        }
+        finally {
+            socket.destroy();
+        }
     }
 }
 //# sourceMappingURL=client.js.map