cccc-sdk 0.4.4 → 0.4.40

package/README.md

@@ -5,7 +5,7 @@ TypeScript/Node.js client for the CCCC daemon (IPC v1).
 ## Relationship to CCCC core
 
 - CCCC core repository: https://github.com/ChesterRa/cccc
-- `cccc` core provides daemon/web/CLI and owns runtime state.
+- `cccc` core provides one native Rust daemon/web/CLI product and owns runtime state.
 - `cccc-sdk` provides Node.js client APIs that call the daemon over IPC.
 
 ## Installation
@@ -14,7 +14,9 @@ TypeScript/Node.js client for the CCCC daemon (IPC v1).
 npm install cccc-sdk
 ```
 
-Compatibility is determined by Daemon IPC v1 contracts and operation probing, not by strict package-version matching.
+Compatibility is determined by Daemon IPC v1 contracts and operation probing,
+not by strict package-version matching. The current message contract is an
+intentional atomic cut: upgrade SDK and daemon together.
 
 ## Quick start
 
@@ -26,34 +28,50 @@ async function main() {
 
   await client.assertCompatible({
     requireIpcV: 1,
-    requireCapabilities: { events_stream: true },
     requireOps: ['groups', 'send', 'reply', 'tracked_send', 'context_sync'],
   });
 
-  const group = await client.groupCreate({ title: 'TS demo' });
-  const groupId = group.group.group_id;
+  // Use an existing Group and an Agent ID from that Group.
+  const groupId = 'g_your_group_id';
 
   await client.send({
     groupId,
     text: 'Please check this and reply.',
-    priority: 'attention',
-    replyRequired: true,
+    mode: 'request_reply',
+    to: ['peer-1'],
   });
 }
 
-main().catch(console.error);
+main().catch(error => {
+  console.error(error);
+  process.exitCode = 1;
+});
 ```
 
 ## Message semantics
 
-- `priority`: `'normal' | 'attention'`
-- `replyRequired`: `boolean` (maps to daemon `reply_required`)
+- `mode`: `'mail' | 'send' | 'request_reply'` (required for new messages)
+- `insight`: optional visible, provisional sender perspective for independent recipient judgment
+- `suggestedUserMessage`: optional proposed next human message; stored visibly and never auto-sent
 
 Supported in:
 - `send(options)`
-- `reply(options)`
 - `sendCrossGroup(options)`
-- `trackedSend(options)`
+
+`mail` stores without an immediate runtime prompt, `send` performs a
+best-effort immediate Push, and `request_reply` adds a concrete reply request.
+`reply(options)` defaults to Send and accepts `mode: 'mail'` for an agent-only,
+non-urgent reply; both modes fulfill the original reply request. The visible
+message emitted by `trackedSend(options)` remains Send. Generic ACK operations no longer exist; consume Inbox contents
+with `inboxRead(options)`. Inbox contains only Mail; inspect past direct or Mail
+traffic without changing the Mail cursor through `messageHistory(options)`.
+
+`suggestedUserMessage` is supported by `send(options)` and `reply(options)`.
+
+`contextGet(groupId, detail)` accepts `overview`, `summary`, or `full`.
+`taskList(options)` supports exact batches, filters, atomic status pages, and
+pagination. `groupSpaceSync(options)` is a read-only legacy-status call; use
+explicit ingest/source operations for mutations.
 
 ## Workflow helpers
 
@@ -64,6 +82,7 @@ await client.trackedSend({
   groupId,
   title: 'Update SDK',
   text: 'Please handle the compatibility update.',
+  insight: 'The compatibility plan may preserve an obsolete boundary.',
   outcome: 'Tests and live compat pass',
   assignee: 'peer-impl',
 });
