cccc-sdk 0.1.0

package/dist/client.js

@@ -0,0 +1,536 @@
+/**
+ * CCCC Client SDK
+ *
+ * High-level API for interacting with CCCC daemon
+ */
+import { callDaemon, pingDaemon } from './transport.js';
+import { createRequest } from './types/ipc.js';
+import { CCCCError } from './errors.js';
+/**
+ * Handle daemon response, throwing on error
+ */
+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;
+    }
+    /**
+     * List all groups
+     */
+    async list() {
+        const response = await this.client.call('groups', {});
+        return (handleResponse(response)).groups;
+    }
+    /**
+     * Get group info
+     */
+    async get(groupId) {
+        const response = await this.client.call('group_show', { group_id: groupId });
+        return handleResponse(response);
+    }
+    /**
+     * Create a new group
+     */
+    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);
+    }
+    /**
+     * Start group (activate all enabled actors)
+     */
+    async start(groupId) {
+        const response = await this.client.call('group_start', { group_id: groupId });
+        handleResponse(response);
+    }
+    /**
+     * Stop group (stop all actors)
+     */
+    async stop(groupId) {
+        const response = await this.client.call('group_stop', { group_id: groupId });
+        handleResponse(response);
+    }
+    /**
+     * Update group
+     */
+    async update(groupId, patch) {
+        const response = await this.client.call('group_update', {
+            group_id: groupId,
+            patch,
+        });
+        handleResponse(response);
+    }
+    /**
+     * Delete group
+     */
+    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;
+    }
+    /**
+     * List actors in a group
+     */
+    async list(groupId) {
+        const response = await this.client.call('actor_list', { group_id: groupId });
+        return (handleResponse(response)).actors;
+    }
+    /**
+     * Add an actor to a 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',
+            title: options.title ?? '',
+            command: options.command ?? [],
+            env: options.env ?? {},
+        });
+        return handleResponse(response).actor;
+    }
+    /**
+     * Start an actor
+     */
+    async start(groupId, actorId, by) {
+        const response = await this.client.call('actor_start', {
+            group_id: groupId,
+            actor_id: actorId,
+            by,
+        });
+        handleResponse(response);
+    }
+    /**
+     * Stop an actor
+     */
+    async stop(groupId, actorId, by) {
+        const response = await this.client.call('actor_stop', {
+            group_id: groupId,
+            actor_id: actorId,
+            by,
+        });
+        handleResponse(response);
+    }
+    /**
+     * Restart an actor
+     */
+    async restart(groupId, actorId, by) {
+        const response = await this.client.call('actor_restart', {
+            group_id: groupId,
+            actor_id: actorId,
+            by,
+        });
+        handleResponse(response);
+    }
+    /**
+     * Remove an actor
+     */
+    async remove(groupId, actorId, by) {
+        const response = await this.client.call('actor_remove', {
+            group_id: groupId,
+            actor_id: actorId,
+            by,
+        });
+        handleResponse(response);
+    }
+}
+/**
+ * Messages API
+ */
+class MessagesAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Send a message
+     */
+    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;
+    }
+    /**
+     * Reply to a message
+     */
+    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;
+    }
+}
+/**
+ * Inbox API
+ */
+class InboxAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List inbox messages
+     */
+    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;
+    }
+    /**
+     * Mark messages as read up to event_id
+     */
+    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);
+    }
+    /**
+     * Mark all messages as read
+     */
+    async markAllRead(groupId, actorId) {
+        const response = await this.client.call('inbox_mark_all_read', {
+            group_id: groupId,
+            actor_id: actorId,
+        });
+        handleResponse(response);
+    }
+}
+/**
+ * Context API
+ */
+class ContextAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get project context
+     */
+    async get(groupId) {
+        const response = await this.client.call('context_get', { group_id: groupId });
+        return handleResponse(response);
+    }
+    /**
+     * Sync context with batch operations
+     */
+    async sync(groupId, ops, dryRun = false) {
+        const response = await this.client.call('context_sync', {
+            group_id: groupId,
+            ops,
+            dry_run: dryRun,
+        });
+        return handleResponse(response);
+    }
+}
+/**
+ * Tasks API
+ */
+class TasksAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List tasks
+     */
+    async list(groupId, includeArchived = false) {
+        const response = await this.client.call('task_list', {
+            group_id: groupId,
+            include_archived: includeArchived,
+        });
+        return (handleResponse(response)).tasks;
+    }
+    /**
+     * Create a task
+     */
+    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;
+    }
+    /**
+     * Update a task
+     */
+    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;
+    }
+}
+/**
+ * Milestones API
+ */
+class MilestonesAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Create a milestone
+     */
+    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',
+                },
+            ],
+        });
+        const result = handleResponse(response);
+        return result.results[0].milestone;
+    }
+    /**
+     * Complete a milestone
+     */
+    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);
+    }
+}
+/**
+ * Vision API
+ */
+class VisionAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Update project vision
+     */
+    async update(groupId, vision) {
+        const response = await this.client.call('context_sync', {
+            group_id: groupId,
+            ops: [{ op: 'vision.update', vision }],
+        });
+        handleResponse(response);
+    }
+}
+/**
+ * Sketch API
+ */
+class SketchAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Update execution sketch
+     */
+    async update(groupId, sketch) {
+        const response = await this.client.call('context_sync', {
+            group_id: groupId,
+            ops: [{ op: 'sketch.update', sketch }],
+        });
+        handleResponse(response);
+    }
+}
+/**
+ * Headless API for MCP-driven actors
+ */
+class HeadlessAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get headless session status
+     */
+    async status(groupId, actorId) {
+        const response = await this.client.call('headless_status', {
+            group_id: groupId,
+            actor_id: actorId,
+        });
+        return handleResponse(response);
+    }
+    /**
+     * Set headless session status
+     */
+    async setStatus(groupId, actorId, status, taskId) {
+        const response = await this.client.call('headless_set_status', {
+            group_id: groupId,
+            actor_id: actorId,
+            status,
+            task_id: taskId,
+        });
+        handleResponse(response);
+    }
+    /**
+     * Acknowledge processed message
+     */
+    async ackMessage(groupId, actorId, messageId) {
+        const response = await this.client.call('headless_ack_message', {
+            group_id: groupId,
+            actor_id: actorId,
+            message_id: messageId,
+        });
+        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);
+    }
+    /**
+     * Low-level daemon call
+     */
+    async call(op, args) {
+        const request = createRequest(op, args);
+        return callDaemon(request, this.options);
+    }
+    /**
+     * Shutdown the daemon
+     */
+    async shutdown() {
+        const response = await this.call('shutdown', {});
+        handleResponse(response);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CCCC SDK Error Types
+ */
+export type CCCCErrorCode = 'DAEMON_NOT_RUNNING' | 'SOCKET_NOT_FOUND' | 'TIMEOUT' | 'INVALID_REQUEST' | 'PERMISSION_DENIED' | 'GROUP_NOT_FOUND' | 'ACTOR_NOT_FOUND' | 'INTERNAL' | 'DAEMON_ERROR';
+export declare class CCCCError extends Error {
+    readonly code: CCCCErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: CCCCErrorCode, message: string, details?: Record<string, unknown>);
+    static fromDaemonError(error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    }): CCCCError;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,25 @@
+/**
+ * CCCC SDK Error Types
+ */
+export class CCCCError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = 'CCCCError';
+        this.code = code;
+        this.details = details;
+    }
+    static fromDaemonError(error) {
+        const codeMap = {
+            daemon_unavailable: 'DAEMON_NOT_RUNNING',
+            invalid_request: 'INVALID_REQUEST',
+            permission_denied: 'PERMISSION_DENIED',
+            group_not_found: 'GROUP_NOT_FOUND',
+            actor_not_found: 'ACTOR_NOT_FOUND',
+        };
+        const code = codeMap[error.code] ?? 'DAEMON_ERROR';
+        return new CCCCError(code, error.message, error.details ?? {});
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CCCC Client SDK for Node.js
+ *
+ * @packageDocumentation
+ */
+export { CCCCClient, type CCCCClientOptions } from './client.js';
+export { callDaemon, pingDaemon, getSocketPath, getDefaultCcccHome, socketExists, type TransportOptions, } from './transport.js';
+export { CCCCError, type CCCCErrorCode } from './errors.js';
+export * from './types/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * CCCC Client SDK for Node.js
+ *
+ * @packageDocumentation
+ */
+// Main client
+export { CCCCClient } from './client.js';
+// Transport
+export { callDaemon, pingDaemon, getSocketPath, getDefaultCcccHome, socketExists, } from './transport.js';
+// Errors
+export { CCCCError } from './errors.js';
+// Types
+export * from './types/index.js';
+//# sourceMappingURL=index.js.map

package/dist/transport.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Unix Socket Transport Layer for CCCC daemon IPC
+ *
+ * Protocol:
+ * - Uses Unix Domain Socket at $CCCC_HOME/daemon/ccccd.sock
+ * - Messages are newline-delimited JSON
+ * - Request: {"v": 1, "op": "xxx", "args": {...}}
+ * - Response: {"v": 1, "ok": true/false, "result": {...}, "error": {...}}
+ */
+import type { DaemonRequest, DaemonResponse } from './types/ipc.js';
+export interface TransportOptions {
+    /** CCCC home directory, defaults to ~/.cccc */
+    ccccHome?: string;
+    /** Request timeout in milliseconds, defaults to 60000 */
+    timeoutMs?: number;
+}
+/**
+ * Get default CCCC home directory
+ */
+export declare function getDefaultCcccHome(): string;
+/**
+ * Get socket path for CCCC daemon
+ */
+export declare function getSocketPath(ccccHome?: string): string;
+/**
+ * Check if daemon socket exists
+ */
+export declare function socketExists(ccccHome?: string): boolean;
+/**
+ * Send a request to the CCCC daemon and receive a response
+ */
+export declare function callDaemon(request: DaemonRequest, options?: TransportOptions): Promise<DaemonResponse>;
+/**
+ * Ping the daemon to check if it's running
+ */
+export declare function pingDaemon(options?: TransportOptions): Promise<boolean>;
+//# sourceMappingURL=transport.d.ts.map