capsule-engine 0.1.0__py3-none-any.whl

capsule_engine/console/server.py

@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`capsule console`'s local HTTP server.
+
+stdlib `http.server` only -- no new dependency (see pyproject.toml).
+Single-threaded on purpose: `LedgerStore`'s sqlite3 connection is opened
+once at server startup and is not safe to share across request threads, and
+a local, single-operator console has no concurrency requirement that would
+justify the complication. Binds to localhost by default.
+
+Serves the static console UI -- this directory's own `tokens.css` /
+`components.css` (the same component-library files the gallery uses, never
+re-invented here) plus `console.css` / `console.js` / `console.html` -- and
+a small JSON API over the real `LedgerAPI` (`api.py` in this package).
+
+LOCAL ONLY: no hosted anything, no account system. Every response is
+derived live from the ledger on disk; nothing here calls out to a network.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+import urllib.parse
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+
+from cll.ledger.store import LedgerStore
+
+from . import api
+
+__all__ = ["ConsoleServer", "build_server"]
+
+_STATIC_DIR = Path(__file__).resolve().parent
+_STATIC_FILES = {
+    "/": ("console.html", "text/html; charset=utf-8"),
+    "/console.html": ("console.html", "text/html; charset=utf-8"),
+    "/console.css": ("console.css", "text/css; charset=utf-8"),
+    "/console.js": ("console.js", "application/javascript; charset=utf-8"),
+    "/tokens.css": ("tokens.css", "text/css; charset=utf-8"),
+    "/components.css": ("components.css", "text/css; charset=utf-8"),
+}
+
+
+class ConsoleRequestHandler(BaseHTTPRequestHandler):
+    server_version = "CapsuleConsole/0.1"
+
+    def log_message(self, fmt: str, *args: object) -> None:
+        pass  # the CLI already echoed the one line that matters at startup
+
+    def _send_json(self, payload: dict, status: int = 200) -> None:
+        body = json.dumps(payload, sort_keys=True).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _send_static(self, filename: str, content_type: str) -> None:
+        body = (_STATIC_DIR / filename).read_bytes()
+        self.send_response(200)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self) -> None:  # noqa: N802 (stdlib method name)
+        parsed = urllib.parse.urlsplit(self.path)
+        path = parsed.path
+        query = {k: v[0] for k, v in urllib.parse.parse_qs(parsed.query).items()}
+        store: LedgerStore = self.server.store
+
+        if path in _STATIC_FILES:
+            filename, content_type = _STATIC_FILES[path]
+            self._send_static(filename, content_type)
+            return
+
+        if path == "/api/checkpoint":
+            self._send_json(api.checkpoint_status(store))
+            return
+
+        if path == "/api/records":
+            filters = {
+                "agent": query.get("agent") or None,
+                "since": query.get("since") or None,
+                "until": query.get("until") or None,
+                "counterparty": query.get("counterparty") or None,
+                "verdict": query.get("verdict") or None,
+                "action_type": query.get("action_type") or None,
+                "limit": int(query["limit"]) if query.get("limit") else None,
+            }
+            self._send_json(api.list_records(store, filters))
+            return
+
+        if path.startswith("/api/records/"):
+            capsule_id = urllib.parse.unquote(path[len("/api/records/") :])
+            detail = api.record_detail(store, capsule_id)
+            if detail is None:
+                self._send_json({"error": f"no such capsule {capsule_id!r}"}, status=404)
+                return
+            self._send_json(detail)
+            return
+
+        self.send_error(404, "not found")
+
+
+class ConsoleServer(HTTPServer):
+    """Single-threaded (see module docstring). Owns the `LedgerStore` it was
+    built with and any throwaway import directory, closing/removing both on
+    `server_close()`."""
+
+    def __init__(self, server_address: tuple[str, int], store: LedgerStore, cleanup_dir: Path | None = None):
+        super().__init__(server_address, ConsoleRequestHandler)
+        self.store = store
+        self._cleanup_dir = cleanup_dir
+
+    def server_close(self) -> None:
+        super().server_close()
+        self.store.close()
+        if self._cleanup_dir is not None:
+            shutil.rmtree(self._cleanup_dir, ignore_errors=True)
+
+
+def build_server(ledger_path: str, host: str = "127.0.0.1", port: int = 8420) -> ConsoleServer:
+    """Open `ledger_path` (a `LedgerStore` directory, or a JSONL fixture
+    imported once into a throwaway store -- the same convenience every
+    other ledger-backed verb offers via `cli/ledger_io.py`) and bind a
+    server to it. Does not start serving -- call `.serve_forever()`."""
+    p = Path(ledger_path)
+    if p.is_dir():
+        store = LedgerStore(p)
+        cleanup_dir = None
+    else:
+        cleanup_dir = Path(tempfile.mkdtemp(prefix="capsule-ledger-console-"))
+        store = LedgerStore(cleanup_dir)
+        store.import_jsonl(p)
+
+    return ConsoleServer((host, port), store=store, cleanup_dir=cleanup_dir)

