@compaction/cli 0.1.4 → 0.3.0

package/dist/core/activity-view.js

@@ -0,0 +1,120 @@
+export const DEFAULT_ACTIVITY_LIMIT = 20;
+export const NO_ACTIVITY_MESSAGE = "No activity recorded yet — run a supported workflow (e.g. `compaction run <tool> -- …`) and it will appear here.";
+function axisSource(event, axis) {
+    const axisData = event.token_source?.[axis];
+    if (!axisData)
+        return { source: "unknown" };
+    return { source: axisData.source, reason: axisData.unavailable_reason };
+}
+function autoApplyStatus(event) {
+    const auto = event.auto_apply;
+    if (!auto)
+        return "n/a";
+    if (auto.applied_automatically === true)
+        return "auto-applied (policy)";
+    if (auto.preference === "auto-when-gates-pass")
+        return "preference: auto-when-gates-pass (application pending)";
+    return "ask each time";
+}
+/** Build the rendered rows: newest first, optional surface filter, then limit. */
+export function buildActivityRows(events, options = {}) {
+    const limit = options.limit ?? DEFAULT_ACTIVITY_LIMIT;
+    // The store appends chronologically; most recent is the LAST line. Newest-first for display.
+    const ordered = [...events].reverse();
+    const filtered = options.surface ? ordered.filter((event) => event.surface === options.surface) : ordered;
+    const shown = filtered.slice(0, Math.max(0, limit));
+    return shown.map((event, index) => {
+        const input = axisSource(event, "input");
+        const output = axisSource(event, "output");
+        const outputUnavailable = output.source === "unavailable" || output.source === "unknown";
+        const outputCount = typeof event.output_after === "number"
+            ? event.output_after
+            : typeof event.output_before === "number"
+                ? event.output_before
+                : typeof event.output_estimate === "number"
+                    ? event.output_estimate
+                    : null;
+        return {
+            position: index + 1,
+            activity_event_id: event.activity_event_id ?? "unknown",
+            surface: event.surface,
+            provider: event.provider ?? "unknown",
+            model_label: event.model_label ?? "unknown",
+            input_before: typeof event.input_before === "number" ? event.input_before : null,
+            input_after: typeof event.input_after === "number" ? event.input_after : null,
+            input_source: input.source,
+            ...(input.reason ? { input_unavailable_reason: input.reason } : {}),
+            output_tokens: outputUnavailable ? null : outputCount,
+            output_source: output.source,
+            ...(output.reason ? { output_unavailable_reason: output.reason } : {}),
+            policy_used: event.policy_used ?? "none",
+            approval_status: event.approval_status ?? "not-recorded",
+            auto_apply_status: autoApplyStatus(event),
+            sync_status: event.sync_status ?? "local-only"
+        };
+    });
+}
+function renderInputCell(row) {
+    if (row.input_source === "unavailable")
+        return `unavailable (${row.input_source})`;
+    if (row.input_before === null)
+        return `— (${row.input_source})`;
+    // Only show before→after when a real reshaping happened (both present); else a measured count.
+    if (row.input_after === null)
+        return `${row.input_before} measured (${row.input_source})`;
+    return `${row.input_before}→${row.input_after} (${row.input_source})`;
+}
+function renderOutputCell(row) {
+    if (row.output_tokens === null)
+        return `unavailable (${row.output_source})`;
+    return `${row.output_tokens} measured (${row.output_source})`;
+}
+export function buildActivityJson(rows, meta) {
+    return {
+        activity: rows,
+        meta: {
+            total_events: meta.totalEvents,
+            shown: rows.length,
+            limit: meta.limit,
+            surface_filter: meta.surface ?? null,
+            ordering: "append-recency (events carry no wall-clock time); position 1 = most recent",
+            labels: "token counts are shown at each event's own axis tier (local-estimate | provider-reported | unavailable); output is a measured token count, never a savings figure; no cost or billing figure is shown"
+        },
+        ...(meta.skippedCount && meta.skippedCount > 0
+            ? { skipped_note: `${meta.skippedCount} malformed line(s) were skipped (not shown)` }
+            : {})
+    };
+}
+/** Human table. Content-free; honest labels; a header note that ordering is append-recency. */
+export function formatActivityTable(rows, meta) {
+    if (rows.length === 0) {
+        if (meta.surface) {
+            return `No activity recorded for surface "${meta.surface}" yet. ${NO_ACTIVITY_MESSAGE}`;
+        }
+        return NO_ACTIVITY_MESSAGE;
+    }
+    const header = ["#", "surface", "provider/model", "input (before→after)", "output tokens", "policy", "approval", "auto-apply", "sync"];
+    const table = rows.map((row) => [
+        `${row.position}`,
+        row.surface,
+        `${row.provider}/${row.model_label}`,
+        renderInputCell(row),
+        renderOutputCell(row),
+        row.policy_used,
+        row.approval_status,
+        row.auto_apply_status,
+        row.sync_status
+    ]);
+    const widths = header.map((cell, col) => Math.max(cell.length, ...table.map((line) => line[col].length)));
+    const pad = (cells) => cells.map((cell, col) => cell.padEnd(widths[col])).join("  ");
+    const surfaceNote = meta.surface ? ` (surface "${meta.surface}")` : "";
+    const preamble = [
+        `Recent activity${surfaceNote}: showing ${rows.length} of ${meta.totalEvents} recorded run(s).`,
+        `Ordered by append recency (activity events carry no wall-clock time); #1 = most recent.`,
+        `Token counts are local estimates unless labeled provider-reported; output is a measured count, not a savings figure.`
+    ];
+    const lines = [pad(header), pad(header.map((_, col) => "-".repeat(widths[col]))), ...table.map(pad)];
+    const trailer = meta.skippedCount && meta.skippedCount > 0 ? [``, `(${meta.skippedCount} malformed line(s) skipped.)`] : [];
+    return [...preamble, ``, ...lines, ...trailer].join("\n");
+}
+//# sourceMappingURL=activity-view.js.map

