release: finalize 0.4.7

Author: ChesterRa

docs/release/v0.4.7_release_notes.md

@@ -0,0 +1,58 @@
+# CCCC v0.4.7 Release Notes
+
+`v0.4.7` builds on `v0.4.6` with a focused set of workflow, presentation, and Web UX improvements.
+
+Compared with `v0.4.6`, this release makes Presentation a first-class shared workspace, tightens task workflow handling across Web and MCP, adds Web branding controls, and cleans up several runtime and operator-facing rough edges.
+
+## Highlights
+
+## 1) Presentation became a real shared workspace
+
+The main change in `v0.4.7` is the new Presentation surface.
+
+Groups can now publish and manage slot-based presentation content through the daemon, Web UI, and MCP layer. The Chat surface also gained a dedicated Presentation rail and viewer flow, so shared artifacts no longer have to live only as chat text.
+
+## 2) Interactive browser-backed views landed
+
+`v0.4.7` also adds the browser-surface path for Presentation.
+
+This makes it possible to handle harder Web content in a more useful way than a simple static preview. The viewer lifecycle and controls were refined as part of the same work, including better handling for refresh, fullscreen, replacement, and URL entry.
+
+## 3) Chat and Presentation are now connected by references
+
+Presentation references were added to the message flow, which means chat can point back to a specific Presentation view instead of relying on vague text-only handoffs.
+
+Snapshot and compare behavior were also added so the quoted view can be preserved more clearly when users and agents are discussing live content.
+
+## 4) Task workflow handling is stricter
+
+This release also improves the task workflow layer.
+
+Task state handling in the Web UI is more structured, context/task workflow logic is tighter, and MCP-side task update compatibility was improved so task status changes are less fragile in practice.
+
+## 5) Web polish and branding moved forward
+
+`v0.4.7` includes a broad Web polish pass as well.
+
+Highlights include:
+
+- Web branding controls for product name and logo assets
+- stronger group/context/unread refresh behavior
+- general message, panel, and console usability cleanup
+
+## 6) Runtime and startup behavior were cleaned up further
+
+This release also includes smaller but important runtime fixes.
+
+Notably, the default `cccc` entry path now respects top-level `--host` / `--port` overrides throughout supervised Web startup and restart, and Kimi runtime defaults were updated to match the current preferred path.
+
+## Summary
+
+In short, `v0.4.7` is the release that brings together:
+
+1. the first real Presentation workspace
+2. browser-backed interactive presentation views
+3. chat-to-presentation references
+4. tighter task workflow handling
+5. Web branding and usability polish
+6. another round of runtime/startup cleanup

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cccc-pair"
-version = "0.4.7rc1"
+version = "0.4.7"
 description = "Global multi-agent delivery kernel with working groups, scopes, and an append-only collaboration ledger"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.9"

src/cccc/cli/common.py

@@ -86,6 +86,20 @@ def _resolve_web_server_binding() -> tuple[str, int]:
     return host, port
 
 
+def _resolve_invocation_web_server_binding(
+    *,
+    web_host_override: str = "",
+    web_port_override: Optional[int] = None,
+) -> tuple[str, int]:
+    host, port = _resolve_web_server_binding()
+    override_host = str(web_host_override or "").strip()
+    if override_host:
+        host = override_host
+    if web_port_override is not None:
+        port = int(web_port_override)
+    return host, int(port)
+
+
 def _default_entry_lock_path(home: Path) -> Path:
     return home / "daemon" / "cccc-app.lock"
 
@@ -432,7 +446,7 @@ def _show_welcome() -> None:
     print("=" * 60)
     print()
 
-def _default_entry() -> int:
+def _default_entry(*, web_host_override: str = "", web_port_override: Optional[int] = None) -> int:
     """Default entry: start daemon + web together, stop both on Ctrl+C."""
     import threading
 
@@ -571,8 +585,15 @@ def _stop_daemon() -> None:
         _lifecycle.stop_daemon()
         daemon_process = _lifecycle.process
 
-    # Keep runtime binding aligned with remote_access settings/UI.
-    host, port = _resolve_web_server_binding()
+    # Saved binding is the baseline, but top-level `cccc --host/--port`
+    # must win for this invocation, including supervised child restarts.
+    def _resolve_invocation_binding() -> tuple[str, int]:
+        return _resolve_invocation_web_server_binding(
+            web_host_override=web_host_override,
+            web_port_override=web_port_override,
+        )
+
+    host, port = _resolve_invocation_binding()
     log_level = str(os.environ.get("CCCC_WEB_LOG_LEVEL") or "").strip() or "info"
     reload_mode = _env_flag("CCCC_WEB_RELOAD", default=False)
     web_process = None
