@agentsdock/server 1.0.7-beta.5

package/server/interactive_chat_controls.py

@@ -0,0 +1,153 @@
+"""Explicit one-chat controls; no server imports, HTTP proxy, or authority lookup.
+
+The router authenticates the share and supplies its chat identity. The owner
+injects native models/callbacks and projects their results for the guest. Native
+exceptions are deliberately not converted to safe denials: a callback may have
+already committed work. Only ChatControlError is known to precede invocation.
+"""
+from __future__ import annotations
+
+import json
+import re
+from types import MappingProxyType
+
+
+SETTINGS_FIELDS = frozenset({
+    "title", "backend", "model", "effort", "system_prompt",
+    "claude_permission_mode", "codex_approval_policy", "codex_sandbox_mode",
+    "codex_permission_profile", "codex_approvals_reviewer", "cursor_permission_mode",
+    "provider_jobs_access",
+})
+GOAL_FIELDS = frozenset({"objective", "status", "token_budget", "time_budget_seconds"})
+JOB_FIELDS = frozenset({
+    "title", "prompt", "schedule_kind", "interval_seconds", "cron_expression",
+    "rrule", "timezone", "loop", "max_runs", "enabled", "backend",
+})
+ACTIONS = frozenset({
+    "state", "turn.stop", "turn.steer", "queue.run_now", "queue.edit", "queue.delete",
+    "queue.move", "settings.update", "goal.set", "goal.resume", "goal.pause", "goal.delete",
+    "job.create", "job.update", "job.delete", "job.toggle", "job.run", "approval.respond",
+})
+
+
+class ChatControlError(ValueError):
+    """A bounded rejection before any native callback or mutation."""
+
+    def __init__(self, code="invalid_request"):
+        self.code = code
+        super().__init__("This chat control request is not permitted" if code == "forbidden"
+                         else "Invalid chat control request")
+
+
+def _identity(value):
+    if not isinstance(value, str) or re.fullmatch(r"[A-Za-z0-9_.-]{1,128}", value) is None:
+        raise ChatControlError()
+    return value
+
+
+def _fields(payload, allowed=(), required=(), *, nonempty=False):
+    if set(payload) - set(allowed) or not set(required).issubset(payload) or nonempty and not payload:
+        raise ChatControlError()
+
+
+class InteractiveChatControls:
+    """Dispatch to fixed native functions with a server-bound first argument.
+
+    Callback keys normally equal action names; approval uses approval.codex or
+    approval.claude. Native models are keyed by their class names. turn.steer is
+    the owner's enqueue/exact-promotion wrapper; job.run is the owner's atomic
+    expected-session wrapper, never the global unscoped run_job endpoint.
+    """
+
+    def __init__(self, callbacks, models):
+        self.callbacks = MappingProxyType(dict(callbacks))
+        self.models = MappingProxyType(dict(models))
+
+    def _model(self, name, fields):
+        model = self.models.get(name)
+        if model is None:
+            raise ChatControlError("forbidden")
+        try:
+            return model.model_validate(fields)
+        except ValueError:
+            # Never expose native validation input, paths or object reprs.
+            raise ChatControlError() from None
+
+    async def dispatch(self, session_id, action, payload, *, share_id=None, request_id=None):
+        _identity(session_id)
+        if not isinstance(action, str) or action not in ACTIONS:
+            raise ChatControlError("forbidden")
+        if not isinstance(payload, dict) or any(not isinstance(key, str) for key in payload):
+            raise ChatControlError()
+        try:
+            encoded = json.dumps(payload, ensure_ascii=False, allow_nan=False).encode("utf-8")
+        except (TypeError, ValueError, UnicodeError, RecursionError):
+            raise ChatControlError() from None
+        if len(encoded) > 64 * 1024:
+            raise ChatControlError()
+        payload = json.loads(encoded)  # Callback sees an owned immutable-in-transit value.
+        callback_key, args, kwargs = action, [session_id], {}
+
+        if action in {"state", "turn.stop", "goal.delete", "goal.resume", "goal.pause"}:
+            _fields(payload)
+            if action in {"goal.resume", "goal.pause"}:
+                args.append(self._model("CodexGoalRequest", {"status": "active" if action == "goal.resume" else "paused"}))
+        elif action == "turn.steer":
+            _fields(payload, {"prompt"}, {"prompt"})
+            if not isinstance(payload["prompt"], str) or not payload["prompt"].strip():
+                raise ChatControlError()
+            if not isinstance(share_id, str) or re.fullmatch(r"interactive_[a-f0-9]{32}", share_id) is None:
+                raise ChatControlError("forbidden")
+            if not isinstance(request_id, str) or re.fullmatch(r"[A-Za-z0-9_-]{16,128}", request_id) is None:
+                raise ChatControlError()
+            args.append(payload["prompt"])
+            kwargs = {"share_id": share_id, "request_id": request_id}
+        elif action in {"queue.delete", "queue.run_now", "job.delete", "job.run"}:
+            _fields(payload, {"id"}, {"id"})
+            args.append(_identity(payload["id"]))
+            if action == "queue.run_now":
+                args.append(self._model("RunQueuedTurnNowRequest", {"accept_deferred_queue_response": True}))
+        elif action == "queue.edit":
+            _fields(payload, {"id", "prompt", "expected_message_revision"}, {"id", "prompt"})
+            args.append(_identity(payload.pop("id")))
+            if not isinstance(payload["prompt"], str):
+                raise ChatControlError()
+            args.append(self._model("UpdateQueuedTurnRequest", payload))
+        elif action == "queue.move":
+            _fields(payload, {"id", "direction", "expected_adjacent_queued_id"}, {"id", "direction"})
+            args.append(_identity(payload.pop("id")))
+            if not isinstance(payload["direction"], str) or payload["direction"] not in {"up", "down"}:
+                raise ChatControlError()
+            if "expected_adjacent_queued_id" in payload:
+                _identity(payload["expected_adjacent_queued_id"])
+            args.append(self._model("MoveQueuedTurnRequest", payload))
+        elif action == "settings.update":
+            _fields(payload, SETTINGS_FIELDS, nonempty=True)
+            args.append(self._model("UpdateSessionRequest", payload))
+        elif action == "goal.set":
+            _fields(payload, GOAL_FIELDS, nonempty=True)
+            args.append(self._model("CodexGoalRequest", payload))
+        elif action == "job.create":
+            _fields(payload, JOB_FIELDS | {"first_run_at"}, {"title", "prompt"})
+            args.append(self._model("CreateScopedJobRequest", {**payload, "context_mode": "chat"}))
+        elif action in {"job.update", "job.toggle"}:
+            allowed = {"id", "enabled"} if action == "job.toggle" else JOB_FIELDS | {"id", "next_run_at"}
+            _fields(payload, allowed, {"id", "enabled"} if action == "job.toggle" else {"id"})
+            args.append(_identity(payload.pop("id")))
+            if not payload or action == "job.toggle" and type(payload["enabled"]) is not bool:
+                raise ChatControlError()
+            args.append(self._model("UpdateJobRequest", payload))
+        elif action == "approval.respond":
+            _fields(payload, {"id", "backend", "response"}, {"id", "backend", "response"})
+            backend = payload["backend"]
+            if backend not in ("codex", "claude") or not isinstance(payload["response"], dict):
+                raise ChatControlError()
+            args.append(_identity(payload["id"]))
+            args.append(self._model("CodexInteractionResponseRequest" if backend == "codex" else "ClaudeInteractionResponseRequest",
+                                    {"response": payload["response"]}))
+            callback_key = "approval." + backend
+
+        callback = self.callbacks.get(callback_key)
+        if not callable(callback):
+            raise ChatControlError("forbidden")
+        return await callback(*args, **kwargs)

