@cesarus777/opencode-cgp 0.0.0-stage → 0.1.0

package/dist/types/adapter.d.ts

@@ -0,0 +1,18 @@
+import { type SnapshotRpcPort } from "./snapshotserver.js";
+import type { Plugin } from "@opencode/plugin";
+import type { TelemetrySink } from "./types.js";
+export interface Host {
+    rpc?: SnapshotRpcPort;
+    app: {
+        version: string;
+    };
+    options: unknown;
+    location: {
+        directory: string;
+    };
+    session: Pick<Plugin.Context["session"], "get" | "compact" | "hook">;
+    model: Pick<Plugin.Context["model"], "list">;
+    event: Plugin.Context["event"];
+    storage: Pick<Plugin.Context["storage"], "get" | "set">;
+}
+export declare function setup(ctx: Host, injectedSink?: TelemetrySink): Promise<() => Promise<void>>;

package/dist/types/config.d.ts

@@ -0,0 +1,2 @@
+import type { Config } from "./types.js";
+export declare function parseConfig(value?: unknown): Config;

package/dist/types/core.d.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./config.js";
+export * from "./policy.js";
+export * from "./monitor.js";
+export * from "./scheduler.js";
+export * from "./estimate.js";
+export * from "./snapshot.js";
+export * from "./family.js";

package/dist/types/estimate.d.ts

@@ -0,0 +1 @@
+export declare function estimate(value: unknown, maxChars?: number): number | undefined;

package/dist/types/family.d.ts

@@ -0,0 +1,39 @@
+import type { ContextSnapshot } from "./snapshot.js";
+export type ExecutionStatus = "running" | "idle" | "completed" | "failed" | "unknown";
+export interface SessionNode {
+    readonly sessionId: string;
+    readonly parentId?: string;
+    readonly agent?: string;
+    readonly model?: string;
+    readonly status: ExecutionStatus;
+    readonly interrupted?: boolean;
+}
+export interface GuardRow {
+    readonly node: SessionNode;
+    readonly snapshot?: ContextSnapshot;
+    readonly depth: number;
+    readonly current: boolean;
+    readonly freshness: "fresh" | "stale" | "missing" | "invalid";
+    readonly pressure: "normal" | "near" | "crossed" | "unknown";
+    readonly pressureRatio?: number;
+    readonly utilizationPercent?: number;
+    readonly triggerDeltaTokens?: number;
+    readonly hidden: number;
+}
+export declare function metric(snapshot: ContextSnapshot | undefined, now: number, staleMs: number): {
+    readonly triggerDeltaTokens?: number;
+    readonly utilizationPercent?: number;
+    readonly pressureRatio?: number;
+    readonly freshness: "fresh" | "stale" | "missing" | "invalid";
+    readonly pressure: "unknown" | "crossed" | "normal" | "near";
+};
+export declare function familyRows(nodes: readonly SessionNode[], snapshots: ReadonlyMap<string, ContextSnapshot>, current: string, now: number, staleMs: number, expanded?: ReadonlySet<string>, limit?: number, timing?: (id: string) => {
+    now: number;
+    staleMs: number;
+}, stableOrder?: readonly string[]): GuardRow[];
+export interface ExecutionEvidence {
+    readonly startedAt?: number;
+    readonly terminalAt?: number;
+    readonly outcome?: "succeeded" | "failed" | "interrupted";
+}
+export declare function executionStatus(known: boolean, nativeRunning: boolean, evidence: ExecutionEvidence): ExecutionStatus;

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from "@opencode/plugin";
+declare const _default: Plugin.Plugin;
+export default _default;

package/dist/types/monitor.d.ts