@@ -640,7 +661,7 @@ def _print_web_banner(cur_host: str, cur_port: int) -> None:
                     reload=reload_mode,
                     log_level=log_level,
                     launch_source="default_entry",
-                    resolve_binding=_resolve_web_server_binding,
+                    resolve_binding=_resolve_invocation_binding,
                     log=lambda msg: print(f"[cccc] {msg}", file=sys.stderr),
                 )
                 if restarted is None:

src/cccc/cli/main.py

@@ -523,7 +523,12 @@ def main(argv: Optional[list[str]] = None) -> int:
     previous_env, applied_env = _apply_invocation_web_overrides(args)
     try:
         if not getattr(args, "cmd", None):
-            return int(_default_entry())
+            return int(
+                _default_entry(
+                    web_host_override=str(getattr(args, "web_host", "") or ""),
+                    web_port_override=getattr(args, "web_port", None),
+                )
+            )
         return int(args.func(args))
     finally:
         _restore_invocation_web_overrides(previous_env, applied_env)

tests/test_cli_default_entry_ownership.py

@@ -257,6 +257,84 @@ def start(self) -> None:
         finally:
             cleanup()
 
+    def test_default_entry_applies_invocation_port_override_to_initial_web_start(self) -> None:
+        from cccc.cli import common
+
+        home, cleanup = self._with_home()
+        try:
+            daemon_proc = _DaemonProc()
+            web_proc = object()
+
+            class _DummyThread:
+                def __init__(self, *args, **kwargs) -> None:
+                    _ = args, kwargs
+
+                def start(self) -> None:
+                    return None
+
+            with patch.object(common, "_is_first_run", return_value=False), patch(
+                "cccc.paths.ensure_home", return_value=home
+            ), patch.object(common, "_acquire_default_entry_lock", return_value=("lock", None)), patch.object(
+                common, "_stop_existing_web_runtime", return_value=True
+            ), patch.object(common, "_stop_existing_daemon", return_value=True), patch.object(
+                common, "_resolve_web_server_binding", return_value=("0.0.0.0", 8848)
+            ), patch.object(common, "call_daemon", return_value={"ok": True}), patch.object(
+                common.subprocess, "Popen", return_value=daemon_proc
+            ), patch.object(common, "start_supervised_web_child", return_value=(web_proc, None)) as mock_start_web, patch.object(
+                common, "wait_for_child_exit_interruptibly", side_effect=KeyboardInterrupt()
+            ), patch.object(common, "stop_web_child", return_value=True), patch.object(
+                common, "release_lockfile"
+            ), patch("threading.Thread", _DummyThread):
+                ret = common._default_entry(web_port_override=9000)
+
+            self.assertEqual(ret, 0)
+            self.assertEqual(mock_start_web.call_args.kwargs["host"], "0.0.0.0")
+            self.assertEqual(mock_start_web.call_args.kwargs["port"], 9000)
+        finally:
+            cleanup()
+
+    def test_default_entry_keeps_invocation_port_override_on_web_restart(self) -> None:
+        from cccc.cli import common
+
+        home, cleanup = self._with_home()
+        try:
+            daemon_proc = _DaemonProc()
+            first_web_proc = unittest.mock.Mock(pid=1111)
+            restarted_web_proc = unittest.mock.Mock(pid=2222)
+
+            class _DummyThread:
+                def __init__(self, *args, **kwargs) -> None:
+                    _ = args, kwargs
+
+                def start(self) -> None:
+                    return None
+
+            def _restart_with_assertion(**kwargs):
+                self.assertEqual(kwargs["resolve_binding"](), ("0.0.0.0", 9000))
+                return restarted_web_proc, "0.0.0.0", 9000
+
+            with patch.object(common, "_is_first_run", return_value=False), patch(
+                "cccc.paths.ensure_home", return_value=home
+            ), patch.object(common, "_acquire_default_entry_lock", return_value=("lock", None)), patch.object(
+                common, "_stop_existing_web_runtime", return_value=True
+            ), patch.object(common, "_stop_existing_daemon", return_value=True), patch.object(
+                common, "_resolve_web_server_binding", return_value=("0.0.0.0", 8848)
+            ), patch.object(common, "call_daemon", return_value={"ok": True}), patch.object(
+                common.subprocess, "Popen", return_value=daemon_proc
+            ), patch.object(common, "start_supervised_web_child", return_value=(first_web_proc, None)), patch.object(
+                common, "wait_for_child_exit_interruptibly", side_effect=[common.WEB_RUNTIME_RESTART_EXIT_CODE, KeyboardInterrupt()]
+            ), patch.object(
+                common, "restart_supervised_web_child_with_fallback", side_effect=_restart_with_assertion
+            ) as mock_restart, patch.object(common, "stop_web_child", return_value=True), patch.object(
+                common, "release_lockfile"
+            ), patch("threading.Thread", _DummyThread):
+                ret = common._default_entry(web_port_override=9000)
+
+            self.assertEqual(ret, 0)
+            self.assertEqual(mock_restart.call_count, 1)
+        finally:
+            cleanup()
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_cli_main.py