package/dist/core/api-client/index.d.ts

@@ -8,6 +8,8 @@
  * explicitly invokes `apiStatus` / `sendRequest`.
  */
 export { DEFAULT_API_URL, DEFAULT_TIMEOUT_MS, resolveApiConfig, buildHeaders, type ApiConfig, type EnvLike } from "./config.js";
+export { configDir, configPath, readPersistedConfig, writePersistedConfig, maskKey, isLocalDefaultUrl, urlHost, resolveTarget, healthCheckConfig, type PersistedConfig, type ResolvedTarget, type Source } from "./persisted-config.js";
 export { isContentBearing, ConsentError, buildOptimizeRequest, buildEvaluateRequest, buildReportsRequest, previewPayload, type OptimizeBuildOptions, type EvaluateBuildOptions, type ReportsBuildOptions, type PayloadPreview } from "./payload.js";
 export { apiStatus, sendRequest, ApiNotConfirmedError, ApiTransportError, type ApiResponse, type SendOptions } from "./client.js";
-export { CONTENT_BEARING_PAYLOAD_CLASSES, type PayloadClass, type TokenSource, type Consent, type Trace, type TokenUsage, type OptimizeRequest, type EvaluateRequest, type ReportsRequest, type ApiRequestBody, type StatusResponse, type ApiErrorBody } from "./types.js";
+export { CONTENT_BEARING_PAYLOAD_CLASSES, type PayloadClass, type TokenSource, type Consent, type Trace, type TokenUsage, type ProviderMetadata, type OptimizeRequest, type EvaluateRequest, type ReportsRequest, type ApiRequestBody, type StatusResponse, type ApiErrorBody } from "./types.js";
+export { TOOL_NAMES, isToolName, resolveToolName, type ToolName } from "./tool.js";

package/dist/core/api-client/index.js

@@ -8,7 +8,11 @@
  * explicitly invokes `apiStatus` / `sendRequest`.
  */
 export { DEFAULT_API_URL, DEFAULT_TIMEOUT_MS, resolveApiConfig, buildHeaders } from "./config.js";
+// ADDITIVE opt-in persisted-config layer (upgrade/status). Does NOT change the env-only
+// `resolveApiConfig` contract above.
+export { configDir, configPath, readPersistedConfig, writePersistedConfig, maskKey, isLocalDefaultUrl, urlHost, resolveTarget, healthCheckConfig } from "./persisted-config.js";
 export { isContentBearing, ConsentError, buildOptimizeRequest, buildEvaluateRequest, buildReportsRequest, previewPayload } from "./payload.js";
 export { apiStatus, sendRequest, ApiNotConfirmedError, ApiTransportError } from "./client.js";
 export { CONTENT_BEARING_PAYLOAD_CLASSES } from "./types.js";
