@compaction/cli 0.1.0

package/dist/core/run-labels.js

@@ -0,0 +1,80 @@
+/**
+ * Local-only run labels (Strong-MVP Track E, task 3).
+ *
+ * A tiny, OPTIONAL, file-based tag a developer can attach to a recorded run so the
+ * multi-session aggregate can group / filter / attribute it. These labels are written
+ * to `.compaction/runs/<run>/run-labels.json` — they are LOCAL ONLY and are NEVER
+ * uploaded. They carry no trace content: only short operator-supplied strings
+ * (project / workflow / provider-runtime / a free-form user label / an explicit
+ * session id).
+ *
+ * Honesty: a label is metadata the operator typed. It does NOT change any token, cost,
+ * savings, or verification figure, and it carries no evidence weight — it is purely an
+ * organizing tag for the local rollup. Provider/runtime supplied as a LABEL is operator-
+ * asserted, never provider-verified, and is kept distinct from the token-source evidence
+ * label (provider-reported vs local-estimate) that the token accounting carries.
+ */
+/** Marker used wherever a label was not supplied rather than guessed. */
+export const NO_LABEL = "unlabeled";
+/** Schema version for the run-labels file (additive changes bump the minor). */
+export const RUN_LABELS_VERSION = "1.0.0";
+export const RUN_LABELS_NOTE = "Local-only organizing labels. Operator-supplied strings; NEVER uploaded; carry no trace content " +
+    "and no evidence weight. provider here is operator-ASSERTED, not provider-verified.";
+const MAX_LABEL_LENGTH = 200;
+/** Trim, drop empties, and cap length. Returns undefined when the value is not a usable label. */
+function normalizeLabel(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return trimmed.slice(0, MAX_LABEL_LENGTH);
+}
+/** Normalize a supplied label set to the bounded, trimmed shape (drops empty/invalid fields). */
+export function normalizeRunLabels(labels) {
+    const out = {};
+    const project = normalizeLabel(labels.project);
+    const workflow = normalizeLabel(labels.workflow);
+    const provider = normalizeLabel(labels.provider);
+    const userLabel = normalizeLabel(labels.user_label);
+    const session = normalizeLabel(labels.session);
+    if (project !== undefined)
+        out.project = project;
+    if (workflow !== undefined)
+        out.workflow = workflow;
+    if (provider !== undefined)
+        out.provider = provider;
+    if (userLabel !== undefined)
+        out.user_label = userLabel;
+    if (session !== undefined)
+        out.session = session;
+    return out;
+}
+/** True when at least one label field is present after normalization. */
+export function hasAnyLabel(labels) {
+    return Object.keys(normalizeRunLabels(labels)).length > 0;
+}
+/** Build the on-disk artifact from a supplied (already-normalizable) label set. */
+export function buildRunLabelsFile(labels, writtenAt = new Date().toISOString()) {
+    return {
+        labels_version: RUN_LABELS_VERSION,
+        written_at: writtenAt,
+        note: RUN_LABELS_NOTE,
+        ...normalizeRunLabels(labels)
+    };
+}
+/** Parse a value read from a run-labels.json into the bounded label set (tolerant; drops junk). */
+export function parseRunLabels(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return {};
+    const record = value;
+    const pick = (key) => typeof record[key] === "string" ? record[key] : undefined;
+    return normalizeRunLabels({
+        project: pick("project"),
+        workflow: pick("workflow"),
+        provider: pick("provider"),
+        user_label: pick("user_label"),
+        session: pick("session")
+    });
+}
+//# sourceMappingURL=run-labels.js.map

package/dist/core/run-trace-converter.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTrace } from "./types.js";
+import type { LocalCommandRun } from "./command-runner.js";
+export declare function localCommandRunToAgentTrace(run: LocalCommandRun): AgentTrace;

package/dist/core/run-trace-converter.js