@@ -0,0 +1,20 @@
+import { CompactionScheduler } from "./scheduler.js";
+import { type BudgetController, type Config, type ContextUsage, type ContextUsageProvider, type Identity, type Measurement, type ModelLimits, type SessionState, type TelemetrySink, type Tokens } from "./types.js";
+export declare function promptTokens(t: Tokens): number | undefined;
+export declare class ContextMonitor implements ContextUsageProvider {
+    private readonly config;
+    readonly scheduler: CompactionScheduler;
+    private readonly sink;
+    private readonly now;
+    private readonly budget;
+    readonly sessions: Map<string, SessionState>;
+    private readonly resolver;
+    constructor(config: Config, scheduler: CompactionScheduler, sink: TelemetrySink, now?: () => number, budget?: BudgetController);
+    touch(identity: Identity, limits?: ModelLimits): SessionState | undefined;
+    accept(s: SessionState, sequence: number): boolean;
+    measure(s: SessionState, measurement: Measurement, cumulative?: Tokens): void;
+    evaluate(s: SessionState): void;
+    remove(id: string): void;
+    cleanup(): void;
+    getUsage(id: string): Promise<ContextUsage>;
+}

package/dist/types/policy.d.ts

@@ -0,0 +1,12 @@
+import type { Config, Identity, Measurement, ModelLimits, Threshold, Decision } from "./types.js";
+export declare function glob(pattern: string, text: string): boolean;
+export declare class PolicyResolver {
+    private readonly config;
+    constructor(config: Config);
+    resolve(identity: Identity): {
+        threshold: Threshold;
+        policy: string;
+    };
+}
+export declare function usableInput(limits?: ModelLimits, reserve?: number): number | undefined;
+export declare function evaluateThreshold(threshold: Threshold, measurement: Measurement | undefined, limits: ModelLimits | undefined, now: number, staleMs: number, model: string | undefined, policy: string, reserve?: number): Decision;

package/dist/types/recovery.d.ts

@@ -0,0 +1,22 @@
+import type { CompactionState } from "./types.js";
+export interface Recovery {
+    sessionId: string;
+    compaction: CompactionState;
+    sequence?: number;
+}
+export declare function decodeRecovery(v: unknown, max: number): Recovery[];
+export declare function encodeRecovery(rows: Recovery[]): {
+    sessionId: string;
+    sequence: number;
+    compaction: {
+        requestId: string | null;
+        phase: import("./types.js").CompactionPhase;
+        armed: boolean;
+        count: number;
+        failures: number;
+        consecutiveFailures: number;
+        lastAttempt: number | null;
+        lastCompleted: number | null;
+        blockedReason: string | null;
+    };
+}[];

package/dist/types/rpc.d.ts

