release(sdk): align with cccc automation+messaging contracts and harden release docs

Author: ChesterRa

.github/workflows/ts-ci.yml

@@ -0,0 +1,36 @@
+name: ts-ci
+
+on:
+  push:
+    paths:
+      - "ts/**"
+      - ".github/workflows/ts-ci.yml"
+  pull_request:
+    paths:
+      - "ts/**"
+      - ".github/workflows/ts-ci.yml"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: ts/package-lock.json
+
+      - name: Install
+        working-directory: ts
+        run: npm ci
+
+      - name: Typecheck
+        working-directory: ts
+        run: npm run typecheck
+
+      - name: Build
+        working-directory: ts
+        run: npm run build

README.ja.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [中文](README.zh-CN.md) | **日本語**
 
-> ステータス：**0.4.0rc1**（Release Candidate）。契約（contracts）と SDK の使い勝手を硬化中です。
+> ステータス：**0.4.x RC**（Release Candidate）。契約（contracts）と SDK の使い勝手を硬化中です。
 
 CCCC SDK は、**CCCC daemon**（単一 writer の協調カーネル）の上に、より高度なアプリケーションを作るための **クライアント SDK** です。
 
@@ -32,7 +32,7 @@ cccc
 ```bash
 python -m pip install --index-url https://pypi.org/simple \
   --extra-index-url https://test.pypi.org/simple \
-  cccc-sdk==0.4.0rc1
+  cccc-sdk==0.4.0rcN
 ```
 
 3) 互換性チェック（推奨）：
@@ -69,7 +69,7 @@ python python/examples/auto_ack_attention.py --group g_xxx --actor user
 ## バージョニング（RC 番号が CCCC と一致しない理由）
 
 SDK は **CCCC 0.4.0** に major/minor を合わせますが、**RC の連番は SDK 側で管理**します：
-- 例：`cccc-sdk==0.4.0rc1` が `cccc==0.4.0rc16` と互換な場合があります。
+- 例：`cccc-sdk==0.4.0rcN` が `cccc==0.4.x` と互換な場合があります。
 
 互換性は “契約/能力” で保証します（RC 連番の厳密一致には依存しません）：
 - IPC バージョン（`ipc_v`）
@@ -84,7 +84,7 @@ SDK は **CCCC 0.4.0** に major/minor を合わせますが、**RC の連番は
 
 - `spec/` — SDK 開発用の契約文書ミラー
 - `python/` — Python パッケージ（PyPI 名：`cccc-sdk`、import：`cccc_sdk`）
-- `ts/` — TypeScript SDK（予定）
+- `ts/` — TypeScript SDK（Node.js）
 
 ---
 

README.md

@@ -2,7 +2,7 @@
 
 **English** | [中文](README.zh-CN.md) | [日本語](README.ja.md)
 
-> Status: **0.4.0rc1** (Release Candidate). Contracts and SDK ergonomics are still being hardened.
+> Status: **0.4.x RC** (Release Candidate). Contracts and SDK ergonomics are still being hardened.
 
 CCCC SDK is a set of **client SDKs** for building higher-level applications on top of the
 **CCCC daemon** (the single-writer collaboration kernel).
@@ -34,7 +34,7 @@ cccc
 ```bash
 python -m pip install --index-url https://pypi.org/simple \
   --extra-index-url https://test.pypi.org/simple \
-  cccc-sdk==0.4.0rc1
+  cccc-sdk==0.4.0rcN
 ```
 
 3) Compatibility check (recommended):
@@ -71,7 +71,7 @@ python python/examples/auto_ack_attention.py --group g_xxx --actor user
 ## Versioning (why RC numbers may not match CCCC)
 
 SDK versions match **CCCC major/minor** (`0.4.0`), but the **RC sequence is SDK-owned**:
-- Example: `cccc-sdk==0.4.0rc1` can be compatible with `cccc==0.4.0rc16`.
+- Example: `cccc-sdk==0.4.0rcN` can be compatible with `cccc==0.4.x`.
 
 Compatibility is enforced by **contracts**, not by strict RC number matching:
 - IPC version (`ipc_v`)
@@ -86,7 +86,7 @@ See `python/examples/compat_check.py`.
 
 - `spec/` — contract documents mirrored for SDK development
 - `python/` — Python package (`cccc-sdk`, import `cccc_sdk`)
-- `ts/` — TypeScript SDK (planned)
+- `ts/` — TypeScript SDK (Node.js)
 
 ---
 

README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | **中文** | [日本語](README.ja.md)
 
-> 状态：**0.4.0rc1**（Release Candidate）。我们仍在打磨契约与 SDK 易用性，RC 期间可能有行为变化。
+> 状态：**0.4.x RC**（Release Candidate）。我们仍在打磨契约与 SDK 易用性，RC 期间可能有行为变化。
 
 CCCC SDK 是一套**客户端 SDK**，用于在 **CCCC daemon**（单写入者协作内核）之上构建更上层的应用。
 