@@ -88,6 +107,7 @@ const hits = await client.memorySearch({
   actorId: 'dingtalk-worker',
   query: 'How should I reply to this message?',
   limit: 5,
+  minScore: 0.2,
   target: 'memory',
 });
 await client.memoryWrite({
@@ -103,6 +123,8 @@ await client.memoryWrite({
 
 Local memory helpers use daemon `memory_*` ops and are intended for fast local
 CCCC memory access. They do not depend on Group Space / NotebookLM bindings.
+For raw ReMe result shapes or source selection, use `memoryRemeSearch` and
+`memoryRemeGet`. See `spec/SDK_LOCAL_MEMORY_API.md` in the repository root.
 
 ## Automation semantics
 
@@ -134,12 +156,10 @@ const client = await CCCCClient.create();
 
 const upsert = await client.actorProfileUpsert({
   profile: {
-    name: 'Codex PTY',
+    name: 'Codex',
     runtime: 'codex',
-    runner: 'pty',
-    command: ['codex', 'exec'],
+    command: ['codex'],
     submit: 'enter',
-    env: { CODEX_MODEL: 'gpt-5' },
     capabilityDefaults: {
       autoloadCapabilities: ['pack:space'],
       defaultScope: 'actor',
@@ -193,6 +213,194 @@ await client.contextSync({
 
 If you need a daemon op that does not have a dedicated helper yet, you can always fall back to `call()` / `callRaw()`.
 
+## Current native-daemon compatibility surface
+
+```typescript
+// Capture the bounded ANSI screen and exact raw cursor boundary.
+const snapshot = await client.terminalSnapshot({
+  groupId,
+  actorId: 'web-model',
+  limitBytes: 512_000,
+});
+
+// Read or change the durable delivery mode for a Web Model actor.
+const preference = await client.webModelDeliveryPreferencesGet({
+  groupId,
+  actorId: 'web-model',
+});
+await client.webModelDeliveryPreferencesUpdate({
+  groupId,
+  actorId: 'web-model',
+  mode: 'image_compat',
+});
+
+// Inspect a committed legacy turn without moving the actor cursor.
+const recovered = await client.webModelRuntimeRecoverTurn({
+  groupId,
+  actorId: 'web-model',
+  eventIds: ['e_xxx'],
+});
+```
+
+`termResize()` sends the standard `term_resize` operation. For older compatible
+daemon builds that expose `terminal_resize`, the SDK falls back only
+after receiving a structured `unknown_op`; transport failures are never
+replayed, and the legacy result is normalized to the standard shape.
+Auto-discovered clients re-read `ccccd.addr.json` when connection
+establishment fails before any request bytes are sent. Explicit endpoints are
+never replaced.
+
+This alignment pass also corrects the exact ReMe, global Remote Access,
+group-scoped IM authorization, Voice model installation, group-copy, and chat
+wire fields. `capabilitySourceDelete()` is deliberately source-scoped: the
+current daemon does not implement instance-scoped deletion and callers should
+not assume otherwise.
+
+## CCCC 0.4.33 compatibility delta
+
+```typescript
+// Deliberately rotate provider session metadata for Claude, Codex and Grok.
+await client.actorNewSession(groupId, 'reviewer');
+
+// Page through retained PTY output by cursor.
+const page = await client.terminalHistory({
+  groupId,
+  actorId: 'reviewer',
+  limitBytes: 64_000,
+});
+
+// Large group copies use a daemon-local package path instead of base64 IPC.
+const exported = await client.groupCopyExportFile({ groupId });
+const packagePath = String(exported.package_path);
+const preview = await client.groupCopyPreviewImport({ packagePath });
+const copied = await client.groupCopyImport({ packagePath });
+
+// Manage the startup body delivered to the next fresh provider session.
+await client.groupPreambleSet({
+  groupId,
+  content: 'This initialization is not a task. Wait for the targeted mission.\n',
+});
+const preamble = await client.groupPreambleGet({ groupId });
+await client.groupPreambleReset({ groupId, confirm: 'preamble' });
+
+// Upload active-scope files and append one message with daemon-owned attachments.
+await client.sendFiles({
+  groupId,
+  paths: ['reference.png', 'candidate.png'],
+  text: 'Inspect these files',
+  to: ['reviewer'],
+});
+
+// Current terminal operations.
+const recent = await client.terminalSince({ groupId, actorId: 'reviewer', after: 0 });
+await client.termResize({ groupId, actorId: 'reviewer', cols: 120, rows: 40 });
+```
+
+A changed preamble applies on its next delivery; it is not reinjected into a
+session that already received one. `groupReset` creates a new group id and
+does not carry the override forward. If the preamble establishes a standby
+boundary, wait until the actor returns to `waiting` or `idle` before sending
+the authoritative mission. `sendFiles` accepts only regular files beneath
+the group's active scope and validates every path before appending the message.
+
+`events_stream` compatibility is verified by probing the operation itself;
+the SDK does not rely only on the daemon's advertised capability flag.
+
+`groupReset` is destructive: it creates a clean replacement and removes the
+old group after copying selected configuration. `confirmGroupId` must equal
+`groupId`:
+
+```typescript
+await client.groupReset({ groupId, confirmGroupId: groupId });
+```
+
+## CCCC 0.4.18 surface — Hermes runtime and Voice Secretary lease
+
+```typescript
+// Hermes runtime setup diagnostics and MCP preparation
+const status = await client.runtimeHermesStatus();
+await client.runtimeHermesPrepare({ cwd: '.', autoEnableTools: true });
+await client.runtimeHermesMcpTest({ groupId, actorId: 'hermes-1' });
+
+// Cross-tab Voice Secretary recording guard
+const lease = await client.assistantVoiceRecordingLease({
+  groupId,
+  action: 'acquire',
+  ownerId: 'browser-tab-1',
+  ttlSeconds: 30,
+});
+```
+
+## CCCC 0.4.17 surface — new op families
+
+```typescript
+const client = await CCCCClient.create();
+
+// Tracked delegation — atomic task.create + send with idempotent replay
+const tracked = await client.trackedSend({
+  groupId,
+  title: 'Fix login race',
+  text: 'Please pick this up — see issue link',
+  insight: 'The proposed fix may target the symptom rather than the ownership boundary.',
+  to: ['alice'],
+  idempotencyKey: 'fix-login-race-1',
+  refs: [{ kind: 'url', url: 'https://example.com/issue/42' }],
+});
+
+// Per-task drill-down
+const task = await client.taskList({ groupId, taskId: String(tracked.task_id) });
+
+// Structured refs on chat
+await client.send({
+  groupId,
+  text: 'Looking at the demo deck',
+  insight: 'The deck may make the current option set look more settled than it is.',
+  refs: [{ kind: 'presentation_ref', slot_id: 'slot-1' }],
+});
+
+// Presentation workspace (slot-based viewer)
+await client.presentationPublish({
+  groupId,
+  slot: 'slot-1',
+  title: 'Plan',
+  cardType: 'markdown',
+  content: '# Sprint plan\n- ...',
+});
+
+// Built-in Voice Secretary lifecycle
+await client.assistantSettingsUpdate({
+  groupId,
+  assistantId: 'voice_secretary',
+  patch: { enabled: true },
+});
+
+// Copy a group for migration / backup
+const pkg = await client.groupCopyExport({ groupId });
+const newGroup = await client.groupCopyImport({ packageB64: String(pkg.package_b64) });
+
+// Headless runtime control
+await client.headlessSetStatus({ groupId, actorId: 'reviewer', status: 'working' });
+
+// Capability Center extensions
+await client.capabilityInstallTarget({
+  groupId,
+  target: 'github:owner/repo',
+  actorId: 'reviewer',
+  scope: 'session',
+  ttlSeconds: 600,
+});
+
+// Operator-side: terminal tail, ledger snapshot, branding/observability
+await client.terminalTail({ groupId, actorId: 'reviewer', maxChars: 4000 });
+await client.ledgerSnapshot({ groupId, reason: 'manual' });
+await client.brandingUpdate({ patch: { product_name: 'My CCCC' } });
+```
+
+Use `call()` for intentionally low-level or newly added non-streaming ops that
+do not yet have a dedicated helper. Duplex browser/VNC/PTY attach operations
+remain outside this request/response client and require a separate streaming
+transport contract. See `spec/ADAPTATION_PLAN.md` for the exact boundary.
+
 ## Events stream
 
 ```typescript
@@ -219,3 +427,31 @@ npm run build
 ## License
 
 Apache-2.0
+
+## CCCC 0.4.40 alignment
+
+All three SDK package versions are 0.4.40; `spec/core.json` records the supported
+core revision. The matching release number is not a replacement for IPC and
+capability checks.
+
+Qualified Connect sends require a stable caller-owned retry key:
+
+```ts
+await client.connectSend({ groupId: 'local', instanceId: 'remote-instance', targetGroupId: 'remote-group',
+  clientId: 'retained-caller-key', text: 'Please review', mode: 'mail' });
+```
+
+Use `connect_catalog` / `connectCatalog` to read authorized cached peers and
+`connect_send_files` / `connectSendFiles` to send files from the daemon's project
+scope. Accepted means queued locally, not confirmed delivery. Keep the same key
+and body after an uncertain result; the SDK never automatically replays a send.
+Connect replies use the local received event ID with the ordinary reply helper.
+
+`context_sync(if_version=...)` / `contextSync({ ifVersion })` rejects stale
+updates with `version_conflict`. Reload before deciding whether to reapply.
+Terminal history accepts `render_before` / `renderBefore` alongside `before`.
+
+Compatibility requirements that lack an advertised capability and an audited
+safe probe now fail instead of being executed or silently skipped. Retired
+Presentation browser and Voice model-install helpers fail locally with migration
+guidance; their interactive replacement belongs to CCCC Web, not daemon IPC.