stata-code 0.6.4__tar.gz → 0.7.0__tar.gz

{stata_code-0.6.4 → stata_code-0.7.0}/CHANGELOG.md

@@ -6,6 +6,56 @@ to semver-major.minor for the result schema (see `SCHEMA.md` §6).
 
 ## Unreleased
 
+## 0.7.0 — 2026-05-30
+
+### Added
+
+- **Schema-compatible public session ids end to end.** Runner, pool, MCP,
+  and VS Code now accept the schema's `[A-Za-z0-9_-]+` session ids. Values
+  that Stata cannot use as frame names, such as `model-a` or `9abc`, are
+  mapped to deterministic private frame names internally while results and
+  session listings keep echoing the public id.
+- **Graph source attribution.** Captured graphs now receive best-effort
+  `source_command` / `source_line` metadata from the submitted code for
+  named graphs and unambiguous unnamed graph creation.
+- **VS Code pure formatter/session helpers.** Log/data-preview/matrix
+  formatting and session-id rules moved out of `extension.ts` into small
+  tested modules, reducing the monolithic extension entrypoint.
+- **Run-index pagination.** `list_runs` now accepts `offset` alongside
+  `limit` so agents can page through long run-bundle histories.
+
+### Fixed
+
+- **Release-version drift guard.** `scripts/check_versions.py` now checks
+  `vscode/package-lock.json` plus the Claude plugin marketplace manifests,
+  and has regression tests for those release surfaces.
+- **Pool invalid-request classification.** Worker-side `ValueError` and
+  `NotImplementedError` now propagate as caller errors instead of being
+  wrapped as `adapter_crash`.
+- **VS Code RunResult type drift.** The hand-written TypeScript type now
+  includes `origin` and nullable schema fields such as `stata.version` and
+  `stata_elapsed_ms`.
+- **Run-index `since` filtering.** Date-only and seconds-only `since`
+  values are normalized to canonical millisecond UTC before comparison, and
+  malformed values now raise a typed `since_invalid` error.
+- **Run-bundle manifest writes.** Manifest creation and post-run artifact
+  rewrites now use temp-file-and-rename writes with fsync so concurrent
+  `list_runs` readers do not observe torn JSON.
+- **Notebook repair hardening.** Cell edits now retain a compact summary of
+  outputs they clear, abort if the notebook is deleted between read and write,
+  repair fully-id'd pre-4.5 metadata, and expose malformed raw cell indices in
+  `notebook_outline`.
+
+## 0.6.5 — 2026-05-22
+
+### Fixed
+
+- **OpenAI tool-schema compatibility.** `notebook_locate` and
+  `notebook_insert_cell` no longer advertise top-level `oneOf` constraints in
+  their MCP input schemas. OpenAI rejects those schemas during tool
+  registration, while the server-side runtime guards still enforce the
+  "exactly one query/anchor" rules.
+
 ## 0.6.4 — 2026-05-21
 
 ### Added

{stata_code-0.6.4 → stata_code-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stata-code
-Version: 0.6.4
+Version: 0.7.0
 Summary: Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)
 Project-URL: Homepage, https://github.com/brycewang-stanford/stata-code
 Project-URL: Repository, https://github.com/brycewang-stanford/stata-code