@@ -32,7 +32,7 @@ cccc
 ```bash
 python -m pip install --index-url https://pypi.org/simple \
   --extra-index-url https://test.pypi.org/simple \
-  cccc-sdk==0.4.0rc1
+  cccc-sdk==0.4.0rcN
 ```
 
 3) 兼容性检查（推荐先跑一次）：
@@ -69,7 +69,7 @@ python python/examples/auto_ack_attention.py --group g_xxx --actor user
 ## 版本策略（为什么 RC 编号不一定和 CCCC 一致）
 
 SDK 的 major/minor 会对齐 **CCCC 0.4.0**，但 **RC 序号由 SDK 自己维护**：
-- 例如：`cccc-sdk==0.4.0rc1` 也可以兼容 `cccc==0.4.0rc16`。
+- 例如：`cccc-sdk==0.4.0rcN` 也可以兼容 `cccc==0.4.x`。
 
 我们保证兼容性的手段是“契约/能力”，而不是强行对齐 RC 序号：
 - IPC 版本（`ipc_v`）
@@ -84,7 +84,7 @@ SDK 的 major/minor 会对齐 **CCCC 0.4.0**，但 **RC 序号由 SDK 自己维
 
 - `spec/` — 合约文档镜像（用于 SDK 开发）
 - `python/` — Python 包（PyPI 名称 `cccc-sdk`，import 名称 `cccc_sdk`）
-- `ts/` — TypeScript SDK（规划中）
+- `ts/` — TypeScript SDK（Node.js）
 
 ---
 

RELEASING.md

@@ -1,99 +1,105 @@
-# Releasing `cccc-sdk` (Python)
+# Releasing `cccc-sdk`
 
-This repo is a monorepo. The Python package lives under `python/`.
+This repo is a monorepo with two deliverables:
+- Python package: `python/` (PyPI name: `cccc-sdk`)
+- TypeScript package: `ts/` (npm name: `cccc-sdk`)
 
-## Prerequisites (one-time)
-
-### 1) Create accounts
+## Versioning policy
 
-- Create a TestPyPI account (for RC dry-runs).
-- Create a PyPI account (for real releases).
-- Enable 2FA on both accounts (recommended).
+- SDK major/minor tracks CCCC: `0.4.0`.
+- RC sequence is SDK-owned (`0.4.0rcN` for Python, `0.4.0-rc.N` for npm).
+- Compatibility is enforced by contracts/capabilities/op-probing, not by matching RC numbers.
 
-### 2) Create API tokens
+## 0) Sync specs (recommended)
 
-You’ll need **two** tokens:
-- one for TestPyPI
-- one for PyPI
+```bash
+./scripts/sync_specs_from_cccc.sh ../cccc
+```
 
-For the **very first upload** (when the project does not exist yet), TestPyPI/PyPI may only allow an
-**account-scoped** token. After the project exists, prefer a **project-scoped** token and revoke the
-account-scoped one.
+## 1) Python release (PyPI/TestPyPI)
 
-### 3) Configure GitHub Actions secrets
+### Prerequisites
 
-In the GitHub repo `ChesterRa/cccc-sdk`:
+- TestPyPI and PyPI accounts
+- Repository secrets in `ChesterRa/cccc-sdk`:
+  - `TEST_PYPI_API_TOKEN`
+  - `PYPI_API_TOKEN`
 
-`Settings → Secrets and variables → Actions → New repository secret`
+### Bump version
 
-Add:
-- `TEST_PYPI_API_TOKEN` (from TestPyPI)
-- `PYPI_API_TOKEN` (from PyPI)
+Edit `python/pyproject.toml` (`project.version`).
 
-## Versioning policy
+### Local checks
 
-- The SDK version matches **CCCC major/minor**: `0.4.0`.
-- Pre-releases use PEP 440: `0.4.0rc1`, `0.4.0rc2`, ...
-- RC numbers are **SDK-owned** and do not need to match the daemon’s RC sequence.
-- Compatibility is enforced via:
-  - `ipc_v` (ping)
-  - `capabilities` (ping)
-  - op probing (`unknown_op`)
+```bash
+./.venv/bin/python -m unittest discover -s python/tests -p "test_*.py" -v
+```
 
-## 0) Sync specs (recommended)
+### Publish RC to TestPyPI
 
 ```bash
-./scripts/sync_specs_from_cccc.sh ../cccc
+git tag v0.4.0rcN
+git push origin v0.4.0rcN
 ```
 
-## 1) Bump version
+This triggers `.github/workflows/python-publish-testpypi.yml`.
 
