token-runtime 0.1.0a2__py3-none-any.whl

token_runtime/capabilities.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from .compatibility import CompatibilityRecord, CompatibilityRegistry
+
+
+UnknownBool = bool | Literal["unknown"]
+
+
+@dataclass(frozen=True, order=True, slots=True)
+class CapabilityKey:
+    client_family: str
+    protocol_family: str
+    provider_family: str
+    model_family: str | None = None
+    client_version: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class CapabilityProfile:
+    key: CapabilityKey
+    context_window_semantics: str = "unknown"
+    tokenizer_family: str = "unknown"
+    prompt_cache: str = "unknown"
+    server_cache: str = "unknown"
+    stateful_sessions: UnknownBool = "unknown"
+    native_context_management: UnknownBool = "unknown"
+    structured_output: UnknownBool = "unknown"
+    tool_calls: UnknownBool = "unknown"
+    multimodal: UnknownBool = "unknown"
+    reasoning_state: str = "unknown"
+    streaming: UnknownBool = "unknown"
+    exact_byte_preservation: UnknownBool = "unknown"
+    evidence_id: str = "unknown"
+
+    def to_primitive(self) -> dict[str, object]:
+        key: dict[str, object] = {
+            "client_family": self.key.client_family,
+            "protocol_family": self.key.protocol_family,
+            "provider_family": self.key.provider_family,
+            "model_family": self.key.model_family,
+        }
+        if self.key.client_version:
+            key["client_version"] = self.key.client_version
+        return {
+            "key": key,
+            "context_window_semantics": self.context_window_semantics,
+            "tokenizer_family": self.tokenizer_family,
+            "prompt_cache": self.prompt_cache,
+            "server_cache": self.server_cache,
+            "stateful_sessions": self.stateful_sessions,
+            "native_context_management": self.native_context_management,
+            "structured_output": self.structured_output,
+            "tool_calls": self.tool_calls,
+            "multimodal": self.multimodal,
+            "reasoning_state": self.reasoning_state,
+            "streaming": self.streaming,
+            "exact_byte_preservation": self.exact_byte_preservation,
+            "evidence_id": self.evidence_id,
+        }
+
+
+class DuplicateCapabilityError(ValueError):
+    pass
+
+
+class CapabilityRegistry:
+    def __init__(self) -> None:
+        self._profiles: dict[CapabilityKey, CapabilityProfile] = {}
+
+    def register(self, profile: CapabilityProfile) -> CapabilityProfile:
+        existing = self._profiles.get(profile.key)
+        if existing is None:
+            self._profiles[profile.key] = profile
+            return profile
+        if existing == profile:
+            return existing
+        raise DuplicateCapabilityError(f"conflicting capability profile: {profile.key!r}")
+
+    def get(self, key: CapabilityKey) -> CapabilityProfile | None:
+        return self._profiles.get(key)
+
+    def snapshot(self) -> tuple[CapabilityProfile, ...]:
+        return tuple(self._profiles[key] for key in sorted(self._profiles))
+
+
+@dataclass(frozen=True, slots=True)
+class CapabilityDetection:
+    key: CapabilityKey
+    profile: CapabilityProfile | None
+    compatibility: "CompatibilityRecord"
+
+
+class CapabilityDetector:
+    def __init__(
+        self,
+        capabilities: CapabilityRegistry,
+        compatibility: "CompatibilityRegistry",
+    ) -> None:
+        self.capabilities = capabilities
+        self.compatibility = compatibility
+
+    def detect(self, key: CapabilityKey) -> CapabilityDetection:
+        return CapabilityDetection(
+            key=key,
+            profile=self.capabilities.get(key),
+            compatibility=self.compatibility.get(key),
+        )

