agentacct 0.2.0__tar.gz → 0.3.0__tar.gz

{agentacct-0.2.0/src/agentacct.egg-info → agentacct-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentacct
-Version: 0.2.0
+Version: 0.3.0
 Summary: Local-first Agent Work Intelligence for coding agents: usage truth, recorded work, and honest joins
 Author: mikehasa
 License-Expression: MIT

{agentacct-0.2.0 → agentacct-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentacct"
-version = "0.2.0"
+version = "0.3.0"
 description = "Local-first Agent Work Intelligence for coding agents: usage truth, recorded work, and honest joins"
 readme = "README.md"
 requires-python = ">=3.11"

{agentacct-0.2.0 → agentacct-0.3.0}/src/agent_chronicle/agent_capabilities.py

@@ -193,6 +193,15 @@ _OPENCODE_USAGE_FIXTURE = _verification(
         "tests/test_client_usage.py::test_discover_opencode_usage_reads_json_event_stream_tokens_and_cost",
     ),
 )
+_OPENCODE_DB_FIXTURE = _verification(
+    "synthetic_fixture",
+    verified_at="2026-07-29",
+    evidence_refs=(
+        "tests/test_client_usage.py::test_discover_opencode_usage_reads_native_session_db",
+        "tests/test_client_usage.py::test_discover_opencode_usage_recomputes_cost_from_tokens_when_stored_zero",
+        "tests/test_client_usage.py::test_discover_opencode_usage_presence_flags_track_schema_columns",
+    ),
+)
 _OPENCLAW_USAGE_FIXTURE = _verification(
     "synthetic_fixture",
     verified_at="2026-07-17",
@@ -439,8 +448,8 @@ _CLIENTS: tuple[dict[str, Any], ...] = (
         "client": "opencode",
         "display_name": "OpenCode",
         "roadmap_phase": "phase_1",
-        "source_formats": ["captured/exported JSON event stream"],
-        "session_scope": "Usage-bearing step-finish exports only.",
+        "source_formats": ["native opencode.db SQLite session rollup", "captured/exported JSON event stream"],
+        "session_scope": "Usage-bearing session rollups (SQLite) or step-finish exports.",
         "zero_usage_observation": "unavailable",
         "namespace_hardening": "not_hardened",
         "verified_stability": _stability(
@@ -453,19 +462,22 @@ _CLIENTS: tuple[dict[str, Any], ...] = (
         "capabilities": {
             "session_discovery": _capability(
                 "experimental",
-                "Session IDs found in captured/exported JSON step-finish streams.",
+                "Session IDs from the native opencode.db session rollup, or captured/exported JSON step-finish streams as a fallback.",
                 activation="opt_in_project",
-                verification=_OPENCODE_USAGE_FIXTURE,
-                limitations=("The official SQLite store is detected but not imported; zero-token sessions are absent.",),
+                verification=_OPENCODE_DB_FIXTURE,
+                limitations=("Only usage-bearing sessions are emitted; zero-token sessions are absent.",),
             ),
             "usage_import": _capability(
                 "experimental",
-                "Input, output, reasoning, cache, and client cost from exported step-finish rows.",
+                "Per-session input, output, reasoning, and cache token totals from the native SQLite session rollup (JSON export fallback); cost recomputed from tokens when the store records none.",
                 activation="opt_in_project",
-                verification=_OPENCODE_USAGE_FIXTURE,
-                limitations=("Synthetic happy-path fixture only; malformed/schema-drift diagnostics are incomplete.",),
+                verification=_OPENCODE_DB_FIXTURE,
+                limitations=(
+                    "Synthetic-fixture only; per-message granularity is not imported (session totals only).",
+                    "OpenCode usually stores cost 0, so cost is typically estimated_from_tokens; a nonzero stored cost is kept as client_reported.",
+                ),
                 usage_basis="client_reported",
-                cost_basis="client_reported",
+                cost_basis="estimated_from_tokens",
             ),
             "mechanical_capture": _unavailable("No realtime OpenCode plugin adapter is implemented."),
             "mcp_semantics": _capability(
@@ -477,9 +489,10 @@ _CLIENTS: tuple[dict[str, Any], ...] = (
             ),
             "model_attribution": _capability(
                 "experimental",
-                "First model-like field found in a captured JSON export.",
+                "Model id and provider id parsed from the session rollup's model JSON (JSON-export model field as fallback).",
                 activation="opt_in_project",
-                limitations=("No fixture asserts model extraction; model is not bound to each step-finish row.",),
+                verification=_OPENCODE_DB_FIXTURE,
+                limitations=("Per-message model binding is not imported; the session rollup carries one model per session.",),
             ),
             "cache_read": _capability(
                 "experimental",
@@ -501,7 +514,7 @@ _CLIENTS: tuple[dict[str, Any], ...] = (
                 "agentacct renders the setup command but does not write OpenCode user config or install a plugin."
             ),
         },
-        "limitations": ["Remain experimental until real fixtures, namespace hardening, and official SQLite parsing exist."],
+        "limitations": ["Remain experimental until real-client fixtures, namespace hardening, and per-message SQLite granularity exist."],
     },
     {
         "client": "openclaw",

{agentacct-0.2.0 → agentacct-0.3.0}/src/agent_chronicle/canonical/legacy_import.py

@@ -75,6 +75,7 @@ _LEGACY_CUMULATIVE_USAGE_SEMANTICS = frozenset(
         CODEX_LINEAGE_DELTA_SEMANTICS,
         "claude_assistant_message_usage_rows",
         "opencode_step_finish_events",
+        "opencode_session_rollup",
         "hermes_state_db_session_rows",
         "openclaw_assistant_usage_rows",
     }

{agentacct-0.2.0 → agentacct-0.3.0}/src/agent_chronicle/canonical/product_parity.py

@@ -670,6 +670,7 @@ _SOURCE_CUMULATIVE_USAGE_SEMANTICS = frozenset(
         "codex_sqlite_tokens_used_fallback",
         "claude_assistant_message_usage_rows",
         "opencode_step_finish_events",
+        "opencode_session_rollup",
         "hermes_state_db_session_rows",
         "openclaw_assistant_usage_rows",
     }

{agentacct-0.2.0 → agentacct-0.3.0}/src/agent_chronicle/cli.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import errno
 import hashlib
 import json
 import math
@@ -7,6 +8,7 @@ import os
 import shlex
 import shutil
 import signal
+import socket
 import stat
 import sys
 import tempfile
@@ -112,7 +114,7 @@ from .hooks import (
 from .log_evidence import build_log_evidence_index, summarize_log_evidence_donor_rows
 from . import install_guide
 from .install_guide import full_prompt as install_guide_full_prompt, one_line_prompt as install_guide_one_line_prompt
-from .mcp import TOOLS, SentinelMCPServer, run_mcp_event_workflow_smoke, serve_stdio
+from .mcp import DEGRADED_NO_STORE_MESSAGE, TOOLS, SentinelMCPServer, run_mcp_event_workflow_smoke, serve_stdio
 from .mcp_client_smoke import MCPClientSmokeError, assert_deepseek_mcp_client_smoke_passed, run_deepseek_mcp_client_smoke
 from .outcome import (
     apply_judge_result,
@@ -949,11 +951,34 @@ def _print_codex_mcp_setup(config_store_dir: Path | str, *, command: str = "agen
     print(_codex_mcp_toml_block(config_store_dir, command=command).rstrip())
 
 
+def _print_stale_registration_remediation(agent: str) -> None:
+    """Tell the user to remove any leftover pre-rename server before adding agentacct.
+
+    A registration left over from the ``agent-sentinel`` / ``agent-chronicle``
+    era points at a command name that no longer ships (only ``agentacct`` does),
+    so the host tries to launch a missing binary — an ENOENT that reads to the
+    client as a crashed MCP server. Removing the dead entry first is the fix.
+    """
+    console.print(
+        "First remove any stale pre-rename server — a leftover agent-sentinel/agent-chronicle "
+        "entry launches a command that no longer exists (ENOENT), which the client reports as a crash:"
+    )
+    if agent == "generic":
+        console.print(
+            "In the agent's MCP config, delete any server named 'agent-sentinel' or 'agent-chronicle' "
+            "(only 'agentacct' ships now), then add the definition below."
+        )
+        return
+    print(f"{agent} mcp remove agent-sentinel")
+    print(f"{agent} mcp remove agent-chronicle")
+
+
 def _print_agent_mcp_preview(agent: str, config_store_dir: Path | str, *, command: str = "agentacct") -> None:
     quoted_store_dir = shlex.quote(str(config_store_dir))
     quoted_command = shlex.quote(command)
     if agent == "generic":
         console.print("Generic MCP-capable agent")
+        _print_stale_registration_remediation(agent)
         console.print("Use this stdio MCP server definition in the agent's project-local MCP config:")
         print(_claude_mcp_json(config_store_dir, command=command).rstrip())
         console.print("Command form:")
@@ -962,16 +987,19 @@ def _print_agent_mcp_preview(agent: str, config_store_dir: Path | str, *, comman
     if agent == "hermes":
         console.print("Hermes")
         console.print("Hermes manages MCP servers in the active Hermes profile, not in this repo.")
+        _print_stale_registration_remediation(agent)
         console.print("Copy/paste command:")
         print(f"hermes mcp add agentacct --command {quoted_command} --args mcp serve --store-dir {quoted_store_dir}")
         return
     if agent == "opencode":
         console.print("OpenCode")
+        _print_stale_registration_remediation(agent)
         console.print("Copy/paste command:")
         print(f"opencode mcp add agentacct -- {quoted_command} mcp serve --store-dir {quoted_store_dir}")
         return
     if agent == "openclaw":
         console.print("OpenClaw")
+        _print_stale_registration_remediation(agent)
         console.print("Copy/paste command:")
         print(
             "openclaw mcp add agentacct "
@@ -1233,7 +1261,7 @@ def onboard(
                 )
             elif opencode_row is not None:
                 console.print(
-                    "OpenCode native database parsing is pending; current OpenCode import requires captured/exported JSON."
+                    "OpenCode was detected but no single importable store resolved; ensure one home holds an opencode.db session store (or exported JSON) and select it with `--opencode-home`."
                 )
         else:
             console.print("No readable known local usage source was found.")
@@ -3235,15 +3263,31 @@ def mcp_serve(
     """Serve agentacct MCP tools over stdio.
 
     This exposes safe report/outcome/value primitives and does not call paid judge APIs.
-    Store resolution is strict: the MCP client controls this process's cwd, so a
-    visibly failed server beats a silently wrong ledger.
+    Store resolution stays strict — the MCP client controls this process's cwd,
+    so a silently wrong ledger is never acceptable — but a server that EXITS reads
+    to the host as a crash. So an unresolvable store starts a degraded-but-connected
+    session instead: initialize and tools/list still answer, recording tools return
+    a legible "no store configured" error, and no store is ever silently created.
     """
+    # As an MCP server this process's exit is the ONLY liveness signal the host
+    # has: an exit at startup reads as a crash. So an unresolvable store must
+    # NOT exit — it starts a degraded-but-connected session (initialize +
+    # tools/list still answer; recording tools return a legible error). We still
+    # never silently create or pick a store (honesty rule): degraded_reason is
+    # set and no store path is resolved.
+    resolved: Path | None = None
+    degraded_reason: str | None = None
     if store_dir is None:
         try:
             resolved = resolve_store_dir(None).path
         except StoreResolutionError as exc:
-            print(str(exc), file=sys.stderr)
-            raise typer.Exit(2) from exc
+            print(
+                f"agentacct mcp serve: {exc}\n"
+                "Starting a degraded MCP session (connected, but not recording): restart the server with "
+                f"--store-dir <absolute path> or set {ENV_STORE_DIR}=<absolute path>.",
+                file=sys.stderr,
+            )
+            degraded_reason = DEGRADED_NO_STORE_MESSAGE
     else:
         expanded = store_dir.expanduser()
         if expanded.is_absolute():
@@ -3258,7 +3302,7 @@ def mcp_serve(
             # named the store, which beats a dead server.
             try:
                 resolution = resolve_store_dir(None, env={})
-            except StoreResolutionError as exc:
+            except StoreResolutionError:
                 try:
                     env_value = store_env_dir_value(os.environ) or ""
                 except StoreResolutionError:
@@ -3284,13 +3328,19 @@ def mcp_serve(
                         )
                     print(
                         "Fix: re-run `agentacct setup mcp --agent <claude-code|codex> --write` in the project root to "
-                        f"write an absolute store path into the MCP config, or set {ENV_STORE_DIR}=<absolute path>.",
+                        f"write an absolute store path into the MCP config, or set {ENV_STORE_DIR}=<absolute path>. "
+                        "Starting a degraded MCP session (connected, but not recording) until then.",
                         file=sys.stderr,
                     )
-                    raise typer.Exit(2) from exc
+                    degraded_reason = DEGRADED_NO_STORE_MESSAGE
             else:
                 anchor = resolution.project_root if resolution.project_root is not None else resolution.path.parent.parent
                 resolved = anchor / expanded
+    if degraded_reason is not None:
+        # No resolvable store: stay connected but refuse to record. serve_stdio
+        # gets store_dir=None so it never constructs (or creates) a store.
+        serve_stdio(store_dir=None, degraded_reason=degraded_reason)
+        return
     print(f"agentacct mcp serve: store={resolved}", file=sys.stderr)
     serve_stdio(store_dir=resolved)
 
@@ -8006,8 +8056,55 @@ def usage_truth_table_command(
         console.print(f"- {row['integration']}: {row['setup_path']}")
 
 
+_SERVE_PORT_FALLBACK_SPAN = 20
+"""How many ports past the default the dashboard probes before giving up."""
+
+
+def _probe_port_free(host: str, port: int) -> bool:
+    """Return True if ``(host, port)`` can be bound right now.
+
+    Mirrors uvicorn's own socket setup (``SO_REUSEADDR``) so the probe reflects
+    what the server will attempt a moment later. There is an unavoidable TOCTOU
+    window between this check and uvicorn's bind, but for a localhost dashboard
+    the practical risk is negligible.
+    """
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            sock.bind((host, port))
+        except OSError:
+            return False
+    return True
+
+
+def _select_serve_port(
+    host: str,
+    port: int,
+    *,
+    allow_fallback: bool,
+    max_offset: int = _SERVE_PORT_FALLBACK_SPAN,
+) -> int:
+    """Pick a bindable port for the local dashboard.
+
+    When ``allow_fallback`` is False (the user passed an explicit ``--port``) the
+    requested port must be free or an ``OSError`` is raised so the caller can
+    fail with an actionable message. When True (the default-port path) a busy
+    port advances through ``port+1 .. port+max_offset`` and the first free port is
+    returned; ``OSError`` is raised only if the whole range is occupied.
+    """
+    if _probe_port_free(host, port):
+        return port
+    if not allow_fallback:
+        raise OSError(errno.EADDRINUSE, f"port {port} is already in use")
+    for candidate in range(port + 1, port + max_offset + 1):
+        if _probe_port_free(host, candidate):
+            return candidate
+    raise OSError(errno.EADDRINUSE, f"no free port in range {port}-{port + max_offset}")
+
+
 @app.command("serve")
 def serve(
+    ctx: typer.Context,
     host: Annotated[str, typer.Option(help="Bind host. Default is 127.0.0.1 for local dashboard safety.")] = "127.0.0.1",
     port: Annotated[int, typer.Option(help="Bind port for the local dashboard and event API.")] = 8765,
     store_dir: Annotated[
@@ -8016,7 +8113,13 @@ def serve(
     ] = None,
     allow_host: Annotated[Optional[list[str]], typer.Option("--allow-host", help=_ALLOW_HOST_HELP)] = None,
 ) -> None:
-    """Serve the local dashboard on localhost with local usage discovery enabled."""
+    """Serve the local dashboard on localhost with local usage discovery enabled.
+
+    The default port (8765) auto-advances to the next free port when it is busy,
+    so the dashboard never fails to start just because a port is taken. An
+    explicit ``--port`` is honored strictly: if that exact port is occupied the
+    command fails rather than silently moving.
+    """
     import uvicorn
 
     if host not in {"127.0.0.1", "localhost"}:
@@ -8026,7 +8129,29 @@ def serve(
     # not a server crash mid-startup.
     resolution = _resolve_dashboard_cli_store_dir(store_dir)
     effective_store_dir = resolution.path
-    console.print(f"Starting agentacct dashboard: http://{host}:{port}")
+    # Only auto-advance when the port came from the default; an explicit --port
+    # is a specific request and must fail loudly instead of moving. Compare the
+    # click ParameterSource by name -- typer's runtime enum is not identical to
+    # click.core's, so identity/value comparisons are unreliable across versions.
+    port_source = ctx.get_parameter_source("port")
+    port_explicitly_set = getattr(port_source, "name", "DEFAULT") != "DEFAULT"
+    try:
+        bound_port = _select_serve_port(host, port, allow_fallback=not port_explicitly_set)
+    except OSError:
+        if port_explicitly_set:
+            console.print(
+                f"Port {port} is already in use. Pass a free --port, or omit --port to let "
+                "agentacct pick the next free port automatically."
+            )
+        else:
+            console.print(
+                f"Ports {port}-{port + _SERVE_PORT_FALLBACK_SPAN} are all in use. "
+                "Free one up or pass an explicit --port."
+            )
+        raise typer.Exit(1)
+    if bound_port != port:
+        console.print(f"Port {port} was busy; dashboard on http://{host}:{bound_port}")
+    console.print(f"Starting agentacct dashboard: http://{host}:{bound_port}")
     if resolution.source == "global":
         console.print("Dashboard scope: All projects (machine-wide store).")
         _warn_dashboard_mcp_store_shadow(effective_store_dir)
@@ -8045,7 +8170,7 @@ def serve(
             extra_allowed_hosts=tuple(allow_host or ()),
         ),
         host=host,
-        port=port,
+        port=bound_port,
         log_level="info",
     )