@@ -263,6 +263,19 @@ When `stata-code-mcp` lives inside a project virtualenv (recommended for reprodu
 
 For `uvx`-only setups, set `"command": "uvx"` and `"args": ["--from", "stata-code", "stata-code-mcp"]`.
 
+#### MCP troubleshooting
+
+If `stata_run` reports `adapter_crash` with `worker emitted non-JSON: '\n'`,
+upgrade to `stata-code>=0.6.4`, then restart the MCP client so it launches a
+fresh server process. Also check that the client is resolving the expected
+`stata-code-mcp` binary; project virtualenv installs should use the absolute
+`.venv/bin/stata-code-mcp` path instead of relying on a global `PATH` entry.
+
+If an OpenAI-backed client reports `API Error: 400 Invalid schema for function
+'mcp__stata-code__notebook_insert_cell'` and mentions a top-level `oneOf`,
+upgrade to `stata-code>=0.6.5`, then restart the MCP client. Older server
+processes keep advertising the stale schema until they are restarted.
+
 The MCP server registers 15 tools:
 
 | Tool | Purpose |
@@ -281,7 +294,7 @@ The MCP server registers 15 tools:
 | `notebook_edit_cell` | Atomically replace one cell's source (preserves id, clears outputs) |
 | `notebook_insert_cell` | Insert a new cell with a fresh nbformat 4.5+ UUID |
 | `notebook_delete_cell` | Remove a cell by id |
-| `list_runs` | Query run-bundle manifests (filter by notebook / cell_id / session / since / ok) |
+| `list_runs` | Query run-bundle manifests (filter by notebook / cell_id / session / since / ok, page with limit / offset) |
 
 For modern MCP clients, these tools now return structured results through
 `structuredContent` with `outputSchema` metadata, while still keeping the
@@ -435,9 +448,9 @@ stata_code/
 
 - v1.0 result schema ([SCHEMA.md](SCHEMA.md))
 - `pystata`-based runner with native-typed `r()`, `e()`, and matrices
-- Multi-session via Stata frames
+- Multi-session via Stata frames (`session_id` accepts `[A-Za-z0-9_-]+`; ids such as `model-a` are mapped to private legal frame names internally while the public id is echoed back)
 - Per-line error attribution: line number, context, commands_executed
-- Graph capture: `png` / `svg` / `pdf` with ref store
+- Graph capture: `png` / `svg` / `pdf` with ref store and source-command attribution
 - Log truncation with ref store
 - Warning extraction: 5 categories + generic notes
 - 32-kind error taxonomy with canonical suggestions
@@ -446,7 +459,7 @@ stata_code/
 - Matrix size cap + `get_matrix(ref)` for large matrices (>10k cells)
 - Subprocess-backed hard timeout and cancellation for the public Python API and MCP server: `timeout_ms`, `cancel(session_id)`, and MCP `cancel_session`
 - Per-cell repair loop on `.ipynb` via `notebook_outline` / `notebook_get_cell` / `notebook_edit_cell` with optimistic-concurrency `expected_source` guards and `origin_cell_id` echo on `RunResult`
-- Persistent run bundles + `list_runs` query over `manifest.json` files (filter by cell / origin / session / since / ok)
+- Persistent run bundles + `list_runs` query over `manifest.json` files (filter by cell / origin / session / since / ok; page with limit / offset)
 - JSON Schema artifact auto-generated from `schema.py`: [`schema/run_result.schema.json`](schema/run_result.schema.json)
 - VS Code extension published to the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode): syntax highlighting, section outline/navigation, code-lens cell and section runners, sidebar (sessions / last result / run history / logs / graphs), status bar, completions, conservative variable rename, diagnostics, MCP child-process spawn
 - Clean-room license policy ([LICENSE-POLICY.md](LICENSE-POLICY.md))

{stata_code-0.6.4 → stata_code-0.7.0}/README.md

