metergraph-cli 0.2.1 → 0.2.3

package/assets/skills/metergraph-investigate/SKILL.md

@@ -1,50 +1,183 @@
 ---
 name: metergraph-investigate
-description: Investigate a failed or anomalous LLM trace, usage spike or incident through an already connected Metergraph Agent Access server, answering only from bounded, cited evidence. Use after setup is verified; use the metergraph skill first when not connected.
+description: Investigate a failed or anomalous LLM trace, usage spike, cost question (which route, provider or model costs most, a daily trend, a change from the prior period), incident or whether a code change moved cost, reading through the metergraph CLI first (fewer tokens) or a connected Metergraph Agent Access MCP server, answering only from bounded, cited evidence. Use after setup is verified; use the metergraph skill first when neither the CLI nor MCP can read the workspace.
 ---
 
 # Investigate with Metergraph evidence
 
 This skill expands the bounded investigation section of the public `metergraph`
-skill. It adds no tools, scopes or authority. When no Metergraph MCP server is
-connected, or the user has not chosen a client, runtime and deployment, stop and
-use the `metergraph` skill for setup routing. Never ask for, echo or store a
+skill. It adds no tools, scopes or authority. Never ask for, echo or store a
 key.
 
+Read through the `metergraph` CLI first when it is installed and can read the
+workspace: it returns the same Metadata evidence as the MCP tools in far fewer
+tokens. Use the MCP tools for what the CLI does not cover (incidents, ingestion
+health, reports, retained content and replay) and in clients that have no
+shell. Stop and use the `metergraph` skill for setup routing only when neither
+the CLI nor a Metergraph MCP server can read the workspace, or the user has not
+chosen a client, runtime and deployment.
+
 ## 1. Discover before reading data
 
+**With the CLI** (preferred when `metergraph --help` lists `status`,
+`capabilities` and `usage`; an older CLI can run but lack them):
+
+1. Run `metergraph status --json`. Continue when it exits 0 with
+   `data.authenticated: true` and `data.workspace.match: true`. When `match`
+   is null because no workspace was pinned (a coding-agent key without
+   `--workspace`), name `data.workspace.actual` and continue only after the
+   person confirms it is the workspace they mean. When it prints
+   `data.next_action` (for example sign in again, or the coding-agent Metadata
+   key path for a remote session), follow it; never ask for the key in chat.
+2. Run `metergraph capabilities --json` and build the plan from
+   `data.result.agent` (each capability's `available`, `privacy_class` and
+   `required_scope`) and `data.result.bounds` (`max_days`, `max_rows`).
+3. Before using any option, check that `metergraph help <command>` lists it.
+   An option an older CLI lacks is a reason to use the matching MCP tool, not
+   to guess a flag. Always pass `--json`: the evidence is under `data.result`,
+   with `data.notices` and `data.next_action` beside it, and the exit code is
+   the outcome (for example 14 when the deployment does not offer the read).
+
+**With MCP** (no CLI, no shell, or a read the CLI does not offer):
+
 1. Call `metergraph_get_workspace_context`, then `metergraph_get_capabilities`.
    Do not call any other Metergraph tool first.
-2. Confirm with the user that `provenance.workspace_id`, the workspace name and
-   `provenance.deployment_profile` match the installation they intend. A staging
-   or demo workspace is not their production workspace. Stop on a mismatch,
-   an authorization error, or revoked or expired access, and tell the human to
-   reconnect through their client's secure flow.
-3. Build the tool plan only from what the server returns: the workspace
+2. Build the tool plan only from what the server returns: the workspace
    context's `access.scopes`, and each capability under the capabilities
    response's `agent` object with its `available`, `privacy_class` (metadata,
    content or replay), `required_scope`, `mutates` and `external_calls`, plus
    `bounds` (`max_days`, `max_rows`). Treat the tools your client lists as the