@@ -0,0 +1,94 @@
+import { CURRENT_AGENT_TRACE_ARTIFACT_VERSION } from "./trace-parser.js";
+const LOCAL_RUN_MODEL = "local-command-runner";
+function compactPreview(value) {
+    const normalized = value.trim().replace(/\s+/g, " ");
+    return normalized.length > 120 ? `${normalized.slice(0, 117)}...` : normalized;
+}
+function createMessage(id, role, timestamp, content) {
+    return { id, role, timestamp, content };
+}
+function outputLines(value) {
+    return value
+        .split(/\r?\n/)
+        .map((content, index) => ({ content, lineNumber: index + 1 }))
+        .filter((line) => line.content.length > 0);
+}
+function nextMessageId(index) {
+    return `msg_${index.toString().padStart(3, "0")}`;
+}
+export function localCommandRunToAgentTrace(run) {
+    const commandLine = [run.command.executable, ...run.command.args].join(" ");
+    const messages = [
+        createMessage("msg_001", "system", run.startedAt, "Local compaction.dev command run. Environment variables are not captured, output is stored locally, and no upload is performed."),
+        createMessage("msg_002", "user", run.startedAt, `Run local command: ${commandLine}`)
+    ];
+    let nextIndex = 3;
+    for (const line of outputLines(run.stdout)) {
+        messages.push({
+            id: nextMessageId(nextIndex),
+            role: "tool",
+            toolName: "stdout.line",
+            timestamp: run.endedAt,
+            content: line.content,
+            metadata: {
+                stream: "stdout",
+                lineNumber: line.lineNumber,
+                byteLength: Buffer.byteLength(line.content, "utf8")
+            }
+        });
+        nextIndex += 1;
+    }
+    for (const line of outputLines(run.stderr)) {
+        messages.push({
+            id: nextMessageId(nextIndex),
+            role: "tool",
+            toolName: "stderr.line",
+            timestamp: run.endedAt,
+            content: line.content,
+            metadata: {
+                stream: "stderr",
+                lineNumber: line.lineNumber,
+                byteLength: Buffer.byteLength(line.content, "utf8")
+            }
+        });
+        nextIndex += 1;
+    }
+    const status = run.exitCode === 0 ? "succeeded" : "finished with a non-zero exit status";
+    const stdoutSummary = run.stdout.length === 0 ? "stdout was empty" : `stdout preview: ${compactPreview(run.stdout)}`;
+    const stderrSummary = run.stderr.length === 0 ? "stderr was empty" : `stderr preview: ${compactPreview(run.stderr)}`;
+    messages.push({
+        id: nextMessageId(nextIndex),
+        role: "assistant",
+        timestamp: run.endedAt,
+        content: `Command ${status}. Exit code: ${run.exitCode ?? "none"}. Signal: ${run.signal ?? "none"}. Duration: ${run.durationMs} ms. ${stdoutSummary}. ${stderrSummary}.`,
+        metadata: {
+            exitCode: run.exitCode,
+            signal: run.signal,
+            startedAt: run.startedAt,
+            endedAt: run.endedAt,
+            durationMs: run.durationMs,
+            pid: run.pid,
+            stdoutBytes: Buffer.byteLength(run.stdout, "utf8"),
+            stderrBytes: Buffer.byteLength(run.stderr, "utf8"),
+            rawOutputBytes: Buffer.byteLength(run.rawOutput, "utf8")
+        }
+    });
+    return {
+        id: `trace_${run.runId}`,
+        title: `Local command run: ${run.command.executable}`,
+        artifactVersion: CURRENT_AGENT_TRACE_ARTIFACT_VERSION,
+        source: "local_command",
+        createdAt: run.startedAt,
+        generatedAt: run.endedAt,
+        model: LOCAL_RUN_MODEL,
+        command: {
+            command: run.command.executable,
+            args: run.command.args,
+            cwd: process.cwd()
+        },
+        durationMs: run.durationMs,
+        exitCode: run.exitCode,
+        messages
+    };
+}
+//# sourceMappingURL=run-trace-converter.js.map

package/dist/core/safety-report.d.ts

@@ -0,0 +1,52 @@
+import type { PolicyMiddlewareStateCapsule } from "./policy-types.js";
+import type { AgentTrace, ApprovalReadinessStatus, TraceMessage, TraceSource } from "./types.js";
+export type SafetyStatus = "pass" | "warn" | "fail";
+export type SafetyRiskLevel = "low" | "medium" | "high";
+export type { ApprovalReadinessStatus };
+export type EvidenceSourceType = "demo" | "fixture" | "imported_local" | "real_captured" | "provider_reported_usage" | "unknown";
+export type ReviewerType = "human" | "internal" | "independent" | "automated" | "none";
+export interface SafetyReportCheck {
+    id: string;
+    label: string;
+    status: SafetyStatus;
+    required: boolean;
+    details: string;
+}
+export interface SafetyReport {
+    run_id: string;
+    generated_at: string;
+    policy_name: string;
+    status: SafetyStatus;
+    checks: SafetyReportCheck[];
+    warnings: string[];
+    failures: string[];
+    source_pointer_count: number;
+    compacted_message_count: number;
+    tokens_saved: number;
+    savings_scope: "policy_level";
+    source_recoverability: boolean | "unknown";
+    risk_level: SafetyRiskLevel;
+    recommendation: string;
+    evidence_source_type: EvidenceSourceType;
+    reviewer_type: ReviewerType;
+    review_summary_present: boolean;
+    approval_readiness_status: ApprovalReadinessStatus;
+    approval_readiness_reason: string;
+}
+export interface CreateSafetyReportInput {
+    runId: string;
+    generatedAt?: string;
+    originalTrace: AgentTrace;
+    compactedMessages: TraceMessage[];
+    stateCapsules: PolicyMiddlewareStateCapsule[];
+    compactedMessageIds: string[];
+    tokensSaved: number;
+    policyName: string;
+    reviewerType?: ReviewerType;
+    reviewSummaryPresent?: boolean;
+}
+export declare function evidenceSourceTypeFromTrace(source: TraceSource): EvidenceSourceType;
+export declare function approvalReadinessStatusFromReport(status: SafetyStatus, evidenceSourceType: EvidenceSourceType, reviewerType: ReviewerType, reviewSummaryPresent: boolean): ApprovalReadinessStatus;
+export declare function approvalReadinessReasonFromReport(status: SafetyStatus, approvalStatus: ApprovalReadinessStatus, evidenceSourceType: EvidenceSourceType, reviewerType: ReviewerType, reviewSummaryPresent: boolean): string;
+export declare function createSafetyReport(input: CreateSafetyReportInput): SafetyReport;
+export declare function formatSafetyMarkdownReport(report: SafetyReport): string;