@@ -224,6 +224,19 @@ When `stata-code-mcp` lives inside a project virtualenv (recommended for reprodu
 
 For `uvx`-only setups, set `"command": "uvx"` and `"args": ["--from", "stata-code", "stata-code-mcp"]`.
 
+#### MCP troubleshooting
+
+If `stata_run` reports `adapter_crash` with `worker emitted non-JSON: '\n'`,
+upgrade to `stata-code>=0.6.4`, then restart the MCP client so it launches a
+fresh server process. Also check that the client is resolving the expected
+`stata-code-mcp` binary; project virtualenv installs should use the absolute
+`.venv/bin/stata-code-mcp` path instead of relying on a global `PATH` entry.
+
+If an OpenAI-backed client reports `API Error: 400 Invalid schema for function
+'mcp__stata-code__notebook_insert_cell'` and mentions a top-level `oneOf`,
+upgrade to `stata-code>=0.6.5`, then restart the MCP client. Older server
+processes keep advertising the stale schema until they are restarted.
+
 The MCP server registers 15 tools:
 
 | Tool | Purpose |
@@ -242,7 +255,7 @@ The MCP server registers 15 tools:
 | `notebook_edit_cell` | Atomically replace one cell's source (preserves id, clears outputs) |
 | `notebook_insert_cell` | Insert a new cell with a fresh nbformat 4.5+ UUID |
 | `notebook_delete_cell` | Remove a cell by id |
-| `list_runs` | Query run-bundle manifests (filter by notebook / cell_id / session / since / ok) |
+| `list_runs` | Query run-bundle manifests (filter by notebook / cell_id / session / since / ok, page with limit / offset) |
 
 For modern MCP clients, these tools now return structured results through
 `structuredContent` with `outputSchema` metadata, while still keeping the
@@ -396,9 +409,9 @@ stata_code/
 
 - v1.0 result schema ([SCHEMA.md](SCHEMA.md))
 - `pystata`-based runner with native-typed `r()`, `e()`, and matrices
-- Multi-session via Stata frames
+- Multi-session via Stata frames (`session_id` accepts `[A-Za-z0-9_-]+`; ids such as `model-a` are mapped to private legal frame names internally while the public id is echoed back)
 - Per-line error attribution: line number, context, commands_executed
-- Graph capture: `png` / `svg` / `pdf` with ref store
+- Graph capture: `png` / `svg` / `pdf` with ref store and source-command attribution
 - Log truncation with ref store
 - Warning extraction: 5 categories + generic notes
 - 32-kind error taxonomy with canonical suggestions
@@ -407,7 +420,7 @@ stata_code/
 - Matrix size cap + `get_matrix(ref)` for large matrices (>10k cells)
 - Subprocess-backed hard timeout and cancellation for the public Python API and MCP server: `timeout_ms`, `cancel(session_id)`, and MCP `cancel_session`
 - Per-cell repair loop on `.ipynb` via `notebook_outline` / `notebook_get_cell` / `notebook_edit_cell` with optimistic-concurrency `expected_source` guards and `origin_cell_id` echo on `RunResult`
-- Persistent run bundles + `list_runs` query over `manifest.json` files (filter by cell / origin / session / since / ok)
+- Persistent run bundles + `list_runs` query over `manifest.json` files (filter by cell / origin / session / since / ok; page with limit / offset)
 - JSON Schema artifact auto-generated from `schema.py`: [`schema/run_result.schema.json`](schema/run_result.schema.json)
 - VS Code extension published to the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode): syntax highlighting, section outline/navigation, code-lens cell and section runners, sidebar (sessions / last result / run history / logs / graphs), status bar, completions, conservative variable rename, diagnostics, MCP child-process spawn
 - Clean-room license policy ([LICENSE-POLICY.md](LICENSE-POLICY.md))

{stata_code-0.6.4 → stata_code-0.7.0}/SCHEMA.md

@@ -185,7 +185,7 @@ A failed execution sets `ok: false`, `rc != 0`, and populates `error`:
 | --- | --- | --- | --- |
 | `ok` | `bool` | yes | The authoritative success bit. Producers MUST keep `ok`, `rc`, and `error`-presence consistent. Consumers branch on `ok` first. |
 | `rc` | `int` | yes | Stata's `_rc` after the last user-submitted command (after any `capture` masking). `0` on success. Synthetic codes are negative: `-1` adapter crash, `-2` timeout, `-3` cancellation. |
-| `session_id` | `string` | yes | Defaults to `"main"`. MUST match `[A-Za-z0-9_:-]+`. The character `:` is reserved for future remote-prefixing (e.g., `host-7:main`), so v1 producers MUST NOT emit colons. |
+| `session_id` | `string` | yes | Defaults to `"main"`. MUST match `[A-Za-z0-9_-]+`. The character `:` is reserved for future remote-prefixing (e.g., `host-7:main`), so v1 producers MUST NOT emit colons. Producers may map ids that are not legal Stata frame names (for example `model-a` or `9abc`) to private frame names internally, but MUST echo the caller's `session_id` in the result. |
 | `request_id` | `string` | yes | Producer-generated, unique per call. Recommended format: ULID or UUIDv7 (sortable). Consumers use this for log correlation and `ref` lookup. |
 | `started_at` | `string` (ISO 8601 UTC) | yes | Timestamp at which the producer began handling the call, e.g. `"2026-04-30T14:22:08.123Z"`. Always UTC, always with millisecond precision. |
 | `elapsed_ms` | `int` | yes | Wall-clock duration of the call, in milliseconds. Minimum reported value is `1`; sub-millisecond calls round up. |
