@agent-finops/core 0.8.1 → 0.9.0

package/README.md

@@ -41,9 +41,11 @@ keep provenance and confidence labels truthful: reserve `verified` for
 official provider-reported financial evidence, keep modeled/local value
 `estimated` or `missing`, and leave unvalidated adapters `untested`.
 
-This is the open foundation for aibill's financial-accountability mission. It
-does not yet implement company-wide ownership, accepted outcomes, approvals,
-invoice reconciliation, or ROI.
+This is the open foundation for aibill's financial-accountability mission. The
+unreleased source preview includes contracts for locally confirmed ownership,
+local self-attested approvals, and opt-in accepted GitHub outcomes. Those are
+not company-wide identity, RBAC, approval routing, invoice reconciliation, or
+verified business ROI; the public npm v0.8.1 package predates this preview.
 
 Local API-equivalent estimates, subscription context, and official
 provider-reported cost are separate concepts and must not be added together.

package/dist/actionPlanner.d.ts

@@ -0,0 +1,140 @@
+import type { ContextHealthResult } from "./contextHealth.js";
+import type { DeadContextResult } from "./deadContext.js";
+import type { SessionVitalsV0 } from "./sessionVitals.js";
+import { type TokenReductionExperimentV0, type WasteFindingV0 } from "./actionVerification.js";
+export type UserDeclaredQualityV0 = "passed" | "failed" | "missing";
+export type ActionPlannerInputV0 = {
+    sessionVitals: SessionVitalsV0;
+    generatedAt: string;
+    contextHealth?: ContextHealthResult;
+    deadContext?: DeadContextResult;
+    /** Optional user assertion. Absence remains missing rather than inferred. */
+    qualityBySessionRef?: Readonly<Record<string, UserDeclaredQualityV0>>;
+};
+export type TokenReductionActionPlanV0 = {
+    finding: WasteFindingV0;
+    experiment: TokenReductionExperimentV0;
+};
+export type ApplyTokenReductionExperimentV0Input = {
+    approvedAt: string;
+    appliedAt: string;
+    /** Opaque AV references to the exact change, rollback, and canary evidence. */
+    changeRef: string;
+    rollbackRef: string;
+    canaryRef: string;
+    canaryStatus: "passed" | "failed";
+};
+export type RollBackTokenReductionExperimentV0Input = {
+    rolledBackAt: string;
+    rollbackRef: string;
+};
+export type InvalidateTokenReductionExperimentV0Input = {
+    invalidatedAt: string;
+    reason: "manual";
+};
+export type RefreshTokenReductionExperimentV0Input = {
+    sessionVitals: SessionVitalsV0;
+    observedAt: string;
+    /** Current-session evidence prevents an in-progress session entering the post cohort. */
+    contextHealth?: ContextHealthResult;
+    qualityBySessionRef?: Readonly<Record<string, UserDeclaredQualityV0>>;
+};
+export type ActionVerificationProjectionV0 = {
+    schemaVersion: 0;
+    experimentId: string;
+    findingId: string;
+    candidateKey: string;
+    state: "collect_baseline" | "approve_one_change" | "collect_post_change" | "review_measured_result" | "rollback" | "rolled_back" | "cancelled" | "resolve_evidence";
+    tone: "neutral" | "attention" | "positive" | "negative";
+    headline: string;
+    detail: string;
+    evidenceLabel: "calculated" | "missing";
+    qualityLabel: "held" | "regressed" | "insufficient";
+    qualityEvidence: "verified" | "observed" | "user_declared" | "missing";
+    baselineSessions: number;
+    postChangeSessions: number;
+    minimumSessions: number;
+    reductionPercent: number | null;
+};
+/**
+ * Select the experiment every read-only surface should foreground.
+ *
+ * Active work outranks newer terminal history so CLI, MCP, and Glance cannot
+ * silently hand the user different tests. Creation time and stable lineage ID
+ * are deterministic tie-breakers only within the same lifecycle priority.
+ */
+export declare function selectPreferredTokenReductionExperimentV0(experiments: readonly TokenReductionExperimentV0[]): TokenReductionExperimentV0 | undefined;
+export type ResolvedWasteFindingTargetV0 = {
+    status: "resolved";
+    kind: "session";
+    ref: string;
+    agent: "claude-code" | "codex";
+    sessionType: "parent" | "subagent" | "unknown";
+    observedFrom: string;
+    observedTo: string;
+    localOnly: true;
+} | {
+    status: "resolved";
+    kind: "repeated_read_file";
+    ref: string;
+    file: string;
+    readCount: number;
+    localOnly: true;
+} | {
+    status: "resolved";
+    kind: "configured_item";
+    ref: string;
+    name: string;
+    itemKind: string;
+    path?: string;
+    localOnly: true;
+} | {
+    status: "not_found";
+    kind: WasteFindingV0["target"]["kind"];
+    ref: string;
+    localOnly: true;
+};
+/**
+ * Return at most one launch-safe candidate. Signal priority is explicit
+ * compaction, explicit repeated reads, a calculated context ratio, then
+ * measured configured-not-observed inventory. No prompt, path, or item name is
+ * carried into the finding.
+ */
+export declare function selectBestWasteFindingV0(input: ActionPlannerInputV0): WasteFindingV0 | null;
+/** Resolve an opaque candidate only from fresh local evidence supplied by the caller. */
+export declare function resolveWasteFindingTargetV0(input: {
+    finding: WasteFindingV0;
+    sessionVitals?: SessionVitalsV0;
+    contextHealth?: ContextHealthResult;
+    deadContext?: DeadContextResult;
+}): ResolvedWasteFindingTargetV0;
+/** Build one immutable pre-change cohort. Fewer than three sessions fails closed. */
+export declare function buildTokenReductionBaselineV0(input: {
+    finding: WasteFindingV0;
+    sessionVitals: SessionVitalsV0;
+    createdAt: string;
+    contextHealth?: ContextHealthResult;
+    qualityBySessionRef?: Readonly<Record<string, UserDeclaredQualityV0>>;
+}): TokenReductionExperimentV0 | null;
+/** Select one finding and prepare its baseline, or return null without guessing. */
+export declare function planTokenReductionActionV0(input: ActionPlannerInputV0): TokenReductionActionPlanV0 | null;
+/** Record explicit approval, an applied reversible change, and the actual canary outcome. */
+export declare function markTokenReductionAppliedV0(experiment: TokenReductionExperimentV0, input: ApplyTokenReductionExperimentV0Input): TokenReductionExperimentV0;
+/** Record execution of the rollback already frozen at the application boundary. */
+export declare function markTokenReductionRolledBackV0(experiment: TokenReductionExperimentV0, input: RollBackTokenReductionExperimentV0Input): TokenReductionExperimentV0;
+/** Cancel an un-applied baseline so its scope can be used by a future test. */
+export declare function invalidateTokenReductionExperimentV0(experiment: TokenReductionExperimentV0, input: InvalidateTokenReductionExperimentV0Input): TokenReductionExperimentV0;
+/**
+ * Add matched completed session snapshots after the application boundary, then delegate every
+ * median, exclusion, quality guard, and result label to the canonical evaluator.
+ */
+export declare function refreshTokenReductionExperimentV0(experiment: TokenReductionExperimentV0, input: RefreshTokenReductionExperimentV0Input): TokenReductionExperimentV0;
+/** One safe cross-surface projection for CLI, MCP, and Glance adapters. */
+export declare function buildActionVerificationProjectionV0(experiment: TokenReductionExperimentV0): ActionVerificationProjectionV0;
+/**
+ * Produce the opaque source-semantics identity used by every action cohort.
+ * Exported so adapters and contract fixtures cannot reimplement a stale
+ * descriptor fingerprint. The host version remains inside the hash.
+ */
+export declare function createActionPlanningSourceVersionReferenceV0(agent: "claude-code" | "codex", hostVersion: string | undefined): string | undefined;
+//# sourceMappingURL=actionPlanner.d.ts.map