@@ -14,15 +14,17 @@ def test_main_uses_default_entry_when_no_subcommand(self) -> None:
             rc = cli_main.main([])
 
         self.assertEqual(rc, 7)
-        mock_default.assert_called_once_with()
+        mock_default.assert_called_once_with(web_host_override="", web_port_override=None)
 
     def test_main_applies_top_level_port_override_to_default_entry_only_for_invocation(self) -> None:
         cli_main = importlib.import_module("cccc.cli.main")
 
         old_port = os.environ.get("CCCC_WEB_PORT")
 
-        def _assert_port_and_return() -> int:
+        def _assert_port_and_return(*, web_host_override: str, web_port_override: int | None) -> int:
             self.assertEqual(os.environ.get("CCCC_WEB_PORT"), "9000")
+            self.assertEqual(web_host_override, "")
+            self.assertEqual(web_port_override, 9000)
             return 0
 
         try:
@@ -35,7 +37,7 @@ def _assert_port_and_return() -> int:
                 os.environ["CCCC_WEB_PORT"] = old_port
 
         self.assertEqual(rc, 0)
-        mock_default.assert_called_once_with()
+        mock_default.assert_called_once_with(web_host_override="", web_port_override=9000)
         self.assertEqual(os.environ.get("CCCC_WEB_PORT"), old_port)
 
     def test_main_accepts_top_level_port_override_before_subcommand(self) -> None:

web/src/components/presentation/PresentationPinModal.tsx

@@ -4,6 +4,7 @@ import type { PresentationSlot, PresentationWorkspaceItem } from "../../types";
 import { fetchPresentationWorkspaceListing } from "../../services/api";
 import { useModalA11y } from "../../hooks/useModalA11y";
 import { classNames } from "../../utils/classNames";
+import { isValidPresentationWebUrl, normalizePresentationUrlInput } from "../../utils/presentation";
 import { ModalFrame } from "../modals/ModalFrame";
 
 type PresentationPinModalProps = {
@@ -231,9 +232,18 @@ export function PresentationPinModal({
         setError(t("presentationUrlRequired", { defaultValue: "Enter a URL first." }));
         return;
       }
+      const normalizedUrl = normalizePresentationUrlInput(trimmedUrl);
+      if (!isValidPresentationWebUrl(normalizedUrl)) {
+        setError(
+          t("presentationUrlInvalid", {
+            defaultValue: "This does not look like a valid URL. Try example.com or localhost:3000.",
+          }),
+        );
+        return;
+      }
       await onSubmitUrl({
         slotId,
-        url: trimmedUrl,
+        url: normalizedUrl,
         title: String(title || "").trim(),
         summary: String(summary || "").trim(),
       });

web/src/i18n/locales/en/chat.json

@@ -153,6 +153,7 @@
   "presentationSummaryLabel": "Summary",
   "presentationSummaryPlaceholder": "Optional summary shown in the slot preview",
   "presentationUrlRequired": "Enter a URL first.",
+  "presentationUrlInvalid": "This does not look like a valid URL. Try example.com or localhost:3000.",
   "presentationFileRequired": "Choose a file first.",
   "presentationPinSubmit": "Pin to slot",
   "presentationReplaceSubmit": "Save changes",

web/src/i18n/locales/ja/chat.json

@@ -153,6 +153,7 @@
   "presentationSummaryLabel": "要約",
   "presentationSummaryPlaceholder": "任意。スロットのプレビューに表示されます",
   "presentationUrlRequired": "先に URL を入力してください。",
+  "presentationUrlInvalid": "有効な URL に見えません。example.com または localhost:3000 を試してください。",
   "presentationFileRequired": "先にファイルを選択してください。",
   "presentationPinSubmit": "このスロットに固定",
   "presentationReplaceSubmit": "変更を保存",

web/src/i18n/locales/zh/chat.json

@@ -153,6 +153,7 @@
   "presentationSummaryLabel": "摘要",
   "presentationSummaryPlaceholder": "可选，会显示在槽位预览里",
   "presentationUrlRequired": "请先输入 URL。",
+  "presentationUrlInvalid": "这看起来不像有效的 URL。可以试试 example.com 或 localhost:3000。",
   "presentationFileRequired": "请先选择文件。",
   "presentationPinSubmit": "固定到槽位",
   "presentationReplaceSubmit": "保存修改",