@alisio/plugin-telemetry 0.1.0

package/.agents/skills/telemetry/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: telemetry
+description: "Trigger: latency, token cost, tool failures, regressions, usage questions. Read bounded telemetry summaries from the local store before guessing."
+license: Apache-2.0
+metadata:
+  author: "alisio-contributors"
+  version: "1.0"
+---
+
+## Activation Contract
+
+Load this skill when a question is about how the agent has been performing, costing, or failing:
+slow turns, token usage, model mix, tool error rate, recent sessions, or a suspected regression.
+Telemetry is local-first and privacy-preserving; consult the local store through the read-only
+`telemetry_*` tools instead of guessing.
+
+## Hard Rules
+
+- Telemetry is evidence about past runs, not a substitute for reading the current code. Verify a
+  regression against the actual change before blaming it.
+- Every tool returns a bounds envelope (`returned`, `total`, `truncated`, `hint`). When `truncated`
+  is true, narrow the time window or raise `limit`; never assume the visible slice is the whole story.
+- Content search only returns text when content capture is explicitly enabled. When capture is off,
+  answer from metadata (counts, tokens, latency) and say that content is not recorded.
+- Telemetry can reveal how someone works, which repositories they use, and what they type. Treat any
+  captured content as sensitive: do not paste it elsewhere, and never enable capture without the
+  operator's explicit decision.
+- Remote export is opt-in. Local-only is the default; do not claim data left the machine unless
+  remote export is configured and a flush succeeded.
+- Never ask for or handle the OTLP credential. It exists only as an environment variable read at
+  export time.
+
+## Decision Gates
+
+| Question | Tool | Notes |
+| --- | --- | --- |
+| Overall volume, errors, latency | `telemetry_summary` | Start here; default window is one day |
+| Which models, and their token cost | `telemetry_models` | Compare input/output and cached input |
+| Which tools fail or get slow | `telemetry_tools` | Look at error rate and effects |
+| What happened recently | `telemetry_sessions` | Bounded session/run metadata |
+| Find a specific captured text | `telemetry_search` | Requires content capture |
+
+## Execution Steps
+
+1. Pick a bounded window (`windowMinutes`) and a small `limit`; start with `telemetry_summary`.
+2. Drill into `telemetry_models` and `telemetry_tools` to locate the regression.
+3. Correlate timing with a code change, then confirm by reading the code.
+4. If a store is empty or unavailable, say so plainly and continue without telemetry.
+
+## References
+
+- `README.md` in this package documents configuration, privacy defaults, and deletion.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Gutiérrez Mercado
+
+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.

package/README.md

