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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sediment-cli
-Version: 0.2.0
+Version: 0.3.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.3.0
+Requires-Dist: sediment-core==0.3.0
+Requires-Dist: sediment-derive==0.3.0
+Requires-Dist: sediment-export==0.3.0

sediment_cli-0.3.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.3.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.3.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.3.0",
+    "sediment-derive==0.3.0",
+    "sediment-export==0.3.0",
+    "sediment-api==0.3.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.3.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.3.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.86.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.3.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,
+  });
+}

sediment_cli-0.3.0/sediment_cli/_pi/lib/contract.ts

@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: MIT
+// The Sediment client capture contract (docs/agents/capture-clients.md) —
+// pure builders and env resolution. No I/O here; the wiring lives in
+// lib/register.ts. The shapes emitted here are pinned against the golden
+// server-side conformance fixture
+// (packages/capture/tests/fixtures/otlp/sediment/tool_decision.json).
+
+import { dirname } from "node:path";
+
+export const DECISION_EVENT = "sediment.tool_decision";
+
+// The contract scopes decisions to edit tools; reads stay out.
+export const EDIT_TOOLS: ReadonlySet<string> = new Set(["edit", "write"]);
+
+export type AnyValue = { stringValue: string } | { boolValue: boolean };
+
+export interface OtlpAttribute {
+  key: string;
+  value: AnyValue;
+}
+
+export interface OtlpRecord {
+  body: { stringValue: string };
+  timeUnixNano: string;
+  attributes: OtlpAttribute[];
+}
+
+export interface LogsPayload {
+  resourceLogs: [
+    {
+      resource: { attributes: OtlpAttribute[] };
+      scopeLogs: [{ logRecords: OtlpRecord[] }];
+    },
+  ];
+}
+
+export interface DecisionInput {
+  agent: string;
+  sessionId: string;
+  callId: string;
+  toolName: string;
+  decision: "accept" | "reject";
+  explicit: boolean;
+  filePath: string;
+  timeUnixNano: string;
+}
+
+export function buildDecisionRecord(input: DecisionInput): OtlpRecord {
+  const strings: Record<string, string> = {
+    agent: input.agent,
+    "session.id": input.sessionId,
+    tool_use_id: input.callId,
+    tool_name: input.toolName,
+    decision: input.decision,
+    file_path: input.filePath,
+  };
+  const attributes: OtlpAttribute[] = Object.entries(strings).map(
+    ([key, value]) => ({ key, value: { stringValue: value } }),
+  );
+  // explicit must stay a real bool on the wire — the server requires it.
+  attributes.push({ key: "explicit", value: { boolValue: input.explicit } });
+  return {
+    body: { stringValue: DECISION_EVENT },
+    timeUnixNano: input.timeUnixNano,
+    attributes,
+  };
+}
+
+export function buildLogsPayload(
+  records: OtlpRecord[],
+  resourceAttrs: Record<string, string>,
+): LogsPayload {
+  return {
+    resourceLogs: [
+      {
+        resource: {
+          attributes: Object.entries(resourceAttrs).map(([key, value]) => ({
+            key,
+            value: { stringValue: value },
+          })),
+        },
+        scopeLogs: [{ logRecords: records }],
+      },
+    ],
+  };
+}
+
+export interface Env {
+  [key: string]: string | undefined;
+}
+
+/**
+ * The ingest endpoint, or null when not opted in. Deliberately NO
+ * OTEL_EXPORTER_OTLP_ENDPOINT fallback: /v1/logs is the standard OTLP path,
+ * so any collector in the machine's generic telemetry config would silently
+ * accept decision records bound for Sediment. Explicit opt-in only (same
+ * posture as the Python clients).
+ */
+export function resolveEndpoint(env: Env): string | null {
+  // WHATWG URL parsing tolerates surrounding whitespace, so trim before the
+  // slash-strip — mirrors the Python sibling (cli/sediment_cli/transcript.py).
+  const base = (env.SEDIMENT_OTLP_ENDPOINT ?? "").trim().replace(/\/+$/, "");
+  if (!base) return null;
+  let endpoint: URL;
+  try {
+    endpoint = new URL(base);
+  } catch {
+    return null;
+  }
+  const host = endpoint.hostname.toLowerCase();
+  const ipv4Loopback = /^127(?:\.\d{1,3}){3}$/.test(host);
+  const loopback =
+    host === "localhost" || host === "::1" || host === "[::1]" || ipv4Loopback;
+  if (
+    !["http:", "https:"].includes(endpoint.protocol) ||
+    endpoint.username ||
+    endpoint.password ||
+    endpoint.search ||
+    endpoint.hash ||
+    !["/", "/v1/logs"].includes(endpoint.pathname) ||
+    (endpoint.protocol === "http:" && !loopback)
+  ) {
+    return null;
+  }
+  return base.endsWith("/v1/logs") ? base : `${base}/v1/logs`;
+}
+
+/** Pairs of an OTLP-spec list: `Key=url-encoded-value,Key2=...`. */
+function* pairs(list: string | undefined): Generator<[string, string]> {
+  for (const part of (list ?? "").split(",")) {
+    const eq = part.indexOf("=");
+    if (eq >= 0) yield [part.slice(0, eq).trim(), part.slice(eq + 1).trim()];
+  }
+}
+
+export function resolveToken(env: Env): string | null {
+  const token = env.SEDIMENT_INGEST_TOKEN;
+  if (token) return token;
+  // Safe to read the machine's generic OTLP headers here: the token is only
+  // ever sent to the explicit sediment endpoint above.
+  for (const [key, value] of pairs(env.OTEL_EXPORTER_OTLP_HEADERS)) {
+    if (key.toLowerCase() !== "authorization") continue;
+    const decoded = decodeURIComponent(value);
+    const space = decoded.indexOf(" ");
+    const scheme = space < 0 ? decoded : decoded.slice(0, space);
+    const credential = space < 0 ? "" : decoded.slice(space + 1).trim();
+    if (scheme.toLowerCase() === "bearer" && credential) return credential;
+  }
+  return null;
+}
+
+export function resourceUserId(env: Env): string | null {
+  for (const [key, value] of pairs(env.OTEL_RESOURCE_ATTRIBUTES)) {
+    if (key === "user.id" && value) return value;
+  }
+  return null;
+}
+
+/**
+ * The decision a tool_execution_end carries, or null when there is none to
+ * emit. Stock pi has no human approval gesture, so an applied edit is an
+ * implicit accept; an errored execution never touched the file and emits
+ * nothing (absent, never guessed at).
+ */
+export function decisionFromToolEnd(
+  toolName: string,
+  isError: boolean,
+): { decision: "accept"; explicit: false } | null {
+  if (!EDIT_TOOLS.has(toolName) || isError) return null;
+  return { decision: "accept", explicit: false };
+}
+
+/** file_path from tool args; "" when unobservable (the reject convention). */
+export function filePathFromArgs(args: unknown): string {
+  if (typeof args !== "object" || args === null) return "";
+  const path = (args as Record<string, unknown>).path;
+  return typeof path === "string" ? path : "";
+}
+
+/**
+ * The cwd `mark` should run in: the edited file's directory when the path is
+ * absolute, else the session cwd. ACP agents edit clones beneath the
+ * workspace root — the session cwd is not a git repo, so `mark` there heals
+ * nothing. Any directory inside the repo works: git walks up to the repo
+ * root.
+ */
+export function markCwd(filePath: string, sessionCwd: string): string {
+  return filePath.startsWith("/") ? dirname(filePath) : sessionCwd;
+}