@cesarus777/opencode-cgp 0.2.3 → 0.3.0

package/dist/types/core.d.ts

@@ -8,3 +8,4 @@ export * from "./snapshot.js";
 export * from "./family.js";
 export * from "./performance.js";
 export * from "./charts.js";
+export * from "./modelanalytics.js";

package/dist/types/dashboard/command.d.ts

@@ -0,0 +1,5 @@
+import type { DashboardConnectionOptions } from "./connection.js";
+export declare const dashboardHelp = "Usage: context-guard dashboard tui [--server URL] [--directory PATH]\nRead-only standalone terminal dashboard; never starts an OpenCode server.\nRequires an interactive terminal, Bun >=1.3.0 and @opentui/core@0.5.17.\nInstall the renderer beside this package: npm install @opentui/core@0.5.17\nLocal discovery defaults to the current directory.\nAn explicit server requires --directory with an owning absolute server path.\nRemote authentication: CONTEXT_GUARD_PASSWORD and optional CONTEXT_GUARD_USERNAME\n(default opencode). Credentials must never be supplied in the URL.\nKeys: 1 overview, 2 detail, 3 history, arrows/j/k move, / search, f filters,\nl location, w history window, r refresh, ? help, Escape back, q/Ctrl+C quit.";
+export declare function parseDashboardArgs(args: readonly string[], cwd: string, env: Readonly<Record<string, string | undefined>>): DashboardConnectionOptions | "help";
+export declare function checkTerminalRuntime(version: string, interactive: boolean): void;
+export declare function loadTerminalRenderer(): Promise<typeof import("@opentui/core")>;

package/dist/types/dashboard/connection.d.ts

@@ -0,0 +1,36 @@
+import { Service } from "@opencode/client/service";
+import type { HistoryChartRead } from "../historycharts.js";
+import type { SnapshotTransport } from "../tui/transport.js";
+import type { DashboardPort, SessionPageInput } from "./port.js";
+export interface DashboardConnectionOptions {
+    readonly directory: string;
+    readonly server?: string;
+    /** Explicit remote authentication, held only in this process. */
+    readonly password?: string;
+    readonly username?: string;
+    /** Isolated registration file for the connection spike. */
+    readonly serviceFile?: string;
+}
+/** One SDK client; no server lifecycle calls or session mutations are exposed. */
+export declare function connectDashboard(options: DashboardConnectionOptions, discovery?: Pick<typeof Service, "discover" | "headers"> & {
+    readonly fetch?: typeof globalThis.fetch;
+}): Promise<{
+    info(signal: AbortSignal): Promise<import("@opencode/client").ServerInfo>;
+    location: {
+        readonly directory: string;
+    };
+    atLocation(directory: string): DashboardPort;
+    listSessions(input: SessionPageInput, signal: AbortSignal): Promise<{
+        readonly data: readonly import("./port.js").DashboardSession[];
+        readonly cursor?: {
+            readonly next?: string | null;
+        };
+    }>;
+    activeSessions(ids: readonly string[], signal: AbortSignal): Promise<readonly string[]>;
+    monitor(signal: AbortSignal): Promise<{
+        readonly version: 1 | 2;
+        readonly transport: SnapshotTransport;
+    }>;
+    history(input: HistoryChartRead, signal: AbortSignal): Promise<import("../historycharts.js").HistoryChartResult>;
+}>;
+export type DashboardConnection = Awaited<ReturnType<typeof connectDashboard>>;

package/dist/types/dashboard/controller.d.ts