@@ -0,0 +1,188 @@
+# @alisio/plugin-telemetry
+
+Privacy-first local agent observability for
+[Alisio](https://github.com/GustavoGutierrez/alisio). It records what the agent
+does into a local SQLite database, exposes bounded read-only query tools, and can
+optionally export OpenTelemetry-aligned data over OTLP. Local-only is the default;
+remote export is opt-in.
+
+This is an independent plugin. It is not affiliated with the OpenTelemetry
+project and claims no conformance to a stable semantic-convention release.
+
+## Install
+
+```bash
+alisio install npm:@alisio/plugin-telemetry
+```
+
+## What it does
+
+- Observes Alisio `RunEvent`s through a synchronous, non-blocking handler and
+  writes compact records to a local SQLite database.
+- Serves five read-only tools that return bounded, aggregated, privacy-preserving
+  summaries.
+- Optionally exports traces, logs and metrics to an OTLP/HTTP endpoint with
+  durable, idempotent batching.
+- Ships a `telemetry` agent skill explaining when and how to consult it.
+
+## Privacy defaults
+
+- **Metadata-only by default.** Prompt, completion, tool-argument and tool-result
+  content capture is OFF unless explicitly enabled.
+- **Local-only by default.** No network call is made until remote export is
+  enabled with an endpoint.
+- When content capture is enabled, every captured value passes through
+  allowlist-based redaction: bearer/authorization headers, tokens, private keys,
+  secrets in key/value form, absolute machine paths and (in `strict` mode) long
+  high-entropy runs are stripped, and every field is bounded. Redaction is never
+  denylist-only.
+- **The OTLP credential is never persisted, logged, returned or serialized.** It
+  is read at export time only, from the environment variable named by
+  `otlp.tokenEnv` (default `ALISIO_TELEMETRY_OTLP_TOKEN`). The config file may
+  only reference the variable's name.
+- Telemetry can reveal how someone works, which repositories they use, and what
+  they type. Keep `strict` redaction on, prefer metadata-only, and set a
+  retention window you are comfortable with.
+
+## Configuration
+
+Configuration precedence, highest first:
+
+1. Explicit non-secret command/tool argument (for example
+   `/telemetry:telemetry-setup --retention-days 7`).
+2. Environment variables.
+3. The config file at `<configHome>/telemetry/config.json`.
+4. Built-in safe defaults.
+
+`configHome` resolves as `ALISIO_CONFIG_HOME`, else `XDG_CONFIG_HOME/alisio`,
+else `~/.config/alisio`. `stateHome` resolves as `ALISIO_STATE_HOME`, else
+`XDG_STATE_HOME/alisio`, else `~/.local/state/alisio`.
+
+The database path is `ALISIO_TELEMETRY_DB`, else
+`<stateHome>/telemetry/telemetry.sqlite`. Telemetry stores its data through the
+host-provided SQLite storage port (`api.storage.sqlite`), so the plugin never
+depends on a runtime SQLite driver. Because the host port sets no pragmas, the
+plugin hardens the port right after opening: it enables WAL, a `busy_timeout`,
+foreign keys and `NORMAL` synchronous mode, ensures parent directories are
+`0700` and the database file is `0600`, and periodically runs `PRAGMA optimize`.
+
+An invalid configuration **fails closed**: telemetry is disabled and an actionable
+message is reported. It never crashes the host.
+
+### Settings
+
+| Field | Meaning |
+| --- | --- |
+| `retentionDays` | How long records are kept before `telemetry-prune` removes them |
+| `capture.prompts` / `.completions` / `.toolArguments` / `.toolResults` | Opt-in content capture (redacted, bounded) |
+| `redaction.mode` | `strict` (default) or `standard` |
+| `otlp.enabled` | Master switch for remote export |
+| `otlp.endpoint` | OTLP/HTTP base URL, e.g. `https://collector.example.com:4318` |
+| `otlp.headers` | Non-secret headers only; secret-shaped headers are refused |
+| `otlp.tokenEnv` | Name of the environment variable that holds the token |
+| `otlp.serviceName` / `.environment` / `.instanceId` | Resource attributes |
+| `otlp.samplingRatio` | Deterministic per-run sampling, `0`–`1` |
+| `otlp.signals.traces` / `.logs` / `.metrics` | Which signals to export |
+| `otlp.gzip` | Gzip the request body |
+| `otlp.maxAttempts` / `.timeoutMs` / `.batchSize` | Export bounds |
+| `batch.batchSize` / `.flushIntervalMs` / `.maxQueue` | Local write bounds |
+
+### Environment variables
+
+`ALISIO_TELEMETRY_DB`, `ALISIO_CONFIG_HOME`, `ALISIO_STATE_HOME`,
+`XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `ALISIO_TELEMETRY_RETENTION_DAYS`,
+`ALISIO_TELEMETRY_OTLP_ENABLED`, `ALISIO_TELEMETRY_OTLP_ENDPOINT`,
+`ALISIO_TELEMETRY_OTLP_TOKEN_ENV`, `ALISIO_TELEMETRY_OTLP_INSTANCE_ID`,
+`ALISIO_TELEMETRY_SERVICE_NAME`, `ALISIO_TELEMETRY_ENVIRONMENT`,
+`ALISIO_TELEMETRY_SAMPLING_RATIO`, `ALISIO_TELEMETRY_CAPTURE_PROMPTS`,
+`ALISIO_TELEMETRY_CAPTURE_COMPLETIONS`, `ALISIO_TELEMETRY_CAPTURE_TOOL_ARGUMENTS`,
+`ALISIO_TELEMETRY_CAPTURE_TOOL_RESULTS`, `ALISIO_TELEMETRY_REDACTION_MODE`,
+`ALISIO_TELEMETRY_OTLP_SIGNALS`, `ALISIO_TELEMETRY_OTLP_GZIP`,
+`ALISIO_TELEMETRY_BATCH_SIZE`, `ALISIO_TELEMETRY_FLUSH_INTERVAL_MS`,
+`ALISIO_TELEMETRY_MAX_QUEUE`.
+
+The token itself is read only from `ALISIO_TELEMETRY_OTLP_TOKEN` (or the variable
+named by `otlp.tokenEnv`).
+
+## Tools
+
+All tools are read-only (`read`), closed-schema, and return a bounds envelope
+(`window`, `returned`, `total`, `truncated`, `hint`). They never dump raw events
+and never expose secrets or absolute machine paths.
+
+| Tool | Returns |
+| --- | --- |
+| `telemetry_summary` | Sessions, runs, turns, tokens, tool errors, latency and a time series |
+| `telemetry_models` | Model mix with token usage, calls and average turn duration |
+| `telemetry_tools` | Tool call counts, error rate, latency and effects |
+| `telemetry_sessions` | Recent sessions/runs with bounded metadata |
+| `telemetry_search` | Bounded content search; only returns content when capture is enabled |
+
+## Commands
+
+Alisio namespaces external plugin commands as `<plugin id>:<name>`, so the real
+invocation form is:
+
+```
+/telemetry:telemetry-setup [options]
+/telemetry:telemetry-status
+/telemetry:telemetry-flush
+/telemetry:telemetry-prune [--days <n>]
+```
+
+`telemetry-setup` persists configuration non-interactively and reports exactly
+which fields changed, without ever echoing a credential. Use `--json` on any of
+these for machine-readable output.
+
+## OpenTelemetry alignment
+
+The plugin emits OTLP/HTTP JSON to `/v1/traces`, `/v1/logs` and `/v1/metrics`
+under the configured base endpoint. It uses standard names where they exist, for
+example `gen_ai.operation.name`, `gen_ai.provider.name`, `gen_ai.request.model`,
+`gen_ai.response.model`, `gen_ai.usage.input_tokens`,
+`gen_ai.usage.output_tokens`, `gen_ai.usage.cached_input_tokens`,
+`gen_ai.tool.name`, `gen_ai.tool.call.id`, `gen_ai.conversation.id`, and the
+stable core attributes `error.type`, `server.address` and `server.port`. Span
+names follow `{gen_ai.operation.name} {target}`, using `invoke_agent`, `chat` and
+`execute_tool`.
+
+**Honesty constraint.** Every `gen_ai.*` semantic convention is currently
+Development/experimental, not stable, and the GenAI conventions moved out of the
+main semantic-conventions repository. There is no stable release for metrics.
+These attribute names may change and this plugin claims no stability. Where no
+standard exists — cost, retry rate, cache-hit ratio, approval outcomes, context
+growth — the plugin uses clearly namespaced `alisio.telemetry.*` attributes or
+metrics instead of inventing `gen_ai.*` names. Cost and approval outcomes are not
+captured at all.
+
+Export behavior: HTTP 200 (including a partial-success body) is success and is
+never retried; only `429`, `502`, `503` and `504` are retried, with bounded
+attempts and floor-ed exponential backoff honoring `Retry-After`. Redirects are
+refused and response bodies are read through a hard cap. Payloads are persisted as
+batches keyed by their content hash before any network call, so a failed export
+stays queued and a retry is idempotent — data is neither lost nor duplicated
+silently. Non-retryable responses are marked `dead` and surfaced in
+`telemetry-status` rather than discarded.
+
+## Deleting telemetry
+
+`/telemetry:telemetry-prune [--days <n>]` deletes runs, turns, tool calls and
+content older than the cutoff, purges the full-text search index, then runs
+`optimize` and `VACUUM`. To remove everything, run it with a cutoff in the
+future (for example `--days 0`), or delete the SQLite file directly.
+
+**FTS caveat:** the full-text search shadow tables (`content_fts\*`) can retain
+fragments even after rows are deleted; prune clears the index and vacuums, but a
+copy of the database made earlier may still contain forensic traces. Treat any
+captured content as sensitive.
+
+## Requirements
+
+Node.js **>= 22.16** and an Alisio host with `@alisio/sdk`
+`>=0.1.0-alpha.10` that provides the SQLite storage port
+(`api.storage.sqlite`). Zero runtime dependencies: Node built-ins and native
+`fetch` only.
+
+## License
+
+MIT.

package/cover.svg

@@ -0,0 +1,54 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="900" viewBox="0 0 1600 900" role="img" aria-labelledby="title desc">
+  <title id="title">Telemetry</title>
+  <desc id="desc">A dashboard with a token-usage chart, tool-call bars, and a local database cylinder feeding an opt-in export arrow.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#07111f"/>
+      <stop offset="1" stop-color="#0d1c31"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#22d3ee"/>
+      <stop offset="1" stop-color="#6366f1"/>
+    </linearGradient>
+    <linearGradient id="area" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#22d3ee" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#22d3ee" stop-opacity="0.02"/>
+    </linearGradient>
+  </defs>
+  <rect width="1600" height="900" fill="url(#bg)"/>
+  <rect x="120" y="110" width="940" height="520" rx="32" fill="#0b1a2e" stroke="#1e3a5f" stroke-width="6"/>
+  <rect x="170" y="160" width="250" height="22" rx="11" fill="#94a3b8" opacity="0.55"/>
+  <rect x="170" y="196" width="150" height="22" rx="11" fill="#38bdf8" opacity="0.75"/>
+  <path d="M180 540 L320 470 L460 500 L600 370 L740 410 L880 300 L1020 340" fill="none" stroke="url(#accent)" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M180 540 L320 470 L460 500 L600 370 L740 410 L880 300 L1020 340 L1020 560 L180 560 Z" fill="url(#area)"/>
+  <g fill="#1b2f4d" stroke="#2b4a76" stroke-width="4">
+    <rect x="170" y="250" width="70" height="290" rx="10"/>
+    <rect x="270" y="320" width="70" height="220" rx="10"/>
+    <rect x="370" y="290" width="70" height="250" rx="10"/>
+    <rect x="470" y="380" width="70" height="160" rx="10"/>
+    <rect x="570" y="300" width="70" height="240" rx="10"/>
+  </g>
+  <g fill="#38bdf8" opacity="0.85">
+    <rect x="170" y="470" width="70" height="70" rx="10"/>
+    <rect x="270" y="470" width="70" height="70" rx="10"/>
+    <rect x="370" y="470" width="70" height="70" rx="10"/>
+    <rect x="470" y="470" width="70" height="70" rx="10"/>
+    <rect x="570" y="470" width="70" height="70" rx="10"/>
+  </g>
+  <g transform="translate(1140 150)">
+    <ellipse cx="160" cy="70" rx="150" ry="46" fill="#132a45" stroke="#2b4a76" stroke-width="6"/>
+    <path d="M10 70v300c0 25 67 46 150 46s150-21 150-46V70" fill="#0f2138" stroke="#2b4a76" stroke-width="6"/>
+    <path d="M10 170c0 25 67 46 150 46s150-21 150-46M10 270c0 25 67 46 150 46s150-21 150-46" fill="none" stroke="#2b4a76" stroke-width="6"/>
+    <ellipse cx="160" cy="70" rx="118" ry="30" fill="none" stroke="#22d3ee" stroke-width="6" opacity="0.8"/>
+  </g>
+  <path d="M1080 420h140" stroke="#475569" stroke-width="12" stroke-linecap="round" stroke-dasharray="4 24"/>
+  <path d="M1330 420h150" stroke="url(#accent)" stroke-width="12" stroke-linecap="round"/>
+  <path d="M1478 388l52 32-52 32z" fill="#6366f1"/>
+  <g transform="translate(1150 560)">
+    <path d="M20 46a42 42 0 0 1 84 0" fill="none" stroke="url(#accent)" stroke-width="12" stroke-linecap="round"/>
+    <rect x="0" y="44" width="124" height="70" rx="16" fill="#0f2138" stroke="url(#accent)" stroke-width="12"/>
+    <circle cx="62" cy="82" r="10" fill="#22d3ee"/>
+  </g>
+  <text x="800" y="790" fill="#f8fafc" font-family="sans-serif" font-size="82" font-weight="700" text-anchor="middle">TELEMETRY</text>
+  <text x="800" y="850" fill="#94a3b8" font-family="sans-serif" font-size="30" text-anchor="middle">local-first agent observability, opt-in OTLP export</text>
+</svg>

package/dist/commands.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Operator commands: setup, status, maintenance.
+ *
+ * Alisio namespaces external plugin commands as `<plugin id>:<name>`. This
+ * plugin registers the names below, so the real invocation form is
+ * `/telemetry:telemetry-setup`, `/telemetry:telemetry-status`,
+ * `/telemetry:telemetry-flush` and `/telemetry:telemetry-prune`.
+ *
+ * `telemetry-setup` persists configuration non-interactively and reports exactly
+ * which fields changed. It never echoes a credential: the OTLP token is only
+ * ever referenced by the name of the environment variable that holds it.
+ */
+import type { PluginAPI } from "@alisio/sdk";
+import type { TelemetryRuntime } from "./runtime.js";
+export declare const COMMAND_NAMES: readonly ["telemetry-setup", "telemetry-status", "telemetry-flush", "telemetry-prune"];
+/** Replace a home-directory prefix with `~` so a path is not machine-specific. */
+export declare function displayPath(path: string, home: string | undefined): string;
+export declare function registerCommands(api: PluginAPI, runtime: TelemetryRuntime): void;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAkB,SAAS,EAAE,MAAM,aAAa,CAAC;AAU7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,eAAO,MAAM,aAAa,YACxB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,CACT,CAAC;AAiKX,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAI1E;AAMD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CA0JhF"}

package/dist/commands.js

@@ -0,0 +1,298 @@
+import { ConfigError, createDefaultConfig, describeConfig, updateConfig, writeConfigFile, } from "./config.js";
+import { sanitizeField } from "./format.js";
+export const COMMAND_NAMES = [
+    "telemetry-setup",
+    "telemetry-status",
+    "telemetry-flush",
+    "telemetry-prune",
+];
+const SETUP_USAGE = [
+    "Usage: /telemetry:telemetry-setup [options]",
+    "  --enable-remote | --disable-remote",
+    "  --endpoint <url>",
+    "  --token-env <ENV_VAR_NAME>        (the value is never stored)",
+    "  --service-name <name>  --environment <name>  --instance-id <id>",
+    "  --sampling <0..1>  --retention-days <n>",
+    "  --capture <prompts,completions,tool-arguments,tool-results|none>",
+    "  --redaction <strict|standard>",
+    "  --flush-interval-ms <n>  --batch-size <n>  --otlp-batch-size <n>",
+    "  --gzip | --no-gzip  --json",
+].join("\n");
+function parseArguments(args) {
+    const tokens = args.trim() === "" ? [] : args.trim().split(/\s+/);
+    const values = new Map();
+    const flags = new Set();
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (!token.startsWith("--"))
+            return { values, flags };
+        const key = token.slice(2);
+        if (key === "")
+            return { values, flags };
+        if (["enable-remote", "disable-remote", "gzip", "no-gzip", "json"].includes(key)) {
+            flags.add(key);
+            continue;
+        }
+        const value = tokens[index + 1];
+        if (value === undefined || value.startsWith("--")) {
+            values.set(key, "");
+            continue;
+        }
+        values.set(key, value);
+        index += 1;
+    }
+    return { values, flags };
+}
+function integerValue(parsed, key) {
+    const raw = parsed.values.get(key);
+    if (raw === undefined || raw === "")
+        return undefined;
+    if (!/^-?\d+$/.test(raw))
+        throw new ConfigError(`--${key}: expected an integer`);
+    return Number(raw);
+}
+function ratioValue(parsed, key) {
+    const raw = parsed.values.get(key);
+    if (raw === undefined || raw === "")
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0 || value > 1)
+        throw new ConfigError(`--${key}: expected a number between 0 and 1`);
+    return value;
+}
+function captureValue(parsed) {
+    const raw = parsed.values.get("capture");
+    if (raw === undefined)
+        return undefined;
+    if (raw === "none" || raw === "")
+        return { prompts: false, completions: false, toolArguments: false, toolResults: false };
+    const enabled = new Set(raw.split(",").map((value) => value.trim().toLowerCase()));
+    const known = ["prompts", "completions", "tool-arguments", "tool-results"];
+    for (const value of enabled) {
+        if (!known.includes(value))
+            throw new ConfigError(`--capture: unknown value "${value}"`);
+    }
+    return {
+        prompts: enabled.has("prompts"),
+        completions: enabled.has("completions"),
+        toolArguments: enabled.has("tool-arguments"),
+        toolResults: enabled.has("tool-results"),
+    };
+}
+function buildOverrides(parsed) {
+    const overrides = {};
+    if (parsed.flags.has("enable-remote") || parsed.flags.has("disable-remote")) {
+        overrides.otlp = {
+            ...(overrides.otlp ?? {}),
+            enabled: parsed.flags.has("enable-remote"),
+        };
+    }
+    const endpoint = parsed.values.get("endpoint");
+    if (endpoint !== undefined && endpoint !== "") {
+        overrides.otlp = { ...(overrides.otlp ?? {}), endpoint };
+    }
+    const tokenEnv = parsed.values.get("token-env");
+    if (tokenEnv !== undefined && tokenEnv !== "") {
+        overrides.otlp = { ...(overrides.otlp ?? {}), tokenEnv };
+    }
+    const serviceName = parsed.values.get("service-name");
+    if (serviceName !== undefined && serviceName !== "") {
+        overrides.otlp = { ...(overrides.otlp ?? {}), serviceName };
+    }
+    const environment = parsed.values.get("environment");
+    if (environment !== undefined) {
+        overrides.otlp = { ...(overrides.otlp ?? {}), environment };
+    }
+    const instanceId = parsed.values.get("instance-id");
+    if (instanceId !== undefined) {
+        overrides.otlp = { ...(overrides.otlp ?? {}), instanceId };
+    }
+    const sampling = ratioValue(parsed, "sampling");
+    if (sampling !== undefined)
+        overrides.otlp = { ...(overrides.otlp ?? {}), samplingRatio: sampling };
+    if (parsed.flags.has("gzip") || parsed.flags.has("no-gzip")) {
+        overrides.otlp = { ...(overrides.otlp ?? {}), gzip: parsed.flags.has("gzip") };
+    }
+    const otlpBatchSize = integerValue(parsed, "otlp-batch-size");
+    if (otlpBatchSize !== undefined)
+        overrides.otlp = { ...(overrides.otlp ?? {}), batchSize: otlpBatchSize };
+    const retentionDays = integerValue(parsed, "retention-days");
+    if (retentionDays !== undefined)
+        overrides.retentionDays = retentionDays;
+    const capture = captureValue(parsed);
+    if (capture !== undefined)
+        overrides.capture = capture;
+    const redaction = parsed.values.get("redaction");
+    if (redaction !== undefined && redaction !== "") {
+        if (redaction !== "strict" && redaction !== "standard")
+            throw new ConfigError("--redaction: expected strict or standard");
+        overrides.redaction = { mode: redaction };
+    }
+    const flushIntervalMs = integerValue(parsed, "flush-interval-ms");
+    if (flushIntervalMs !== undefined)
+        overrides.batch = { ...(overrides.batch ?? {}), flushIntervalMs };
+    const batchSize = integerValue(parsed, "batch-size");
+    if (batchSize !== undefined)
+        overrides.batch = { ...(overrides.batch ?? {}), batchSize };
+    return overrides;
+}
+/** Flatten a config to comparable dot-path primitives, without credentials. */
+function flatten(value, prefix = "") {
+    if (value === null || typeof value !== "object")
+        return { [prefix]: JSON.stringify(value) };
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        const path = prefix === "" ? key : `${prefix}.${key}`;
+        Object.assign(out, flatten(item, path));
+    }
+    return out;
+}
+function diffConfig(before, after) {
+    const left = flatten(before);
+    const right = flatten(after);
+    const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+    const changes = [];
+    for (const key of [...keys].sort()) {
+        if (left[key] !== right[key])
+            changes.push(`${key}: ${left[key] ?? "(unset)"} -> ${right[key] ?? "(unset)"}`);
+    }
+    return changes;
+}
+/** Replace a home-directory prefix with `~` so a path is not machine-specific. */
+export function displayPath(path, home) {
+    if (home !== undefined && home !== "" && path.startsWith(home))
+        return `~${path.slice(home.length)}`;
+    return path;
+}
+function asJson(parsed) {
+    return parsed.flags.has("json");
+}
+export function registerCommands(api, runtime) {
+    const register = (name, description, argumentHint, handler) => {
+        api.commands.register(name, handler, { description, argumentHint });
+    };
+    register("telemetry-setup", "Persist telemetry configuration non-interactively", "[options]", async (args) => {
+        const parsed = parseArguments(args);
+        try {
+            const base = runtime.config ?? createDefaultConfig();
+            const overrides = buildOverrides(parsed);
+            const next = updateConfig(base, overrides);
+            writeConfigFile(runtime.paths.configFile, next);
+            const before = runtime.config ? describeConfig(runtime.config, runtime.env) : null;
+            const after = describeConfig(next, runtime.env);
+            const changes = before === null ? ["configuration file created"] : diffConfig(before, after);
+            const payload = {
+                saved: true,
+                configFile: displayPath(runtime.paths.configFile, runtime.env.HOME),
+                changed: changes,
+                restartRequired: true,
+                note: "The OTLP token is never stored. It is read at export time from the environment variable named below.",
+                tokenEnv: next.otlp.tokenEnv,
+            };
+            if (asJson(parsed))
+                return JSON.stringify(payload);
+            return [
+                `Telemetry configuration saved to ${payload.configFile}.`,
+                changes.length === 0 ? "No fields changed." : "Changed:",
+                ...changes.map((change) => `  ${change}`),
+                `Token environment variable: ${payload.tokenEnv} (value never stored).`,
+                "Restart Alisio to apply the new settings.",
+            ].join("\n");
+        }
+        catch (error) {
+            const message = error instanceof ConfigError ? error.message : "configuration could not be saved";
+            return asJson(parsed)
+                ? JSON.stringify({ saved: false, error: message })
+                : `Telemetry setup failed: ${message}\n${SETUP_USAGE}`;
+        }
+    });
+    register("telemetry-status", "Show effective telemetry configuration and local store stats", "", async (args) => {
+        const parsed = parseArguments(args);
+        const counts = runtime.store?.counts() ?? null;
+        const payload = {
+            enabled: runtime.store !== null,
+            error: runtime.configError,
+            config: runtime.config ? describeConfig(runtime.config, runtime.env) : null,
+            database: displayPath(runtime.paths.database, runtime.env.HOME),
+            configFile: displayPath(runtime.paths.configFile, runtime.env.HOME),
+            remoteExport: runtime.exporter !== null,
+            counts,
+        };
+        if (asJson(parsed))
+            return JSON.stringify(payload);
+        if (runtime.configError !== null) {
+            return `Telemetry is disabled: ${runtime.configError}\nConfig file: ${payload.configFile}\nDatabase: ${payload.database}`;
+        }
+        const config = payload.config ?? {};
+        return [
+            "Telemetry status",
+            `  local store:   ${runtime.store === null ? "unavailable" : "open"}`,
+            `  remote export: ${payload.remoteExport ? "enabled" : "disabled (local-only)"}`,
+            `  database:      ${payload.database}`,
+            `  config file:   ${payload.configFile}`,
+            `  retention:     ${config.retentionDays ?? "-"} day(s)`,
+            `  counts:        ${counts ? `${counts.runs} run(s), ${counts.turns} turn(s), ${counts.toolCalls} tool call(s), ${counts.content} content row(s)` : "-"}`,
+            `  batches:       ${counts ? `${counts.pendingBatches} pending, ${counts.deadBatches} dead` : "-"}`,
+            "  content capture is metadata-only unless explicitly enabled; the OTLP token is never stored.",
+        ].join("\n");
+    });
+    register("telemetry-flush", "Flush queued records and attempt remote export", "", async (args) => {
+        const parsed = parseArguments(args);
+        const report = await runtime.flush();
+        const payload = {
+            records: report.records,
+            content: report.content,
+            dropped: report.dropped,
+            queueSize: report.queueSize,
+            optimized: report.optimized,
+            error: report.error,
+            exports: report.exports.map((result) => ({
+                signal: result.signal,
+                status: result.status,
+                attempts: result.attempts,
+                httpStatus: result.httpStatus,
+                error: sanitizeField(result.error ?? "", 200),
+            })),
+        };
+        if (asJson(parsed))
+            return JSON.stringify(payload);
+        const lines = [
+            `Flushed ${report.records} record(s) (${report.content} content row(s)) to the local store.`,
+            `Queue: ${report.queueSize} pending, ${report.dropped} dropped since start.`,
+            report.error === null ? "No flush errors." : `Flush error: ${report.error}`,
+        ];
+        if (payload.exports.length === 0)
+            lines.push("Remote export is disabled (local-only); no network call was made.");
+        else
+            for (const result of payload.exports)
+                lines.push(`  ${result.signal}: ${result.status} after ${result.attempts} attempt(s)${result.httpStatus === null ? "" : ` (HTTP ${result.httpStatus})`}`);
+        return lines.join("\n");
+    });
+    register("telemetry-prune", "Delete telemetry older than the retention window", "[--days <n>] [--json]", async (args) => {
+        const parsed = parseArguments(args);
+        const days = integerValue(parsed, "days");
+        try {
+            const report = runtime.prune(days);
+            const payload = {
+                cutoff: report.cutoff,
+                retentionDays: report.retentionDays,
+                deleted: report.deleted,
+                note: report.note,
+            };
+            if (asJson(parsed))
+                return JSON.stringify(payload);
+            return [
+                `Pruned telemetry older than ${report.retentionDays} day(s) (before ${report.cutoff}).`,
+                `Deleted ${report.deleted.runs} run(s), ${report.deleted.turns} turn(s), ${report.deleted.toolCalls} tool call(s), ${report.deleted.content} content row(s).`,
+                report.note,
+            ].join("\n");
+        }
+        catch (error) {
+            const message = error instanceof ConfigError ? error.message : "prune failed";
+            return asJson(parsed)
+                ? JSON.stringify({ pruned: false, error: message })
+                : `Telemetry prune failed: ${message}`;
+        }
+    });
+}
+//# sourceMappingURL=commands.js.map