sediment-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{sediment_cli-0.2.0 → sediment_cli-0.4.0}/.gitignore

@@ -13,8 +13,7 @@ exports/
 !docs/exports/
 .env
 .DS_Store
-.claude/settings.local.*
-.claude/worktrees/
+.claude/
 
 # Deployment-local compose overrides (mirror credentials etc.) — never in PRs
 compose.override.yml
@@ -29,4 +28,3 @@ litellm/config.local.yaml
 !.env.example
 .agents/
 skills-lock.json
-.claude/skills/asd-ste100

{sediment_cli-0.2.0 → sediment_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sediment-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: The sediment command: login, install, server, facts, exports
 Project-URL: Source, https://github.com/sediment-ai/sediment
 Project-URL: Documentation, https://github.com/sediment-ai/sediment/tree/main/docs
@@ -10,7 +10,7 @@ License-Expression: AGPL-3.0-or-later
 License-File: LICENSE
 Requires-Python: >=3.12
 Requires-Dist: httpx>=0.27
-Requires-Dist: sediment-api==0.2.0
-Requires-Dist: sediment-core==0.2.0
-Requires-Dist: sediment-derive==0.2.0
-Requires-Dist: sediment-export==0.2.0
+Requires-Dist: sediment-api==0.4.0
+Requires-Dist: sediment-core==0.4.0
+Requires-Dist: sediment-derive==0.4.0
+Requires-Dist: sediment-export==0.4.0

sediment_cli-0.4.0/hatch_build.py

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Include the MIT pi runtime in wheels and source distributions."""
+
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class PiExtensionHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        # Editable installs resolve shims/pi directly from the checkout.
+        if version == "editable":
+            return
+        root = Path(self.root)
+        bundled = root / "sediment_cli" / "_pi"
+        # A source distribution already contains the runtime as package data.
+        if bundled.is_dir():
+            return
+        source = root.parent / "shims" / "pi"
+        for name in ("index.ts", "lib", "package.json", "LICENSE", "README.md"):
+            build_data["force_include"][str(source / name)] = f"sediment_cli/_pi/{name}"

{sediment_cli-0.2.0 → sediment_cli-0.4.0}/pyproject.toml

@@ -5,7 +5,7 @@
 # Depends on sediment-api deliberately: the operator verbs are DB-local by
 # design (ADR 0001) and `server`/reports/mirror-gc forward into it.
 name = "sediment-cli"
-version = "0.2.0"
+version = "0.4.0"
 description = "The sediment command: login, install, server, facts, exports"
 requires-python = ">=3.12"
 license = "AGPL-3.0-or-later"
@@ -14,10 +14,10 @@ license-files = ["LICENSE"]
 # so an install never mixes member versions (the release workflow asserts
 # the versions agree before publishing).
 dependencies = [
-    "sediment-core==0.2.0",
-    "sediment-derive==0.2.0",
-    "sediment-export==0.2.0",
-    "sediment-api==0.2.0",
+    "sediment-core==0.4.0",
+    "sediment-derive==0.4.0",
+    "sediment-export==0.4.0",
+    "sediment-api==0.4.0",
     "httpx>=0.27",
 ]
 
@@ -37,6 +37,9 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["sediment_cli"]
 
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
 [tool.uv.sources]
 sediment-core = { workspace = true }
 sediment-derive = { workspace = true }

sediment_cli-0.4.0/sediment_cli/__init__.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""The sediment CLI — the top-level `cli/` workspace member.
+
+Remote verbs speak HTTP through `.client`; operator verbs run where the
+facts live (ADR 0001); `.attribution` is the stdlib-only stamper. The
+version is single-sourced from ``sediment_api`` (the string ``/v1/me``
+and ``/health`` report)."""
+
+import re
+
+from sediment_api import __version__ as __version__
+
+# The release policy's two shapes, X.Y.Z and X.Y.ZrcN, in ASCII digits.
+_RELEASE_VERSION = re.compile(r"[0-9]+\.[0-9]+\.[0-9]+(?:rc[0-9]+)?")
+# A release candidate pins these at the same pre-release; uv admits a
+# pre-release only when a direct requirement names it.
+_FIRST_PARTY_DEPENDENCIES = (
+    "sediment-api",
+    "sediment-capture",
+    "sediment-core",
+    "sediment-derive",
+    "sediment-export",
+)
+
+
+def install_command(version: str) -> str:
+    """The installer's uv command pinned to *version*.
+
+    A pinned install replaces the tool in either direction. `uv tool upgrade`
+    keeps an earlier pin and otherwise moves only to the newest release.
+    """
+    command = f"uv tool install --python 3.12 --upgrade 'sediment-cli=={version}'"
+    if re.fullmatch(r"[0-9.]+rc[0-9]+", version):
+        command += "".join(
+            f" --with '{name}=={version}'" for name in _FIRST_PARTY_DEPENDENCIES
+        )
+    return command
+
+
+def version_skew_advice(server_version: object, client_version: str) -> str | None:
+    """How to match the server's version, or None when it matches or is absent.
+
+    The server controls *server_version*; only a release version reaches the
+    copyable command, so a server can't put shell syntax or terminal control
+    characters into it.
+    """
+    if server_version is None or server_version == client_version:
+        return None
+    if not isinstance(server_version, str) or not _RELEASE_VERSION.fullmatch(
+        server_version
+    ):
+        return (
+            f"server reported an unrecognized version; client is {client_version}. "
+            f"Install your deployment's release: {install_command('<version>')}"
+        )
+    return (
+        f"server version {server_version} differs from client {client_version}; "
+        f"install the server's version: {install_command(server_version)}"
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Refuse unsupported capture installation before importing POSIX operators."""
+    import os
+    import sys
+
+    args = sys.argv[1:] if argv is None else argv
+    if os.name == "nt" and args[:1] == ["install"]:
+        from .attribution import main as run
+    else:
+        from .cli import main as run
+    return run(args)

sediment_cli-0.4.0/sediment_cli/_pi/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sediment
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sediment_cli-0.4.0/sediment_cli/_pi/README.md

@@ -0,0 +1,204 @@
+# sediment-pi
+
+The pi-harness shim captures agent work and retrieves evidence from a previous
+Session. Capture follows the Sediment client capture contract
+(`docs/agents/capture-clients.md`):
+
+| seam | behavior |
+|---|---|
+| Inference calls | `before_provider_headers` stamps the live Session identifier on requests for the configured provider and API. |
+| decisions | edit/write `tool_execution_end` (no error) → `sediment.tool_decision` record to `POST $SEDIMENT_OTLP_ENDPOINT/v1/logs`. Always `accept` / `explicit=false` — stock pi has no human approval gesture, and a gesture we cannot observe is absent, never guessed at. |
+| attribution | edit/write `tool_execution_end` (error or not) → `sediment mark --tool pi` with `{session_id, cwd}` on stdin |
+| transcripts | When `SEDIMENT_PI_TRANSCRIPTS=1`, `session_shutdown` (except `reason: "reload"`, which tears down the extension runtime, not the Session) → `sediment transcript --agent pi` with `{session_id, transcript_path}` on stdin |
+
+Capture failures never throw into the harness. Each channel reports failures
+independently; Attribution doesn't prove a missing Decision or Edit observation.
+With `SEDIMENT_DELIVERY_DIR`, the shared Python helper retains prepared Decision
+and opted-in transcript payloads before delivery. Without it, delivery is best-effort.
+
+## Install
+
+Use pi 0.84.1 or later with Node 24. Node 22.18 or later in the Node 22
+release line is also supported. The shim rejects other Node release lines.
+The shim has no runtime package dependencies and doesn't require `npm install`.
+Your pi installation is a separate prerequisite: inventory its packages and
+support status before installing it in your deployment.
+
+The `sediment-cli` wheel includes the extension's TypeScript source, package
+manifest, README, and MIT license. Its SPDX headers remain intact. No build or
+dependency installation runs on the developer machine. Start pi once to create
+`~/.pi/agent`, then run:
+
+```
+sediment install <repo>
+```
+
+The command registers the packaged extension in `~/.pi/agent/settings.json`
+(`extensions` list) alongside the Git hooks and detected agent hooks. Editable
+source installations register `shims/pi/` instead. `uninstall --agents` removes
+the entry. With pi present, `doctor` reports `FAIL` if the extension is missing
+or unregistered. Keep `sediment` on PATH when you start pi.
+
+## Opt in to Edit observations
+
+Transcript capture sends applied edit text and observed file text. Decision
+capture and Attribution don't authorize that content capture.
+
+To opt in, run `sediment install --transcripts <repo>`.
+Load the generated environment before you restart pi.
+
+If you use `--no-env`, set the endpoint, token, and explicit content opt-in in
+the environment that starts pi:
+
+```bash
+export SEDIMENT_OTLP_ENDPOINT=https://sediment-api.example.com
+export SEDIMENT_INGEST_TOKEN='<deployment token>'
+export SEDIMENT_PI_TRANSCRIPTS=1
+```
+
+An existing pi installation that supplies only an endpoint and token continues
+to send Developer decisions and mark Attribution. To continue Edit observations,
+you must opt in to transcript content with `SEDIMENT_PI_TRANSCRIPTS=1`.
+An unset variable or any other value disables transcript extraction.
+
+## Retrieve context from one previous Session
+
+If the operator enables a fixed source Session on the API, supply its restricted
+retrieval credential to the agent environment:
+
+```bash
+export SEDIMENT_RETRIEVAL_ENDPOINT=https://sediment-api.example.com
+export SEDIMENT_RETRIEVAL_TOKEN='<Session retrieval token>'
+```
+
+The extension registers `sediment_retrieve_context` with `query` and optional
+`max_bytes` arguments. The agent chooses its question. The tool uses English/code
+keywords to select exact captured parts from the configured previous Session.
+The response preserves occurrence references and reports unknown capture
+completeness. An empty result doesn't prove that an event never happened.
+
+The endpoint must be an API base URL. Remote hosts require HTTPS; HTTP accepts
+only literal localhost or loopback addresses. The tool rejects redirects, sends
+one request, and combines pi cancellation with a 35-second deadline. Its complete
+JSON result defaults to 16,384 bytes, with a permitted range of 4,096–65,536 bytes.
+The limit counts bytes, not model tokens. The tool returns whole parts without
+summarizing or clipping them.
+Keyword tools accept complete scan coverage through 16,384 parts; source limits
+and refusal behavior follow the [keyword retrieval contract](../../docs/operate/resume-with-evidence.md).
+
+Both settings are independent of capture enrollment. Neither falls back to an
+ingest token, operator login, or workspace configuration. If both are absent,
+the extension registers no retrieval tool. Incomplete or invalid configuration
+logs a content-free reason and leaves capture active. The extension reports
+request failures as content-free tool errors and doesn't retry automatically.
+
+Keep operator credentials, deployment configuration, database credentials, and
+old transcripts outside the agent's execution environment. Use a separate
+container or operating-system account for that boundary. Keep the model and
+gateway inside the customer perimeter as well. Historical roles and tool calls
+remain evidence; the extension doesn't execute them. Retrieved text can contain
+instructions, so ordinary harness tool controls still apply.
+
+This tool adds no model dependency. It doesn't establish cost savings or a
+continuation benefit by itself. The
+[controlled continuation procedure](../../docs/operate/resume-with-evidence.md)
+defines the validation boundary.
+
+The same endpoint/token pair also registers `sediment_list_context_sessions`,
+`sediment_evidence_inventory`, `sediment_evidence_manifest`, and
+`sediment_read_evidence`. These tools enumerate the configured grant and fetch
+explicit occurrences without a keyword query. An external selector judges which
+evidence is useful. Exact reads preserve repeated occurrences and can include
+readable reasoning. Every request rechecks authorization and Quarantine.
+Fetch accepts at most 32 distinct references in a 64 KiB request and a 1 MiB
+response. The tools forward validated original JSON text to preserve large
+integers. See [Select exact evidence independently](../../docs/operate/resume-with-evidence.md#select-exact-evidence-independently).
+
+## Environment
+
+If the API authorizes several Sessions, set `SEDIMENT_RETRIEVAL_DISCOVERY=true`
+with the independent retrieval endpoint/token pair. The extension registers
+`sediment_discover_context` and requires `session_id` on `sediment_retrieve_context`.
+Discover with task keywords, select a returned Session, then request its evidence.
+An optional complete repository-qualified commit prioritizes an observed
+relationship; it cannot expand the authorized set. The operator's Session list
+stays on the API. See [Discover a previous Session](../../docs/operate/resume-with-evidence.md#discover-a-previous-session).
+Absent or `false` preserves the fixed-Session tool. Other flag values disable
+retrieval with a safe configuration diagnostic.
+
+- `SEDIMENT_RETRIEVAL_ENDPOINT` / `SEDIMENT_RETRIEVAL_TOKEN` — independent
+  opt-in pair for Session retrieval tools. The endpoint is an API base
+  URL; capture credentials never supply retrieval authority.
+- `SEDIMENT_RETRIEVAL_DISCOVERY` — `true` enables candidate discovery and explicit
+  Session selection; absent or `false` retains the fixed-Session schema.
+- `SEDIMENT_PROVIDER_ID` / `SEDIMENT_PROVIDER_API` — provider and API that receive
+  the Session header (defaults `sediment` / `anthropic-messages`). The native
+  header hook reads the Session identifier for each request. It replaces stale
+  Session headers and preserves all other headers. If the identifier is absent
+  or invalid for an HTTP header, the shim omits it and logs a content-free
+  diagnostic. Decision capture and Attribution continue independently.
+- `SEDIMENT_OTLP_ENDPOINT` — ingest base URL. Required for decision capture;
+  unset means not opted in (there is deliberately no
+  `OTEL_EXPORTER_OTLP_ENDPOINT` fallback — see the contract doc). Remote hosts
+  require HTTPS. Plain HTTP accepts only literal `localhost`, IPv4 loopback,
+  or `[::1]`; authenticated POSTs reject redirects.
+- `SEDIMENT_INGEST_TOKEN` — bearer token (falls back to an `Authorization`
+  header in `OTEL_EXPORTER_OTLP_HEADERS`, only ever sent to the explicit
+  endpoint above).
+- `SEDIMENT_PI_TRANSCRIPTS` — explicit content opt-in. Only the exact value
+  `1` enables transcript extraction. It doesn't change decision capture,
+  Attribution, or gateway Session identity.
+- `SEDIMENT_EXTRACT_ON_SETTLE` — a nonempty value also extracts on
+  `agent_settled`, provided `SEDIMENT_PI_TRANSCRIPTS=1`. Set it only for hosts
+  that use one Session per task. An interactive Session can settle before its
+  final edit; first-write-wins storage would retain that earlier observation.
+  A runtime reload never triggers transcript extraction.
+- `OTEL_RESOURCE_ATTRIBUTES` — `user.id` is forwarded as resource identity.
+- `SEDIMENT_SCRIPT_DIR` — fallback directory containing
+  `sediment_attribution.py`, `sediment_transcript.py`, and `sediment_delivery.py`.
+  Copy the delivery implementation from `cli/sediment_cli/delivery.py`, not the
+  checkout shim. The shim prefers an
+  installed `sediment` executable on `PATH`. Without one, each source-checkout
+  script resolves independently, so a missing transcript client doesn't
+  disable attribution.
+- `SEDIMENT_PYTHON` — interpreter for the Python clients (default
+  `python3`; stdlib-only, any 3.12+ works).
+- `SEDIMENT_DELIVERY_DIR` — opt-in private prepared-payload storage. Run
+  `sediment delivery replay --watch` under your existing process supervisor.
+  Startup requests a bounded drain; it doesn't install a background service.
+  See [Sender replay operations](../../docs/capture/local-capture.md#preserve-prepared-payloads-through-outages)
+  for content consent, limits, retention, active credentials, and recovery.
+
+Child processes have a bounded deadline. On macOS and Linux, the runner stops
+its owned process group, including descendants. Spawn, stdin, timeout, and
+nonzero-exit failures produce content-free channel diagnostics. The runner drains
+stderr without relaying its contents. A successful enqueue requires a matching
+structured acknowledgment; exit zero alone doesn't prove durable acceptance.
+Pi explicitly requests the shared helper's storage-fault fallback. If private
+storage is unsafe, unavailable, or busy, one direct attempt preserves the prepared
+Decision. A validated direct acknowledgment reports `best_effort` and its storage
+reason. Capacity and identity declines remain failures. Repair storage even when
+the direct send succeeds; that send has no durable recovery guarantee.
+
+## Develop
+
+```
+npm ci
+npm test           # node --test (type stripping; Node 24 or Node 22.18+)
+npm run typecheck  # tsc --noEmit
+```
+
+The `shims` workflow builds and installs Sediment wheels. Its tests load the
+registered extension through pi's native loader outside the checkout and verify
+capture through the installed command. Packaging, registration, and shared Python
+delivery changes also trigger this workflow. To exercise the same tests locally,
+set `SEDIMENT_PI_TEST_PYTHON` to the installed environment's Python executable
+and `SEDIMENT_PI_TEST_INSTALLED_BIN` to its `bin` directory before `npm test`.
+
+The lockfile pins pi 0.87.1 (`@earendil-works/pi-coding-agent`) as a development
+dependency. The native retrieval test exercises its extension registration,
+argument validation, agent loop, and model-visible tool result with a scripted
+model stream. It makes no paid inference request and downloads no package during
+the test. Run these native checks on Node 24; pi's own minimum is Node 22.19.
+Runtime extension imports remain standard-library imports; pi types are erased.
+Source installation still needs no shim `node_modules` directory.

sediment_cli-0.4.0/sediment_cli/_pi/index.ts

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: MIT
+// sediment-pi — the pi-harness shim for Sediment capture.
+//
+// Closes pi's capture gaps client-side, per docs/agents/capture-clients.md:
+//   decisions    — edit-tool executions emit sediment.tool_decision records
+//                  to $SEDIMENT_OTLP_ENDPOINT/v1/logs, through the Python
+//                  delivery helper when buffering is enrolled (accepted,
+//                  explicit=false: stock pi has no human approval gesture)
+//   attribution  — edit-tool executions invoke sediment_attribution.py
+//                  `mark --tool pi` (the stamper is tool-agnostic)
+//   transcripts  — session_shutdown invokes sediment_transcript.py
+//                  `--agent pi` (the pair is the fact; ADR 0007)
+//   completions  — the native provider-header event attaches the current
+//                  Session to requests for the configured gateway
+//
+// All capture is best-effort: a failure degrades the signal to the
+// notes/jaccard backstop and must never break the agent.
+
+import { accessSync, constants, existsSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  register,
+  type CaptureProgram,
+  type Deps,
+  type PiLike,
+} from "./lib/register.ts";
+import { runCaptureProcess } from "./lib/process.ts";
+import { registerRetrieval } from "./lib/retrieval.ts";
+
+const POST_TIMEOUT_MS = 10_000;
+const MAX_ACKNOWLEDGMENT_BYTES = 16_384;
+
+async function post(
+  url: string,
+  payload: unknown,
+  token: string | null,
+): Promise<void> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(payload),
+    redirect: "error",
+    signal: AbortSignal.timeout(POST_TIMEOUT_MS),
+  });
+  if (response.status !== 200 || !response.body) {
+    await response.body?.cancel();
+    throw new Error("invalid_acknowledgment");
+  }
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let bytes = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytes += value.length;
+      if (bytes > MAX_ACKNOWLEDGMENT_BYTES) {
+        throw new Error("invalid_acknowledgment");
+      }
+      chunks.push(value);
+    }
+    const acknowledgment = JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)),
+    );
+    // OTLP acknowledgment describes delivery, never the number of Facts.
+    if (
+      !acknowledgment || Array.isArray(acknowledgment) ||
+      typeof acknowledgment !== "object" || Object.keys(acknowledgment).length !== 0
+    ) {
+      throw new Error("invalid_acknowledgment");
+    }
+  } finally {
+    await reader.cancel();
+  }
+}
+
+function runScript(
+  script: string | CaptureProgram,
+  args: string[],
+  stdin: unknown,
+  captureOutput = false,
+): Promise<string> {
+  // ponytail: PATH python3 (overridable via SEDIMENT_PYTHON) — the scripts
+  // are stdlib-only, so any 3.12+ interpreter runs them; the stamper's hook
+  // fragments pin sys.executable instead because hooks fire in bare envs.
+  const python = process.env.SEDIMENT_PYTHON ?? "python3";
+  const executable = typeof script === "string" ? python : script.executable;
+  const commandArgs =
+    typeof script === "string"
+      ? [script, ...args]
+      : [...script.arguments, ...args];
+  return runCaptureProcess(executable, commandArgs, stdin, captureOutput);
+}
+
+function findSediment(): string | null {
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, "sediment");
+    try {
+      accessSync(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+      // Try the next PATH entry.
+    }
+  }
+  return null;
+}
+
+function resolveScripts(): Deps["scripts"] {
+  const sediment = findSediment();
+  if (sediment) {
+    return {
+      attribution: { executable: sediment, arguments: [] },
+      transcript: { executable: sediment, arguments: ["transcript"] },
+      delivery: { executable: sediment, arguments: ["delivery"] },
+    };
+  }
+  // Default: installed in place, <repo>/shims/pi/index.ts → <repo>/scripts.
+  const dir =
+    process.env.SEDIMENT_SCRIPT_DIR ||
+    join(dirname(fileURLToPath(import.meta.url)), "..", "..", "scripts");
+  const attribution = join(dir, "sediment_attribution.py");
+  const transcript = join(dir, "sediment_transcript.py");
+  const delivery = join(dir, "sediment_delivery.py");
+  const resolved = {
+    attribution: existsSync(attribution) ? attribution : null,
+    transcript: existsSync(transcript) ? transcript : null,
+    delivery: existsSync(delivery) ? delivery : null,
+  };
+  if (!resolved.attribution)
+    console.error("sediment-pi: attribution capture degraded (script not found)");
+  if (!resolved.transcript)
+    console.error("sediment-pi: transcript capture degraded (script not found)");
+  return resolved.attribution || resolved.transcript || resolved.delivery
+    ? resolved : null;
+}
+
+export default function (pi: PiLike & Parameters<typeof registerRetrieval>[0]) {
+  const version = /^(22|24)\.(\d+)\.\d+$/.exec(process.versions.node);
+  if (!version || (version[1] === "22" && Number(version[2]) < 18)) {
+    console.error("sediment-pi: unsupported Node runtime; use Node 24 or Node 22.18+");
+    return;
+  }
+  registerRetrieval(pi, process.env);
+  register(pi, {
+    post,
+    runScript,
+    scripts: resolveScripts(),
+    env: process.env,
+    now: Date.now,
+  });
+}