@basein/runner 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,276 @@
+# BaseInstRunnerMCP
+
+A recording MCP **proxy**. It sits between any MCP client (Claude Code, Cursor,
+Codex, an Agent SDK session) and every MCP server that client uses, executes each
+call on the client's behalf, and records the run as a reusable scenario in the
+BaseIn service.
+
+The design this implements is [docs/BaseInstRunner.md](docs/BaseInstRunner.md).
+This README is the operator's half: how to run it, what it records, and what it
+cannot. For v2 — running a calculated scenario when a prompt means the same thing
+as one you have run before — see [docs/calculatedReplay.md](docs/calculatedReplay.md)
+and its runbook [docs/calculatedReplayGuide.md](docs/calculatedReplayGuide.md).
+
+```
+model ──mcp__chrome-devtools__*──▶ bir-proxy ──stdio/http──▶ chrome-devtools-mcp
+hooks ──built-ins, prompt, stop──▶ bir-hooks (control server) ──▶ BaseIn /recordings/*
+                                        ▲
+                          bir-proxy ────┘  step reports
+```
+
+---
+
+## Install
+
+On a runner machine, one command does machine, account and project scope:
+
+```powershell
+.\scripts\install-runner.ps1 C:\work\repo -AuthUrl https://your-basein-service   # Windows
+```
+
+```bash
+BIR_AUTH_URL=https://your-basein-service ./scripts/install-runner.sh ~/work/repo  # macOS/Linux
+```
+
+Step by step, for one machine: [docs/quickstart.md](docs/quickstart.md).
+For a fleet — packaging, releases, offline installs, updates:
+[docs/installRun.md](docs/installRun.md).
+
+By hand, or when developing BaseInstRunner itself:
+
+```bash
+npm i -g @basein/runner          # or: npm install && npm run build, in a checkout
+cd the-project-you-record-from
+bir install --global             # --local from a checkout; plain `bir install` writes a pinned npx entry
+```
+
+`bir install` rewrites your MCP entries in place, keeping every key (so
+`mcp__<server>__<tool>` names never change), and wires Claude Code's hooks. It
+stashes the original text of every file first — `bir uninstall` puts it back
+byte-for-byte.
+
+```bash
+export BIR_AUTH_URL=https://your-basein-service   # required to record anything
+bir login                                        # once
+bir-hooks                                        # leave running; Ctrl-C to stop
+claude                                           # your session, now recorded
+```
+
+Check it:
+
+```bash
+bir status     # what is wrapped, and which config scope won
+bir doctor     # is it working *right now* — exits non-zero if not
+```
+
+### Any other MCP client
+
+Nothing here knows where Cursor or Codex keep their settings, and it does not
+guess. Two paths:
+
+```bash
+bir install --config /path/to/that/client/mcp.json
+bir wrap --server-name my-server -- node my-server.js    # prints an entry to paste
+```
+
+---
+
+## The two tiers
+
+Only Claude Code has hooks, so run ownership is negotiated at proxy startup.
+
+| Tier | When | Records |
+|---|---|---|
+| **1 — Bound** | a control server (`bir-hooks`) is discoverable for this cwd | built-ins **and** MCP, one ordered step stream, prompt and final answer |
+| **2 — Standalone** | no control server within 5 s | MCP calls only — no prompt, no final answer, no built-in steps |
+
+Tier 2 is not a bug; it is the honest ceiling of what an MCP proxy can observe. A
+run records which tier produced it in `metadata.tier`, so nothing downstream
+mistakes a partial trace for a complete one.
+
+Steps taken while the tier is still being decided are **buffered**, not dropped —
+the host may spawn MCP servers before `SessionStart` fires, and the ordering
+between the two is not guaranteed.
+
+---
+
+## What it will not do
+
+- **Non-MCP tools without the hook binary.** `Bash`, `Read`, `Edit` and friends
+  are not MCP traffic. An MCP server sees only MCP traffic addressed to it. That
+  is a structural fact, not a limitation of this implementation.
+- **`claude-in-chrome`.** It is `scope: "dynamic"`, present in no config file, so
+  there is no entry to rewrite.
+- **Replay, unless you turn it on.** Recording is the default and the whole of
+  what runs out of the box. Calculated replay — running a matched prompt's
+  scenario instead of rediscovering it — ships, but needs `bir install --replay`
+  *and* `BIR_REPLAY=1`, for the reason in the next section.
+- **Change what the model does.** Tool descriptions are never edited. The
+  model-visible changes are schema relaxation, below, and — only with
+  `--replay` — one first-party tool.
+
+---
+
+## Calculated replay
+
+When the service recognises that a prompt means the same thing as one you have
+run before, it hands back the *calculated scenario* derived from that earlier
+run: an intent, a parameter schema, and one bit of logic per step that recomputes
+that step's arguments. `bir` can run it instead of letting the model rediscover
+the plan token by token.
+
+The design is [docs/calculatedReplay.md](docs/calculatedReplay.md); the runbook —
+record, calculate, check, enable, read the audit lines — is
+[docs/calculatedReplayGuide.md](docs/calculatedReplayGuide.md).
+
+```bash
+bir install --replay      # adds the `bir` MCP server; raises the prompt-hook timeout
+BIR_REPLAY=1 bir-hooks    # and this is the switch
+```
+
+Two switches, not one, because of what replay is: **a scenario is a pre-approved
+list of tool calls with computed arguments.** A steered step is answered
+`permissionDecision: "allow"`, so a pinned `Bash` or `Edit` runs without the
+prompt you would have seen. A *directly executed* step never reaches the
+permission system at all — it is dispatched to a `bir-proxy` and called on a
+connection that is already open. Set `BIR_REPLAY_ALLOW_SERVERS` to the servers
+you are content to have called unattended, and read
+[the guide's §5.1](docs/calculatedReplayGuide.md) before enabling it anywhere
+that matters.
+
+What it buys: on a scenario whose every step is a wrapped MCP tool, the whole
+sequence runs through connections the proxies already hold — **zero model tokens**
+— and the model's only job is one tool call that reads the results. Mixed
+scenarios steer the live session instead, pinning each step's arguments. Either
+way the turn reports what it cost, so the savings ledger measures something real.
+
+---
+
+## Two things to know before you turn it on
+
+**1. Correlation auto-approves wrapped MCP calls.** Merging the hook's view of a
+call with the proxy's requires carrying an id through the tool's arguments, and
+the mechanism for that is answering `PreToolUse` with
+`permissionDecision: "allow"`. That skips a permission prompt you might otherwise
+have seen for those tools. To keep the prompt:
+
+```bash
+BIR_CORRELATION_DECISION=ask bir-hooks
+```
+
+Hosts that ignore `updatedInput` on a non-allow decision then fall back to
+fingerprint matching, which is lossy under identical concurrent calls.
+
+**2. Schema relaxation is visible to the model.** Carrying that id means adding
+`additionalProperties: true` plus one declared key to each wrapped tool's schema,
+on every call — not only recorded ones. It is applied **only** in Tier 1 with
+correlation active, and **only** to wrapped servers. `--no-correlation` turns it
+off entirely and joins on `(server, tool, hash(args))` inside a 30 s window
+instead.
+
+---
+
+## Configuration
+
+| Variable | Effect |
+|---|---|
+| `BIR_AUTH_URL` | BaseIn auth-service. **Unset means nothing is recorded** — everything else still works. |
+| `BIR_AUTH_DISABLE=1` | Skip authentication (local dev / CI). |
+| `BIR_CONTROL_PORT` | Preferred control-server port (default 53411). |
+| `BIR_CONTROL_URL` / `BIR_CONTROL_TOKEN` | Point a proxy at a control server directly, bypassing discovery. Injected into generated config; the only reliable channel for an SDK session. |
+| `BIR_CORRELATION_DECISION` | `allow` (default) or `ask` — see above. |
+| `BIR_NO_CORRELATION=1` | Never inject a call id. |
+| `BIR_HOME` | Where state lives (default `~/.baseinstrunner`). |
+| `BIR_CLAUDE_JSON` | Override the `~/.claude.json` location. |
+| `BIR_VERBOSE=1` | Per-message detail lines on stderr. |
+
+Calculated replay adds these, all read by `bir-hooks` only — the proxies are told
+what to do when they register, so there is one switch and no second copy of it:
+
+| Variable | Effect |
+|---|---|
+| `BIR_REPLAY=1` | Enable replay. Nothing below matters until it is set. |
+| `BIR_REPLAY_ALLOW_SERVERS` | Server keys eligible for **direct** execution. Unset means every wrapped server; setting it is the recommendation. |
+| `BIR_MIN_STEER_SIMILARITY` | Minimum match similarity to replay (default `0.92`, above the service's own `0.9` detection threshold). |
+| `ANTHROPIC_API_KEY` | Enables parameter derivation. Without it, replay uses the scenario's recorded sample values — free, and often still correct. |
+| `BIR_DERIVE_MODEL` | Derivation model (default `claude-haiku-4-5-20251001`). |
+| `BIR_MATCH_BUDGET_MS` | How long the prompt hook waits for a match (default `2500`). |
+| `BIR_DERIVE_BUDGET_MS` | How long the first `PreToolUse` waits for parameters (default `8000`). |
+| `BIR_REPLAY_BUDGET_MS` / `BIR_STEP_TIMEOUT_MS` | Whole-plan and per-step ceilings for direct execution (default `120000` / `60000`). |
+
+### The audit log
+
+Every decision is one `key=value` line on **stderr** — never stdout, which is the
+host's JSON-RPC stream. There is no file sink to configure; persistence is the
+shell's job:
+
+```bash
+bir-hooks 2>&1 | tee -a ~/.baseinstrunner/audit.log
+grep run.lossy ~/.baseinstrunner/audit.log
+```
+
+---
+
+## Failure behaviour
+
+The governing rule: **a host session never fails because of BaseInstRunner.**
+
+| Failure | Behaviour |
+|---|---|
+| Control server unreachable at startup | buffer ≤ 5 s, then Tier 2; logged once |
+| Control server dies mid-session | the proxy switches to Tier 2 for the rest; run flagged lossy |
+| Recorder HTTP fails | send dropped and logged; never retried inline |
+| Upstream fails to start | `initialize` still answers; requests return an error — one broken server, not a broken session |
+| Upstream dies mid-call | `isError: true` with the transport message, so the model can react |
+| Unknown JSON-RPC method | forwarded; any rejection is relayed back |
+| Step queue overflow | oldest dropped, run flagged lossy |
+| Host sends unparseable input | `-32700` and the relay keeps going |
+
+---
+
+## Development
+
+```bash
+npm run build       # src → dist
+npm test            # 233 tests: transcript identity, passthrough, correlation, config, replay
+npm run typecheck
+npm run test:smoke  # end-to-end replay with real processes (needs build + pretest first)
+```
+
+The core test is **transcript identity**: the same scripted conversation is run
+against a fake upstream directly and through the proxy, and every host-visible
+message must match. If a change breaks transparency, that test says so first.
+
+`test/smoke-replay.mjs` is the other one worth running by hand. Everything else
+runs in-process; this starts a stand-in BaseIn service, a real `bir-hooks`, a real
+`bir-proxy` wrapping a real MCP server and a real `bir-scenario`, then drives a
+two-step scenario through actual stdio. It is what catches the seams between
+processes — and it is how the "a proxy between polls is not a missing proxy" bug
+was found.
+
+`test/fake-upstream.ts` is a scriptable MCP server — arbitrary capabilities,
+prompts, resources, `list_changed` notifications, reverse-direction
+`elicitation/create`, delays, failures, and dying on command. Everything else
+builds on it.
+
+---
+
+## Known gaps
+
+- **`metadata.lossy` is the value known at run start.** A run that turns lossy
+  later says so on the audit log (`run.lossy`) and in the step gap, but the
+  metadata is not updated: the service exposes no metadata patch, and this is
+  exactly open question 1 in the design. Fixing it properly needs a server-side
+  decision, not a client-side workaround.
+- **Subagent steps are attributed, not partitioned.** `SubagentStart` /
+  `SubagentStop` give us `agent_id`, which is prefixed onto a step's `context`.
+  A real agent column is a schema change, and out of scope for v1 (D6).
+- **`--lazy` defers to the first host message, not to `tools/list`.** Deferring
+  further would mean answering `initialize` before the upstream exists — that is,
+  fabricating its capabilities, which is the thing Phase 3 exists to prevent. For
+  a client that connects at session start (Claude Code does) the flag saves
+  nothing; for one that connects on demand it saves the whole process. See
+  `src/upstream/lazy-client.ts`.
+- **Coexistence with RRepeat is untested.** Both would record the same session.
+  Runs carry `metadata.recorder`, so server-side dedupe is possible, but nothing
+  here detects the other (design §13, open question 2).

package/dist/auth/client.d.ts

@@ -0,0 +1,85 @@
+/**
+ * auth client — ported from RRepeat's `src/auth/client.ts` (Phase 4.1).
+ *
+ * Authenticates the CLI user against the BaseIn auth-service and returns a JWT
+ * session. Every recording call carries that access token; the recording's owner
+ * is the JWT subject on the server side, which is what makes tenancy work
+ * without BaseInstRunner knowing anything about it.
+ *
+ * Flow:
+ *   1. Load the cached session from ~/.baseinstrunner/credentials.json.
+ *   2. If the access token is still valid, reuse it.
+ *   3. Else if a refresh token is present, POST /auth/refresh (silent).
+ *   4. Else prompt for email + password and POST /auth/login.
+ *   5. Persist the result (mode 0600) and return it.
+ *
+ * WHY IT NEVER `process.exit`s: `bir-proxy` runs inside the host's process tree.
+ * Failing to authenticate must degrade to not-recording (§10), not kill a server
+ * the host is waiting on. Callers get `undefined` and decide.
+ *
+ * Config:
+ *   BIR_AUTH_URL      base URL of the BaseIn auth-service (required).
+ *   BIR_AUTH_DISABLE  "1" to skip auth entirely (local dev / CI).
+ */
+export interface AuthUser {
+    id: string;
+    email: string;
+    name?: string;
+}
+export interface AuthSession {
+    accessToken: string;
+    refreshToken: string;
+    /** Epoch milliseconds at which the access token expires. */
+    accessExpiresAt: number;
+    user: AuthUser;
+}
+export interface AuthenticateOptions {
+    /** Base URL of the auth service. Defaults to BIR_AUTH_URL. */
+    authUrl?: string;
+    /** Never prompt: fail (return undefined) if no valid/refreshable session exists. */
+    nonInteractive?: boolean;
+}
+/**
+ * Where the cached session lives.
+ *
+ * A **function**, not a constant: `configDir()` reads `BIR_HOME`, and freezing
+ * this at import time meant the directory we created and the file we wrote could
+ * disagree the moment anything set that variable after load — which surfaced as
+ * an ENOENT deep inside a token refresh.
+ */
+export declare function credentialsPath(): string;
+/** Load the cached session, or undefined if missing/unreadable/malformed. */
+export declare function loadCredentials(): AuthSession | undefined;
+/** Persist the session with mode 0600. */
+export declare function saveCredentials(session: AuthSession): void;
+/** Remove the cached session (`bir logout`). No-op if absent. */
+export declare function clearCredentials(): void;
+export declare function resolveAuthUrl(opts?: AuthenticateOptions): string;
+/**
+ * Follow a redirect on the base URL *once*, so a bearer token is never sent to
+ * a URL that will bounce it.
+ *
+ * WHY THIS EXISTS. A service behind a TLS-terminating proxy answers plain HTTP
+ * with `308 → https://…`. Node's `fetch` follows that, and because `http:` and
+ * `https:` are different origins the spec requires it to **strip the
+ * `Authorization` header**. The request arrives unauthenticated.
+ *
+ * The failure is maddening because sign-in works: login sends credentials in the
+ * BODY, which a 308 preserves. So `auth.ok` is printed, and then every
+ * subsequent call fails `401 {"error":"missing_token"}` — the server saying it
+ * saw no token at all, which reads like a bug in the client rather than a
+ * redirect. Observed against a Caddy-fronted deployment; the whole session
+ * recorded nothing.
+ *
+ * A same-host upgrade to https is adopted silently — it is what the operator
+ * meant. Anything else (a different host, a downgrade to http) is reported and
+ * NOT followed: quietly re-sending someone's bearer token to a host they did not
+ * configure is worse than failing.
+ */
+export declare function normalizeAuthUrl(baseUrl: string, fetchImpl?: typeof fetch): Promise<string>;
+/**
+ * Authenticate and return a valid session, or `undefined` when none can be
+ * obtained. Callers degrade to not-recording rather than failing the session.
+ */
+export declare function authenticate(opts?: AuthenticateOptions): Promise<AuthSession | undefined>;
+//# sourceMappingURL=client.d.ts.map