token_runtime/cli.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+import argparse
+import io
+import json
+from pathlib import Path
+import socket
+import sys
+import tempfile
+from urllib.parse import urlparse
+
+from .benchmark import BenchmarkCase, benchmark_cases
+from .config import (
+    TokenConfig,
+    default_config_path,
+    default_state_dir,
+    load_config,
+    save_config,
+)
+from .engine import OptimizationEngine
+from .gateway import GatewayCore, serve
+from .integrations import (
+    apply_plan,
+    detect_integrations,
+    plan_install,
+    uninstall_integration,
+)
+from .metrics import MetricsStore
+from .model import ContextBlock, RequestEnvelope
+from .planner import ContextPlanner
+from .store import RecoveryStore
+from .terminal_ui import render_welcome
+
+
+def _add_config_argument(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--config", default=None)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="token")
+    subs = parser.add_subparsers(dest="command")
+    for name in ("serve", "status", "doctor"):
+        sub = subs.add_parser(name)
+        _add_config_argument(sub)
+
+    optimize = subs.add_parser("optimize")
+    _add_config_argument(optimize)
+    optimize.add_argument("--endpoint", default="/v1/responses")
+
+    benchmark = subs.add_parser("benchmark")
+    _add_config_argument(benchmark)
+    benchmark.add_argument("--file", default=None)
+
+    install = subs.add_parser("install")
+    _add_config_argument(install)
+    install.add_argument("--root", default=None)
+    install.add_argument("--upstream", default=None)
+    install.add_argument("--dry-run", action="store_true")
+
+    uninstall = subs.add_parser("uninstall")
+    _add_config_argument(uninstall)
+    uninstall.add_argument("--root", default=None)
+    uninstall.add_argument("--dry-run", action="store_true")
+
+    return parser
+
+
+def _config_path(value: str | None) -> Path:
+    return Path(value) if value else default_config_path()
+
+
+def _runtime(config):
+    state = Path(config.state_dir)
+    state.mkdir(parents=True, exist_ok=True)
+    metrics = MetricsStore(state / "metrics.db")
+    engine = OptimizationEngine(
+        planner=ContextPlanner(),
+        store=RecoveryStore(state / "recovery.db"),
+    )
+    return GatewayCore(engine=engine, metrics=metrics), metrics
+
+
+def _read_input_bytes(stdin) -> bytes:
+    if hasattr(stdin, "buffer"):
+        return stdin.buffer.read()
+    value = stdin.read()
+    return value.encode("utf-8") if isinstance(value, str) else value
+
+def _reachable(host: str, port: int, timeout: float = 0.5) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+def doctor_report(config_path: Path) -> dict[str, bool]:
+    report = {
+        "config_ok": False,
+        "state_ok": False,
+        "gateway_reachable": False,
+        "upstream_reachable": False,
+    }
+    config = load_config(config_path)
+    report["config_ok"] = True
+
+    state = Path(config.state_dir)
+    try:
+        state.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(dir=state):
+            pass
+        RecoveryStore(state / "recovery.db")
+        MetricsStore(state / "metrics.db")
+        report["state_ok"] = True
+    except OSError:
+        return report
+
+    report["gateway_reachable"] = _reachable(config.host, config.port)
+    parsed = urlparse(config.upstream)
+    upstream_port = parsed.port or (443 if parsed.scheme == "https" else 80)
+    report["upstream_reachable"] = bool(parsed.hostname) and _reachable(
+        parsed.hostname, upstream_port
+    )
+    return report
+
+def _write_json(stdout, value) -> None:
+    stdout.write(json.dumps(value, sort_keys=True) + "\n")
+
+
+def _root_path(value: str | None) -> Path:
+    return Path(value).expanduser() if value else Path.home()
+
+
+def _install_config(path: Path, args, root: Path) -> TokenConfig:
+    if path.exists():
+        return load_config(path)
+    if not args.upstream:
+        raise FileNotFoundError("TOKEN config is missing; pass --upstream to bootstrap it")
+    config = TokenConfig(
+        upstream=args.upstream,
+        host="127.0.0.1",
+        port=8788,
+        state_dir=str(default_state_dir(root)),
+    )
+    if not args.dry_run:
+        save_config(config, path)
+    return config
+
+
+def _load_benchmark_cases(path: str | Path) -> list[BenchmarkCase]:
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(data, dict) or not isinstance(data.get("cases"), list):
+        raise ValueError("benchmark file must contain a cases array")
+    cases: list[BenchmarkCase] = []
+    for index, item in enumerate(data["cases"]):
+        if not isinstance(item, dict) or not isinstance(item.get("blocks"), list):
+            raise ValueError(f"benchmark case {index} is invalid")
+        blocks = []
+        for block_index, raw in enumerate(item["blocks"]):
+            if not isinstance(raw, dict):
+                raise ValueError(f"benchmark block {index}:{block_index} is invalid")
+            blocks.append(ContextBlock(
+                id=str(raw.get("id", f"b{block_index}")),
+                kind=str(raw["kind"]),
+                text=str(raw["text"]),
+                role=raw.get("role"),
+                turn_index=int(raw.get("turn_index", 0)),
+            ))
+        cases.append(BenchmarkCase(str(item.get("name", f"case-{index}")), RequestEnvelope(tuple(blocks))))
+    return cases
+
+
+def main(argv=None, *, stdin=None, stdout=None) -> int:
+    args = build_parser().parse_args(argv)
+    stdin = sys.stdin if stdin is None else stdin
+    stdout = sys.stdout if stdout is None else stdout
+    if args.command is None:
+        render_welcome(stdout)
+        return 0
+    path = _config_path(args.config)
+
+    if args.command == "install":
+        root = _root_path(args.root)
+        config = _install_config(path, args, root)
+        gateway_url = f"http://{config.host}:{config.port}/v1"
+        integrations = detect_integrations(root)
+        rows = []
+        active = sidecars = blocked = 0
+        for integration in integrations:
+            plan = plan_install(integration, gateway_url=gateway_url)
+            result = apply_plan(plan, apply=not args.dry_run)
+            activation = "managed_gateway" if plan.mode in {"managed_block", "managed_toml"} else "detected_sidecar_only"
+            if not plan.safe_to_apply:
+                blocked += 1
+            elif not args.dry_run and activation == "managed_gateway":
+                active += 1
+            elif not args.dry_run:
+                sidecars += 1
+            rows.append({
+                "kind": integration.kind,
+                "activation": activation,
+                "changed": result.changed,
+                "reason": result.reason,
+                "target": str(result.target_path),
+            })
+        _write_json(stdout, {
+            "mode": "dry_run" if args.dry_run else "apply",
+            "detected": len(integrations),
+            "applied": active,
+            "sidecars": sidecars,
+            "blocked": blocked,
+            "integrations": rows,
+        })
+        return 1 if blocked else 0
+
+    if args.command == "uninstall":
+        root = _root_path(args.root)
+        integrations = detect_integrations(root)
+        rows = []
+        removed = 0
+        for integration in integrations:
+            result = uninstall_integration(integration, apply=not args.dry_run)
+            if not args.dry_run and result.changed:
+                removed += 1
+            rows.append({
+                "kind": integration.kind,
+                "changed": result.changed,
+                "reason": result.reason,
+                "target": str(result.target_path),
+            })
+        _write_json(stdout, {
+            "mode": "dry_run" if args.dry_run else "apply",
+            "detected": len(integrations),
+            "removed": removed,
+            "integrations": rows,
+        })
+        return 0
+
+    config = load_config(path)
+    if args.command == "serve":
+        core, _ = _runtime(config)
+        serve(config.host, config.port, upstream=config.upstream, core=core)
+        return 0
+    if args.command == "status":
+        _, metrics = _runtime(config)
+        _write_json(stdout, metrics.summary())
+        return 0
+    if args.command == "doctor":
+        report = doctor_report(path)
+        _write_json(stdout, report)
+        return 0 if all(report.values()) else 1
+    if args.command == "optimize":
+        core, _ = _runtime(config)
+        prepared = core.prepare(args.endpoint, _read_input_bytes(stdin))
+        stdout.write(prepared.body.decode("utf-8", errors="surrogateescape"))
+        return 0
+    if args.command == "benchmark":
+        if not args.file:
+            raise ValueError("benchmark requires --file")
+        core, _ = _runtime(config)
+        report = benchmark_cases(_load_benchmark_cases(args.file), core.engine)
+        all_fidelity = all(row.protected_byte_fidelity == 1.0 for row in report.cases)
+        all_recoverable = all(row.recoverable for row in report.cases)
+        _write_json(stdout, {
+            "baseline_estimated_tokens": report.baseline_estimated_tokens,
+            "optimized_estimated_tokens": report.optimized_estimated_tokens,
+            "total_saved_pct": report.total_saved_pct,
+            "eligible_saved_pct": report.eligible_saved_pct,
+            "optimized_count": report.optimized_count,
+            "bypass_count": report.bypass_count,
+            "all_protected_fidelity": all_fidelity,
+            "all_recoverable": all_recoverable,
+            "offline_gate": bool(report.eligible_saved_pct >= 20 and all_fidelity and all_recoverable),
+            "cases": [{
+                "name": row.name,
+                "decision": row.decision,
+                "saved_pct": row.saved_pct,
+                "reasons": row.reasons,
+                "protected_byte_fidelity": row.protected_byte_fidelity,
+                "recoverable": row.recoverable,
+            } for row in report.cases],
+        })
+        return 0
+    return 2

token_runtime/codex_recertification.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .capabilities import CapabilityDetector, CapabilityKey, CapabilityProfile, CapabilityRegistry
+from .compatibility import CompatibilityRecord, CompatibilityRegistry, CompatibilityState
+from .openai_certification import CertificationEvidence
+
+
+CODEX_01540_RESPONSES_KEY = CapabilityKey(
+    "codex",
+    "responses",
+    "openai-compatible",
+    client_version="0.154.0",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class CodexRecertArea:
+    area: str
+    state: CompatibilityState
+    evidence_id: str
+    reason: str
+
+    def to_primitive(self) -> dict[str, str]:
+        return {
+            "area": self.area,
+            "state": self.state.value,
+            "evidence_id": self.evidence_id,
+            "reason": self.reason,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class Codex01540RecertificationBundle:
+    profile: CapabilityProfile
+    record: CompatibilityRecord
+    evidence: CertificationEvidence
+    areas: tuple[CodexRecertArea, ...]
+    detector: CapabilityDetector
+
+    def to_primitive(self) -> dict[str, object]:
+        return {
+            "profile": self.profile.to_primitive(),
+            "record": {
+                "state": self.record.state.value,
+                "evidence_id": self.record.evidence_id,
+                "reason": self.record.reason,
+            },
+            "evidence": self.evidence.to_primitive(),
+            "areas": [item.to_primitive() for item in self.areas],
+        }
+
+
+def _area(area: str, state: CompatibilityState, reason: str) -> CodexRecertArea:
+    return CodexRecertArea(
+        area=area,
+        state=state,
+        evidence_id="token-codex-01540-recert-1",
+        reason=reason,
+    )
+
+
+def build_codex_01540_recertification() -> Codex01540RecertificationBundle:
+    evidence = CertificationEvidence(
+        evidence_id="token-codex-01540-recert-1:responses-boundary",
+        version_scope="codex-cli-0.154.0",
+        scope="codex-responses/request-response-boundary",
+        assertion_ids=(
+            "exact-binary-checksum",
+            "responses-direct-loopback",
+            "responses-via-token-loopback",
+            "responses-request-byte-replay",
+            "cached-token-response-byte-fidelity",
+            "resume-history-continuity",
+            "fork-history-continuity",
+        ),
+    )
+    profile = CapabilityProfile(
+        key=CODEX_01540_RESPONSES_KEY,
+        tool_calls=True,
+        reasoning_state="opaque-preserved",
+        streaming=True,
+        exact_byte_preservation=True,
+        evidence_id=evidence.evidence_id,
+    )
+    record = CompatibilityRecord(
+        key=CODEX_01540_RESPONSES_KEY,
+        state=CompatibilityState.CERTIFIED,
+        evidence_id=evidence.evidence_id,
+        reason="request_boundary_certified",
+    )
+    capabilities = CapabilityRegistry()
+    compatibility = CompatibilityRegistry()
+    capabilities.register(profile)
+    compatibility.register(record)
+    areas = (
+        _area("responses_request_fidelity", CompatibilityState.CERTIFIED, "exact_loopback_replay"),
+        _area("responses_response_fidelity", CompatibilityState.CERTIFIED, "opaque_stream_forwarding"),
+        _area("token_off_on_boundary", CompatibilityState.CERTIFIED, "exact_request_boundary_observed"),
+        _area("native_context_compaction", CompatibilityState.PASSTHROUGH_ONLY, "native_internal_state_not_observed_by_token"),
+        _area("authorization_across_compaction", CompatibilityState.PASSTHROUGH_ONLY, "native_authorization_state_not_observed_by_token"),
+        _area("resume_fork_continuity", CompatibilityState.CERTIFIED, "exact_cli_history_continuity_observed"),
+        _area("long_context_continuity", CompatibilityState.PASSTHROUGH_ONLY, "long_context_compaction_semantics_not_observed_end_to_end"),
+        _area("dynamic_plugin_skill_refresh", CompatibilityState.PASSTHROUGH_ONLY, "dynamic_session_capabilities_not_consumed_by_token"),
+        _area("mcp_oauth_rejected_no_replay", CompatibilityState.PASSTHROUGH_ONLY, "mcp_transport_outside_token_gateway_boundary"),
+        _area("prompt_server_cache_semantics", CompatibilityState.PASSTHROUGH_ONLY, "provider_cache_and_billing_not_observed_locally"),
+    )
+    return Codex01540RecertificationBundle(
+        profile=profile,
+        record=record,
+        evidence=evidence,
+        areas=areas,
+        detector=CapabilityDetector(capabilities, compatibility),
+    )