-Edit:
-- `python/pyproject.toml` (`project.version`)
-
-## 2) Run local checks
+Install check:
 
 ```bash
-PYTHONPATH=python/src python -m unittest discover -s python/tests -p "test_*.py" -v
+python -m pip install --index-url https://pypi.org/simple \
+  --extra-index-url https://test.pypi.org/simple \
+  cccc-sdk==0.4.0rcN
 ```
 
-Optional build check (requires a venv because many systems are PEP 668 locked):
+### Publish stable to PyPI
 
 ```bash
-python -m venv .venv
-. .venv/bin/activate
-python -m pip install -U pip build
-python -m build python
+git tag v0.4.0
+git push origin v0.4.0
 ```
 
-## 3) Publish to TestPyPI (recommended for RCs)
+This triggers `.github/workflows/python-publish.yml`.
+
+## 2) TypeScript release (npm)
+
+### Bump version
 
-1) Confirm `python/pyproject.toml` version is the one you want to publish.
-2) Tag and push (auto publishes to TestPyPI):
+Edit `ts/package.json` (`version`).
+
+Examples:
+- RC: `0.4.0-rc.N`
+- Stable: `0.4.0`
+
+### Local checks
 
 ```bash
-git tag v0.4.0rc1
-git push origin v0.4.0rc1
+cd ts
+npm ci
+npm run typecheck
+npm run build
 ```
 
-This triggers `python-publish-testpypi.yml`.
+### Publish RC
 
-Install:
+```bash
+cd ts
+npm publish --tag rc --access public
+```
+
+### Publish stable
 
 ```bash
-python -m pip install --index-url https://pypi.org/simple \
-  --extra-index-url https://test.pypi.org/simple \
-  cccc-sdk==0.4.0rc1
+cd ts
+npm publish --access public
 ```
 
-## 4) Publish to PyPI
+## 3) Post-release sanity
 
-1) Confirm `python/pyproject.toml` version is the one you want to publish.
-2) Tag and push (recommended):
+- Run Python compat check against a running daemon:
 
 ```bash
-git tag v0.4.0
-git push origin v0.4.0
+python python/examples/compat_check.py
 ```
 
-This triggers `python-publish.yml`.
+- Verify npm package installs and can `import { CCCCClient } from 'cccc-sdk'`.

python/README.md

@@ -7,7 +7,7 @@ It requires a running CCCC daemon. The SDK does **not** ship a daemon.
 ## Versioning
 
 This SDK matches **CCCC major/minor** (`0.4.0`), but the **RC sequence is SDK-owned**:
-- Example: `cccc-sdk==0.4.0rc1` can be compatible with `cccc==0.4.0rc16`.
+- Example: `cccc-sdk==0.4.0rcN` can be compatible with `cccc==0.4.x`.
 
 ## Daemon endpoint discovery
 
@@ -23,7 +23,7 @@ The SDK connects to the daemon endpoint described by:
 ```bash
 python -m pip install --index-url https://pypi.org/simple \
   --extra-index-url https://test.pypi.org/simple \
-  cccc-sdk==0.4.0rc1
+  cccc-sdk==0.4.0rcN
 ```
 
 ### From source (development)

python/examples/send.py

@@ -13,12 +13,13 @@ def main() -> int:
     ap.add_argument("--by", default="user", help="principal id (default: user)")
     ap.add_argument("--to", default="", help="comma-separated recipient tokens (empty = broadcast)")
     ap.add_argument("--priority", default="normal", choices=["normal", "attention"], help="message priority")
+    ap.add_argument("--reply-required", action="store_true", help="mark this message as requiring a reply")
     args = ap.parse_args()
 
     to = [t.strip() for t in args.to.split(",") if t.strip()] if args.to else None
 
     c = CCCCClient()
-    res = c.send(group_id=args.group, text=args.text, by=args.by, to=to, priority=args.priority)
+    res = c.send(group_id=args.group, text=args.text, by=args.by, to=to, priority=args.priority, reply_required=args.reply_required)
     print(json.dumps(res, ensure_ascii=False))
     return 0
 

python/examples/send_cross_group.py

@@ -14,12 +14,13 @@ def main() -> int:
     ap.add_argument("--by", default="user", help="principal id (default: user)")
     ap.add_argument("--to", default="", help="comma-separated destination recipient tokens (optional)")
     ap.add_argument("--priority", default="normal", choices=["normal", "attention"], help="message priority")
+    ap.add_argument("--reply-required", action="store_true", help="mark this message as requiring a reply")
     args = ap.parse_args()
 
     to = [t.strip() for t in args.to.split(",") if t.strip()] if args.to else None
 
     c = CCCCClient()
-    res = c.send_cross_group(group_id=args.src, dst_group_id=args.dst, text=args.text, by=args.by, to=to, priority=args.priority)
+    res = c.send_cross_group(group_id=args.src, dst_group_id=args.dst, text=args.text, by=args.by, to=to, priority=args.priority, reply_required=args.reply_required)
     print(json.dumps(res, ensure_ascii=False))
     return 0