capsule_engine/console/tokens.css

@@ -0,0 +1,68 @@
+/* SPDX-License-Identifier: Apache-2.0
+ *
+ * Design tokens for the capsule-ledger console, transcribed verbatim from
+ * its visual language spec (spec v1 · 2026-08-04, capsule format draft-02).
+ * Values are copied from that spec's inline styles, not approximated from a
+ * summary.
+ *
+ * No grays: every neutral in this system is warm (cream/bark/sand ladder).
+ * --asg-brick below is reserved for verification failure ONLY -- see
+ * components.css and the product-law tests in tests/test_console_*.py.
+ */
+
+:root {
+  /* -- color: surfaces -- */
+  --asg-cream: #FAF7F2;       /* default page bg (GC/light surfaces) */
+  --asg-warm-white: #FDF9F4;  /* cards */
+  --asg-desk: #EFE9DF;        /* page bg behind floating cards */
+  --asg-bark: #2C1A0E;        /* dark surface, primary text on light */
+  --asg-console-bg: #231409;  /* dark console page bg */
+
+  /* -- color: accent -- */
+  --asg-amber: #C8611A;       /* THE accent: CTAs, eyebrows, model-class marks */
+  --asg-amber-light: #E8844A; /* hover, amber-on-dark */
+
+  /* -- color: sage (deterministic class, refusals, positive signals) -- */
+  --asg-sage: #7A8C6E;
+  --asg-sage-light: #A8B89C;  /* on dark */
+
+  /* -- color: sand (hairlines/borders) -- */
+  --asg-sand: #E8D5B8;        /* hairlines/borders on light */
+  --asg-sand-dark: #D4BC96;
+
+  /* -- color: text -- */
+  --asg-text-body: #3D2B1F;
+  --asg-text-muted: #7A6355;  /* muted text (light) */
+  --asg-text-dark-1: #E8D5B8; /* text ladder on dark, brightest */
+  --asg-text-dark-2: #D4BC96;
+  --asg-text-dark-3: #A8927D; /* text ladder on dark, dimmest */
+
+  /* -- color: brick -- verification failure ONLY. Nothing else may use it. */
+  --asg-brick: #A93F2B;
+
+  /* -- typography -- */
+  --asg-font-display: 'Playfair Display', ui-serif, Georgia, serif;
+  --asg-font-sans: 'DM Sans', system-ui, -apple-system, sans-serif;
+  --asg-font-mono: 'DM Mono', ui-monospace, 'SF Mono', Consolas, monospace;
+
+  /* eyebrows: DM Sans 500/600, uppercase, letter-spacing 1.5-2.5px, 10-11px */
+  --asg-eyebrow-tracking: 2px;
+  --asg-eyebrow-size: 11px;
+
+  /* -- radii -- */
+  --asg-radius-pill: 100px;
+  --asg-radius-card-sm: 12px;
+  --asg-radius-card-lg: 16px;
+  --asg-radius-floating: 20px;
+  --asg-radius-chip: 6px;      /* 4-9px squares for class marks */
+
+  /* -- shadows: bark-tinted only -- */
+  --asg-shadow-floating-dark: 0 24px 64px rgba(44, 26, 14, 0.22);
+  --asg-shadow-floating-light: 0 24px 64px rgba(44, 26, 14, 0.10);
+  --asg-shadow-amber-button: 0 4px 16px rgba(200, 97, 26, 0.30);
+
+  /* -- motion -- */
+  --asg-ease: cubic-bezier(0.22, 1, 0.36, 1);
+  --asg-motion-hover: 200ms;
+  --asg-motion-msg-in: 400ms;
+}

