cccc-sdk 0.1.4 → 0.4.4

package/dist/client.js

@@ -4,6 +4,9 @@
 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).
  *
@@ -274,6 +277,8 @@ export class CCCCClient {
             command: options.command,
             env: options.env,
             env_private: options.envPrivate,
+            capability_autoload: options.capabilityAutoload,
+            profile_id: options.profileId,
             default_scope_key: options.defaultScopeKey,
             submit: options.submit,
         };
@@ -291,12 +296,17 @@ export class CCCCClient {
      * Update actor
      */
     async actorUpdate(options) {
-        return this.call('actor_update', {
+        const args = {
             group_id: options.groupId,
             actor_id: options.actorId,
-            patch: options.patch,
+            patch: options.patch ?? {},
             by: options.by ?? 'user',
-        });
+        };
+        if (options.profileId != null)
+            args['profile_id'] = options.profileId;
+        if (options.profileAction != null)
+            args['profile_action'] = options.profileAction;
+        return this.call('actor_update', args);
     }
     /**
      * Remove actor
@@ -359,6 +369,280 @@ export class CCCCClient {
             args['unset'] = options.unset;
         return this.call('actor_env_private_update', args);
     }
+    /**
+     * List global actor profiles.
+     */
+    async actorProfileList(by = 'user') {
+        return this.call('actor_profile_list', { by });
+    }
+    /**
+     * Get one actor profile and current usage.
+     */
+    async actorProfileGet(profileId, by = 'user') {
+        return this.call('actor_profile_get', { profile_id: profileId, by });
+    }
+    /**
+     * Create/update one actor profile.
+     */
+    async actorProfileUpsert(options) {
+        const profile = { ...options.profile };
+        if ('capabilityDefaults' in profile) {
+            const rawDefaults = profile['capabilityDefaults'];
+            delete profile['capabilityDefaults'];
+            if (rawDefaults != null && typeof rawDefaults === 'object' && !Array.isArray(rawDefaults)) {
+                const defaults = rawDefaults;
+                profile['capability_defaults'] = {
+                    ...(defaults['autoloadCapabilities'] !== undefined
+                        ? { autoload_capabilities: defaults['autoloadCapabilities'] }
+                        : {}),
+                    ...(defaults['defaultScope'] !== undefined
+                        ? { default_scope: defaults['defaultScope'] }
+                        : {}),
+                    ...(defaults['sessionTtlSeconds'] !== undefined
+                        ? { session_ttl_seconds: defaults['sessionTtlSeconds'] }
+                        : {}),
+                };
+            }
+            else {
+                profile['capability_defaults'] = rawDefaults;
+            }
+        }
+        const args = {
+            profile,
+            by: options.by ?? 'user',
+        };
+        if (options.expectedRevision !== undefined)
+            args['expected_revision'] = options.expectedRevision;
+        return this.call('actor_profile_upsert', args);
+    }
+    /**
+     * Delete one actor profile (rejected when still in use).
+     */
+    async actorProfileDelete(profileId, by = 'user', forceDetach = false) {
+        return this.call('actor_profile_delete', { profile_id: profileId, by, force_detach: forceDetach });
+    }
+    /**
+     * List profile-level secret keys and masked previews.
+     */
+    async actorProfileSecretKeys(profileId, by = 'user') {
+        return this.call('actor_profile_secret_keys', { profile_id: profileId, by });
+    }
+    /**
+     * Update profile-level private env.
+     */
+    async actorProfileSecretUpdate(options) {
+        const args = {
+            profile_id: options.profileId,
+            by: options.by ?? 'user',
+            clear: options.clear ?? false,
+        };
+        if (options.set)
+            args['set'] = options.set;
+        if (options.unset)
+            args['unset'] = options.unset;
+        return this.call('actor_profile_secret_update', args);
+    }
+    /**
+     * Copy one actor's runtime env (public + private) into a profile's private env.
+     */
+    async actorProfileSecretCopyFromActor(options) {
+        return this.call('actor_profile_secret_copy_from_actor', {
+            profile_id: options.profileId,
+            group_id: options.groupId,
+            actor_id: options.actorId,
+            by: options.by ?? 'user',
+        });
+    }
+    /**
+     * Copy one profile's secrets into another profile.
+     */
+    async actorProfileSecretCopyFromProfile(options) {
+        return this.call('actor_profile_secret_copy_from_profile', {
+            profile_id: options.profileId,
+            source_profile_id: options.sourceProfileId,
+            by: options.by ?? 'user',
+        });
+    }
+    // ============================================================
+    // Convenience methods: capabilities
+    // ============================================================
+    /**
+     * Read the global capability overview snapshot.
+     */
+    async capabilityOverview(options = {}) {
+        const args = {};
+        if (options.query)
+            args['query'] = options.query;
+        if (options.limit !== undefined)
+            args['limit'] = options.limit;
+        if (options.includeIndexed !== undefined)
+            args['include_indexed'] = options.includeIndexed;
+        return this.call('capability_overview', args);
+    }
+    /**
+     * Search the capability registry for one group/caller scope.
+     */
+    async capabilitySearch(options = {}) {
+        return this.call('capability_search', compactRecord({
+            group_id: options.groupId,
+            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) {
+        return this.call('capability_enable', compactRecord({
+            group_id: options.groupId,
+            capability_id: options.capabilityId,
+            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.
+     */
+    async capabilityBlock(options) {
+        const args = {
+            group_id: options.groupId,
+            capability_id: options.capabilityId,
+            scope: options.scope ?? 'group',
+            blocked: options.blocked ?? true,
+            by: options.by ?? 'user',
+        };
+        if (options.ttlSeconds !== undefined)
+            args['ttl_seconds'] = options.ttlSeconds;
+        if (options.reason)
+            args['reason'] = options.reason;
+        if (options.actorId)
+            args['actor_id'] = options.actorId;
+        return this.call('capability_block', args);
+    }
+    /**
+     * Read effective capability exposure for one caller scope.
+     */
+    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.
+     */
+    async capabilityAllowlistGet(options = {}) {
+        return this.call('capability_allowlist_get', {
+            by: options.by ?? 'user',
+        });
+    }
+    /**
+     * Dry-run capability allowlist overlay validation without persistence.
+     */
+    async capabilityAllowlistValidate(options = {}) {
+        const args = {
+            mode: options.mode ?? 'patch',
+        };
+        if (options.patch !== undefined)
+            args['patch'] = options.patch;
+        if (options.overlay !== undefined)
+            args['overlay'] = options.overlay;
+        return this.call('capability_allowlist_validate', args);
+    }
+    /**
+     * Persist capability allowlist overlay with optional optimistic concurrency.
+     */
+    async capabilityAllowlistUpdate(options = {}) {
+        const args = {
+            by: options.by ?? 'user',
+            mode: options.mode ?? 'patch',
+        };
+        if (options.expectedRevision)
+            args['expected_revision'] = options.expectedRevision;
+        if (options.patch !== undefined)
+            args['patch'] = options.patch;
+        if (options.overlay !== undefined)
+            args['overlay'] = options.overlay;
+        return this.call('capability_allowlist_update', args);
+    }
+    /**
+     * Reset capability allowlist overlay to empty/default state.
+     */
+    async capabilityAllowlistReset(options = {}) {
+        return this.call('capability_allowlist_reset', {
+            by: options.by ?? 'user',
+        });
+    }
+    /**
+     * Import one structured capability record, with optional readiness probe.
+     */
+    async capabilityImport(options) {
+        const args = {
+            group_id: options.groupId,
+            record: options.record,
+            by: options.by ?? 'user',
+            dry_run: options.dryRun ?? false,
+        };
+        if (options.actorId)
+            args['actor_id'] = options.actorId;
+        if (options.probe !== undefined)
+            args['probe'] = options.probe;
+        if (options.enableAfterImport !== undefined)
+            args['enable_after_import'] = options.enableAfterImport;
+        if (options.scope)
+            args['scope'] = options.scope;
+        if (options.ttlSeconds !== undefined)
+            args['ttl_seconds'] = options.ttlSeconds;
+        if (options.reason)
+            args['reason'] = options.reason;
+        return this.call('capability_import', args);
+    }
+    /**
+     * Uninstall a capability from the target group scope.
+     */
+    async capabilityUninstall(options) {
+        const args = {
+            group_id: options.groupId,
+            capability_id: options.capabilityId,
+            by: options.by ?? 'user',
+        };
+        if (options.reason)
+            args['reason'] = options.reason;
+        if (options.actorId)
+            args['actor_id'] = options.actorId;
+        return this.call('capability_uninstall', args);
+    }
+    /**
+     * Call one enabled dynamic capability tool through daemon IPC.
+     */
+    async capabilityToolCall(options) {
+        const args = {
+            group_id: options.groupId,
+            tool_name: options.toolName,
+            by: options.by ?? 'user',
+        };
+        if (options.arguments)
+            args['arguments'] = options.arguments;
+        if (options.actorId)
+            args['actor_id'] = options.actorId;
+        return this.call('capability_tool_call', args);
+    }
     // ============================================================
     // Convenience methods: messaging
     // ============================================================
@@ -399,6 +683,28 @@ export class CCCCClient {
             args['to'] = options.to;
         return this.call('send_cross_group', args);
     }
+    /**
+     * 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.
@@ -438,17 +744,22 @@ export class CCCCClient {
             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 {
-            for await (const item of stream) {
+            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') {
@@ -461,7 +772,7 @@ export class CCCCClient {
             }
         }
         finally {
-            stream.return(undefined);
+            await stream.return(undefined);
         }
         throw new Error('sendAndWaitForReply: stream ended without reply');
     }
@@ -597,6 +908,375 @@ 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
+    // ============================================================
+    /**
+     * Read Group Space provider and binding status.
+     */
+    async groupSpaceStatus(options) {
+        return this.call('group_space_status', {
+            group_id: options.groupId,
+            provider: options.provider ?? 'notebooklm',
+        });
+    }
+    /**
+     * List available remote spaces for binding.
+     */
+    async groupSpaceSpaces(options) {
+        return this.call('group_space_spaces', {
+            group_id: options.groupId,
+            provider: options.provider ?? 'notebooklm',
+        });
+    }
+    /**
+     * Read the provider capability matrix for a group.
+     */
+    async groupSpaceCapabilities(options) {
+        return this.call('group_space_capabilities', {
+            group_id: options.groupId,
+            provider: options.provider ?? 'notebooklm',
+        });
+    }
+    /**
+     * Bind or unbind one Group Space lane.
+     */
+    async groupSpaceBind(options) {
+        const args = {
+            group_id: options.groupId,
+            provider: options.provider ?? 'notebooklm',
+            lane: options.lane,
+            action: options.action ?? 'bind',
+            by: options.by ?? 'user',
+        };
+        if (options.remoteSpaceId)
+            args['remote_space_id'] = options.remoteSpaceId;
+        return this.call('group_space_bind', args);
+    }
+    /**
+     * Enqueue one Group Space ingest action.
+     */
+    async groupSpaceIngest(options) {
+        const args = {
+            group_id: options.groupId,
+            provider: options.provider ?? 'notebooklm',
+            lane: options.lane,
+            kind: options.kind ?? 'context_sync',
+            by: options.by ?? 'user',
+        };
+        if (options.payload)
+            args['payload'] = options.payload;
+        if (options.idempotencyKey)
+            args['idempotency_key'] = options.idempotencyKey;
+        return this.call('group_space_ingest', args);
+    }
+    /**
+     * Query Group Space knowledge for one lane.
+     */
+    async groupSpaceQuery(options) {
+        const args = {
+            group_id: options.groupId,
+            provider: options.provider ?? 'notebooklm',
+            lane: options.lane,
+            query: options.query,
+        };
+        if (options.options)
+            args['options'] = options.options;
+        return this.call('group_space_query', args);
+    }
+    /**
+     * Manage remote sources in the bound Group Space lane.
+     */
+    async groupSpaceSources(options) {
+        const args = {
+            group_id: options.groupId,
+            provider: options.provider ?? 'notebooklm',
+            lane: options.lane,
+            action: options.action ?? 'list',
+            by: options.by ?? 'user',
+        };
+        if (options.sourceId)
+            args['source_id'] = options.sourceId;
+        if (options.newTitle)
+            args['new_title'] = options.newTitle;
+        return this.call('group_space_sources', args);
+    }
+    /**
+     * List, generate, or download Group Space artifacts.
+     */
+    async groupSpaceArtifact(options) {
+        const args = {
+            group_id: options.groupId,
+            provider: options.provider ?? 'notebooklm',
+            lane: options.lane,
+            action: options.action ?? 'list',
+            by: options.by ?? 'user',
+        };
+        if (options.kind)
+            args['kind'] = options.kind;
+        if (options.options)
+            args['options'] = options.options;
+        if (options.wait !== undefined)
+            args['wait'] = options.wait;
+        if (options.saveToSpace !== undefined)
+            args['save_to_space'] = options.saveToSpace;
+        if (options.outputPath)
+            args['output_path'] = options.outputPath;
+        if (options.outputFormat)
+            args['output_format'] = options.outputFormat;
+        if (options.artifactId)
+            args['artifact_id'] = options.artifactId;
+        if (options.timeoutSeconds !== undefined)
+            args['timeout_seconds'] = options.timeoutSeconds;
+        if (options.initialInterval !== undefined)
+            args['initial_interval'] = options.initialInterval;
+        if (options.maxInterval !== undefined)
+            args['max_interval'] = options.maxInterval;
+        return this.call('group_space_artifact', args);
+    }
+    /**
+     * List or manage Group Space jobs.
+     */
+    async groupSpaceJobs(options) {
+        const args = {
+            group_id: options.groupId,
+            provider: options.provider ?? 'notebooklm',
+            lane: options.lane,
+            action: options.action ?? 'list',
+            by: options.by ?? 'user',
+        };
+        if (options.jobId)
+            args['job_id'] = options.jobId;
+        if (options.state)
+            args['state'] = options.state;
+        if (options.limit !== undefined)
+            args['limit'] = options.limit;
+        return this.call('group_space_jobs', args);
+    }
+    /**
+     * Read or run Group Space synchronization for one lane.
+     */
+    async groupSpaceSync(options) {
+        return this.call('group_space_sync', {
+            group_id: options.groupId,
+            provider: options.provider ?? 'notebooklm',
+            lane: options.lane,
+            action: options.action ?? 'status',
+            force: options.force ?? false,
+            by: options.by ?? 'user',
+        });
+    }
+    /**
+     * Read provider credential status.
+     */
+    async groupSpaceProviderCredentialStatus(options = {}) {
+        return this.call('group_space_provider_credential_status', {
+            provider: options.provider ?? 'notebooklm',
+            by: options.by ?? 'user',
+        });
+    }
+    /**
+     * Update provider credentials.
+     */
+    async groupSpaceProviderCredentialUpdate(options = {}) {
+        const args = {
+            provider: options.provider ?? 'notebooklm',
+            by: options.by ?? 'user',
+            clear: options.clear ?? false,
+        };
+        if (options.authJson)
+            args['auth_json'] = options.authJson;
+        return this.call('group_space_provider_credential_update', args);
+    }
+    /**
+     * Run provider health check.
+     */
+    async groupSpaceProviderHealthCheck(options = {}) {
+        return this.call('group_space_provider_health_check', {
+            provider: options.provider ?? 'notebooklm',
+            by: options.by ?? 'user',
+        });
+    }
+    /**
+     * Control provider auth flow.
+     */
+    async groupSpaceProviderAuth(options = {}) {
+        const args = {
+            provider: options.provider ?? 'notebooklm',
+            action: options.action ?? 'status',
+            by: options.by ?? 'user',
+        };
+        if (options.timeoutSeconds !== undefined)
+            args['timeout_seconds'] = options.timeoutSeconds;
+        return this.call('group_space_provider_auth', args);
+    }
     // ============================================================
     // Event stream
     // ============================================================