package/server/interactive_chat_native.py

@@ -0,0 +1,66 @@
+"""Shared-chat DTOs reuse native UI contracts without file or server authority."""
+from __future__ import annotations
+
+import math
+from shared_chat_videos import normalize_shared_chat_videos
+
+PRIVATE_FIELDS = frozenset({
+    "cwd", "path", "source_path", "root", "file", "files", "artifact", "artifacts",
+    "file_ids", "display_file_ids", "file_path", "notebook_path", "old_path", "new_path",
+    "attachments", "env", "environment", "runtime_env", "runtime_context", "authorization", "headers",
+    "token", "access_token", "refresh_token", "api_key", "password", "secret",
+    "authority", "authority_file", "authority_path", "request_prompt", "provider_cross_chat_route_snapshot",
+    "secure_peer_route_snapshots", "chat_references", "team_references",
+    "claude_session_id", "codex_thread_id", "cursor_session_id",
+})
+SESSION_FIELDS = frozenset({
+    "id", "title", "backend", "model", "effort", "system_prompt", "backend_locked",
+    "claude_permission_mode", "codex_approval_policy", "codex_sandbox_mode",
+    "codex_permission_profile", "codex_approvals_reviewer", "cursor_permission_mode",
+    "provider_jobs_access", "codex_goal", "codex_goal_time_budget_seconds",
+    "codex_goal_time_budget_exhausted", "codex_thread_status",
+    "codex_pending_interaction_count", "codex_needs_user_action",
+    "claude_pending_interaction_count", "claude_needs_user_action",
+    "claude_stop_fence_pending", "created_at", "updated_at", "archived",
+    "latest_event_seq", "latest_event_at", "latest_agent_event_seq", "latest_agent_event_at",
+})
+
+
+def shared_native_value(value, depth=0):
+    """Remove transport/file metadata, not words deliberately present in chat text.
+
+    This is an egress filter, never an authorization decision. Every callback
+    has already selected a single chat and used the native ownership checks.
+    """
+    if depth > 20:
+        raise ValueError("Shared chat data is too deeply nested")
+    if isinstance(value, dict):
+        return {key: shared_native_value(item, depth + 1) for key, item in value.items()
+                if isinstance(key, str) and not key.startswith("_")
+                and key.lower() not in PRIVATE_FIELDS}
+    if isinstance(value, (list, tuple)):
+        return [shared_native_value(item, depth + 1) for item in value]
+    if type(value) is float and not math.isfinite(value):
+        raise ValueError("Shared chat data contains an invalid number")
+    if value is None or type(value) in (str, int, float, bool):
+        return value
+    raise ValueError("Shared chat data is not serializable")
+
+
+def shared_session(value):
+    return shared_native_value({key: item for key, item in value.items() if key in SESSION_FIELDS})
+
+
+def shared_events(events, session_id):
+    output = []
+    for event in events:
+        if not isinstance(event, dict) or event.get("session_id") not in (None, "", session_id):
+            raise ValueError("Shared chat event ownership is invalid")
+        kind = str(event.get("type") or "")
+        # Only explicitly projected video descriptors cross the media boundary.
+        # Tool output is chat content, not direct filesystem access.
+        videos = normalize_shared_chat_videos(event.get("shared_videos", []))
+        if kind.startswith(("file_", "artifact_", "workspace_", "terminal_")) and not (kind == "artifact_created" and len(videos) == 1):
+            continue
+        output.append(shared_native_value(event))
+    return output