-   only callable tools. A tool or capability that is absent, or has
-   `available: false`, is a blocker to report, not something to
-   guess, retry under another name or replace with a dashboard API, generic SQL
-   or a shell command. Some deployments are content-blind or have no replay,
-   incidents, ingestion health or reports.
+   only callable tools.
+
+Either way, confirm with the user that the workspace ID, the workspace name
+and the deployment profile match the installation they intend. A staging or
+demo workspace is not their production workspace. A mismatch, an
+authorization error, or revoked or expired access belongs to that one path:
+when the CLI cannot read the intended workspace but a connected MCP server
+can (or the other way round), use the path that can. Stop and tell the human
+to reconnect through their client's secure flow only when neither the CLI nor
+MCP can verify the intended workspace. A capability that is absent, or
+has `available: false`, is a blocker to report, not something to guess, retry
+under another name or replace with a dashboard API, generic SQL or an ad hoc
+shell command. Some deployments are content-blind or have no replay,
+incidents, ingestion health or reports.
 
 ## 2. Fix the question and the bound
 
-Restate the question, the route or workload if known, and an explicit window in
-whole days (tools accept `days` from 1 to 90; default to the shortest window
-that answers the question). Then choose the smallest tool that can answer:
+Restate the question, the route or workload if known, and an explicit UTC
+window. For grouped usage, windows are UTC: `days: N` means the current UTC
+day so far plus the `N - 1` whole UTC days before it, so today is always
+partial; `since` (inclusive) and `until` (exclusive) give an exact window.
+Plain `metergraph usage --days N` (no grouping) is instead the last N x 24
+hours, rolling and not aligned to UTC days; say so when you report it. Keep
+every window within 90 days and within the capabilities' `bounds.max_days`.
+Default to the shortest window that answers the question. Then choose the
+smallest tool that can answer:
+
+| Question | CLI (check its help first) | MCP tool | Bound |
+| --- | --- | --- | --- |
+| Which route, provider or model costs most; spend with one provider or model; a daily trend | `metergraph usage --group-by ... --json` with `--route`, `--provider`, `--model` or `--environment` | `metergraph_get_usage_aggregates` with `group_by` and the same exact filters | `--days`/`days` or `--since`/`--until`, small limit |
+| Daily cost per route, when grouped usage is unavailable | `metergraph usage --days N --json` | `metergraph_get_usage` | days, small limit |
+| Which routes exist or are replay eligible | `metergraph routes --json` | `metergraph_list_routes` | none needed |
+| Is data arriving | none; use MCP | `metergraph_get_ingestion_health` | `days` |
+| Known alert or anomaly | none; use MCP | `metergraph_list_incidents` | small `limit` |
+| Cost or calls for one prompt, workflow or other tag value | `metergraph usage --group-by metadata.KEY --json`, or `--metadata KEY=VALUE` | `metergraph_get_usage_aggregates` with `group_by` including `metadata.<key>`, or `metadata` (exact pairs) | days, small limit |
+| One failed call | `metergraph traces --status error --limit 1 --json` (also `--route`, `--metadata`) | `metergraph_query_traces` with `status` set to the failure status, and `route`, `trace_id`, `request_id` or `metadata` | limit 1 to 5 |
+| One costly call (it may have succeeded) | `metergraph traces --route NAME --limit 5 --json` with no `--status`, then compare cost on that page | `metergraph_query_traces` with `route`, `trace_id`, `request_id` or `metadata`, no `status` | limit 1 to 5 |
+| Which routes are slow (route level, not one call) | `metergraph usage --group-by route --sort p95-latency --json`; CLI `traces` returns no latency | `metergraph_get_usage_aggregates` grouped by route | days, small limit |
+| One slow call | none; CLI `traces` has no latency, so ask for its trace or request ID and use MCP, or send the person to the trace in the app | `metergraph_query_traces` with that `trace_id` or `request_id` | limit 1 |
+| A finished analysis | none; use MCP | `metergraph_list_reports`, then `metergraph_get_report` | small `limit` |
 