+export { TOOL_NAMES, isToolName, resolveToolName } from "./tool.js";
 //# sourceMappingURL=index.js.map

package/dist/core/api-client/payload.d.ts

@@ -7,7 +7,7 @@
  * `enforceConsent`. The preview shows EXACTLY what would be sent (API key redacted), so the
  * user never sends blind. See `docs/ops/cli-api-client-design.md` §3–§5.
  */
-import { type EvaluateRequest, type OptimizeRequest, type PayloadClass, type ReportsRequest, type Trace } from "./types.js";
+import { type EvaluateRequest, type OptimizeRequest, type PayloadClass, type ReportsRequest, type ToolName, type Trace } from "./types.js";
 /** True when a class carries raw-or-sanitized message CONTENT (requires explicit consent). */
 export declare function isContentBearing(payloadClass: PayloadClass | undefined): boolean;
 /** Thrown by a builder when consent rules are violated. The client must fail closed. */
@@ -36,6 +36,10 @@ export interface OptimizeBuildOptions {
     outputTokens?: number;
     provider?: string;
     runtime?: string;
+    /** Content-free coding-tool identity (which tool produced the captured session). */
+    tool?: ToolName;
+    /** Content-free model identifier (e.g. "claude-sonnet-4-6"); never request content. */
+    model?: string;
     labels?: {
         project?: string;
         session?: string;

package/dist/core/api-client/payload.js

@@ -94,12 +94,14 @@ export function buildOptimizeRequest(opts) {
         },
         optimization_mode: opts.optimizationMode ?? "recommend"
     };
-    if (opts.provider || opts.runtime) {
-        req.provider_metadata = {
-            ...(opts.provider ? { provider: opts.provider } : {}),
-            ...(opts.runtime ? { runtime: opts.runtime } : {})
-        };
-    }
+    const providerMetadata = {
+        ...(opts.provider ? { provider: opts.provider } : {}),
+        ...(opts.runtime ? { runtime: opts.runtime } : {}),
+        ...(opts.tool ? { tool: opts.tool } : {}),
+        ...(opts.model ? { model: opts.model } : {})
+    };
+    if (Object.keys(providerMetadata).length > 0)
+        req.provider_metadata = providerMetadata;
     if (opts.labels)
         req.labels = opts.labels;
     return req;

package/dist/core/api-client/persisted-config.d.ts

@@ -0,0 +1,57 @@
+import { type ApiConfig, type EnvLike } from "./config.js";
+/** On-disk shape. Only these two fields are ever written; nothing else is persisted. */
+export interface PersistedConfig {
+    api_url: string;
+    api_key: string;
+}
+/** Where a value came from in the resolution precedence (for honest status reporting). */
+export type Source = "flag" | "env" | "file" | "default" | "none";
+export interface ResolvedTarget {
+    /** Resolved base URL (no trailing slash). */
+    url: string;
+    /** Resolved bearer token, or `undefined` when none is configured anywhere. */
+    apiKey?: string;
+    urlSource: Source;
+    keySource: Source;
+}
+/** Resolve the config directory. `COMPACTION_CONFIG_DIR` overrides `~/.compaction` (tests use this). */
+export declare function configDir(env?: EnvLike): string;
+/** Absolute path to the persisted config file. */
+export declare function configPath(env?: EnvLike): string;
+/**
+ * Read the persisted config, or `undefined` if absent/empty/malformed. Never throws: a corrupt or
+ * partial file resolves to `undefined` (fail-closed to "not configured") rather than crashing a
+ * command. Only returns a value when BOTH `api_url` and `api_key` are non-empty strings.
+ */
+export declare function readPersistedConfig(env?: EnvLike): PersistedConfig | undefined;
+/**
+ * Persist `{api_url, api_key}` at `~/.compaction/config.json` with mode 0600 (dir 0700). The key
+ * touches disk ONLY here. Returns the absolute path written. `chmod` is applied explicitly AFTER the
+ * write because `writeFileSync`'s `mode` only takes effect on file CREATION (a pre-existing file
+ * keeps its old mode otherwise).
+ */
+export declare function writePersistedConfig(config: PersistedConfig, env?: EnvLike): string;
+/**
+ * Mask an API key for display. Shows a short prefix + the last 4 characters
+ * (e.g. `ck_live_…a1b2`). A key too short to mask safely (< 16 chars, where a prefix+suffix would
+ * reveal most of it) is FULLY masked. Empty → `(none)`. The full key is NEVER returned.
+ */
+export declare function maskKey(key: string | undefined): string;
+/** True iff the resolved URL is the LOCAL-dev default — i.e. NO private/hosted endpoint is set. */
+export declare function isLocalDefaultUrl(url: string): boolean;
+/** Extract the HOST (host:port, no scheme/path) for display. Falls back to the raw string. */
+export declare function urlHost(url: string): string;
+/**
+ * Resolve the effective target for the upgrade/status commands.
+ *
+ * Precedence (independently for url and key): explicit flag > env
+ * (`COMPACTION_API_URL` / `COMPACTION_API_KEY`) > persisted file > `DEFAULT_API_URL` (url) / none
+ * (key). Pure: it reads the given env + the persisted file and returns a plain object.
+ */
+export declare function resolveTarget(opts: {
+    flagUrl?: string;
+    flagKey?: string;
+    env?: EnvLike;
+}): ResolvedTarget;
+/** Build a bounded-timeout `ApiConfig` for a health check from a resolved target. */
+export declare function healthCheckConfig(target: ResolvedTarget, timeoutMs?: number): ApiConfig;

package/dist/core/api-client/persisted-config.js

@@ -0,0 +1,156 @@
+/**
+ * Compaction API client — PERSISTED configuration (PUBLIC CLI/SDK code).
+ *
+ * ADDITIVE layer over the env-only `config.ts`: `config.ts` stays pure/env-only and its
+ * `resolveApiConfig` contract is UNCHANGED. This module adds an OPT-IN on-disk store used ONLY by
+ * `compaction upgrade` / `compaction status` so a private-beta / self-hosted user can save an
+ * endpoint + key once instead of re-exporting env vars every shell.
+ *
+ * HARD RAILS:
+ *  - The file lives at `~/.compaction/config.json`, written with mode 0600 (dir 0700). An env
+ *    override `COMPACTION_CONFIG_DIR` redirects it (tests point it at a tmpdir; the real
+ *    `~/.compaction` is NEVER touched by tests).
+ *  - There is NO baked-in remote URL — the default stays the LOCAL-dev `DEFAULT_API_URL`.
+ *  - The API key is written ONLY to this 0600 file. `maskKey` is the ONLY form that may ever be
+ *    printed, logged, or placed in an artifact/error; the full key is never surfaced anywhere else.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_API_URL, DEFAULT_TIMEOUT_MS } from "./config.js";
+function stripTrailingSlash(url) {
+    return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+/** Resolve the config directory. `COMPACTION_CONFIG_DIR` overrides `~/.compaction` (tests use this). */
+export function configDir(env = process.env) {
+    const override = (env.COMPACTION_CONFIG_DIR ?? "").trim();
+    return override !== "" ? override : join(homedir(), ".compaction");
+}
+/** Absolute path to the persisted config file. */
+export function configPath(env = process.env) {
+    return join(configDir(env), "config.json");
+}
+/**
+ * Read the persisted config, or `undefined` if absent/empty/malformed. Never throws: a corrupt or
+ * partial file resolves to `undefined` (fail-closed to "not configured") rather than crashing a
+ * command. Only returns a value when BOTH `api_url` and `api_key` are non-empty strings.
+ */
+export function readPersistedConfig(env = process.env) {
+    const path = configPath(env);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const url = typeof raw.api_url === "string" ? raw.api_url.trim() : "";
+        const key = typeof raw.api_key === "string" ? raw.api_key.trim() : "";
+        if (url === "" || key === "")
+            return undefined;
+        return { api_url: stripTrailingSlash(url), api_key: key };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Persist `{api_url, api_key}` at `~/.compaction/config.json` with mode 0600 (dir 0700). The key
+ * touches disk ONLY here. Returns the absolute path written. `chmod` is applied explicitly AFTER the
+ * write because `writeFileSync`'s `mode` only takes effect on file CREATION (a pre-existing file
+ * keeps its old mode otherwise).
+ */
+export function writePersistedConfig(config, env = process.env) {
+    const dir = configDir(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, "config.json");
+    const body = `${JSON.stringify({ api_url: stripTrailingSlash(config.api_url.trim()), api_key: config.api_key.trim() }, null, 2)}\n`;
+    writeFileSync(path, body, { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return path;
+}
+/**
+ * Mask an API key for display. Shows a short prefix + the last 4 characters
+ * (e.g. `ck_live_…a1b2`). A key too short to mask safely (< 16 chars, where a prefix+suffix would
+ * reveal most of it) is FULLY masked. Empty → `(none)`. The full key is NEVER returned.
+ */
+export function maskKey(key) {
+    const k = (key ?? "").trim();
+    if (k === "")
+        return "(none)";
+    // Too short to reveal a prefix AND a suffix without exposing most of the key → fully mask.
+    if (k.length < 16)
+        return "…(hidden)";
+    return `${k.slice(0, 8)}…${k.slice(-4)}`;
+}
+/** True iff the resolved URL is the LOCAL-dev default — i.e. NO private/hosted endpoint is set. */
+export function isLocalDefaultUrl(url) {
+    return stripTrailingSlash(url.trim()) === DEFAULT_API_URL;
+}
+/** Extract the HOST (host:port, no scheme/path) for display. Falls back to the raw string. */
+export function urlHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Resolve the effective target for the upgrade/status commands.
+ *
+ * Precedence (independently for url and key): explicit flag > env
+ * (`COMPACTION_API_URL` / `COMPACTION_API_KEY`) > persisted file > `DEFAULT_API_URL` (url) / none
+ * (key). Pure: it reads the given env + the persisted file and returns a plain object.
+ */
+export function resolveTarget(opts) {
+    const env = opts.env ?? process.env;
+    const file = readPersistedConfig(env);
+    const flagUrl = (opts.flagUrl ?? "").trim();
+    const envUrl = (env.COMPACTION_API_URL ?? "").trim();
+    let url;
+    let urlSource;
+    if (flagUrl !== "") {
+        url = flagUrl;
+        urlSource = "flag";
+    }
+    else if (envUrl !== "") {
+        url = envUrl;
+        urlSource = "env";
+    }
+    else if (file) {
+        url = file.api_url;
+        urlSource = "file";
+    }
+    else {
+        url = DEFAULT_API_URL;
+        urlSource = "default";
+    }
+    const flagKey = (opts.flagKey ?? "").trim();
+    const envKey = (env.COMPACTION_API_KEY ?? "").trim();
+    let apiKey;
+    let keySource;
+    if (flagKey !== "") {
+        apiKey = flagKey;
+        keySource = "flag";
+    }
+    else if (envKey !== "") {
+        apiKey = envKey;
+        keySource = "env";
+    }
+    else if (file) {
+        apiKey = file.api_key;
+        keySource = "file";
+    }
+    else {
+        apiKey = undefined;
+        keySource = "none";
+    }
+    return { url: stripTrailingSlash(url), apiKey, urlSource, keySource };
+}
+/** Build a bounded-timeout `ApiConfig` for a health check from a resolved target. */
+export function healthCheckConfig(target, timeoutMs = 5000) {
+    return {
+        url: target.url,
+        apiKey: target.apiKey,
+        timeoutMs: timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS
+    };
+}
+//# sourceMappingURL=persisted-config.js.map

package/dist/core/api-client/tool.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Canonical coding-tool identity (PUBLIC CLI/SDK code).
+ *
+ * The single source of truth for the `tool` attribution value the CLI tags onto a recorded run.
+ * It is CONTENT-FREE metadata — a short, fixed identifier of WHICH coding tool produced a captured
+ * session (e.g. Claude Code vs Codex vs Cursor), never any prompt/completion/trace content.
+ *
+ * This union is hand-mirrored — with no cross-package import — by the `tool` enum in
+ * `apps/api/src/schemas.ts` and the `tool` CHECK constraint in `apps/control-plane` migration
+ * 0007 / 0008. Keep the five values in lock-step across all three.
+ *
+ * `cursor` is a first-class recognized value so a Cursor run records correctly the moment a Cursor
+ * capture adapter lands. No live Cursor (or Codex) CAPTURE adapter ships today — Codex is import
+ * only and Cursor's session format is not yet verified — so a real CLI capture currently resolves
+ * to `claude-code` / `openai-agents`, or `other` when the source is unknown. The wire never carries
+ * a tool the producing adapter did not actually set.
+ */
+export type ToolName = "claude-code" | "codex" | "cursor" | "openai-agents" | "other";
+/** The five canonical tool values, in declaration order. */
+export declare const TOOL_NAMES: readonly ToolName[];
+/** Narrowing guard: true iff `value` is one of the canonical tool names. */
+export declare function isToolName(value: unknown): value is ToolName;
+/**
+ * Resolve a CONTENT-FREE tool identifier from a capture-adapter id or a trace-source string
+ * (e.g. `provenance.captureAdapter` or `trace.source`). Honest by construction: an unknown or
+ * absent hint resolves to `other` rather than guessing a specific tool. Never returns a value the
+ * caller did not actually produce.
+ */
+export declare function resolveToolName(hint: string | null | undefined): ToolName;

package/dist/core/api-client/tool.js

@@ -0,0 +1,50 @@
+/**
+ * Canonical coding-tool identity (PUBLIC CLI/SDK code).
+ *
+ * The single source of truth for the `tool` attribution value the CLI tags onto a recorded run.
+ * It is CONTENT-FREE metadata — a short, fixed identifier of WHICH coding tool produced a captured
+ * session (e.g. Claude Code vs Codex vs Cursor), never any prompt/completion/trace content.
+ *
+ * This union is hand-mirrored — with no cross-package import — by the `tool` enum in
+ * `apps/api/src/schemas.ts` and the `tool` CHECK constraint in `apps/control-plane` migration
+ * 0007 / 0008. Keep the five values in lock-step across all three.
+ *
+ * `cursor` is a first-class recognized value so a Cursor run records correctly the moment a Cursor
+ * capture adapter lands. No live Cursor (or Codex) CAPTURE adapter ships today — Codex is import
+ * only and Cursor's session format is not yet verified — so a real CLI capture currently resolves
+ * to `claude-code` / `openai-agents`, or `other` when the source is unknown. The wire never carries
+ * a tool the producing adapter did not actually set.
+ */
+/** The five canonical tool values, in declaration order. */
+export const TOOL_NAMES = [
+    "claude-code",
+    "codex",
+    "cursor",
+    "openai-agents",
+    "other"
+];
+/** Narrowing guard: true iff `value` is one of the canonical tool names. */
+export function isToolName(value) {
+    return typeof value === "string" && TOOL_NAMES.includes(value);
+}
+/**
+ * Resolve a CONTENT-FREE tool identifier from a capture-adapter id or a trace-source string
+ * (e.g. `provenance.captureAdapter` or `trace.source`). Honest by construction: an unknown or
+ * absent hint resolves to `other` rather than guessing a specific tool. Never returns a value the
+ * caller did not actually produce.
+ */
+export function resolveToolName(hint) {
+    if (!hint)
+        return "other";
+    const h = hint.trim().toLowerCase();
+    if (h === "claude-code" || h === "claude_code")
+        return "claude-code";
+    if (h === "openai-agents" || h === "openai_agents")
+        return "openai-agents";
+    if (h.startsWith("codex"))
+        return "codex"; // codex, codex_import, codex-exec
+    if (h.startsWith("cursor"))
+        return "cursor"; // cursor, cursor_import (adapter pending)
+    return "other";
+}
+//# sourceMappingURL=tool.js.map

package/dist/core/api-client/types.d.ts

@@ -19,6 +19,20 @@ export type PayloadClass = "metrics_only" | "redacted_structure" | "sanitized_sn
 export declare const CONTENT_BEARING_PAYLOAD_CLASSES: ReadonlySet<PayloadClass>;
 /** Honest token-source labels (mirror of `apps/api` `TokenSourceSchema`). Never upgraded. */
 export type TokenSource = "provider-reported" | "local-estimate" | "unknown";
+/** Canonical coding-tool identity (re-exported from the source of truth in `./tool`). */
+export type { ToolName } from "./tool.js";
+import type { ToolName } from "./tool.js";
+/**
+ * Content-free provider/tool attribution sent alongside a request. All fields are short
+ * identifiers (provider, tool, model name) — NEVER prompt/completion/trace content. The server
+ * records them on the content-free usage event so a workspace can be grouped by tool/provider/model.
+ */
+export interface ProviderMetadata {
+    provider?: string;
+    runtime?: string;
+    tool?: ToolName;
+    model?: string;
+}
 export interface Consent {
     upload_permitted: boolean;
     redacted: boolean;
@@ -37,10 +51,7 @@ export interface OptimizeRequest {
     trace: Trace;
     consent: Consent;
     payload_class?: PayloadClass;
-    provider_metadata?: {
-        provider?: string;
-        runtime?: string;
-    };
+    provider_metadata?: ProviderMetadata;
     token_usage: TokenUsage;
     evidence_labels?: Record<string, unknown>;
     labels?: {

package/dist/core/auto-apply-ask.d.ts

@@ -0,0 +1,58 @@
+import { type PolicyPreference, type PolicyPreferenceScope } from "./policy-preferences.js";
+/** The exact §11a block-4 binary question. No scope menu — the scope is inferred, never asked. */
+export declare const AUTO_APPLY_QUESTION_LINES: readonly string[];
+/** A stored preference records these gate names (the founder's gate list from `auto-apply-gates`). */
+export declare const AUTO_APPLY_PREFERENCE_GATES_REQUIRED: readonly string[];
+export type AutoApplyAnswer = "yes" | "no";
+/**
+ * Interpret a raw answer. DEFAULT IS NO: only an explicit `y` / `yes` (case-insensitive, trimmed) is
+ * `yes`; empty, `n`, `no`, undefined, or anything unrecognized is `no`. Never throws.
+ */
+export declare function interpretAutoApplyAnswer(raw: string | null | undefined): AutoApplyAnswer;
+/** Inputs from which the SAFEST scope is inferred — never a scope menu; the caller supplies facts. */
+export interface AutoApplyScopeInputs {
+    /** REQUIRED. The workflow/tool this run belongs to (never global/cross-tool). */
+    tool?: string;
+    /** OPTIONAL. The repo, when detectable (content-free identifier). */
+    repo?: string;
+    /** REQUIRED. The policy type that was approved (content-free identifier). */
+    policyType?: string;
+}
+export interface AutoApplyOfferInput {
+    /** TRUE only when an explicit in-workflow approval already emitted an approved context. */
+    approvedInWorkflow: boolean;
+    /** The interpreted answer to the binary question (default no). */
+    answer: AutoApplyAnswer;
+    /** The facts from which the safest scope is inferred. */
+    scope: AutoApplyScopeInputs;
+}
+export type AutoApplyOfferDecision = 
+/** No approval happened, or the answer was no/default — save nothing (the common, safe path). */
+{
+    action: "skip";
+    reason: string;
+}
+/** Approval + explicit yes, but the scope could not be inferred safely — fail-closed, save nothing. */
+ | {
+    action: "blocked";
+    problems: string[];
+}
+/** Approval + explicit yes + a safe scope — the CLI should upsert this preference (applies nothing). */
+ | {
+    action: "save";
+    scope: PolicyPreferenceScope;
+    preference: "auto-when-gates-pass";
+    gatesRequired: string[];
+};
+/**
+ * Resolve the binary offer into a DECISION. PURE — no I/O, no side effects. Enforces every rail:
+ * offer only after approval; default no; safest inferred scope; never global/cross-tool. Saving is
+ * left to the CLI boundary (`savePolicyPreference`); this never applies anything.
+ */
+export declare function resolveAutoApplyOffer(input: AutoApplyOfferInput): AutoApplyOfferDecision;
+/**
+ * The §11a block-5 saved-preference confirmation (scope · gates · undo hint). Honest: states the
+ * preference is stored and that every FUTURE application would be logged, evidence-labeled, undoable —
+ * it does NOT claim anything was applied. No wall-clock, no content.
+ */
+export declare function formatSavedPreferenceConfirmation(preference: PolicyPreference): string;