@agent-finops/core 0.5.5 → 0.5.7

package/dist/glance.d.ts

@@ -0,0 +1,161 @@
+import { type LocalAgentActivity, type LocalAgentCall, type LocalAgentLogResult, type LocalAgentRateLimitWindow } from "./localAgentLogs.js";
+import type { DetectedPlan } from "./planDetection.js";
+import { type ContextHealthResult } from "./contextHealth.js";
+export type GlanceSession = {
+    status: "active" | "recent";
+    agent: LocalAgentCall["agent"];
+    project?: string;
+    model: string;
+    startedAt: string;
+    lastActivityAt: string;
+    durationMinutes: number;
+    apiEquivalentUsd: number | null;
+    costConfidence: "estimated" | "missing";
+    inputTokens: number;
+    outputTokens: number;
+};
+export type GlanceLimit = {
+    agent: LocalAgentCall["agent"];
+    kind: LocalAgentRateLimitWindow["kind"];
+    name: string;
+    usedPercent: number;
+    remainingPercent: number;
+    windowMinutes: number;
+    observedAt: string;
+    resetsAt: string;
+    source: "transcript_reported";
+    projectedExhaustionAt: string | null;
+    projectedToExhaustBeforeReset: boolean;
+    projectionConfidence: "estimated";
+};
+export type GlanceAnomaly = {
+    kind: "session_spend" | "session_tokens";
+    ratioToMedian: number;
+    summary: string;
+    action: string;
+    confidence: "derived";
+};
+export type GlancePlanContext = {
+    agent: LocalAgentCall["agent"];
+    planId: string | null;
+    planLabel: string;
+    billing: DetectedPlan["billing"];
+    monthlyUsd: number | null;
+    priceConfidence: "published_list" | "missing";
+    source: "locally_detected" | "user_declared";
+};
+export type GlanceFocus = {
+    windowDays: number;
+    summary: string;
+    kind: LocalAgentActivity["kind"];
+    project?: string;
+    file?: string;
+    agents: Array<LocalAgentCall["agent"]>;
+    sessions: number;
+    activitySharePercent: number;
+    measure: "observed_prompt_and_tool_activity";
+    confidence: "high" | "medium" | "low";
+};
+export type GlancePrimaryAction = {
+    intent: "start_fresh" | "review_context" | "trim_context" | "protect_runway" | "continue_focus" | "resume_focus" | "inspect_current_work";
+    label: string;
+    detail: string;
+    project?: string;
+    focus?: string;
+    agentPrompt: string;
+    source: "context_health_focus_and_reported_runway";
+    confidence: "high" | "medium" | "low";
+    execution: "copy_prompt";
+    requiresUserConfirmation: true;
+};
+export type GlanceProvenance = {
+    session: {
+        source: "local_transcript_metadata";
+        agents: Array<LocalAgentCall["agent"]>;
+        filesParsed: number;
+    };
+    sessionValue: {
+        source: "local_calculation";
+        basis: "transcript_tokens_at_public_api_rates";
+        confidence: GlanceSession["costConfidence"];
+        pricingAsOf: string;
+    };
+    plan: {
+        source: "local_agent_account_metadata" | "user_declared" | "not_available";
+        agent?: LocalAgentCall["agent"];
+    };
+    limits: {
+        source: "transcript_reported" | "not_available";
+        agents: Array<LocalAgentCall["agent"]>;
+        windows: Array<LocalAgentRateLimitWindow["kind"]>;
+        projection: "local_pace_estimate";
+    };
+    focus: {
+        source: "local_prompt_and_tool_activity" | "not_available";
+        agents: Array<LocalAgentCall["agent"]>;
+        rawPromptTextReturned: false;
+    };
+    anomaly: {
+        source: "local_session_history" | "not_available";
+        comparison: "same_agent_session_median";
+    };
+    contextHealth: {
+        source: "canonical_context_health_contract";
+        hookPayload: "not_executed_or_inferred";
+    };
+    primaryAction: {
+        source: "canonical_context_health_focus_and_reported_runway";
+        execution: "copy_prompt";
+        automaticExecution: false;
+    };
+    network: {
+        uploaded: false;
+    };
+};
+export type UsageGlanceSnapshot = {
+    dataMode: "local_transcripts";
+    generatedAt: string;
+    coverage: {
+        filesParsed: number;
+        supportedTranscriptAgents: Array<LocalAgentCall["agent"]>;
+        detectedAgents: Array<LocalAgentCall["agent"]>;
+        rateLimitMetadata: Array<{
+            agent: LocalAgentCall["agent"];
+            status: "reported" | "not_reported_by_transcript" | "not_seen";
+            windowsReported: Array<LocalAgentRateLimitWindow["kind"]>;
+        }>;
+        providerConnectionRequired: ["cursor", "github-copilot"];
+    };
+    provenance: GlanceProvenance;
+    currentSession: GlanceSession | null;
+    plan: GlancePlanContext | null;
+    limits: GlanceLimit[];
+    focus: GlanceFocus | null;
+    anomaly: GlanceAnomaly | null;
+    sessionHealth: ContextHealthResult;
+    primaryAction: GlancePrimaryAction;
+    caveats: string[];
+};
+export type BuildUsageGlanceOptions = {
+    now?: Date;
+    activeWithinMinutes?: number;
+    focusWindowDays?: number;
+    filesParsed?: number;
+    detectedAgents?: Array<LocalAgentCall["agent"]>;
+    /** Locally detected or explicitly declared subscription/API billing modes. */
+    detectedPlans?: DetectedPlan[];
+    /** Account-level limit metadata should not be removed by a project filter. */
+    limitCalls?: LocalAgentCall[];
+    /** Canonical result shared with CLI/MCP. Falls back to session-only health. */
+    contextHealth?: ContextHealthResult;
+};
+/**
+ * Build the read model used by the native Glance surface.
+ *
+ * Token counts, projects, models, timestamps, and Codex limit windows come
+ * directly from local transcript metadata. Dollar values and exhaustion
+ * times are deterministic estimates and are labeled as such.
+ */
+export declare function buildUsageGlance(calls: LocalAgentCall[], options?: BuildUsageGlanceOptions): UsageGlanceSnapshot;
+export declare function buildUsageGlanceFromLogs(logs: LocalAgentLogResult, options?: Omit<BuildUsageGlanceOptions, "filesParsed">): UsageGlanceSnapshot;
+//# sourceMappingURL=glance.d.ts.map