@@ -326,7 +326,7 @@ A summary of the active Stata frame *after* the command ran. Always populated.
 
 | Field | Type | Notes |
 | --- | --- | --- |
-| `frame` | `string` | Active frame name. Stata's master frame is named `"default"`. ⚠ Note this is unrelated to `session_id == "main"`. |
+| `frame` | `string` | Active Stata frame name. Stata's master frame is named `"default"`. For session ids that are not legal Stata frame names, this may be a private generated frame name. ⚠ Note this is unrelated to `session_id == "main"`. |
 | `n_obs` | `int` | `_N`. |
 | `n_vars` | `int` | `c(k)`. |
 | `changed` | `bool` | `c(changed)`. ⚠ Stata sets this on *any* dataset-touching command, including no-op replaces — treat as a "may be dirty" hint, not a guarantee. |
@@ -481,7 +481,7 @@ The schema also dictates what callers may *ask for*. Every frontend exposes the
 | Option | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `code` | `string` | — | The Stata code to run. |
-| `session_id` | `string` | `"main"` | Routes to a named persistent session. Pattern: `[A-Za-z0-9_-]+` (no colons in v1). |
+| `session_id` | `string` | `"main"` | Routes to a named persistent session. Pattern: `[A-Za-z0-9_-]+` (no colons in v1). The public id is stable even when the backend maps it to a private Stata frame name. |
 | `log_lines_head` | `int` | `20` | Lines to retain at the start of `log.head`. `0` disables. |
 | `log_lines_tail` | `int` | `20` | Lines to retain at the end of `log.tail`. `0` disables. |
 | `include_full_log` | `bool` | `false` | If `true`, the full log is placed inline in `log.head` regardless of size; `truncated: false`, `ref: null`. Use when token budget is generous and follow-up calls are expensive. |
@@ -514,7 +514,7 @@ The schema implies a small set of follow-up calls. Frontends expose them under c
 | `list_sessions()` | Enumerate live sessions. | `[{session_id, started_at, last_used_at, n_obs}, ...]` |
 | `reset_session(session_id?)` | Hard-reset a session (`clear all`). Invalidates all refs scoped to it. | `Result` with the cleared state. |
 | `stata_info()` | Report installed Stata. | `{stata: {...}, available: bool, capabilities: [...]}` |
-| `list_runs(log_dir or origin_path, cell_id?, session_id?, ok?, since?, limit?)` | Read-only query over persisted run-bundle manifests. Returns newest-first compact summaries of prior runs that landed under `<origin dir>/log-files/`. | `{log_dir, scanned_count, match_count, skipped_count, limit, truncated, runs: [...]}` |
+| `list_runs(log_dir or origin_path, cell_id?, session_id?, ok?, since?, limit?, offset?)` | Read-only query over persisted run-bundle manifests. Returns newest-first compact summaries of prior runs that landed under `<origin dir>/log-files/`. `since` accepts canonical millisecond UTC plus common date/seconds shorthands; `offset` pages through matches. | `{log_dir, scanned_count, match_count, skipped_count, limit, offset, truncated, runs: [...]}` |
 
 These are *additions* to `run()`. A minimal client only needs `run()` plus whichever auxiliaries match the truncation/ref behavior the producer can emit.
 
@@ -610,8 +610,9 @@ This section tracks how much of the schema is wired up in code. Not normative
 - `dataset` block — `n_obs`, `n_vars`, `frame`, `changed`, `filename`,
   and `variables` (capped at 200 entries).
 - `graphs[]` with `ref` + on-disk capture pipeline; format restricted to
