mostlyright-data 0.27.1__tar.gz → 0.28.0__tar.gz

{mostlyright_data-0.27.1 → mostlyright_data-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.27.1
+Version: 0.28.0
 Summary: Mostly Right hosted CLI for reviewed datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/

{mostlyright_data-0.27.1 → mostlyright_data-0.28.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mostlyright-data"
-version = "0.27.1"
+version = "0.28.0"
 description = "Mostly Right hosted CLI for reviewed datasets"
 readme = "README.md"
 requires-python = ">=3.11"

{mostlyright_data-0.27.1 → mostlyright_data-0.28.0}/skills/mr-data-build/SKILL.md

@@ -14,10 +14,16 @@ references. Load the reference for the current stage only, not the entire librar
 1. Run `mr-data whoami --json` once. If authentication needs repair, read
    [authentication](references/cloud-authentication-preflight.md) and follow the reported action.
    Never print credentials or bypass their storage protection.
-2. Create the dataset once with `mr-data dataset create --name "Working title" --handoff --json`.
-   Keep its `dataset_id`. Link the stable `dashboard_url` in the first build message; open the
-   separate `navigation.url` in the host's visible browser if available. A missing handoff does
-   not undo creation: do not create a duplicate dataset.
+2. If the user handed you a `dataset_id` with the request, that dataset is the one: its page is
+   already open in their browser. Do not create another, do not run `mr-data open`, and put that
+   id in the recipe's `dataset.id`. Otherwise create the dataset once with
+   `mr-data dataset create --name "Working title" --handoff --json` and keep its `dataset_id`.
+   A create that answers `open_request_reused` made nothing: it found the dataset the user already
+   opened for this request, so build into that `dataset_id` and do not open it again; use
+   `--separate` only when the user asked for another dataset. After a real create, link the stable
+   `dashboard_url` in the first build message and open the separate `navigation.url` in the
+   host's visible browser if available. A missing handoff does not undo creation: do not create a
+   duplicate dataset.
 3. Settle purpose, row grain, tables, coverage, required sources and update cadence before
    dependent work. In an attended build, ask unresolved material questions in one concise message
    with recommended choices; recording an assumption is not asking the user. Default to one joined,

{mostlyright_data-0.27.1 → mostlyright_data-0.28.0}/skills/mr-data-build/references/1-open-the-page-and-the-link-to-it-in-the-first-message.md

@@ -1,5 +1,12 @@
 ### 1. Open — the page, and the link to it, in the first message
 
+**If the user handed you a `dataset_id` with the request, the page already exists and is open in
+their browser.** Skip this stage's create and do not open anything: hold that `dataset_id`, link its
+page once in the first message, and bind the recipe to it as `dataset.id`. The same holds when
+`dataset create` answers `open_request_reused`: it made nothing, its `navigation.url` is the plain
+page rather than a handoff, and `navigation.open_before_research` is false. If the quoted request is
+a different dataset from the one you are building, run `dataset create --separate` instead.
+
 Create the dataset from a working title and put it in front of whoever is watching, **before any
 source lookup**. This is the first command after the preflight — nothing reads a note, searches a
 catalog, opens a provider page or fetches a URL until it has returned:

{mostlyright_data-0.27.1 → mostlyright_data-0.28.0}/skills/mr-data-build/references/commands.md

@@ -11,7 +11,7 @@ gap rather than doing anything, and `export-hosted-candidate`, which is a backen
 | `mr-data clarify` | Check whether clarification is allowed. Use `--attended` for an active user chat and `--unattended` for a scheduled invocation; an explicit operator veto such as `MOSTLYRIGHT_ATTENDED=0` still wins. A non-TTY subprocess does not prove the user is absent. The command does not ask the person in chat or wait for a reply; the agent must do that. It exits non-zero when nobody can answer or the recipe is already registered. |
 | `mr-data probe` | `probe SOURCE_ID QUESTION_ID --dataset DATASET_ID [--kind source_inspect\|sample_rows\|profile_columns\|evaluate_expression]` asks one already-registered source one question and prints the answer. **Do not plan a source inspection around it.** Both positionals are identifiers — `QUESTION_ID` is a question identifier, which no v4 registration receipt returns — and the command rides the frozen `/v3/sessions` routes, which a deployment may have switched off. Read a source instead by registering the recipe and taking one run without `--window` under `--max-rows`, then `peek`, `query` and `receipt`. |
 | `mr-data catalog` | `catalog search "QUESTION"` asks the sealed public-source catalogue which of its entries might answer a question and ranks them best first. Every ranked entry comes back with the disposition its own facts earned — `admitted`, `human_escalation_required` or `refused` — because an entry the catalogue could not vouch for is still a finding. `--format csv` states the one data format the question requires — one token per question, never repeated — and it is not a filter: an entry that does not declare that format still comes back ranked, with disposition `refused` and `filters_match` false, so nothing is held back; `--limit N` ranks at most N, up to 25. It fetches nothing and registers nothing. The catalogue holds one provider (Data.gov) and only part of it, so it is never exhaustive and an empty answer is not evidence that no such source exists. When the answer is `catalog_unavailable`, this deployment has no catalogue to search: record the lane and carry on. |
-| `mr-data dataset` | Bring the dataset page into existence before there is anything on it, then fill it in while somebody watches. `dataset create --name TEXT` mints it and prints the `dataset_id`; `dataset show ID` reads it back; `dataset set ID --name TEXT --topics "a,b,c" --license ID --description-file F` writes the title, the descriptive tags, the SPDX licence and the description under the version it was read at, retrying once if somebody else wrote first, and an empty `--topics` or `--license` takes that value off the page; send `--name` and `--topics` whenever you send `--description-file`, because a description sent on its own can make Studio write a new title and new tags, and read `changed` and `written_by_studio` on the receipt for every field the write moved; a saved write whose public sync fails exits 2 and reports `public_projection_synced: false` — use `dataset sync ID` to retry that sync without rewriting Studio; `dataset note ID --heading H --blocks-file B` writes one cell of the decision record that OUTLIVES every run, and `--list` reads it back; `dataset watch ID` follows the page's own event stream; `dataset activity ID --phase P --message TEXT` says what is happening right now, silently, and is never a chat message and never a cell; `dataset publish ID [--mode public|link|private]` says who can read the dataset — `public` lists it in the public directory and serves it at an address anybody can read, `link` serves it at an unlisted address, `private` takes it back to the workspace — and `dataset publish ID --show` reads that back without changing it; `dataset archive ID --confirm-name TITLE` retires the page and frees its title, deleting nothing. |
+| `mr-data dataset` | Bring the dataset page into existence before there is anything on it, then fill it in while somebody watches. `dataset create --name TEXT` mints it and prints the `dataset_id`, unless the user's own request already has an empty dataset open, in which case it answers `open_request_reused` with that `dataset_id` and mints nothing (`--separate` mints a new one for a different dataset); `dataset show ID` reads it back; `dataset set ID --name TEXT --topics "a,b,c" --license ID --description-file F` writes the title, the descriptive tags, the SPDX licence and the description under the version it was read at, retrying once if somebody else wrote first, and an empty `--topics` or `--license` takes that value off the page; send `--name` and `--topics` whenever you send `--description-file`, because a description sent on its own can make Studio write a new title and new tags, and read `changed` and `written_by_studio` on the receipt for every field the write moved; a saved write whose public sync fails exits 2 and reports `public_projection_synced: false` — use `dataset sync ID` to retry that sync without rewriting Studio; `dataset note ID --heading H --blocks-file B` writes one cell of the decision record that OUTLIVES every run, and `--list` reads it back; `dataset watch ID` follows the page's own event stream; `dataset activity ID --phase P --message TEXT` says what is happening right now, silently, and is never a chat message and never a cell; `dataset publish ID [--mode public|link|private]` says who can read the dataset — `public` lists it in the public directory and serves it at an address anybody can read, `link` serves it at an unlisted address, `private` takes it back to the workspace — and `dataset publish ID --show` reads that back without changing it; `dataset archive ID --confirm-name TITLE` retires the page and frees its title, deleting nothing. |
 | `mr-data recipe` | Register one recipe document — dataset, question, table plan, sources, transform, checks and units — in one call, and print the identifiers the server derived. The document is read first and every fault comes back in one refusal, each with the JSON pointer that names it; `--no-lint` sends it as written instead. Registration refuses `THIN_BRIEF_MISSING` when the dataset's record carries no answered question and no delegation, and `THIN_RECIPE_DATASET_UNBOUND` when the document names no `dataset.id`; `--delegated "their words"` writes the delegation onto the dataset and registers in the same command, and clears the first of those two and never the second. `mr-data recipe show ID` reads one back. `mr-data recipe explain FILE` (or a recipe identifier) lists every reason its table can or cannot refresh, each with a rule code and Studio's suggested repair, and exits 2 when one blocks it. `mr-data recipe forecast RECIPE_ID --digest DIGEST` says what one run would ask of each source before it runs, and exits 3 when the run would overrun today's platform quota or one attempt. `mr-data recipe readiness --table TABLE_ID --current-only` reads the revision one table runs now. [Making a table incremental](making-a-table-incremental.md#the-loop-explain-forecast-run-diagnose) says when to use each. |
 | `mr-data cover` | Generate and attach one branded 1200×630 dataset cover. Give it the dataset ID and what the image should depict; Studio fixes the model, single-color style, curated random palette, dimensions and storage. |
 | `mr-data run` | Start one run against a registered recipe, named as `--recipe RECIPE_ID --digest RECIPE_DIGEST` — both required, neither positional, and the digest is the bare hex the registration receipt printed. The mode is one of six: `sample`, `full`, `refresh`, `backfill`, `compact` and `replay`. Four have a shorthand flag (`--sample`, `--full`, `--refresh`, `--backfill`) and two do not, so write `--mode MODE`, which is accepted for every one of them. A refresh executes only Studio's persisted source-action plan, and a plan shape it does not refresh returns `RESYNC_REQUIRED` before acquisition; [which plans refresh](making-a-table-incremental.md#which-plans-refresh) lists them, and `mr-data recipe explain` says which one a table is. Use `mr-data table resync TABLE_ID --request-id UUID` for an explicit full source reread, retaining that UUID if the response is uncertain. `--backfill` states the exact window with `--window START END`. `--mode replay --sources-from RUN_ID` asks Studio to run the registered revision against the RETAINED RAW INPUTS of one named successful run of the same table: nothing is fetched from this computer, nothing is acquired again, the result is compared against that run and never becomes the live version, and it neither asks for nor records an approval. Where Studio has replay switched off, or the named run is not successful, not the same table, or no longer retains its inputs, it answers a typed refusal — report the code rather than retrying in another mode. `--sources-from` on any other mode is refused `THIN_ARGUMENT_INVALID` before anything is sent. `--max-rows` and `--max-source-bytes` bound ONE SOURCE rather than the finished table. A large run is held for a spend confirmation, which `--confirm` settles and whose printed `confirm_command` re-states every argument the request carried. `--approve-full RUN_ID` releases the full an existing legacy sample-first pair is holding once its preview has succeeded, naming either half of the pair; where the deployment still wants a person at a browser it answers `THIN_INTERACTIVE_HUMAN_REQUIRED` and names the run page. `--retry RUN_ID` tries one failed run again when its triple carries `room_fault: true`, re-stating that run's own coordinate under a byte ceiling that cannot narrow it, and refuses with the triple when the recipe was at fault. `--cancel RUN` stops one. |

{mostlyright_data-0.27.1 → mostlyright_data-0.28.0}/skills/mr-data-build/references/required-protocol.md

@@ -21,7 +21,9 @@ are the first two acts of the session after the preflight — before the durable
 before `mr-data runs`, before a catalog is searched, before a provider's page is opened and before
 any URL is fetched. Research is what fills the page, and a page created after the research already
 happened is the assertion this stage exists to prevent. Nothing in stage 1 depends on knowing the
-sources: the title is a working one and stage 5 settles it.
+sources: the title is a working one and stage 5 settles it. A `dataset_id` handed over with the
+request, or a create that answers `open_request_reused`, is that page already open: build into it
+and open nothing.
 
 **Then establish whether anybody can be asked.** When the host provides an active user
 conversation, pass `--attended`; a tool subprocess without a terminal is not proof that the user

{mostlyright_data-0.27.1 → mostlyright_data-0.28.0}/src/mostlyright/data_harness/thin/recipe.py

@@ -1231,7 +1231,8 @@ def register(
             DATASET_UNBOUND_CODE,
             "this document names no dataset.id, so there is no page whose record could carry the "
             "brief this recipe rests on, and no page for the build to appear on. State the "
-            "identifier mr-data dataset create printed. --delegated cannot help here: it records "
+            "dataset identifier you were handed with the request, or the one mr-data dataset "
+            "create printed. --delegated cannot help here: it records "
             "a delegation onto a dataset, and this document names none",
         )
     delegated = getattr(args, "delegated", None)

{mostlyright_data-0.27.1 → mostlyright_data-0.28.0}/src/mostlyright/data_harness/thin/session.py

@@ -111,6 +111,17 @@ CLOUD_DATASET_RESOLVE_PATH = "/api/cli/datasets/resolve"
 #: What the resolve route stamps on both of its answers.
 CLOUD_DATASET_RESOLVED_SCHEMA = "mostlyright-cli-dataset-resolved.v1"
 
+#: Cloud's device-key route that names the dataset a person already created for the request they
+#: handed their AI tool, while that dataset is still empty and waiting for the build.
+#:
+#: ⚠ ASKED BEFORE A DATASET IS MINTED, BECAUSE A SECOND ONE IS THE BUG (owner, 2026-09-29: "ONE
+#: DATASET, one URL, one experience in one window"). ``/datasets/new`` creates the dataset and opens
+#: its page before the handoff is pasted, and an agent that ran ``dataset create`` anyway built onto
+#: a second page with its own address. Only Cloud holds the request, so only Cloud can answer. It
+#: answers 200 with ``open_request: null`` when nothing is waiting, so a 404 means a Cloud older
+#: than the route and the client carries on as it did before.
+CLOUD_OPEN_REQUEST_PATH = "/api/cli/datasets/open-request"
+
 MAX_TOKEN_RESPONSE_BYTES = 32 * 1024
 TOKEN_EXCHANGE_RETRY_ATTEMPTS = 2
 TOKEN_EXCHANGE_MAX_RETRY_SECONDS = 30.0

{mostlyright_data-0.27.1 → mostlyright_data-0.28.0}/src/mostlyright/data_harness/thin/v4_datasets.py

@@ -94,6 +94,7 @@ module moved.
 from __future__ import annotations
 
 import argparse
+import http.client
 import re
 import time
 from collections.abc import Callable, Collection, Mapping, Sequence
@@ -129,6 +130,7 @@ from mostlyright.data_harness.thin.session import (
     CLOUD_DATASET_RESOLVE_PATH,
     CLOUD_DATASET_RESOLVED_SCHEMA,
     CLOUD_DATASETS_LIST_PATH,
+    CLOUD_OPEN_REQUEST_PATH,
     CLOUD_REFUSAL_CODE,
     MAX_JSON_RESPONSE_BYTES,
     MAX_STATED_MESSAGE_CHARS,
@@ -143,7 +145,7 @@ from mostlyright.data_harness.thin.session import (
     stated_sentence,
 )
 from mostlyright.data_harness.thin.stream import RunEventStream
-from mostlyright.data_harness.thin.transport import ThinLaneError, Transport
+from mostlyright.data_harness.thin.transport import ThinLaneError, Transport, UrlLibTransport
 from mostlyright.data_harness.thin.v4 import (
     ARCHIVE_DATASET_PATH,
     COMMAND_REQUEST_VERSION_FLOOR,
@@ -173,7 +175,11 @@ from mostlyright.data_harness.thin.v4_public import (
     is_public_slug,
     show_public_dataset,
 )
-from mostlyright.data_harness.ux.credentials import LoginError, resolve_cloud_credentials
+from mostlyright.data_harness.ux.credentials import (
+    LoginError,
+    ResolvedCloudCredentials,
+    resolve_cloud_credentials,
+)
 from mostlyright.data_harness.ux.plain_file import PlainFileRefusal, read_plain_file
 
 CREATE_SCHEMA = f"{THIN_SCHEMA_PREFIX}-v4-dataset-created.v1"
@@ -408,6 +414,9 @@ _NO_SUCH_DATASET = (
 CLOUD_COMPOSED_REFUSAL = "step_up_required"
 
 
+_OPEN_REQUEST_ACT = "ask whether your request already has a dataset"
+
+
 class CloudDatasetAccessClient(CloudClient):
     """Dataset access and identity routes over the shared device-key Cloud client.
 
@@ -444,6 +453,11 @@ class CloudDatasetAccessClient(CloudClient):
             maximum=MAX_JSON_RESPONSE_BYTES,
         )
 
+    def open_request(self) -> dict[str, Any]:
+        """Ask which dataset this person already created for their request, if one is waiting."""
+
+        return self.call("GET", CLOUD_OPEN_REQUEST_PATH, act=_OPEN_REQUEST_ACT)
+
     def resolve_dataset(self, reference: str) -> dict[str, Any]:
         """Ask Cloud which dataset a slug, a dataset URL or either uuid names, reading nothing else.
 
@@ -701,6 +715,14 @@ def declare_arguments(parser: argparse.ArgumentParser) -> None:
         action="store_true",
         help="With create, also prepare the address the host opens immediately",
     )
+    parser.add_argument(
+        "--separate",
+        action="store_true",
+        help=(
+            "With create, make a new dataset even while the page the user opened for their "
+            "request is still empty. Only when the user asked for another, separate dataset"
+        ),
+    )
     parser.add_argument(
         "--description-file",
         dest="description_file",
@@ -1092,17 +1114,125 @@ def _replayed(headers: Mapping[str, str]) -> bool:
 # ------------------------------------------------------------------------------------------------
 
 
+#: How long ``dataset create`` waits for Cloud's answer about an open request. The question is
+#: advisory, so it gets the short clock the activity report gets rather than a command's thirty
+#: seconds: a slow Cloud may not add half a minute to every create.
+OPEN_REQUEST_TIMEOUT_SECONDS = 5.0
+
+
+def open_request(
+    cloud: CloudDatasetAccessClient | None = None,
+    *,
+    credentials: ResolvedCloudCredentials | None = None,
+) -> dict[str, Any] | None:
+    """The dataset the person already created for their request, while it waits for the build.
+
+    ⚠ NEVER THE REASON A DATASET CANNOT BE MADE. No credential, a Cloud older than the route (its
+    404), a refusal, an outage, a timeout, a reset connection or an answer this client cannot read
+    all mean "nothing to reuse", and ``dataset create`` does what it did before the route existed.
+    The rule deciding what is waiting is Cloud's (``lib/mcp/handoff-adoption.ts`` there); a second
+    opinion here would drift.
+    """
+
+    try:
+        selected = cloud or CloudDatasetAccessClient(
+            credentials or resolve_cloud_credentials(),
+            transport=UrlLibTransport(timeout=OPEN_REQUEST_TIMEOUT_SECONDS),
+        )
+        answer = selected.open_request()
+    except (ThinLaneError, LoginError, OSError, http.client.HTTPException, ValueError):
+        return None
+    waiting = answer.get("open_request") if isinstance(answer, Mapping) else None
+    if not isinstance(waiting, Mapping):
+        return None
+    try:
+        dataset_id = str(UUID(str(waiting.get("dataset_id"))))
+    except ValueError:
+        return None
+    if dataset_id != waiting.get("dataset_id"):
+        return None
+    try:
+        dashboard_url = dataset_dashboard_url(selected.cloud_url, dataset_id)
+    except ThinLaneError:
+        return None
+    request = waiting.get("request")
+    name = waiting.get("name")
+    return {
+        "dataset_id": dataset_id,
+        "name": name if isinstance(name, str) else None,
+        "request": request if isinstance(request, str) else "",
+        "dashboard_url": dashboard_url,
+    }
+
+
+def _reused_open_request(waiting: Mapping[str, Any]) -> dict[str, Any]:
+    """The receipt for a create that found the person's own request waiting, and made nothing."""
+
+    dataset_id = waiting["dataset_id"]
+    asked = f' ("{waiting["request"]}")' if waiting["request"] else ""
+    return {
+        "schema_version": CREATE_SCHEMA,
+        "navigation": {
+            "url": waiting["dashboard_url"],
+            "target": f"/datasets/{dataset_id}",
+            # Already open in the person's browser: opening it again is the second window.
+            "open_before_research": False,
+            "follow_agent": True,
+            "status": "already_open",
+        },
+        "status": "open_request_reused",
+        "lane": "hosted",
+        "reused_open_request": True,
+        "dataset_id": dataset_id,
+        "name": waiting["name"],
+        "version": None,
+        "dashboard_url": waiting["dashboard_url"],
+        "note": (
+            f"No dataset was created. The user already created this dataset for their "
+            f"request{asked} and its page is open in their browser, waiting for this build. If "
+            f"that request is the one you are building, put this dataset_id in the recipe's "
+            f"dataset.id and build into it; do not run mr-data open, and do not show the user "
+            f"another dataset link. If your task is a different dataset from that request, run "
+            f"mr-data dataset create --separate instead."
+        ),
+        "next": (
+            f"The --name and description you gave were not applied. Give this dataset its title "
+            f"and description with mr-data dataset set {dataset_id} --name ... --topics ... "
+            f"--description-file ..."
+        ),
+    }
+
+
 def create(
     args: argparse.Namespace,
     *,
     client: StudioV4DatasetClient | None = None,
     stdin: Any = None,
+    cloud: CloudDatasetAccessClient | None = None,
 ) -> dict[str, Any]:
-    """``mr-data dataset create --name TEXT``: the page, before anything is on it."""
+    """``mr-data dataset create --name TEXT``: the page, before anything is on it.
+
+    ⚠ UNLESS THE PERSON'S OWN REQUEST ALREADY HAS ONE (owner, 2026-09-29). A dataset created on
+    ``/datasets/new`` is open in their browser before the agent starts; creating another put the
+    build on a second page with its own address. Cloud is asked first (:func:`open_request`), and
+    a waiting dataset is answered instead of a new one. ``--separate`` skips the question. An
+    injected Studio client asks only an injected Cloud: a caller that substituted one origin has
+    not agreed to reach the other for real.
+    """
 
     name = checked_name(getattr(args, "name", None), needed_by="create")
     description = read_description(args, stdin=stdin)
-    selected = client or _client(args)
+    # Resolved once and shared, so a keychain is read (and may prompt) once per create.
+    credentials = resolve_cloud_credentials() if client is None else None
+    if not getattr(args, "separate", False) and (client is None or cloud is not None):
+        waiting = open_request(cloud, credentials=credentials)
+        if waiting is not None:
+            return _reused_open_request(waiting)
+    if client is not None:
+        selected = client
+    else:
+        assert credentials is not None
+        selected = StudioV4DatasetClient(open_studio_session(credentials))
     record = selected.create_dataset(name=name, description=description)
     dataset_id = _dataset_id(record, verb="create")
     navigation = {
@@ -2355,6 +2485,8 @@ def dataset(
     action = getattr(args, "action", None)
     if getattr(args, "handoff", False) and action != "create":
         raise ThinLaneError("THIN_REQUEST_INVALID", "--handoff belongs to dataset create")
+    if getattr(args, "separate", False) and action != "create":
+        raise ThinLaneError("THIN_REQUEST_INVALID", "--separate belongs to dataset create")
     if getattr(args, "expected_version", None) is not None and action not in {"set", "draft"}:
         raise ThinLaneError("THIN_REQUEST_INVALID", "--expected-version belongs to set or draft")
     if action == "draft" and getattr(args, "name", None) is not None:

{mostlyright_data-0.27.1 → mostlyright_data-0.28.0}/src/mostlyright/data_harness/ux/render.py

@@ -346,6 +346,11 @@ STATUS_HEADLINES: dict[str, str] = {
     # two: "the page is there now" and "the page has been corrected" are not one event, and a
     # single word covering them would let a rename read as a page that was just created.
     "dataset_created": "The dataset page exists now, and it is empty. Open it before you start.",
+    # ⚠ NOT "CREATED", AND NOT "OPEN IT". Nothing was made: the person's own request already had a
+    # page, open in their browser, and a second window onto it is the bug this answer exists for.
+    "open_request_reused": (
+        "No dataset was created. Build into the one the user already opened for this request."
+    ),
     "dashboard_ready": "The dataset page is ready to open.",
     "description_drafting": "The description draft is saved for preview.",
     "dataset_reported": "Here is the dataset page as Studio holds it.",