package/server/interactive_chat_projection.py

@@ -0,0 +1,152 @@
+"""Incremental, bounded text-only chat projection; no server imports or timers."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import stat
+import threading
+from typing import Callable
+
+from public_chat_transcript import (
+    MAX_LINE_BYTES, MAX_LOG_BYTES, MAX_MESSAGE_BYTES, MAX_MESSAGES,
+    MAX_RECORDS, MAX_TEXT_BYTES, PublicTranscriptError,
+    _is_goal_followup, _public_timestamp,
+)
+
+
+class IncrementalChatTranscript:
+    """Use one fresh privacy projector for the lifetime of an append-only log.
+
+    The owner must discard this reader after a known history rewrite or privacy
+    projection change. Stat checks detect replacement, truncation and same-size
+    changes; no incremental reader can prove an earlier prefix was not changed
+    in place while also growing without rereading that prefix.
+    """
+
+    def __init__(self, path: Path, projector: Callable[[dict], dict | None]):
+        self.path = Path(path)
+        self.projector = projector
+        self._lock = threading.Lock()
+        self._stamp = None
+        self._offset = 0
+        self._revision = 0
+        self._records = 0
+        self._total_text = 0
+        self._messages: list[dict] = []
+        self._outputs: dict[str, list[str]] = {}
+        self._failed = False
+
+    def _snapshot(self) -> dict:
+        return {"messages": [dict(message) for message in self._messages],
+                "through_bytes": self._offset, "revision": str(self._revision)}
+
+    @staticmethod
+    def _file_stamp(value):
+        return (value.st_dev, value.st_ino, value.st_size, value.st_mtime_ns, value.st_ctime_ns)
+
+    def load(self) -> dict:
+        """Read only new complete records; a detected error requires a new reader."""
+        with self._lock:
+            if self._failed:
+                raise PublicTranscriptError("Chat history changed; reopen the conversation")
+            try:
+                return self._load()
+            except Exception as exc:
+                # The supplied projector has private state and cannot be rolled
+                # back after a partially consumed bad page. Never reuse it.
+                self._failed = True
+                if isinstance(exc, PublicTranscriptError):
+                    raise
+                raise PublicTranscriptError("Chat history is unavailable") from exc
+
+    def _load(self) -> dict:
+        try:
+            fd = os.open(self.path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+        except FileNotFoundError:
+            if self._stamp is None:
+                return self._snapshot()
+            raise PublicTranscriptError("Chat history changed; reopen the conversation") from None
+        with os.fdopen(fd, "rb") as stream:
+            initial = os.fstat(stream.fileno())
+            if not stat.S_ISREG(initial.st_mode):
+                raise PublicTranscriptError("Chat history is unavailable")
+            stamp = self._file_stamp(initial)
+            if initial.st_size > MAX_LOG_BYTES:
+                raise PublicTranscriptError("Chat exceeds the 64 MiB sharing limit")
+            if self._stamp is not None:
+                if (stamp[:2] != self._stamp[:2] or stamp[2] < self._stamp[2]
+                        or stamp[2] == self._stamp[2] and stamp[3:] != self._stamp[3:]):
+                    raise PublicTranscriptError("Chat history changed; reopen the conversation")
+                if stamp == self._stamp:
+                    return self._snapshot()
+            stream.seek(self._offset)
+            while self._offset < initial.st_size:
+                line = stream.readline(min(MAX_LINE_BYTES + 1, initial.st_size - self._offset))
+                if len(line) > MAX_LINE_BYTES:
+                    raise PublicTranscriptError("A chat record exceeds the sharing limit")
+                if not line.endswith(b"\n"):
+                    break  # Re-read this uncommitted tail only after it grows.
+                self._offset += len(line)
+                self._records += 1
+                if self._records > MAX_RECORDS:
+                    raise PublicTranscriptError("Chat exceeds the sharing record limit")
+                try:
+                    raw = json.loads(line)
+                except (ValueError, UnicodeError, RecursionError) as exc:
+                    raise PublicTranscriptError("Chat history contains an unreadable record") from exc
+                if not isinstance(raw, dict) or not isinstance(raw.get("type"), str):
+                    raise PublicTranscriptError("Chat history contains an invalid event")
+                self._consume(raw)
+            final = os.fstat(stream.fileno())
+            current = self.path.stat(follow_symlinks=False)
+            if (not stat.S_ISREG(current.st_mode)
+                    or (current.st_dev, current.st_ino) != stamp[:2]
+                    or final.st_size < initial.st_size
+                    or final.st_size == initial.st_size and self._file_stamp(final)[3:] != stamp[3:]):
+                raise PublicTranscriptError("Chat history changed; reopen the conversation")
+            # Save the boundary actually read, not a later concurrent append.
+            self._stamp = stamp
+        return self._snapshot()
+
+    def _consume(self, raw: dict) -> None:
+        kind = raw["type"]
+        if kind not in {"turn_started", "assistant_text", "turn_finished", "reasoning_summary"} and not _is_goal_followup(raw):
+            return
+        if kind == "reasoning_summary" and raw.get("phase") != "commentary":
+            return
+        event = self.projector(raw)
+        if not event:
+            return
+        if not isinstance(event, dict):
+            raise PublicTranscriptError("Chat history projection is invalid")
+        run = str(event.get("run_id") or "")
+        if kind == "turn_started" or _is_goal_followup(event):
+            self._outputs[run] = []
+            role, text = "user", event.get("prompt")
+        else:
+            role = "assistant"
+            text = event.get("result_text") if kind == "turn_finished" else event.get("text")
+        if not isinstance(text, str) or not text.strip():
+            return
+        try:
+            size = len(text.encode("utf-8"))
+        except UnicodeEncodeError as exc:
+            raise PublicTranscriptError("Chat history contains invalid Unicode text") from exc
+        if size > MAX_MESSAGE_BYTES:
+            raise PublicTranscriptError("A message exceeds the 256 KiB sharing limit")
+        normalized = " ".join(text.split())
+        previous = self._outputs.setdefault(run, [])
+        if kind == "turn_finished" and (normalized in previous or normalized == " ".join(previous)):
+            return
+        if kind == "assistant_text":
+            previous.append(normalized)
+        self._total_text += size
+        if self._total_text > MAX_TEXT_BYTES or len(self._messages) >= MAX_MESSAGES:
+            raise PublicTranscriptError("Chat exceeds the 1,000-message / 2 MiB sharing limit")
+        message = {"role": role, "text": text}
+        timestamp = _public_timestamp(event.get("ts"))
+        if timestamp is not None:
+            message["timestamp"] = timestamp
+        self._messages.append(message)
+        self._revision = self._offset

package/server/interactive_chat_runtime.py

@@ -0,0 +1,132 @@
+"""Demand-driven live projections for open shared-chat pages, never a poller."""
+from __future__ import annotations
+
+import asyncio
+from collections import OrderedDict
+from dataclasses import dataclass, field
+import secrets
+
+from public_chat_transcript import PublicTranscriptError
+
+
+@dataclass
+class _OpenChat:
+    reader: object
+    generation: int = 0
+    identity: str = field(default_factory=lambda: secrets.token_hex(8))
+    lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    waiters: set = field(default_factory=set)
+    reset_reader: bool = False
+
+    @property
+    def revision(self):
+        return f"{self.identity}:{self.generation}"
+
+
+class InteractiveChatLiveState:
+    """One bounded incremental reader per recently viewed chat.
+
+    The existing event hub calls notify synchronously. It does only an O(1)
+    lookup for unrelated chats and never reads disk, sends a socket, or waits
+    for a guest while the owner's event delivery lock is held.
+    """
+
+    def __init__(self, reader_factory, session_exists, public_state=None, *, max_cached=16, native_snapshot=None):
+        self.reader_factory = reader_factory
+        self.session_exists = session_exists
+        self.public_state = public_state
+        self.native_snapshot = native_snapshot
+        self.max_cached = max_cached
+        self.entries = OrderedDict()
+
+    def notify(self, session_id, event):
+        entry = self.entries.get(session_id)
+        if entry is None:
+            return
+        kind = event.get("type", "")
+        if not isinstance(kind, str):
+            return
+        if self.native_snapshot is None and not (
+            kind in {"turn_started", "turn_finished", "turn_stopped", "turn_steered",
+                     "assistant_text", "history_imported", "history_reconciled", "session_deleted", "turn_unqueued"}
+            or kind.startswith("turn_queue")
+            or kind == "reasoning_summary" and event.get("phase") == "commentary"
+        ):
+            return
+        if kind in {"history_reconciled", "history_imported"}:
+            # Existing bytes can acquire stricter provenance without changing
+            # their size. Rebuild only when a viewer next asks for the text.
+            entry.reset_reader = True
+            if self.native_snapshot is not None:
+                # The native renderer must replace an older history prefix,
+                # not merge repaired same-ID events into a stale generation.
+                entry.identity = secrets.token_hex(8)
+        entry.generation += 1
+        for waiter in tuple(entry.waiters):
+            if not waiter.done():
+                waiter.set_result(True)
+
+    async def load(self, session_id):
+        if not self.session_exists(session_id):
+            raise PublicTranscriptError("Chat is unavailable")
+        entry = self.entries.get(session_id)
+        if entry is None:
+            if len(self.entries) >= self.max_cached:
+                candidate = next((key for key, item in self.entries.items()
+                                  if not item.waiters and not item.lock.locked()), None)
+                if candidate is None:
+                    raise PublicTranscriptError("Shared chat viewers are busy; retry shortly")
+                self.entries.pop(candidate)
+            entry = _OpenChat(None if self.native_snapshot is not None else self.reader_factory(session_id))
+            self.entries[session_id] = entry
+        self.entries.move_to_end(session_id)
+        async with entry.lock:
+            if entry.reset_reader:
+                if self.native_snapshot is None:
+                    entry.reader = self.reader_factory(session_id)
+                entry.reset_reader = False
+            # Capture before I/O: a concurrent append then makes wait() return
+            # immediately, closing the initial snapshot-to-subscription gap.
+            revision = entry.revision
+            # Native views need tool/progress/settings/approval updates too;
+            # notify still performs no I/O and unopened chats have no entry.
+            task = asyncio.create_task(self.native_snapshot(session_id) if self.native_snapshot is not None
+                else asyncio.to_thread(entry.reader.load))
+            try:
+                snapshot = await asyncio.shield(task)
+            except asyncio.CancelledError:
+                # Do not release the reader's lock while its thread is alive.
+                while not task.done():
+                    try:
+                        await asyncio.shield(task)
+                    except asyncio.CancelledError:
+                        continue
+                    except Exception:
+                        break
+                if not task.cancelled():
+                    task.exception()
+                raise
+            except Exception:
+                self.entries.pop(session_id, None)
+                raise
+            if not self.session_exists(session_id):
+                self.entries.pop(session_id, None)
+                raise PublicTranscriptError("Chat is unavailable")
+            if self.native_snapshot is not None:
+                return {**snapshot, "revision": revision}
+            state = self.public_state(session_id)
+            return {"messages": [*snapshot["messages"], *state.get("queued", [])],
+                    "revision": revision, "busy": state.get("busy") is True}
+
+    async def wait(self, session_id, revision, timeout):
+        entry = self.entries.get(session_id)
+        if entry is None or entry.revision != revision:
+            return True
+        waiter = asyncio.get_running_loop().create_future()
+        entry.waiters.add(waiter)
+        try:
+            return await asyncio.wait_for(waiter, timeout=timeout)
+        except asyncio.TimeoutError:
+            return False
+        finally:
+            entry.waiters.discard(waiter)