@@ -0,0 +1,57 @@
+import { type InventoryLimits } from "./inventory.js";
+import type { DashboardPort } from "./port.js";
+import { type DashboardView, type DashboardScreen, type DashboardFilters, type HistoryWindow } from "./view.js";
+export interface DashboardControllerOptions {
+    readonly limits?: InventoryLimits;
+    readonly now?: () => number;
+    readonly elapsed?: () => number;
+    /** Zero disables automatic inventory/age ticks for deterministic callers. */
+    readonly refreshIntervalMs?: number;
+}
+/** Shared application state; subscribers never acquire additional upstream streams. */
+export declare class DashboardController {
+    private readonly locations;
+    private readonly cache;
+    private readonly listeners;
+    private readonly limits;
+    private readonly now;
+    private readonly elapsed;
+    private readonly refreshIntervalMs;
+    private state;
+    private scope;
+    private running;
+    private screen;
+    private filters;
+    private windowMs;
+    private generation;
+    private historyGeneration;
+    private pendingHistory;
+    private historyAbort;
+    private historyBusy;
+    private historyStatus;
+    private refreshTimer;
+    private ageTimer;
+    private view;
+    constructor(port: DashboardPort, options?: DashboardControllerOptions);
+    private createLocation;
+    getView(): DashboardView;
+    subscribe(listener: (view: DashboardView) => void): () => void;
+    private publish;
+    start(): Promise<void>;
+    stop(): void;
+    selectLocation(directory: string): Promise<void>;
+    selectSession(id: string): void;
+    setScreen(screen: DashboardScreen): void;
+    setWindow(windowMs: HistoryWindow): void;
+    setFilters(filters: Partial<DashboardFilters>): void;
+    refresh(): Promise<void>;
+    private current;
+    private scan;
+    private monitor;
+    private cacheKey;
+    private cancelHistory;
+    private queueHistory;
+    private pumpHistory;
+    private serverNow;
+    private buildView;
+}

package/dist/types/dashboard/inventory.d.ts

@@ -0,0 +1,17 @@
+import type { DashboardPort, DashboardSession } from "./port.js";
+export interface InventoryLimits {
+    readonly maxNodes: number;
+    readonly maxPages: number;
+    readonly maxDepth: number;
+}
+export type InventoryNotice = "node-limit" | "page-limit" | "depth-limit" | "repeated-cursor" | "inventory-unavailable" | "foreign-location" | "invalid-hierarchy";
+export interface DashboardInventory {
+    readonly sessions: readonly DashboardSession[];
+    readonly complete: boolean;
+    readonly pages: number;
+    readonly notices: readonly InventoryNotice[];
+}
+export declare const inventoryLimits: InventoryLimits;
+export declare function validateInventoryLimits(limits: InventoryLimits): void;
+/** Bounded breadth-first discovery of a whole location, without transcript reads. */
+export declare function discoverInventory(port: Pick<DashboardPort, "location" | "listSessions">, signal: AbortSignal, limits?: InventoryLimits): Promise<DashboardInventory>;

package/dist/types/dashboard/port.d.ts