-  `png` / `svg` / `pdf`; PNG `width` / `height` parsed from IHDR.
-  `inline` populated when `include_graphs="inline"`.
+  `png` / `svg` / `pdf`; PNG `width` / `height` parsed from IHDR;
+  best-effort `source_command` / `source_line` attribution from the
+  submitted code. `inline` populated when `include_graphs="inline"`.
 - Structured `error` — 32-kind enum, `varname` / `path` / `name`
   extracted from Stata's English error text by regex, structured
   `context` (`{before, failing, after}`), `commands_executed` parsed
@@ -620,7 +621,9 @@ This section tracks how much of the schema is wired up in code. Not normative
 - `request_id` (uuid4 hex), `started_at` (ISO 8601 UTC ms),
   `stata_elapsed_ms`, `capabilities`.
 - Multi-session via Stata frames — `session_id="main"` ↔ `default`
-  frame; other ids create / route to same-named frames.
+  frame; other ids create / route to same-named frames when Stata allows
+  it, or deterministic private frame names when the public id needs
+  mapping.
 - `Warning` is `{kind, message}`; five built-in patterns
   (`omitted_collinear`, `convergence`, `singular`, `boundary`, generic
   `note`) + dedup.

{stata_code-0.6.4 → stata_code-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stata-code"
-version = "0.6.4"
+version = "0.7.0"
 description = "Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)"
 readme = "README.md"
 license = "MIT"

{stata_code-0.6.4 → stata_code-0.7.0}/scripts/check_versions.py

@@ -32,7 +32,7 @@ def _tag_version(tag: str) -> str:
 
 def main() -> int:
     parser = argparse.ArgumentParser(
-        description="Check pyproject/Python/MCP/VS Code version literals."
+        description="Check Python, MCP, VS Code, and plugin version literals."
     )
     parser.add_argument(
         "--tag",
@@ -40,6 +40,10 @@ def main() -> int:
     )
     args = parser.parse_args()
 
+    vscode_lock = json.loads(_read("vscode/package-lock.json"))
+    plugin_manifest = json.loads(_read(".claude-plugin/plugin.json"))
+    marketplace_manifest = json.loads(_read(".claude-plugin/marketplace.json"))
+
     versions = {
         "pyproject.toml": _extract(
             "pyproject.toml", r'(?m)^\s*version\s*=\s*"([^"]+)"'
@@ -51,7 +55,18 @@ def main() -> int:
             "stata_code/mcp/server.py", r'(?m)^__version__\s*=\s*"([^"]+)"'
         ),
         "vscode/package.json": json.loads(_read("vscode/package.json"))["version"],
+        "vscode/package-lock.json": vscode_lock["version"],
+        "vscode/package-lock.json packages['']": vscode_lock["packages"][""]["version"],
+        ".claude-plugin/plugin.json": plugin_manifest["version"],
+        ".claude-plugin/marketplace.json metadata": marketplace_manifest["metadata"][
+            "version"
+        ],
     }
+    for idx, plugin in enumerate(marketplace_manifest.get("plugins", [])):
+        if isinstance(plugin, dict) and "version" in plugin:
+            versions[f".claude-plugin/marketplace.json plugins[{idx}]"] = plugin[
+                "version"
+            ]
 
     # mcpClient.ts used to carry a literal version; we now resolve it at
     # build time via ``import { version } from "../package.json"``. If the

{stata_code-0.6.4 → stata_code-0.7.0}/stata_code/__init__.py

@@ -174,7 +174,7 @@ def is_available() -> bool:
     return True
 
 
-__version__ = "0.6.4"
+__version__ = "0.7.0"
 
 __all__ = [
     # Primary entry points

{stata_code-0.6.4 → stata_code-0.7.0}/stata_code/core/_pool.py

@@ -235,11 +235,19 @@ def _worker_main() -> int:
                 }
             else:
                 response = {"id": req_id, "ok": False, "error": f"unknown op: {op}"}
+        except (ValueError, NotImplementedError) as exc:
+            response = {
+                "id": req_id,
+                "ok": False,
+                "error": f"{type(exc).__name__}: {exc}",
+                "error_kind": "invalid_request",
+            }
         except Exception as exc:  # noqa: BLE001
             response = {
                 "id": req_id,
                 "ok": False,
                 "error": f"{type(exc).__name__}: {exc}",
+                "error_kind": "worker_error",
             }
         proto_out.write(json.dumps(response) + "\n")
         proto_out.flush()
@@ -354,6 +362,8 @@ class WorkerProcess:
                     f"worker response id mismatch: expected {req_id}, got {response.get('id')}"
                 )
             if not response.get("ok"):