capsule_engine/conversation/__init__.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The interim conversation-capsule profile (pre-VAC).
+
+Per-turn ``fyi`` capsules sealed AT TURN
+TIME (speaker role, turn-content digest -- never the content itself),
+chained turn-to-turn so there is no unsigned window between a turn
+happening and the ledger holding a signed record of it, plus one
+session-close capsule binding every turn's digest into a single session
+digest (Merkle-style, via ``capsule_emit.checkpoint`` -- the neutral CLL/MMR
+core capsule-ledger consumes rather than forks) for selective disclosure at
+TURN granularity.
+
+This is the interim, ledger-native shape -- it migrates to Verifiable
+Agent Conversations (Birkholz et al., COSE_Sign1 session records) once that
+cross-party coordination lands; the no-unsigned-window property this module
+establishes is itself a candidate contribution back to that draft, which
+today has no equivalent guarantee.
+
+Per-speaker judgment targeting (B3, the judge harness) reads
+``speaker_role`` off these turn capsules -- ``SPEAKER_ROLES`` is the
+complete, closed vocabulary a judge may target.
+
+Public surface:
+- ``build_turn_capsule`` / ``build_session_close_capsule`` -- pure capsule
+  builders (no ledger I/O), same layering as ``guards.capsule``.
+- ``build_turn_reference_capsule`` -- a typed cross-reference from a turn to
+  capsule(s) it gave rise to (e.g. a caller's own tool-call capsules),
+  resolved back via ``find_turn_reference``.
+- ``find_session_turns`` / ``find_session_close`` / ``find_turn_reference``
+  -- read a session (or a cross-reference) back off any ``LedgerAPI``.
+- ``session_root`` / ``turn_inclusion_proof`` / ``verify_turn_inclusion`` --
+  the Merkle session-digest primitives (``.merkle``).
+- ``ConversationSession`` -- the stateful recorder: seals and appends each
+  turn immediately, then ``close()``s the session.
+- ``build_conversation_exchange_capsule`` / ``digest_conversation_exchange``
+  -- one capsule per exchange, in the mesh inference capsule shape
+  (``model_attestation.compute_attestation`` with ``agent_input_digest``/
+  ``agent_output_digest`` plus the labeled ``reasoning_digest``/
+  ``tool_calls_digest`` sub-digests, ``.exchange``).
+"""
+from __future__ import annotations
+
+from .capsules import (
+    EVENT_CONVERSATION_TURN,
+    EVENT_SESSION_CLOSE,
+    EVENT_TURN_REFERENCE,
+    SPEAKER_ROLES,
+    InvalidSpeakerRole,
+    build_session_close_capsule,
+    build_turn_capsule,
+    build_turn_reference_capsule,
+    find_session_close,
+    find_session_turns,
+    find_turn_reference,
+)
+from .exchange import (
+    EVENT_CONVERSATION_EXCHANGE,
+    build_conversation_exchange_capsule,
+    build_usage,
+    digest_conversation_exchange,
+    stringify_floats,
+)
+from .merkle import session_root, turn_inclusion_proof, verify_turn_inclusion
+from .session import ConversationSession, SessionAlreadyClosedError
+
+__all__ = [
+    "SPEAKER_ROLES",
+    "EVENT_CONVERSATION_TURN",
+    "EVENT_SESSION_CLOSE",
+    "EVENT_TURN_REFERENCE",
+    "EVENT_CONVERSATION_EXCHANGE",
+    "InvalidSpeakerRole",
+    "build_turn_capsule",
+    "build_session_close_capsule",
+    "build_turn_reference_capsule",
+    "build_conversation_exchange_capsule",
+    "digest_conversation_exchange",
+    "build_usage",
+    "stringify_floats",
+    "find_session_turns",
+    "find_session_close",
+    "find_turn_reference",
+    "session_root",
+    "turn_inclusion_proof",
+    "verify_turn_inclusion",
+    "ConversationSession",
+    "SessionAlreadyClosedError",
+]

capsule_engine/conversation/capsules.py

@@ -0,0 +1,268 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Builders for the conversation-capsule profile's two record types:
+``conversation_turn`` (one per turn, sealed at turn time) and
+``conversation_session_close`` (one per session, binding every turn's
+digest into a single session digest).
+
+Both are passive ``fyi`` records -- built via ``events.capsule``'s
+``build_event_capsule``, the same mechanism this codebase already uses for
+degradation/recovery events and policy-manifest activations
+(``policy/activation.py``) -- so a conversation capsule is an ordinary,
+independently verifiable ledger record with no special-cased verification
+path, same as every other capsule this codebase produces.
+
+Record-type identity lives in ``asg_payload.event`` (never a repurposed
+spec-defined field, matching the workspace's extension-field rule) --
+``EVENT_CONVERSATION_TURN`` / ``EVENT_SESSION_CLOSE`` below, discovered via
+``find_session_turns`` / ``find_session_close``, the same linear-scan-plus-
+filter shape ``policy/activation.py``'s ``find_latest_activation`` uses.
+
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from agent_action_capsule.contracts import is_hex64
+from cll.ledger.api import LedgerAPI, ScanQuery
+from cll.ledger.records import LedgerRecord
+
+from ..events.capsule import build_event_capsule
+from ..guards.signing import Signer
+from .merkle import session_root
+
+__all__ = [
+    "SPEAKER_ROLES",
+    "EVENT_CONVERSATION_TURN",
+    "EVENT_SESSION_CLOSE",
+    "EVENT_TURN_REFERENCE",
+    "InvalidSpeakerRole",
+    "build_turn_capsule",
+    "build_session_close_capsule",
+    "build_turn_reference_capsule",
+    "find_session_turns",
+    "find_session_close",
+    "find_turn_reference",
+]
+
+# Interim speaker-role vocabulary (pre-VAC; migrates when the Birkholz VAC
+# binding lands). Deliberately CLOSED rather than registry-open: B3's
+# per-speaker judgment targeting depends on this exact set, so a typo'd
+# role must fail loud at seal time, not silently land as a fourth,
+# unaddressable role. Widen only alongside a B3 consumer that can target
+# the new value.
+SPEAKER_ROLES = frozenset({"user", "assistant", "human-agent"})
+
+EVENT_CONVERSATION_TURN = "conversation_turn"
+EVENT_SESSION_CLOSE = "conversation_session_close"
+EVENT_TURN_REFERENCE = "conversation_turn_reference"
+
+
+class InvalidSpeakerRole(ValueError):
+    """``speaker_role`` is not one of ``SPEAKER_ROLES``."""
+
+
+def _require_speaker_role(speaker_role: str) -> None:
+    if speaker_role not in SPEAKER_ROLES:
+        raise InvalidSpeakerRole(f"speaker_role must be one of {sorted(SPEAKER_ROLES)}; got {speaker_role!r}")
+
+
+def _require_content_digest(content_digest: str) -> None:
+    # The turn's own content never enters the record in any mode (H2
+    # invariant) -- only a digest of it, same 64-hex-SHA-256 shape every
+    # other digest field in this codebase requires.
+    if not is_hex64(content_digest):
+        raise ValueError(f"content_digest must be a 64-hex SHA-256 digest; got {content_digest!r}")
+
+
+def build_turn_capsule(
+    *,
+    session_id: str,
+    turn_index: int,
+    speaker_role: str,
+    content_digest: str,
+    operator: str,
+    developer: str,
+    signer: Signer,
+    previous_turn_capsule_id: str | None = None,
+    timestamp: str | None = None,
+    action_id: str | None = None,
+) -> dict:
+    """Seal one conversation turn as a passive ``fyi`` capsule, AT TURN TIME
+    -- every turn is signed and ready to append the moment it is built, so a
+    conversation never carries an unsigned window between what was said and
+    what the ledger can prove was said.
+
+    Turn 0 opens the session standalone (no chain parent); every later turn
+    chains to ``previous_turn_capsule_id`` with relation ``"follows"`` --
+    the same generic sequencing relation capsule-emit's emit path
+    (``capsule_emit.core``) defaults to for a non-adapter caller. None of the chain-relation
+    registry's seeded values (``confirms``/``supersedes``/``epoch_opens``)
+    describe "next turn in an ongoing conversation", so this deliberately
+    does not reach for one of them.
+    """
+    if turn_index < 0:
+        raise ValueError(f"turn_index must be >= 0; got {turn_index}")
+    if turn_index == 0:
+        if previous_turn_capsule_id is not None:
+            raise ValueError("turn_index=0 (the session's first turn) must not chain to a previous_turn_capsule_id")
+    elif previous_turn_capsule_id is None:
+        raise ValueError(f"turn_index={turn_index} requires previous_turn_capsule_id (only turn 0 is standalone)")
+
+    _require_speaker_role(speaker_role)
+    _require_content_digest(content_digest)
+
+    detail = {
+        "session_id": session_id,
+        "turn_index": turn_index,
+        "speaker_role": speaker_role,
+        "content_digest": content_digest,
+    }
+    return build_event_capsule(
+        operator=operator,
+        developer=developer,
+        signer=signer,
+        event=EVENT_CONVERSATION_TURN,
+        detail=detail,
+        timestamp=timestamp,
+        action_id=action_id or f"conversation.turn/{session_id}/{turn_index}",
+        chain_parent=previous_turn_capsule_id,
+        chain_relation="follows",
+    )
+
+
+def build_session_close_capsule(
+    *,
+    session_id: str,
+    turn_capsule_ids: Sequence[str],
+    operator: str,
+    developer: str,
+    signer: Signer,
+    timestamp: str | None = None,
+    action_id: str | None = None,
+) -> dict:
+    """Bind every turn in ``turn_capsule_ids`` (append order) into one
+    session digest -- an MMR root over the ordered turn capsule ids
+    (``merkle.session_root``) -- and seal that binding as one more ``fyi``
+    capsule chained to the last turn. This is what makes selective
+    disclosure at TURN granularity possible: a holder can later disclose
+    one turn's content plus a ``merkle.turn_inclusion_proof`` against this
+    capsule's ``session_digest``, without ever revealing the rest of the
+    session.
+
+    Requires at least one turn -- there is no such thing as an empty
+    session's completeness certificate.
+    """
+    if not turn_capsule_ids:
+        raise ValueError("turn_capsule_ids must be non-empty -- cannot close a session with zero turns")
+
+    digest = session_root(turn_capsule_ids)
+    detail = {
+        "session_id": session_id,
+        "turn_count": len(turn_capsule_ids),
+        "session_digest": digest,
+        "turn_capsule_ids": list(turn_capsule_ids),
+    }
+    return build_event_capsule(
+        operator=operator,
+        developer=developer,
+        signer=signer,
+        event=EVENT_SESSION_CLOSE,
+        detail=detail,
+        timestamp=timestamp,
+        action_id=action_id or f"conversation.session_close/{session_id}",
+        chain_parent=turn_capsule_ids[-1],
+        chain_relation="follows",
+    )
+
+
+def build_turn_reference_capsule(
+    *,
+    turn_capsule_id: str,
+    referenced_capsule_ids: Sequence[str],
+    operator: str,
+    developer: str,
+    signer: Signer,
+    timestamp: str | None = None,
+    action_id: str | None = None,
+) -> dict:
+    """A typed cross-reference from one turn to the capsule(s) it gave rise
+    to (e.g. tool-call capsules a caller's own pipeline recorded for that
+    turn) -- built via the same ``build_event_capsule`` every other passive
+    record in this module uses, not a new mechanism.
+
+    Chains to the turn with relation ``"confirms"`` (the reference only
+    makes sense once the turn it names already exists), so a caller that
+    already has ``turn_capsule_id`` from ``ConversationSession.record_turn``
+    can call this once per turn that produced one or more referenced
+    capsules -- letting a caller resolve any of those capsules back to the
+    turn that prompted it via ``find_turn_reference``, without requiring the
+    referenced capsule itself to carry the link (which is often built and
+    appended before the turn is even known -- e.g. a tool call dispatched
+    live, while the turn is only reconstructable after the fact from a full
+    trajectory).
+    """
+    if not referenced_capsule_ids:
+        raise ValueError("referenced_capsule_ids must be non-empty")
+
+    detail = {
+        "turn_capsule_id": turn_capsule_id,
+        "referenced_capsule_ids": list(referenced_capsule_ids),
+    }
+    return build_event_capsule(
+        operator=operator,
+        developer=developer,
+        signer=signer,
+        event=EVENT_TURN_REFERENCE,
+        detail=detail,
+        timestamp=timestamp,
+        action_id=action_id or f"conversation.turn_reference/{turn_capsule_id}",
+        chain_parent=turn_capsule_id,
+        chain_relation="confirms",
+    )
+
+
+def _matches(record: LedgerRecord, event: str, session_id: str) -> bool:
+    payload = record.capsule.get("asg_payload") or {}
+    if payload.get("event") != event:
+        return False
+    return (payload.get("detail") or {}).get("session_id") == session_id
+
+
+def find_session_turns(ledger: LedgerAPI, session_id: str) -> list[LedgerRecord]:
+    """Every turn capsule recorded for ``session_id``, sorted by
+    ``turn_index`` (not append order -- defensive against an out-of-order
+    replay/import; a live ``ConversationSession`` always appends in order).
+    """
+    matches = [r for r in ledger.scan(ScanQuery(action_type="fyi")) if _matches(r, EVENT_CONVERSATION_TURN, session_id)]
+    matches.sort(key=lambda r: (r.capsule.get("asg_payload") or {}).get("detail", {}).get("turn_index", 0))
+    return matches
+
+
+def find_session_close(ledger: LedgerAPI, session_id: str) -> LedgerRecord | None:
+    """The session-close capsule for ``session_id``, or ``None`` if the
+    session is still open (or never existed). ``scan()`` is append-ordered
+    and a session closes at most once, so the last match wins if more than
+    one is ever found (defensive; not an expected shape).
+    """
+    latest: LedgerRecord | None = None
+    for record in ledger.scan(ScanQuery(action_type="fyi")):
+        if _matches(record, EVENT_SESSION_CLOSE, session_id):
+            latest = record
+    return latest
+
+
+def find_turn_reference(ledger: LedgerAPI, capsule_id: str) -> LedgerRecord | None:
+    """The turn-reference capsule (if any) that names ``capsule_id`` among
+    its ``referenced_capsule_ids`` -- lets a caller resolve any capsule
+    (e.g. a tool-call capsule from an unrelated pipeline) back to the
+    conversation turn that gave rise to it. ``None`` if no such reference
+    was ever recorded.
+    """
+    for record in ledger.scan(ScanQuery(action_type="fyi")):
+        payload = record.capsule.get("asg_payload") or {}
+        if payload.get("event") != EVENT_TURN_REFERENCE:
+            continue
+        detail = payload.get("detail") or {}
+        if capsule_id in (detail.get("referenced_capsule_ids") or []):
+            return record
+    return None