cccc-sdk 0.4.3 → 0.4.4

package/dist/client.js

@@ -1,8 +1,12 @@
 /**
  * CCCC SDK client
  */
-import { DaemonAPIError, IncompatibleDaemonError, } from './errors.js';
+import { DaemonAPIError, IncompatibleDaemonError, ErrorCodes, } from './errors.js';
+import { isStreamEvent } from './types.js';
 import { discoverEndpoint, callDaemon, openEventsStream, readLines, } from './transport.js';
+function compactRecord(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
 /**
  * Client for communicating with the CCCC daemon over IPC (Unix socket or TCP).
  *
@@ -50,22 +54,23 @@ export class CCCCClient {
             args: args ?? {},
         };
         const response = await callDaemon(this._endpoint, request, this._timeoutMs);
-        if (!response.ok && response.error) {
-            throw new DaemonAPIError(response.error.code ?? 'error', response.error.message ?? 'daemon error', response.error.details ?? {}, response);
+        if (!response.ok) {
+            throw new DaemonAPIError(response.error?.code ?? 'error', response.error?.message ?? 'daemon error', response.error?.details ?? {}, response);
         }
         return response;
     }
     /**
      * Send an IPC request and return only the result payload.
+     * @typeParam T - Expected result type (defaults to `Record<string, unknown>`).
      * @param op - The IPC operation name.
      * @param args - Operation arguments.
-     * @returns The `result` field from the daemon response (empty object if absent).
+     * @returns The `result` field from the daemon response, cast to `T`.
      * @throws {DaemonAPIError} If the daemon returns an error.
      * @throws {DaemonUnavailableError} If the connection fails.
      */
     async call(op, args) {
         const response = await this.callRaw(op, args);
-        return response.result ?? {};
+        return (response.result ?? {});
     }
     /**
      * Assert that the connected daemon meets the caller's compatibility requirements.
@@ -77,12 +82,8 @@ export class CCCCClient {
      */
     async assertCompatible(options = {}) {
         const pingResult = await this.ping();
-        const rawIpcV = pingResult['ipc_v'];
-        const ipcV = typeof rawIpcV === 'number' ? rawIpcV : 0;
-        const rawCaps = pingResult['capabilities'];
-        const capabilities = (rawCaps !== null && typeof rawCaps === 'object' && !Array.isArray(rawCaps))
-            ? rawCaps
-            : {};
+        const ipcV = pingResult.ipc_v ?? 0;
+        const capabilities = pingResult.capabilities ?? {};
         // Check IPC version
         const requiredV = options.requireIpcV ?? 1;
         if (ipcV < requiredV) {
@@ -103,7 +104,7 @@ export class CCCCClient {
                 await this.callRaw(op, {});
             }
             catch (e) {
-                if (e instanceof DaemonAPIError && e.code === 'unknown_op') {
+                if (e instanceof DaemonAPIError && e.code === ErrorCodes.UNKNOWN_OP) {
                     throw new IncompatibleDaemonError(`Operation not supported: ${op}`);
                 }
                 // Other errors (e.g. missing_group_id) imply the operation exists.
@@ -207,7 +208,7 @@ export class CCCCClient {
     async groupAutomationManage(options) {
         const actions = options.actions;
         if (actions.length === 0) {
-            throw new DaemonAPIError('invalid_args', 'groupAutomationManage requires a non-empty actions array', {});
+            throw new DaemonAPIError(ErrorCodes.INVALID_ARGS, 'groupAutomationManage requires a non-empty actions array', {});
         }
         const args = {
             group_id: options.groupId,
@@ -314,10 +315,25 @@ export class CCCCClient {
         return this.call('actor_remove', { group_id: groupId, actor_id: actorId, by });
     }
     /**
-     * Start actor
+     * Start actor.
+     * @param groupId - Group ID.
+     * @param actorId - Actor ID.
+     * @param options - Optional settings. Pass `{ idempotent: true }` to suppress errors when the actor is already running.
+     * @returns The daemon result.
+     * @throws {DaemonAPIError} On error (unless idempotent and actor already running).
      */
-    async actorStart(groupId, actorId, by = 'user') {
-        return this.call('actor_start', { group_id: groupId, actor_id: actorId, by });
+    async actorStart(groupId, actorId, options) {
+        const by = typeof options === 'string' ? options : (options?.by ?? 'user');
+        const idempotent = typeof options === 'object' && options?.idempotent === true;
+        try {
+            return await this.call('actor_start', { group_id: groupId, actor_id: actorId, by });
+        }
+        catch (e) {
+            if (idempotent && e instanceof DaemonAPIError && e.code === ErrorCodes.CONFLICT) {
+                return {};
+            }
+            throw e;
+        }
     }
     /**
      * Stop actor
@@ -466,48 +482,35 @@ export class CCCCClient {
     /**
      * Search the capability registry for one group/caller scope.
      */
-    async capabilitySearch(options) {
-        const args = {
+    async capabilitySearch(options = {}) {
+        return this.call('capability_search', compactRecord({
             group_id: options.groupId,
-            by: options.by ?? 'user',
-        };
-        if (options.actorId)
-            args['actor_id'] = options.actorId;
-        if (options.query)
-            args['query'] = options.query;
-        if (options.kind !== undefined)
-            args['kind'] = options.kind;
-        if (options.sourceId)
-            args['source_id'] = options.sourceId;
-        if (options.trustTier)
-            args['trust_tier'] = options.trustTier;
-        if (options.qualificationStatus !== undefined)
-            args['qualification_status'] = options.qualificationStatus;
-        if (options.includeExternal !== undefined)
-            args['include_external'] = options.includeExternal;
-        if (options.limit !== undefined)
-            args['limit'] = options.limit;
-        return this.call('capability_search', args);
+            by: options.by,
+            actor_id: options.actorId,
+            query: options.query,
+            kind: options.kind,
+            source_id: options.sourceId,
+            trust_tier: options.trustTier,
+            qualification_status: options.qualificationStatus,
+            include_external: options.includeExternal,
+            limit: options.limit,
+        }));
     }
     /**
      * Enable or disable a capability.
      */
     async capabilityEnable(options) {
-        const args = {
+        return this.call('capability_enable', compactRecord({
             group_id: options.groupId,
             capability_id: options.capabilityId,
-            scope: options.scope ?? 'session',
-            enabled: options.enabled ?? true,
-            cleanup: options.cleanup ?? false,
-            by: options.by ?? 'user',
-        };
-        if (options.reason)
-            args['reason'] = options.reason;
-        if (options.ttlSeconds !== undefined)
-            args['ttl_seconds'] = options.ttlSeconds;
-        if (options.actorId)
-            args['actor_id'] = options.actorId;
-        return this.call('capability_enable', args);
+            scope: options.scope,
+            enabled: options.enabled,
+            cleanup: options.cleanup,
+            by: options.by,
+            reason: options.reason,
+            ttl_seconds: options.ttlSeconds,
+            actor_id: options.actorId,
+        }));
     }
     /**
      * Block or unblock a capability.
@@ -531,14 +534,15 @@ export class CCCCClient {
     /**
      * Read effective capability exposure for one caller scope.
      */
-    async capabilityState(options) {
-        const args = {
-            group_id: options.groupId,
-            by: options.by ?? 'user',
-        };
-        if (options.actorId)
-            args['actor_id'] = options.actorId;
-        return this.call('capability_state', args);
+    async capabilityState(options = {}, actorId) {
+        const args = typeof options === 'string'
+            ? { group_id: options, actor_id: actorId }
+            : {
+                group_id: options.groupId,
+                by: options.by,
+                actor_id: options.actorId,
+            };
+        return this.call('capability_state', compactRecord(args));
     }
     /**
      * Read capability allowlist default, overlay, and effective snapshots.
@@ -645,7 +649,7 @@ export class CCCCClient {
     /**
      * Send a chat message to a group.
      * @param options - Message content, recipients, and priority.
-     * @returns The daemon result (includes event id).
+     * @returns The created event and optional ack event.
      * @throws {DaemonAPIError} On invalid group, missing permissions, etc.
      */
     async send(options) {
@@ -663,7 +667,8 @@ export class CCCCClient {
         return this.call('send', args);
     }
     /**
-     * Send message across groups
+     * Send message across groups.
+     * @returns The created event and optional ack event.
      */
     async sendCrossGroup(options) {
         const args = {
@@ -679,7 +684,30 @@ export class CCCCClient {
         return this.call('send_cross_group', args);
     }
     /**
-     * Reply message
+     * Create a durable task and send one linked visible message.
+     */
+    async trackedSend(options) {
+        const args = compactRecord({
+            group_id: options.groupId,
+            title: options.title,
+            text: options.text,
+            outcome: options.outcome,
+            assignee: options.assignee,
+            handoff_to: options.handoffTo,
+            waiting_on: options.waitingOn,
+            checklist: options.checklist,
+            notes: options.notes,
+            by: options.by ?? 'user',
+            to: options.to,
+            priority: options.priority ?? 'normal',
+            reply_required: options.replyRequired ?? true,
+            path: options.path,
+        });
+        return this.call('tracked_send', args);
+    }
+    /**
+     * Reply to a message.
+     * @returns The created event and optional ack event.
      */
     async reply(options) {
         const args = {
@@ -694,6 +722,60 @@ export class CCCCClient {
             args['to'] = options.to;
         return this.call('reply', args);
     }
+    /**
+     * Send a message and wait for a reply to it.
+     * Opens the event stream **before** sending to avoid race conditions,
+     * then yields control to the stream until a matching reply arrives.
+     *
+     * @param options - Send options plus `listenAs` (the actor to listen as) and optional `waitTimeoutMs`.
+     * @returns The reply event (a `chat.message` whose `reply_to` matches the sent event ID).
+     * @throws {DaemonAPIError} On send/stream errors.
+     * @throws {Error} If the timeout elapses or the signal is aborted before a reply arrives.
+     */
+    async sendAndWaitForReply(options) {
+        const waitTimeout = options.waitTimeoutMs ?? 60000;
+        const deadline = Date.now() + waitTimeout;
+        // Open stream FIRST (with sinceTs = now) to avoid missing replies
+        // that arrive between send() returning and stream connecting.
+        const stream = this.eventsStream({
+            groupId: options.groupId,
+            by: options.listenAs,
+            kinds: ['chat.message'],
+            sinceTs: new Date().toISOString(),
+            signal: options.signal,
+        });
+        let nextItem = stream.next();
+        // Now send the message
+        const sendResult = await this.send(options);
+        const sentEventId = sendResult.event.id;
+        try {
+            while (true) {
+                if (options.signal?.aborted) {
+                    throw new Error('sendAndWaitForReply aborted');
+                }
+                if (Date.now() > deadline) {
+                    throw new Error(`sendAndWaitForReply timed out after ${waitTimeout}ms`);
+                }
+                const { value: item, done } = await nextItem;
+                if (done)
+                    break;
+                nextItem = stream.next();
+                if (isStreamEvent(item)) {
+                    const evt = item.event;
+                    if (evt.kind === 'chat.message') {
+                        const data = evt.data;
+                        if (data['reply_to'] === sentEventId) {
+                            return evt;
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            await stream.return(undefined);
+        }
+        throw new Error('sendAndWaitForReply: stream ended without reply');
+    }
     /**
      * Acknowledge chat message
      */
@@ -705,6 +787,56 @@ export class CCCCClient {
             by: by ?? actorId,
         });
     }
+    /**
+     * Send a file as a chat attachment.
+     * @param options - File path (relative to scope root), optional caption and recipients.
+     * @returns The created event and optional ack event.
+     */
+    async fileSend(options) {
+        const args = {
+            group_id: options.groupId,
+            path: options.path,
+            by: options.by ?? 'user',
+            priority: options.priority ?? 'normal',
+            reply_required: options.replyRequired ?? false,
+        };
+        if (options.text)
+            args['text'] = options.text;
+        if (options.to)
+            args['to'] = options.to;
+        return this.call('file_send', args);
+    }
+    /**
+     * Get recent chat messages from the ledger.
+     * @param options - Group ID, limit, and max chars.
+     * @returns The ledger tail result.
+     */
+    async ledgerTail(options) {
+        const args = {
+            group_id: options.groupId,
+            by: options.by ?? 'user',
+        };
+        if (options.limit !== undefined)
+            args['limit'] = options.limit;
+        if (options.maxChars !== undefined)
+            args['max_chars'] = options.maxChars;
+        return this.call('ledger_tail', args);
+    }
+    /**
+     * Get recent terminal output from an actor.
+     * @param options - Group ID, actor ID, and line count.
+     * @returns The terminal tail result.
+     */
+    async terminalTail(options) {
+        const args = {
+            group_id: options.groupId,
+            actor_id: options.actorId,
+            by: options.by ?? 'user',
+        };
+        if (options.lines !== undefined)
+            args['lines'] = options.lines;
+        return this.call('terminal_tail', args);
+    }
     // ============================================================
     // Convenience methods: inbox
     // ============================================================
@@ -776,6 +908,173 @@ export class CCCCClient {
             dry_run: options.dryRun ?? false,
         });
     }
+    contextOp(groupId, op, by = 'system', dryRun = false) {
+        return this.contextSync({ groupId, by, dryRun, ops: [op] });
+    }
+    /** Update the shared coordination brief (Context Ops v3). */
+    async coordinationBriefUpdate(options) {
+        return this.contextOp(options.groupId, compactRecord({
+            op: 'coordination.brief.update',
+            objective: options.objective,
+            current_focus: options.currentFocus,
+            constraints: options.constraints,
+            project_brief: options.projectBrief,
+            project_brief_stale: options.projectBriefStale,
+        }), options.by, options.dryRun);
+    }
+    /** Add a compact coordination decision or handoff note. */
+    async coordinationNoteAdd(options) {
+        return this.contextOp(options.groupId, compactRecord({
+            op: 'coordination.note.add',
+            kind: options.kind,
+            summary: options.summary,
+            task_id: options.taskId,
+        }), options.by, options.dryRun);
+    }
+    /** Create a Context Ops v3 task. */
+    async taskCreate(options) {
+        return this.contextOp(options.groupId, compactRecord({
+            op: 'task.create',
+            title: options.title,
+            outcome: options.outcome,
+            status: options.status,
+            parent_id: options.parentId,
+            assignee: options.assignee,
+            priority: options.priority,
+            blocked_by: options.blockedBy,
+            waiting_on: options.waitingOn,
+            handoff_to: options.handoffTo,
+            task_type: options.taskType,
+            notes: options.notes,
+            checklist: options.checklist,
+        }), options.by, options.dryRun);
+    }
+    /** Update a Context Ops v3 task. */
+    async taskUpdate(options) {
+        return this.contextOp(options.groupId, compactRecord({
+            op: 'task.update',
+            task_id: options.taskId,
+            title: options.title,
+            outcome: options.outcome,
+            status: options.status,
+            assignee: options.assignee,
+            priority: options.priority,
+            blocked_by: options.blockedBy,
+            waiting_on: options.waitingOn,
+            handoff_to: options.handoffTo,
+            notes: options.notes,
+            checklist: options.checklist,
+        }), options.by, options.dryRun);
+    }
+    /** Move a task through the canonical lifecycle operation. */
+    async taskMove(options) {
+        return this.contextOp(options.groupId, {
+            op: 'task.move',
+            task_id: options.taskId,
+            status: options.status,
+        }, options.by, options.dryRun);
+    }
+    /** Restore an archived task. */
+    async taskRestore(options) {
+        return this.contextOp(options.groupId, {
+            op: 'task.restore',
+            task_id: options.taskId,
+        }, options.by, options.dryRun);
+    }
+    /** Update per-actor working memory. */
+    async agentStateUpdate(options) {
+        return this.contextOp(options.groupId, compactRecord({
+            op: 'agent_state.update',
+            actor_id: options.actorId,
+            active_task_id: options.activeTaskId,
+            focus: options.focus,
+            next_action: options.nextAction,
+            what_changed: options.whatChanged,
+            blockers: options.blockers,
+            open_loops: options.openLoops,
+            commitments: options.commitments,
+            environment_summary: options.environmentSummary,
+            user_model: options.userModel,
+            persona_notes: options.personaNotes,
+            resume_hint: options.resumeHint,
+        }), options.by, options.dryRun);
+    }
+    /** Clear per-actor working memory. */
+    async agentStateClear(options) {
+        return this.contextOp(options.groupId, {
+            op: 'agent_state.clear',
+            actor_id: options.actorId,
+        }, options.by, options.dryRun);
+    }
+    /** Merge restricted projection metadata. */
+    async metaMerge(options) {
+        return this.contextOp(options.groupId, {
+            op: 'meta.merge',
+            data: options.data,
+        }, options.by, options.dryRun);
+    }
+    // ============================================================
+    // Convenience methods: capability use and memory
+    // ============================================================
+    async capabilityUse(options) {
+        const enableResult = await this.capabilityEnable(options);
+        if (!options.toolName)
+            return enableResult;
+        return this.call('capability_tool_call', compactRecord({
+            group_id: options.groupId,
+            actor_id: options.actorId,
+            by: options.by,
+            tool_name: options.toolName,
+            arguments: options.toolArguments ?? {},
+        }));
+    }
+    async memorySearch(options) {
+        return this.call('memory_search', compactRecord({
+            group_id: options.groupId,
+            actor_id: options.actorId,
+            query: options.query,
+            limit: options.limit,
+            tags: options.tags,
+            target: options.target,
+        }));
+    }
+    async memoryGet(options) {
+        return this.call('memory_get', compactRecord({
+            group_id: options.groupId,
+            actor_id: options.actorId,
+            path: options.path,
+            target: options.target,
+            date: options.date,
+            offset: options.offset,
+            limit: options.limit,
+        }));
+    }
+    async memoryWrite(options) {
+        return this.call('memory_write', compactRecord({
+            group_id: options.groupId,
+            actor_id: options.actorId,
+            target: options.target,
+            content: options.content,
+            tags: options.tags,
+            source_refs: options.sourceRefs,
+            idempotency_key: options.idempotencyKey,
+            dedup_intent: options.dedupIntent,
+            dedup_query: options.dedupQuery,
+        }));
+    }
+    async memoryHealth(options = {}) {
+        return this.call('memory_health', compactRecord({
+            group_id: options.groupId,
+        }));
+    }
+    async memoryProfileGet(options) {
+        return this.call('memory_profile_get', compactRecord({
+            group_id: options.groupId,
+            actor_id: options.actorId,
+            user_id: options.userId,
+            tags: options.tags,
+        }));
+    }
     // ============================================================
     // Convenience methods: Group Space
     // ============================================================
@@ -985,11 +1284,14 @@ export class CCCCClient {
      * Subscribe to the group event stream (Server-Sent Events style, long-lived connection).
      * Yields {@link EventStreamItem} objects as they arrive. The socket is destroyed
      * when the generator is returned or thrown.
-     * @param options - Group ID, event filters, and optional since cursor.
+     * @param options - Group ID, event filters, optional since cursor, and optional AbortSignal.
      * @yields {EventStreamItem} Each event or heartbeat from the stream.
      * @throws {DaemonAPIError} If the handshake fails.
      */
     async *eventsStream(options) {
+        // Check abort before connecting
+        if (options.signal?.aborted)
+            return;
         const args = {
             group_id: options.groupId,
             by: options.by ?? 'user',
@@ -1015,20 +1317,37 @@ export class CCCCClient {
             socket.destroy();
             throw new DaemonAPIError(handshake.error?.code ?? 'unknown', handshake.error?.message ?? 'Handshake failed', handshake.error?.details, handshake);
         }
+        // Wire up AbortSignal to destroy the socket
+        const onAbort = () => { socket.destroy(); };
+        options.signal?.addEventListener('abort', onAbort, { once: true });
         try {
             for await (const line of readLines(socket, initialBuffer)) {
+                if (options.signal?.aborted)
+                    return;
+                let parsed;
                 try {
-                    const parsed = JSON.parse(line);
-                    if (parsed !== null && typeof parsed === 'object' && 't' in parsed) {
-                        yield parsed;
-                    }
+                    parsed = JSON.parse(line);
                 }
                 catch {
-                    // Skip invalid JSON lines.
+                    // Non-JSON line from daemon; surface as an error so callers know
+                    // something unexpected happened instead of silently losing data.
+                    throw new DaemonAPIError('invalid_stream_data', `Unparseable event stream line: ${line.slice(0, 200)}`, {});
+                }
+                if (parsed !== null && typeof parsed === 'object') {
+                    const obj = parsed;
+                    // Daemon may send error objects in the stream (ok: false).
+                    if ('ok' in obj && obj['ok'] === false) {
+                        const err = obj['error'];
+                        throw new DaemonAPIError(err?.['code'] ?? 'stream_error', err?.['message'] ?? 'Daemon sent error in event stream', err?.['details'] ?? {}, obj);
+                    }
+                    if ('t' in obj) {
+                        yield parsed;
+                    }
                 }
             }
         }
         finally {
+            options.signal?.removeEventListener('abort', onAbort);
             socket.destroy();
         }
     }