@@ -0,0 +1,41 @@
+import type { ExecutionStatus } from "../family.js";
+import type { HistoryChartRead, HistoryChartResult } from "../historycharts.js";
+import type { SnapshotTransport } from "../tui/transport.js";
+/** The inventory boundary deliberately excludes titles, metadata, and content. */
+export interface DashboardSession {
+    readonly sessionId: string;
+    readonly directory: string;
+    readonly parentId?: string;
+    readonly agent?: string;
+    readonly model?: string;
+    readonly outcome?: "succeeded" | "failed" | "interrupted";
+    readonly terminalAt?: number;
+}
+export interface SessionPageInput {
+    readonly parentID?: string | null;
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface DashboardPort {
+    readonly location: {
+        readonly directory: string;
+    };
+    /** Rebind the same authenticated client, never create another server/client. */
+    atLocation(directory: string): DashboardPort;
+    listSessions(input: SessionPageInput, signal: AbortSignal): Promise<{
+        readonly data: readonly DashboardSession[];
+        readonly cursor?: {
+            readonly next?: string | null;
+        };
+    }>;
+    activeSessions(ids: readonly string[], signal: AbortSignal): Promise<readonly string[]>;
+    monitor(signal: AbortSignal): Promise<{
+        readonly version: 1 | 2;
+        readonly transport: SnapshotTransport;
+    }>;
+    history(input: HistoryChartRead, signal: AbortSignal): Promise<HistoryChartResult>;
+}
+export interface InventoryNode extends DashboardSession {
+    readonly status: ExecutionStatus;
+    readonly inventoryStale: boolean;
+}

package/dist/types/dashboard/terminal.d.ts

@@ -0,0 +1,36 @@
+import type { CliRenderer, TextRenderable } from "@opentui/core";
+import { DashboardController } from "./controller.js";
+import { type DashboardConnectionOptions } from "./connection.js";
+type Editor = "search" | "agent" | "model" | "location";
+export interface TerminalKey {
+    readonly name: string;
+    readonly sequence?: string;
+    readonly ctrl?: boolean;
+    readonly meta?: boolean;
+}
+/** Only presentation state lives here; application state stays in the controller. */
+export declare class TerminalShell {
+    readonly controller: DashboardController;
+    private readonly quit;
+    scroll: number;
+    metric: number;
+    sample: number;
+    help: boolean;
+    editor: Editor | undefined;
+    input: string;
+    notice: string;
+    private rowOffset;
+    private historyIdentity;
+    constructor(controller: DashboardController, quit: () => void);
+    private task;
+    paste(text: string): void;
+    key(key: TerminalKey, page?: number): void;
+    frame(width: number, height: number): string;
+}
+/** Public renderer lifecycle; injected renderer permits offline native tests. */
+export declare function mountTerminal(controller: DashboardController, renderer: CliRenderer, text: TextRenderable, finished: (failed: boolean) => void): {
+    shell: TerminalShell;
+    shutdown: (failed?: boolean) => void;
+};
+export declare function runTerminal(options: DashboardConnectionOptions): Promise<void>;
+export {};

package/dist/types/dashboard/terminalview.d.ts

@@ -0,0 +1,15 @@
+import type { DashboardRow, DashboardView } from "./view.js";
+export declare function overviewRow(row: DashboardRow): string;
+export declare const snapshotFields: readonly ["sessionId", "parentId", "agent", "model", "revision", "observedAt", "measurement.tokens", "measurement.at", "measurement.model", "measurement.provenance", "measurement.scope", "measurement.confidence", "measurement.requestId", "limits.input", "limits.context", "limits.output", "capacityTokens", "outputReserveTokens", "peakTokens", "policy.id", "policy.configured.type", "policy.configured.value", "policy.triggerTokens", "policy.comparison", "policy.reason", "policy.crossed", "compaction.phase", "compaction.count", "compaction.armed", "compaction.blockedReason", "compaction.lastAttempt", "compaction.lastCompleted", "compaction.cooldownUntil", "cumulativeScope", "cumulative.input", "cumulative.output", "cumulative.reasoning", "cumulative.cache.read", "cumulative.cache.write", "lastObservedActive", "performance.sessionCreatedAt", "performance.sessionOutputTokens", "performance.observedSince", "performance.at", "performance.status", "performance.partial", "performance.liveTps", "performance.averageModelTps", "performance.averageSessionTps", "performance.ttftMs", "performance.latestRequestTps", "performance.requestId", "performance.requestAgent", "performance.requestModel", "performance.requestOutputTokens", "performance.requestStartedAt", "performance.firstOutputAt", "performance.streamEndedAt", "performance.estimatedOutputTokens", "performance.modelOutputTokens", "performance.modelDurationMs", "performance.completedRequests", "performance.tokenSource"];
+export declare function terminalDetail(row: DashboardRow | undefined): string[];
+interface Observation {
+    time: number;
+    value: number | undefined;
+    details: Readonly<Record<string, unknown>>;
+}
+export declare function historyObservations(view: DashboardView, metricIndex: number): Observation[];
+export declare function terminalHistory(view: DashboardView, width: number, metricIndex: number, sample: number): string[];
+export declare const terminalHelp: string[];
+export declare function wrapped(lines: readonly string[], width: number): string[];
+export declare function headerLines(view: DashboardView, width: number): string[];
+export {};

package/dist/types/dashboard/view.d.ts

@@ -0,0 +1,83 @@
+import type { GuardRow } from "../family.js";
+import type { MonitorHealth } from "../snapshot.js";
+import type { HistoryChartResult } from "../historycharts.js";
+import type { Connection } from "../tui/transport.js";
+import type { InventoryNotice } from "./inventory.js";
+export type Immutable<T> = T extends object ? {
+    readonly [K in keyof T]: Immutable<T[K]>;
+} : T;
+export declare const historyWindows: readonly [300000, 3600000, 86400000, 604800000];
+export type HistoryWindow = (typeof historyWindows)[number];
+export type DashboardScreen = "overview" | "detail" | "history";
+export interface DashboardFilters {
+    readonly search: string;
+    readonly agent: string;
+    readonly model: string;
+}
+export interface DashboardRow extends GuardRow {
+    readonly inventoryStale: boolean;
+    readonly liveStale: boolean;
+    readonly measurementAgeMs?: number;
+    readonly performanceAvailable: boolean;
+    readonly performanceFreshness: "fresh" | "stale" | "missing" | "invalid";
+}
+export interface HistorySummary {
+    readonly source: "matched-request-records";
+    readonly observedRequests: number;
+    readonly matchedRequests: number;
+    readonly partial: boolean;
+    readonly outputTokens?: number;
+    readonly durationMs?: number;
+    readonly averageModelTps?: number;
+}
+export interface DashboardHistory {
+    readonly status: "idle" | "loading" | "ready" | "disabled" | "unavailable";
+    readonly windowMs: HistoryWindow;
+    readonly maxWindowMs: 604800000;
+    readonly maxPoints: 500;
+    readonly sessionId?: string;
+    readonly from?: number;
+    readonly to?: number;
+    readonly stale: boolean;
+    readonly notices: readonly string[];
+    readonly result?: Immutable<HistoryChartResult>;
+    readonly summary?: HistorySummary;
+}
+export type DashboardView = Immutable<{
+    schemaVersion: 1;
+    generatedAt: number;
+    running: boolean;
+    location: string;
+    locations: readonly string[];
+    screen: DashboardScreen;
+    filters: DashboardFilters;
+    connection: Connection;
+    monitorVersion?: 1 | 2;
+    health?: MonitorHealth;
+    inventory: {
+        refreshing: boolean;
+        complete: boolean;
+        stale: boolean;
+        pages: number;
+        total: number;
+        visible: number;
+        monitored: number;
+        active: number;
+        maxNodes: number;
+        maxPages: number;
+        maxDepth: number;
+        notices: readonly InventoryNotice[];
+    };
+    rows: readonly DashboardRow[];
+    selectedSessionId?: string;
+    selected?: DashboardRow;
+    history: DashboardHistory;
+    notices: readonly string[];
+}>;
+/** Clone before freezing so transport-owned objects never become UI-owned state. */
+export declare function immutableView<T>(value: T): T;
+export declare function projectHistory(result: HistoryChartResult, filters: DashboardFilters): {
+    result: HistoryChartResult;
+    summary: HistorySummary;
+    notices: string[];
+};

package/dist/types/modelanalytics.d.ts

@@ -0,0 +1,60 @@
+import type { HistoryRecord } from "./history.js";
+export interface ModelAnalyticsOptions {
+    /** Caller-owned location identity; never inferred from archive contents. */
+    location: string;
+    model?: string;
+    agent?: string;
+    from?: number;
+    to?: number;
+    maxRequests?: number;
+}
+export interface AnalyticsRequest {
+    location: string;
+    sessionId: string;
+    requestId: string;
+    startedAt: number;
+    completedAt?: number;
+    model?: string;
+    agent?: string;
+    attribution: "request" | "legacy-record" | "unknown";
+    partial: boolean;
+    outputTokens?: number;
+    ttftMs?: number;
+}
+export interface ModelSummary {
+    model?: string;
+    sessions: number;
+    completedRequests: number;
+    partialRequests: number;
+    legacyAttributionRequests: number;
+    tpsRequests: number;
+    ttftRequests: number;
+    excludedTpsRequests: number;
+    excludedTtftRequests: number;
+    outputTokens: number;
+    durationMs: number;
+    averageTps?: number;
+    meanTtftMs?: number;
+    medianTtftMs?: number;
+    p95TtftMs?: number;
+}
+export interface ModelAnalyticsResult {
+    schemaVersion: 1;
+    location: string;
+    models: ModelSummary[];
+    coverage: {
+        source: "retained-request-records";
+        scannedRecords: number;
+        unscannedRecords: number;
+        duplicateRecords: number;
+        conflictingRequests: number;
+        missingIdentityRecords: number;
+        incompleteRequests: number;
+        invalidTimingRequests: number;
+        gapRecords: number;
+        maxRequests: number;
+        partial: boolean;
+    };
+}
+/** Aggregate raw request records before any chart downsampling or session limits. */
+export declare function aggregateModels(records: readonly HistoryRecord[], options: ModelAnalyticsOptions): ModelAnalyticsResult;

package/dist/types/modelcli.d.ts

@@ -0,0 +1 @@
+export declare function inspectModels(args: readonly string[]): Promise<void>;

package/dist/types/tui/compactformat.d.ts

@@ -1,4 +1,4 @@
-import { type ContextSample } from "./contextchart.js";
+import { type ContextSample, type ContextChartSegment } from "./contextchart.js";
 import type { GuardRow } from "../family.js";
 export declare function tokens(value: number | undefined): string;
 export declare function columns(left: string, right: string, width: number): string[];
@@ -6,8 +6,9 @@ export declare function progress(ratio: number | undefined, width: number): stri
 export interface MainSection {
     readonly tone: "base" | "execution" | "pressure" | "measurement" | "threshold";
     readonly lines: readonly string[];
+    readonly segments?: readonly ContextChartSegment[];
 }
-export declare function mainSections(row: GuardRow | undefined, width: number, age: number, samples?: readonly ContextSample[]): MainSection[];
+export declare function mainSections(row: GuardRow | undefined, width: number, age: number, samples?: readonly ContextSample[], chartCapacity?: number): MainSection[];
 export declare function mainLines(row: GuardRow | undefined, width: number, age: number): string[];
 export declare const statusSymbol: {
     readonly running: "●";

package/dist/types/tui/contextchart.d.ts

@@ -2,18 +2,35 @@ import type { GuardRow } from "../family.js";
 export interface ContextSample {
     readonly at: number;
     readonly tokens?: number;
+    /** Display-only carry-forward; never a new measurement. */
+    readonly held?: boolean;
+    readonly compacted?: boolean;
 }
 export interface ContextTrace {
     readonly sessionId: string;
     readonly model: string | undefined;
     readonly capacity: number | undefined;
     readonly samples: readonly ContextSample[];
+    readonly lastCompleted?: number;
+    readonly pendingCompleted?: number;
 }
-/** Keep only actual measurements, never copies made by age/render ticks. */
+/** Bounded display history. Raw usage and enforcement remain in the snapshot. */
 export declare function updateContextTrace(previous: ContextTrace | undefined, row: GuardRow | undefined): ContextTrace;
+/** Share traces across sidebar/panel mounts without persisting provider data. */
+export declare class ContextTraceStore {
+    private readonly traces;
+    update(row: GuardRow | undefined): ContextTrace;
+    clear(): void;
+}
+export interface ContextChartSegment {
+    readonly text: string;
+    readonly held: boolean;
+    readonly tone: "axis" | "threshold" | "value" | "held";
+}
 export interface ContextChartLine {
     readonly line: string;
     readonly threshold: boolean;
+    readonly segments?: readonly ContextChartSegment[];
 }
-/** Fixed capacity scale and observation order; no interpolation across missing samples. */
-export declare function contextChart(samples: readonly ContextSample[], capacity: number | undefined, trigger: number | undefined, width: number): ContextChartLine[];
+/** Fixed capacity scale; held levels preserve bar geometry and render in a muted color. */
+export declare function contextChart(samples: readonly ContextSample[], capacity: number | undefined, trigger: number | undefined, width: number, now?: number): ContextChartLine[];

package/dist/types/tui/state.d.ts

@@ -1,4 +1,5 @@
 import type { Plugin } from "@opencode/plugin/tui";
+import { type GuardRow } from "../family.js";
 export declare function createGuardState(context: Plugin.Context): {
     version: import("solid-js").Accessor<number>;
     acquire: (id: string) => {
@@ -6,8 +7,9 @@ export declare function createGuardState(context: Plugin.Context): {
         release(): void;
     };
     history(id: string, from: number, to: number, signal: AbortSignal): Promise<import("../historycharts.js").HistoryChartResult>;
-    rows: (stableOrder?: readonly string[], allDescendants?: boolean) => import("../family.js").GuardRow[];
-    dispose: () => void;
+    rows: (stableOrder?: readonly string[], allDescendants?: boolean) => GuardRow[];
+    contextTrace: (row: GuardRow | undefined) => import("./contextchart.js").ContextTrace;
+    dispose(): void;
     age(id: string): number;
     health(): import("../snapshot.js").MonitorHealth | undefined;
     connection(): "unavailable" | "loading" | "live" | "reconnecting" | "incompatible";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cesarus777/opencode-cgp",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "type": "module",
   "exports": {
     ".": {
@@ -45,7 +45,9 @@
     "validate": "bun run format:check && bun run typecheck && bun test && bun run test:package",
     "test:metrics-live": "bun scripts/metrics-live.ts",
     "charts": "bun src/cli.ts charts",
-    "test:metrics-server-live": "bun scripts/metrics-server-live.ts"
+    "test:metrics-server-live": "bun scripts/metrics-server-live.ts",
+    "test:dashboard-spike": "bun scripts/dashboard-spike.ts",
+    "test:dashboard-terminal": "bun scripts/dashboard-terminal-live.ts"
   },
   "dependencies": {
     "@opencode/plugin": "2.0.29",
@@ -104,6 +106,7 @@
   "files": [
     "dist",
     "LICENSE",
+    "CHANGELOG.md",
     "README.md"
   ],
   "bin": {