-| Question | First tool | Bound |
+Use grouped usage (`metergraph usage --group-by`, or
+`metergraph_get_usage_aggregates`) only when capabilities list
+`usage_aggregates` as available. On an older deployment it is absent: say so,
+answer what `metergraph_get_usage` can (cost per route and day), and do not
+rebuild provider or model totals by paging traces.
+
+### Cost questions
+
+`metergraph_get_usage_aggregates` groups calls by any ordered subset of
+`provider`, `model`, `route` and `day` (the call's UTC calendar day), plus at
+most one `metadata.<key>`. Cost is
+attributed per call, so a trace that used two providers adds each call's cost
+to that call's provider. Groups come back highest cost first, at most `limit`
+of them; `totals` cover every matching call whatever the limit. From a shell,
+the `metergraph` CLI sends the same read and prints the same evidence. Check
+`metergraph help usage` first: use these commands only when it lists
+`--group-by`. An older CLI has only `metergraph usage --days N` (cost per route
+and day); use the tool instead, or say a newer CLI is needed.
+
+| Question | Tool arguments | CLI |
 | --- | --- | --- |
-| How much, how many, which route costs most | `metergraph_get_usage` | `days`, small `limit` |
-| Which routes exist or are replay eligible | `metergraph_list_routes` | none needed |
-| Is data arriving | `metergraph_get_ingestion_health` | `days` |
-| Known alert or anomaly | `metergraph_list_incidents` | small `limit` |
-| One failed, slow or costly call | `metergraph_query_traces` with `status`, `route`, `trace_id` or `request_id` | `limit` 1 to 5 |
-| A finished analysis | `metergraph_list_reports`, then `metergraph_get_report` | small `limit` |
+| Most expensive route today | `{"group_by": ["route"], "days": 1}` | `metergraph usage --group-by route --today --json` |
+| Spend with one provider | `{"group_by": ["provider"], "provider": ["<name>"], "days": 7}` | `metergraph usage --group-by provider --provider <name> --days 7 --json` |
+| Spend by model | `{"group_by": ["model"], "days": 7}` | `metergraph usage --group-by model --days 7 --json` |
+| One route's daily trend | `{"group_by": ["day"], "route": ["<route>"], "days": 14}` | `metergraph usage --route <route> --group-by day --days 14 --json` |
+| Cost by prompt ID | `{"group_by": ["metadata.prompt_id"], "days": 7}` | `metergraph usage --group-by metadata.prompt_id --days 7 --json` |
+| Today against yesterday | two reads: `days: 1`, then `since`/`until` for the prior UTC day | `metergraph usage --group-by route --today --compare previous --json` |
+
+Rank only what was returned. When `coverage.rows.truncated` is true (more
+groups matched than `limit`), a ranking by calls, errors or latency covers
+only the listed groups. Before naming a "top" group, raise `limit` to
+`coverage.rows.matched` when that is at most 200 and at most the
+capabilities' `bounds.max_rows`; otherwise narrow the read. Name the latency
+you report:
+`latency.avg_ms` is the mean over `latency.samples` calls that reported one,
+and `latency.p95_ms` is an estimate from a fixed histogram
+(`p95_method: histogram_estimate`), not an exact percentile.
+
+A "costs most" answer needs exact pricing. When `pricing.cost` is
+`lower_bound` (the overall `pricing`, or a group's own), some calls are not
+fully priced, so a group with more unpriced calls can look cheaper than it is.
+Name the group with the highest recorded cost as a lower bound and say the
+ranking is not definitive until pricing is exact; never call it the most
+expensive outright.
+
+A prior-period comparison needs two reads with stated windows. Comparing
+today so far with all of yesterday is not like for like: say so, or compare
+with yesterday up to the same UTC time (`--compare previous-same-time` in the
+CLI). A group missing from a truncated window is unknown, not zero.
+
+A route is not a prompt. One route (for example `support-reply`) can carry
+several prompt IDs in its metadata (SDK tags), and one prompt ID can run on
+several routes. To answer "which prompt costs most", group by the metadata key
+alone, so each prompt is one row across every route. Add `route` to `group_by`
+only to show how a route splits by prompt. Keep the same `days` on every
+follow-up read, so the examples come from the window you just summarised:
+
+```json
+{"name": "metergraph_get_usage_aggregates", "arguments": {"days": 7, "group_by": ["metadata.prompt_id"]}}
+{"name": "metergraph_query_traces", "arguments": {"days": 7, "metadata": {"prompt_id": "reply-v3"}, "limit": 3}}
+```
+
+Metadata values are exact, case-sensitive opaque strings: `reply-v3` does not
+match `reply-v30`, a call without the key never matches a filter, and several
+filter keys must all match. In a read grouped by a metadata key, calls in the
+window that have no value for the grouped key form the group whose value is
+`null`, and `coverage.reasons` names `metadata_key_missing` (or
+`metadata_value_ineligible` for a non-string or oversize value). Report that
+group rather than dropping it. If you also filtered on that same key, no such
+calls remain, so there is no `null` group. A `metadata_key_mostly_missing`
+warning means most calls or cost have no value for the key; say so, and
+suggest checking the key's spelling. `metadata_groups.unlisted` accounts for
+every call not listed with a value: `other_values` (values past the limit, with
+a group count), `missing_key` and `ineligible_value`. Report the spend in
+`missing_key` plus `ineligible_value` as not attributed to any value of the
+key, so a prompt ranking never reads as the whole spend. When
+`coverage.rows.truncated` is true, the listed groups are not the whole window:
+quote `totals` for the window and `coverage.rows.matched` as the number of
+matched groups. That counts groups, not distinct values of the key: with
+`group_by: ["route", "metadata.prompt_id"]` one prompt used on three routes is
+three groups. For a count of distinct values, read with the metadata key as
+the only dimension.
+
+The CLI can run the same reads (`metergraph usage --group-by
+metadata.prompt_id --days 7 --json`, where `--group-by-metadata prompt_id` is
+the same dimension and the way to give a key that contains a comma, and
+`metergraph traces --days 7 --metadata prompt_id=reply-v3 --json`) only in versions that
+have these options. Check that `metergraph usage --help` lists `--group-by`
+(and `metergraph traces --help` lists `--metadata`) before you suggest them,
+and otherwise use the tools above.
 
 Follow `next_cursor` only while you are still inside the agreed bound, and say
 how many pages you read. Never request every trace, every report or unbounded
@@ -69,14 +202,23 @@ point to the human action in the Metergraph app instead.
 
 ## 4. Answer only from returned evidence
 
-Every answer cites, from the tool responses you actually received:
+Every answer cites, from the CLI results or tool responses you actually
+received (a CLI result carries the same fields under `data.result`, plus
+`data.notices`):
 
 - **Workspace**: workspace name and `provenance.workspace_id`, plus
   `deployment_profile`.
-- **Window**: `window.since` to `window.until` (or `days`) for each read.
+- **Window**: `window.since` to `window.until` in UTC (or `days`) for each
+  read, and whether the last day is partial.
 - **Provenance**: the tool name, `provenance.source` and `generated_at`.
 - **Evidence and completeness**: `evidence.rows`, `evidence.complete`,
-  `page.truncated` and whether a `next_cursor` was left unread.
+  `page.truncated` and whether a `next_cursor` was left unread; for usage,
+  `coverage.completeness` with its `reasons`, `coverage.rows.matched` against
+  the rows returned, and whether a total is the whole population
+  (`totals.scope`) or only the returned rows.
+- **Pricing and attribution**: `pricing.cost` (`exact` or a `lower_bound`) and
+  `attribution.level`. A trace cost is a whole-trace total and is never split
+  by provider.
 - **Warnings**: every returned `warnings[].code` with its message. Say "no
   warnings returned" when the list is empty.
 - **Identifiers and links**: trace, request, incident or analysis IDs, and
@@ -87,16 +229,61 @@ window, incomplete or truncated evidence, capability unavailable in this
 deployment, classification pending, ambiguous request match
 (`request_match.ambiguous`), failed analysis, and missing report. An empty page
 does not prove there was no traffic; check ingestion health or a longer bounded
-window before saying so. Do not round, extrapolate or invent totals.
+window before saying so. Do not round, extrapolate or invent totals. Never
+attribute a cost change, or the absence of one, to a code change from source
+code or a git diff; see section 5.
+
+## 5. Code changes and cost: never decide from the diff
+
+When the question is whether a commit, pull request, deploy or config change
+raised, lowered or did not change cost, a git diff is never the evidence. Read
+it to form a hypothesis (a different model, a longer prompt, a new retry loop, a
+changed `max_tokens`, an added tool call), then say it is a hypothesis. Do not
+answer "this commit increased cost", "this commit saved money" or "this commit
+has no cost impact" from code alone, including a diff that touches no model or
+prompt code: wrappers, retries, caching, routing, traffic and provider prices
+change spend without appearing in the diff.
+
+A cost conclusion needs returned Metergraph usage evidence:
+
+1. Establish when the change reached the traffic Metergraph observes, from
+   recorded commit or deployment identity (a deploy record, or the commit the
+   telemetry itself carries). Merge time is not deploy time. Without that
+   record, any before-and-after reading is only a time correlation: call it
+   that, give the windows, and do not attribute the difference to the commit.
+   If no one knows when it shipped, say the comparison cannot be anchored.
+2. Read usage for the same route or workload over comparable, bounded UTC
+   windows before and after that point (`metergraph_get_usage_aggregates`
+   with explicit `since` and `until` and the same filters, or
+   `metergraph_get_usage` where grouped usage is unavailable), and cite both
+   reads as in section 4. Windows of equal length avoid comparing a partial
+   day with a whole one. Filter both reads to the environment the deployment
+   record names (`environment`), so traffic in another environment that
+   shares the route is not credited to the change. If that environment
+   cannot be isolated (for example the grant or deployment has no
+   environment filter), say the cost impact is unknown.
+3. Compare per-call cost and token counts as well as totals, so a traffic
+   change is not mistaken for a code change. Name what else changed in the
+   window when you know it (traffic, provider prices, other deploys).
+4. If either window is incomplete, truncated or warned, if the windows are not
+   comparable, or if the returned data cannot separate traffic by the change,
+   state that the cost impact is unknown and name the next bounded check. Do
+   not fill the gap from the diff.
+
+Present the diff and the usage evidence separately: what the code suggests,
+and what Metergraph measured.
 
-## 5. Worked workflow: one failed trace
+## 6. Worked workflow: one failed trace
 
-1. Discover: context, then capabilities. Confirm the workspace with the user.
-2. Find: `metergraph_query_traces` with `status` set to the failure status, the
-   agreed `days` and `limit` 1. If the user gave a request ID and the match is
+1. Discover: `metergraph status --json` and `metergraph capabilities --json`
+   (or the context and capabilities tools). Confirm the workspace with the user.
+2. Find: `metergraph traces --status error --days N --limit 1 --json` (or
+   `metergraph_query_traces` with `status` set to the failure status, the
+   agreed `days` and `limit` 1). If the user gave a request ID and the match is
    ambiguous, list the candidates and ask which one.
-3. Explain from metadata: route, model, provider, tokens, cost, latency, status
-   and span count, with the citations above. If metadata is enough, stop here.
+3. Explain from metadata: route, model, provider, tokens, cost, status and
+   span count, plus latency only when the read returns it (CLI `traces` does
+   not; never infer it from timestamps), with the citations above. If metadata is enough, stop here.
 4. Optional content: with consent, `metergraph_get_trace` for that one trace to
    read the error, tool calls and root-cause classification.
 5. Optional replay: only with explicit approval and when the trace is replay

package/assets/skills/metergraph-onboarding/SKILL.md

@@ -117,6 +117,13 @@ connection, paid eval rule or provider invocation just to manufacture proof.
    still needed and the next eval selection action. A synthetic demonstration
    does not meet real application or hosted pilot acceptance.
 
+A person's first cost question after setup ("which route costs most today")
+is a bounded usage read, not a trace scan: `metergraph usage --group-by route
+--today --json` from a CLI whose `metergraph help usage` lists `--group-by`, or
+`metergraph_get_usage_aggregates` when capabilities list `usage_aggregates`. Use `metergraph-investigate` for it. A
+remote or CI agent reads with the coding-agent Metadata key path in the
+`metergraph` skill, never with the application's ingest key.
+
 Verify the named trace through the connected client's advertised MCP tools,
 with an explicit source label and the same workspace/deployment before and
 after any permitted content read. The older trace-debug contract has no

package/assets/skills/metergraph-report/SKILL.md

@@ -18,8 +18,25 @@ only with the tools the capabilities advertise.
 ## 1. Read it
 
 1. `metergraph_get_analysis_run` with the run ID. Continue only when the status
-   is final. If `report.available` is false on a completed run, the report is
-   missing: say so and give the run's page (below).
+   is final. If it is not, show where the run is, as described next, and stop. If
+   `report.available` is false on a completed run, the report is missing: say
+   so and give the run's page (below).
+
+   For a run that is not final, draw `run.stages.items` in the order returned,
+   using each item's `state` exactly as given: `✓` completed, `●` current, `✗`
+   failed, `–` skipped, `○` not started. For example:
+
+   ```
+   ✓ queued → ✓ exporting → ● analyzing → ○ classified → ○ importing → ○ completed
+   ```
+
+   Under it, say in plain text which stages are done, which one is current and
+   since when (its `entered_at`, checked at `provenance.generated_at`), and
+   which are still to come. Never give a percentage, an ETA or a time remaining.
+   When `run.stages.available` is false, or `stages` is missing, draw nothing:
+   say the stage breakdown is unavailable (`unavailable_reason`, when present)
+   and report the `status` and timestamps instead. `metergraph-analyze`, when
+   installed, describes the same progress report in more detail.
 2. `metergraph_get_report` with `report.analysis_id`. Read the `outcome`, each
    workload's `state`, `sample_count` and `reason`, each `model_swap`
    opportunity (`recommendation_status`, `quality_vs_reference`,

package/bin/metergraph.js

@@ -7,5 +7,5 @@ import { main } from "../src/cli.js";
 process.stdout.on("error", () => {});
 
 const argv = process.argv.slice(2);
-const io = { stdout: process.stdout, stderr: process.stderr };
+const io = { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin };
 process.exitCode = handsOff(argv) ? await handOff(argv, io) : await main(argv, io);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metergraph-cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Metergraph command line tool with a read-only connection probe, a project skill installer, Metadata-only sign in and bounded workspace Metadata reads",
   "type": "module",
   "bin": {

package/src/agent-key.js

@@ -0,0 +1,160 @@
+import { verifyContext } from "./auth-oauth.js";
+import { DEFAULT_ORIGIN, MAX_BODY_BYTES, METADATA_SCOPE } from "./constants.js";
+import { CREDENTIAL_MIN_LENGTH, readCredentialFile } from "./deployment-credential.js";
+import { checkDeployment } from "./doctor.js";
+import { AGENT_TOKEN_ENV, AGENT_URL_ENV } from "./environment.js";
+import { parseOrigin } from "./origin.js";
+import { send } from "./transport.js";
+
+// The read commands' second credential: a coding-agent key with Metadata
+// access that a person created on the Keys page and handed to the agent's
+// environment as a secret. It is for agents where browser sign in cannot
+// finish (SSH, cloud workspaces, CI, some containers).
+//
+// The key comes only from the METERGRAPH_AGENT_TOKEN environment variable or
+// from a private file named by --agent-token-file (checked as setup checks
+// its agent token file). There is no argv or stdin form. The key is never
+// written anywhere, never printed, and sent only as a bearer header to the
+// chosen origin, and only after that origin has answered the unauthenticated
+// deployment probe as a supported Metergraph service. Before any read, the
+// service's own workspace and capabilities documents must show exactly the
+// Metadata scope, no content access, the expected deployment profile and,
+// when one is pinned, the expected workspace. A broader key fails closed:
+// there is no fallback to Debug or Replay access.
+
+const TOKEN = new RegExp(`^[\\x21-\\x7e]{${CREDENTIAL_MIN_LENGTH},8192}$`);
+
+const stop = (outcome, reason) => ({ ok: false, outcome, reason });
+
+// Which key source this run has, or null. An explicit file wins over the
+// environment variable.
+export function agentKeySource(options, env) {
+  if (typeof options.agentTokenFile === "string") return { kind: "file", file: options.agentTokenFile };
+  if (typeof env[AGENT_TOKEN_ENV] === "string" && env[AGENT_TOKEN_ENV] !== "") return { kind: "env" };
+  return null;
+}
+
+// Where the key may be sent and what it must prove, before any request.
+// A project binding pins the origin, workspace and profile; --url (or
+// METERGRAPH_URL) and --workspace may repeat them but never contradict them.
+// Without a binding, --workspace pins the workspace; without that, the
+// key's own workspace is used and reported as unpinned.
+// originConfirmed is true when this machine holds a saved sign in for the
+// binding's origin, which proves the person chose that origin here.
+export function keyTarget({ binding, options, env, originConfirmed = false }) {
+  let requested = options.origin ?? null;
+  let source = requested === null ? null : "flag";
+  const rawEnv = env[AGENT_URL_ENV];
+  if (requested === null && typeof rawEnv === "string" && rawEnv !== "") {
+    requested = parseOrigin(rawEnv);
+    if (requested === null) return stop("invalid_input", "metergraph_url_invalid");
+    source = "env";
+  }
+  const pinned = options.workspace ?? null;
+  if (binding !== null) {
+    if (requested !== null && requested !== binding.origin) return stop("conflict", "bound_to_other_origin");
+    // The binding is repository content, so it may come from anyone who can
+    // commit. A key is sent to the origin it names only when that is the
+    // hosted service, this machine signed in to it, or the person confirmed
+    // the same origin with --url or METERGRAPH_URL; otherwise a committed
+    // file could direct the key to another server.
+    if (requested === null && binding.origin !== DEFAULT_ORIGIN && !originConfirmed) {
+      return stop("conflict", "agent_key_origin_unconfirmed");
+    }
+    if (pinned !== null && pinned !== binding.workspace_id) return stop("conflict", "bound_to_other_workspace");
+    return {
+      ok: true,
+      origin: binding.origin,
+      workspaceId: binding.workspace_id,
+      profile: binding.deployment_profile,
+      originSource: "binding",
+    };
+  }
+  return {
+    ok: true,
+    origin: requested ?? DEFAULT_ORIGIN,
+    workspaceId: pinned,
+    profile: null,
+    originSource: source ?? "default",
+  };
+}
+
+// Resolves with the same shape as auth-session's sessionFor:
+//   { ok: true, session, documents, knownCredentials }
+//   { ok: false, outcome, reason }
+// verifiedProfile is the profile the caller already read from GET
+// /v1/deployment under the same deadline, or null to read it here.
+// access is "metadata" for the read commands, or "experiment_start" for
+// experiments start, which needs Debug access and the start grant instead
+// (verifyContext) and uses the key for that one request.
+export async function keySession({ target, source, env, signal, verifiedProfile = null, access = "metadata" }) {
+  // A key already in the environment is checked for shape before any
+  // request; a key file is opened only once the origin has proven itself.
+  let key = source.kind === "env" ? readAgentKey(source, env) : null;
+  if (key !== null && !key.ok) return key;
+  let profile = verifiedProfile;
+  if (profile === null) {
+    const deployment = checkDeployment(
+      await send(target.origin, "/v1/deployment", { signal, maxBytes: MAX_BODY_BYTES }),
+    );
+    if (deployment.outcome !== null) return stop(deployment.outcome, deployment.reason);
+    profile = deployment.profile;
+  }
+  if (target.profile !== null && profile !== target.profile) return stop("verification_failed", "profile_mismatch");
+
+  // Only now, with the origin proven to be a supported Metergraph service,
+  // is the key read.
+  if (key === null) key = readAgentKey(source, env);
+  if (!key.ok) return key;
+  const { token } = key;
+
+  const verified = await verifyContext(
+    target.origin,
+    token,
+    { profile, workspaceId: target.workspaceId, anyWorkspace: target.workspaceId === null, access },
+    signal,
+  );
+  if (!verified.ok) {
+    if (signal?.aborted) return stop("authorization_failed", "cancelled");
+    // 401: the key is unknown, expired or revoked. 403: the key is valid but
+    // lacks Metadata access to this workspace (for example an ingest key).
+    if (verified.denied && verified.status === 403) return stop("permission_denied", "agent_key_insufficient_scope");
+    if (verified.denied) return stop("login_required", "agent_key_rejected");
+    return stop(verified.outcome, verified.reason);
+  }
+  return {
+    ok: true,
+    session: {
+      origin: target.origin,
+      workspaceId: verified.workspaceId,
+      profile,
+      scopes: access === "metadata" ? [METADATA_SCOPE] : verified.scopes,
+      accessToken: token,
+    },
+    documents: verified.documents,
+    // Internal only, for checking output before it is printed.
+    knownCredentials: [token],
+  };
+}
+
+// { ok: true, token } or { ok: false, outcome, reason } with a fixed reason.
+// No path, value or system error text is ever returned.
+export function readAgentKey(source, env) {
+  if (source.kind === "file") {
+    const read = readCredentialFile(source.file);
+    if (read.ok) return read;
+    // The file's own reasons, renamed so they are never mistaken for the
+    // private sign in store's reasons: credential_missing becomes
+    // agent_token_file_missing, and so on.
+    const reason = read.reason.startsWith("credential_") ? read.reason.slice("credential_".length) : read.reason;
+    return stop(read.outcome, read.reason === "platform_credential_handoff" ? read.reason : `agent_token_file_${reason}`);
+  }
+  let value = env[AGENT_TOKEN_ENV];
+  if (typeof value !== "string") return stop("login_required", "agent_token_missing");
+  if (value.endsWith("\r\n")) value = value.slice(0, -2);
+  else if (value.endsWith("\n")) value = value.slice(0, -1);
+  // One token only: whitespace means a label such as "Bearer", a second
+  // token or a second line.
+  if (!TOKEN.test(value)) return stop("invalid_input", "agent_token_malformed");
+  return { ok: true, token: value };
+}

package/src/approval-handoff.js

@@ -19,6 +19,11 @@ import { envelope, toJsonLine } from "./output.js";
 const BIN = fileURLToPath(new URL("../bin/metergraph.js", import.meta.url));
 const WAITER = "METERGRAPH_APPROVAL_WAITER";
 
+// True in the detached waiter that handOff starts.
+export function isApprovalWaiter(env = process.env) {
+  return env[WAITER] === "1";
+}
+
 export function handsOff(argv, env = process.env) {
   if (env[WAITER] === "1") return false;
   const parsed = parseArgs(argv);