+                if response.get("error_kind") == "invalid_request":
+                    raise ValueError(response.get("error", "<no error>"))
                 raise _WorkerError(
                     f"worker reported failure: {response.get('error', '<no error>')}"
                 )
@@ -478,6 +488,8 @@ class WorkerProcess:
                     f"worker response id mismatch: expected {req_id}, got {response.get('id')}"
                 )
             if not response.get("ok"):
+                if response.get("error_kind") == "invalid_request":
+                    raise ValueError(response.get("error", "<no error>"))
                 raise _WorkerError(
                     f"worker reported failure: {response.get('error', '<no error>')}"
                 )

{stata_code-0.6.4 → stata_code-0.7.0}/stata_code/core/log_artifacts.py

@@ -6,6 +6,7 @@ import json
 import os
 import re
 import shutil
+import tempfile
 import uuid
 from datetime import datetime, timezone
 from pathlib import Path
@@ -13,6 +14,50 @@ from typing import Any
 
 from stata_code.core.schema import LogFileInfo, StataInfo
 
+
+def _atomic_write_text(path: Path, text: str) -> None:
+    """Write ``text`` to ``path`` atomically (temp file + rename in same dir).
+
+    The bytes are flushed and ``fsync``'d before the rename so a reader — the
+    run index scans ``manifest.json`` concurrently with new runs — never
+    observes a torn or half-written file. ``update_run_artifact_manifest`` also
+    rewrites the manifest in place after graphs/outputs are copied; doing that
+    non-atomically risked a partial JSON that ``list_runs`` would skip.
+    """
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".tmp", dir=str(path.parent)
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(text)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp_name, path)
+        _fsync_directory(path.parent)
+    except Exception:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+
+
+def _fsync_directory(directory: Path) -> None:
+    """Best-effort durability for the rename entry itself."""
+    flags = os.O_RDONLY
+    if hasattr(os, "O_DIRECTORY"):
+        flags |= os.O_DIRECTORY
+    try:
+        fd = os.open(directory, flags)
+    except OSError:
+        return
+    try:
+        os.fsync(fd)
+    except OSError:
+        pass
+    finally:
+        os.close(fd)
+
 _SAFE_PART_RE = re.compile(r"[^A-Za-z0-9._-]+")
 _MAX_OUTPUT_ARTIFACT_BYTES = 50 * 1024 * 1024
 _OUTPUT_EXTENSIONS = {
@@ -128,7 +173,8 @@ def persist_run_log_files(
         policy="per_run_directory",
         append=False,
     )
-    manifest_path.write_text(
+    _atomic_write_text(
+        manifest_path,
         json.dumps(
             _manifest(
                 info=info,
@@ -151,7 +197,6 @@ def persist_run_log_files(
             sort_keys=True,
         )
         + "\n",
-        encoding="utf-8",
     )
     return info
 
@@ -280,9 +325,9 @@ def update_run_artifact_manifest(info: LogFileInfo) -> None:
         }
     )
     manifest["working_dir"] = info.working_dir
-    manifest_path.write_text(
+    _atomic_write_text(
+        manifest_path,
         json.dumps(manifest, indent=2, sort_keys=True) + "\n",
-        encoding="utf-8",
     )
 
 
@@ -453,4 +498,3 @@ def _unique_file(path: Path) -> Path:
     raise FileExistsError(
         f"could not allocate unique artifact path under {path.parent}"
     )
-