@@ -0,0 +1,51 @@
+import type { SnapshotBatch, SnapshotRead, SnapshotReadResult } from "./snapshot.js";
+export declare const readSchema: {
+    type: "object";
+    properties: Record<string, object>;
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare const batchSchema: {
+    type: "object";
+    properties: Record<string, object>;
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare const resultSchema: {
+    type: "object";
+    properties: Record<string, object>;
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare const monitorRpc: {
+    readonly id: "context-guard.monitor.v1";
+    readonly methods: {
+        readonly read: {
+            readonly input: {
+                type: "object";
+                properties: Record<string, object>;
+                required: string[];
+                additionalProperties: boolean;
+            };
+            readonly output: {
+                type: "object";
+                properties: Record<string, object>;
+                required: string[];
+                additionalProperties: boolean;
+            };
+        };
+    };
+    readonly events: {
+        readonly changed: {
+            readonly schema: {
+                type: "object";
+                properties: Record<string, object>;
+                required: string[];
+                additionalProperties: boolean;
+            };
+        };
+    };
+};
+export declare function isRead(value: unknown): value is SnapshotRead;
+export declare function isBatch(value: unknown): value is SnapshotBatch;
+export declare function isResult(value: unknown): value is SnapshotReadResult;

package/dist/types/scheduler.d.ts

@@ -0,0 +1,18 @@
+import type { CompactionPort, Config, SessionState, TelemetrySink } from "./types.js";
+export declare class CompactionScheduler {
+    private readonly config;
+    private readonly port;
+    private readonly sink;
+    private readonly now;
+    private readonly id;
+    private stopped;
+    private readonly jobs;
+    constructor(config: Config, port: CompactionPort, sink: TelemetrySink, now?: () => number, id?: () => string);
+    consider(s: SessionState): void;
+    lifecycle(s: SessionState, event: "started" | "ended" | "failed", at: number): void;
+    measured(s: SessionState): void;
+    tick(s: SessionState): void;
+    private emit;
+    flush(): Promise<void>;
+    stop(): void;
+}

package/dist/types/snapshot.d.ts

@@ -0,0 +1,95 @@
+import type { Config, SessionState, Measurement, ModelLimits, Threshold, Tokens, CompactionPhase } from "./types.js";
+export interface ContextSnapshot {
+    readonly sessionId: string;
+    readonly revision: number;
+    readonly observedAt: number;
+    readonly parentId?: string;
+    readonly agent?: string;
+    readonly model?: string;
+    readonly measurement?: Readonly<Measurement>;
+    readonly limits?: Readonly<ModelLimits>;
+    readonly capacityTokens?: number;
+    readonly outputReserveTokens?: number;
+    /** Peak prompt tokens observed during monitor residency. */
+    readonly peakTokens?: number;
+    readonly policy: {
+        readonly id: string;
+        readonly configured: Readonly<Threshold>;
+        readonly triggerTokens?: number;
+        readonly comparison: ">=" | ">";
+        readonly reason: string;
+        readonly crossed: boolean;
+    };
+    readonly compaction: {
+        readonly phase: CompactionPhase;
+        /** Completed lifecycle events observed by the monitor, never admissions. */
+        readonly count?: number;
+        readonly armed: boolean;
+        readonly blockedReason?: string;
+        readonly lastAttempt?: number;
+        readonly lastCompleted?: number;
+        readonly cooldownUntil?: number;
+    };
+    readonly cumulative?: Readonly<Omit<Tokens, "cache">> & {
+        readonly cache: Readonly<Tokens["cache"]>;
+    };
+    readonly cumulativeScope: "session" | "unknown";
+    readonly lastObservedActive: boolean;
+}
+export interface MonitorHealth {
+    readonly enabled: boolean;
+    readonly mode: "observe" | "enforce";
+    readonly enforcement: "observing" | "available" | "suspended" | "disabled";
+    readonly reasons: readonly string[];
+    readonly staleMs: number;
+    readonly maxSessions: number;
+}
+export interface SnapshotBatch {
+    readonly schemaVersion: 1;
+    readonly epoch: string;
+    readonly sequence: number;
+    readonly generatedAt: number;
+    readonly health: MonitorHealth;
+    readonly upserts: readonly ContextSnapshot[];
+    readonly removed: readonly {
+        readonly sessionId: string;
+        readonly revision: number;
+        readonly reason: "deleted" | "evicted";
+    }[];
+}
+export interface SnapshotRead {
+    readonly schemaVersion: 1;
+    readonly sessionIds: readonly string[];
+}
+export interface SnapshotReadResult extends SnapshotBatch {
+    readonly unavailable: readonly {
+        readonly sessionId: string;
+        readonly reason: "not-monitored";
+    }[];
+}
+export declare function project(s: SessionState, config: Config, now: number, revision?: number): ContextSnapshot;
+export declare class SnapshotStore {
+    private readonly config;
+    private readonly sessions;
+    private readonly now;
+    readonly epoch: string;
+    private sequence;
+    private revision;
+    private rows;
+    private deleted;
+    private dirty;
+    private listeners;
+    private healthKey;
+    private reasons;
+    constructor(config: Config, sessions: () => ReadonlyMap<string, SessionState>, now?: () => number, epoch?: string);
+    health(): MonitorHealth;
+    degrade(reason: "event-stream-gap" | "persistence-unavailable" | "capacity-exceeded" | "model-metadata-unavailable"): void;
+    recover(reason: "capacity-exceeded" | "model-metadata-unavailable"): void;
+    mark(id: string): void;
+    markAll(): void;
+    remove(id: string): void;
+    listen(fn: (batch: SnapshotBatch) => void): () => void;
+    private batch;
+    flush(): void;
+    read(input: SnapshotRead): SnapshotReadResult;
+}

package/dist/types/snapshotserver.d.ts

@@ -0,0 +1,7 @@
+import type { RpcHandlers, RpcRegistration } from "@opencode/plugin/promise/rpc";
+export interface SnapshotRpcPort {
+    register(definition: typeof monitorRpc, handlers: RpcHandlers<typeof monitorRpc>): Promise<RpcRegistration<typeof monitorRpc>>;
+}
+import { monitorRpc } from "./rpc.js";
+import type { SnapshotStore } from "./snapshot.js";
+export declare function serveSnapshots(rpc: SnapshotRpcPort | undefined, store: SnapshotStore): Promise<() => void>;

package/dist/types/telemetry.d.ts

@@ -0,0 +1,17 @@
+import type { Config, TelemetryEvent, TelemetrySink } from "./types.js";
+export declare function defaultPath(directory: string): string;
+export declare class JsonlTelemetrySink implements TelemetrySink {
+    readonly path: string;
+    private readonly config;
+    private pending;
+    private working;
+    private disabled;
+    private bytes;
+    private ready;
+    constructor(path: string, config: Config["telemetry"]);
+    emit(event: TelemetryEvent): void;
+    private kick;
+    private drain;
+    flush(): Promise<void>;
+}
+export declare function readJournal(path: string, maxBytes?: number): Promise<unknown[]>;

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

@@ -0,0 +1,10 @@
+import type { Plugin } from "@opencode/plugin/tui";
+import type { GuardRow } from "../family.js";
+import type { GuardState } from "./state.js";
+export declare function CompactSidebar(props: {
+    sessionID: string;
+    rows: readonly GuardRow[];
+    state: GuardState;
+    context: Plugin.Context;
+    width: number;
+}): import("solid-js").JSX.Element;

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

@@ -0,0 +1,28 @@
+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[];
+export declare function progress(ratio: number | undefined, width: number): string;
+export interface MainSection {
+    readonly tone: "base" | "execution" | "pressure" | "measurement";
+    readonly lines: readonly string[];
+}
+export declare function mainSections(row: GuardRow | undefined, width: number, age: number): MainSection[];
+export declare function mainLines(row: GuardRow | undefined, width: number, age: number): string[];
+export declare const statusSymbol: {
+    readonly running: "●";
+    readonly idle: "◌";
+    readonly unknown: "◌";
+    readonly completed: "✓";
+    readonly failed: "✕";
+};
+export declare function agentHeading(row: GuardRow, width: number): string;
+export declare function agentLines(row: GuardRow, width: number): string[];
+export declare function subagentTree(rows: readonly GuardRow[], sessionID: string, collapsed: ReadonlySet<string>, hideCompleted: boolean, byPressure: boolean): {
+    all: GuardRow[];
+    visible: {
+        row: GuardRow;
+        depth: number;
+        hasChildren: boolean;
+    }[];
+};
+export declare function statistics(rows: readonly GuardRow[], sessionID: string, complete: boolean, width: number): string[];

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

@@ -0,0 +1,7 @@
+import type { GuardRow } from "../family.js";
+export declare function quantity(n: number | undefined): string;
+export declare function cells(value: string): number;
+export declare function clip(value: string, width: number): string;
+export declare function rowLines(row: GuardRow, width: number): string[];
+export declare function detailLines(row: GuardRow | undefined, width: number, expanded?: boolean, ageMs?: number): string[];
+export declare function wrap(value: string, width: number): string[];

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

@@ -0,0 +1,18 @@
+import type { OpenCodeClient, SessionInfo } from "@opencode/client";
+interface Branch {
+    readonly id: string;
+    readonly depth: number;
+    readonly cursor?: string;
+    readonly cursors: readonly string[];
+}
+export interface Inventory {
+    readonly sessions: ReadonlyMap<string, SessionInfo>;
+    readonly complete: boolean;
+    readonly rootId: string;
+    readonly pages: number;
+    readonly pending: readonly Branch[];
+    readonly scanned: ReadonlySet<string>;
+    readonly damaged: boolean;
+}
+export declare function discoverFamily(client: Pick<OpenCodeClient, "session">, currentId: string, signal: AbortSignal, cached: (id: string) => SessionInfo | undefined, maxNodes?: number, previous?: Inventory): Promise<Inventory>;
+export {};

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

@@ -0,0 +1,8 @@
+import type { Plugin } from "@opencode/plugin/tui";
+import type { PanelInput } from "@opencode/plugin/tui/context";
+import type { GuardState } from "./state.js";
+export declare function GuardPanel(props: {
+    input: PanelInput;
+    state: GuardState;
+    context: Plugin.Context;
+}): import("solid-js").JSX.Element;

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

@@ -0,0 +1,13 @@
+import type { Plugin } from "@opencode/plugin/tui";
+import type { GuardState } from "./state.js";
+import type { GuardRow } from "../family.js";
+export declare function GuardView(props: {
+    sessionID: string;
+    state: GuardState;
+    context: Plugin.Context;
+    width: number;
+    expanded?: boolean;
+    family?: readonly GuardRow[];
+    selectedId?: string;
+    inspectId?: string | undefined;
+}): import("solid-js").JSX.Element;

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

@@ -0,0 +1,29 @@
+import type { Plugin } from "@opencode/plugin/tui";
+export declare function createGuardState(context: Plugin.Context): {
+    version: import("solid-js").Accessor<number>;
+    acquire: (id: string) => {
+        update(next: string): void;
+        release(): void;
+    };
+    rows: (stableOrder?: readonly string[], allDescendants?: boolean) => import("../family.js").GuardRow[];
+    dispose: () => void;
+    age(id: string): number;
+    health(): import("../snapshot.js").MonitorHealth | undefined;
+    connection(): "unavailable" | "loading" | "live" | "reconnecting" | "incompatible";
+    complete(): boolean;
+    refresh(): void;
+    loadMore(): void;
+    expand(id: string): void;
+};
+export type GuardState = ReturnType<typeof createGuardState>;
+export declare function locationKey(location: {
+    directory: string;
+    workspaceID?: string;
+}): string;
+export declare function sameLocation(a: {
+    directory: string;
+    workspaceID?: string;
+}, b: {
+    directory: string;
+    workspaceID?: string;
+}): boolean;

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

@@ -0,0 +1,40 @@
+import type { ContextSnapshot, MonitorHealth } from "../snapshot.js";
+export interface SnapshotTransport {
+    read(location: string, ids: readonly string[], signal: AbortSignal): Promise<unknown>;
+    subscribe(location: string, signal: AbortSignal): AsyncIterable<unknown>;
+}
+export type Connection = "loading" | "live" | "reconnecting" | "unavailable" | "incompatible";
+export declare class SnapshotClient {
+    private readonly transport;
+    private readonly changed;
+    private readonly elapsed;
+    readonly rows: Map<string, ContextSnapshot>;
+    health: MonitorHealth | undefined;
+    connection: Connection;
+    private epoch;
+    private sequence;
+    private revisions;
+    private baselines;
+    private controller;
+    private generation;
+    private ids;
+    private location;
+    private refreshTimer;
+    private reading;
+    private buffered;
+    private overflow;
+    private retryTimer;
+    private failures;
+    private serverAt;
+    private receivedAt;
+    private refreshAgain;
+    private subscriptionActive;
+    constructor(transport: SnapshotTransport, changed: () => void, elapsed?: () => number);
+    now(): number;
+    setIds(ids: readonly string[]): void;
+    start(location: string, ids: readonly string[]): void;
+    private merge;
+    refresh(): Promise<void>;
+    private supervise;
+    stop(): void;
+}

package/dist/types/tui.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from "@opencode/plugin/tui";
+declare const _default: Plugin.Definition;
+export default _default;

package/dist/types/types.d.ts

@@ -0,0 +1,142 @@
+export type Threshold = {
+    type: "tokens" | "ratio" | "remaining";
+    value: number;
+};
+export interface Match {
+    role?: "main" | "subagent";
+    model?: string;
+    agent?: string;
+}
+export interface Policy {
+    match: Match;
+    threshold: Threshold;
+}
+export interface Config {
+    enabled: boolean;
+    mode: "observe" | "enforce";
+    defaults: {
+        threshold: Threshold;
+    };
+    policies: Policy[];
+    safety: {
+        cooldownMs: number;
+        minReclaimTokens: number;
+        maxConsecutiveFailures: number;
+        pendingTimeoutMs: number;
+        staleMs: number;
+        maxSessions: number;
+        sessionTtlMs: number;
+        outputReserveTokens?: number;
+    };
+    telemetry: {
+        enabled: boolean;
+        jsonl: boolean;
+        path?: string;
+        maxBytes: number;
+    };
+}
+export interface ModelLimits {
+    context: number;
+    input?: number;
+    output: number;
+}
+export interface Identity {
+    sessionId: string;
+    parentId?: string;
+    agent?: string;
+    model?: string;
+}
+export interface Tokens {
+    input: number;
+    output: number;
+    reasoning: number;
+    cache: {
+        read: number;
+        write: number;
+    };
+}
+export interface Measurement {
+    tokens: number;
+    at: number;
+    model: string;
+    requestId?: string;
+    provenance: "provider-normalized" | "serialized-estimate";
+    confidence: "reported" | "approximate";
+    scope: "completed-request" | "prepared-request";
+}
+export interface ContextUsage {
+    current?: Measurement;
+    cumulative?: Tokens;
+    cumulativeScope: "session" | "unknown";
+    peak: number;
+    modelRequests: number;
+    toolCalls: number;
+    countersSince: number;
+}
+export interface ContextUsageProvider {
+    getUsage(sessionId: string): Promise<ContextUsage>;
+}
+export type CompactionPhase = "idle" | "requesting" | "accepted" | "running" | "awaiting-measurement" | "blocked" | "uncertain";
+export interface CompactionState {
+    phase: CompactionPhase;
+    count: number;
+    failures: number;
+    consecutiveFailures: number;
+    lastAttempt?: number;
+    lastCompleted?: number;
+    before?: number | undefined;
+    beforeModel?: string | undefined;
+    beforeConfidence?: Measurement["confidence"] | undefined;
+    requestId?: string;
+    blockedReason?: string;
+    armed: boolean;
+}
+export interface Decision {
+    crossed: boolean;
+    reason: string;
+    policy: string;
+    threshold?: number;
+    budget?: number;
+    percentage?: number;
+}
+export interface SessionState extends Identity {
+    usage: ContextUsage;
+    compaction: CompactionState;
+    limits?: ModelLimits;
+    decision?: Decision;
+    lastSeen: number;
+    lastExecutionEnd?: number;
+    sequence: number;
+    active: boolean;
+}
+export type BudgetAction = {
+    type: "continue";
+} | {
+    type: "warn" | "compact" | "checkpoint" | "rotate" | "stop";
+    reason: string;
+};
+export interface BudgetInput {
+    session: Readonly<SessionState>;
+    now: number;
+    elapsedMs: number;
+    depth?: number;
+    inheritedTokenBudget?: number;
+}
+export interface BudgetController {
+    evaluate(input: BudgetInput): BudgetAction;
+}
+export declare class NoopBudgetController implements BudgetController {
+    evaluate(_input: BudgetInput): BudgetAction;
+}
+export interface TelemetryEvent {
+    time: number;
+    type: string;
+    session?: SessionState;
+    detail?: string;
+}
+export interface TelemetrySink {
+    emit(event: TelemetryEvent): void;
+}
+export interface CompactionPort {
+    compact(sessionId: string, requestId: string): Promise<void>;
+}