@agent-finops/core 0.8.1 → 0.9.1

package/dist/activitySnapshot.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { aggregateCalls, dedupeCumulativeSessionCalls } from "./localAgentLogs.js";
 import { localAgentFormatDescriptors } from "./localAgentFormats/registry.js";
 import { canPriceTokenUsageAtScope, estimateTokenCostUsd, PRICING_TABLE_AS_OF } from "./modelPricing.js";
+import { subscriptionPlans } from "./planMath.js";
 import { isBundledSampleUsage } from "./schema.js";
 import { sourceValidationCoverageValues } from "./sourceStatus.js";
 const DAY_MS = 24 * 60 * 60 * 1_000;
@@ -163,6 +164,8 @@ export const activitySnapshotSubscriptionAgentSchema = z.object({
     agent: agentSchema,
     billing: z.literal("subscription"),
     planId: planIdSchema,
+    /** C-lane §2.1: detected-plan list price; null when the plan is unpriced. */
+    committedUsdPerMonth: usdSchema.nullable(),
     apiEquivalent: activitySnapshotApiEquivalentWindowsSchema,
     limits: z.array(activitySnapshotLimitSchema).max(2),
     pressure: z.enum(["extra_usage_credits_exhausted"]).nullable()
@@ -215,6 +218,41 @@ const activitySnapshotUnresolvedSchema = z.object({
         });
     }
 });
+/**
+ * C-lane §2.1: a provider-billed subscription with no local agent (cursor
+ * today). The writer includes a billed30d amount ONLY when its financial
+ * evidence is "verified"; the renderer independently drops anything else
+ * (double lock: estimated/unverified provider dollars can never reach a
+ * statusline segment).
+ */
+export const activitySnapshotProviderSubscriptionSchema = z.object({
+    provider: z.enum(activitySnapshotProviderValues),
+    billing: z.literal("subscription"),
+    planLabel: z.string().min(1).max(64).nullable(),
+    committedUsdPerMonth: usdSchema.nullable(),
+    billed30d: activitySnapshotBilledWindowSchema
+}).strict();
+/** C-lane §2.1: the committed $/mo total across every detected subscription. */
+export const activitySnapshotCommittedTotalSchema = z.object({
+    amountUsd: usdSchema.nullable(),
+    pricedSubs: countSchema,
+    totalSubs: countSchema
+}).strict().superRefine((total, context) => {
+    if (total.pricedSubs > total.totalSubs) {
+        context.addIssue({
+            code: "custom",
+            path: ["pricedSubs"],
+            message: "Priced subscriptions cannot exceed total subscriptions."
+        });
+    }
+    if ((total.amountUsd === null) !== (total.pricedSubs === 0)) {
+        context.addIssue({
+            code: "custom",
+            path: ["amountUsd"],
+            message: "A committed total exists exactly when at least one subscription is priced."
+        });
+    }
+});
 export const activitySnapshotOverageSchema = z.object({
     amountUsd: z.number().finite().positive(),
     currency: z.literal("USD"),
@@ -330,7 +368,10 @@ export const activitySnapshotCoverageSchema = z.object({
 });
 export const activitySnapshotSchema = z.object({
     kind: z.literal("aibill.activity_snapshot"),
-    schemaVersion: z.literal(1),
+    // v2 (C-lane §2.1): adds per-agent committedUsdPerMonth, provider-billed
+    // subscriptions, and the committed total. The writer dual-writes a v1
+    // payload for already-installed v1 runners during the deprecation window.
+    schemaVersion: z.literal(2),
     currency: z.literal("USD"),
     asOf: isoTimestampSchema,
     generatedAt: isoTimestampSchema,
@@ -347,6 +388,8 @@ export const activitySnapshotSchema = z.object({
     subscription: activitySnapshotSubscriptionSchema.nullable(),
     metered: activitySnapshotMeteredSchema.nullable(),
     unresolved: activitySnapshotUnresolvedSchema.nullable(),
+    providers: z.array(activitySnapshotProviderSubscriptionSchema).max(5).nullable(),
+    committedTotal: activitySnapshotCommittedTotalSchema,
     overage: activitySnapshotOverageSchema.nullable(),
     coverage: activitySnapshotCoverageSchema,
     networkUploaded: z.literal(false)
@@ -372,6 +415,20 @@ export const activitySnapshotSchema = z.object({
         (snapshot.subscription || snapshot.metered || snapshot.unresolved || snapshot.overage)) {
         invalid("Empty and error snapshots cannot carry financial cohorts.", ["mode"]);
     }
+    if ((snapshot.mode === "empty" || snapshot.mode === "error") &&
+        (snapshot.providers || snapshot.committedTotal.amountUsd !== null ||
+            snapshot.committedTotal.totalSubs !== 0)) {
+        invalid("Empty and error snapshots cannot carry subscription pricing.", ["committedTotal"]);
+    }
+    if (snapshot.providers &&
+        new Set(snapshot.providers.map((provider) => provider.provider)).size !== snapshot.providers.length) {
+        invalid("A provider subscription may appear only once.", ["providers"]);
+    }
+    const expectedTotalSubs = (snapshot.subscription?.agents.length ?? 0) +
+        (snapshot.providers?.length ?? 0);
+    if (snapshot.committedTotal.totalSubs !== expectedTotalSubs) {
+        invalid("The committed total must count every subscription row exactly once.", ["committedTotal"]);
+    }
     if (snapshot.mode === "error" && snapshot.refresh.status !== "error") {
         invalid("Error mode requires an error refresh state.", ["refresh"]);
     }
@@ -559,9 +616,32 @@ export function buildActivitySnapshot(input) {
     } : null;
     const overage = buildOverage(meteredBilledRecords, overageIds, asOfMs);
     const coverage = buildCoverage(classified.map((entry) => entry.record), scans, providers, input.pricingAsOf ?? PRICING_TABLE_AS_OF, deduplicated.conflictingIds);
+    const finalSubscription = mode === "metered" || mode === "unresolved" || mode === "empty"
+        ? null
+        : subscription;
+    // Writer-side lock (C-lane §2.1): a provider-billed amount survives only
+    // when its supplied window is verified; anything else degrades to missing.
+    const providerSubscriptionRows = mode === "empty"
+        ? []
+        : (input.providerSubscriptions ?? []).map((row) => ({
+            provider: row.provider,
+            billing: "subscription",
+            planLabel: row.planLabel,
+            committedUsdPerMonth: row.committedUsdPerMonth,
+            billed30d: row.billed30d &&
+                row.billed30d.financialEvidence === "verified" &&
+                row.billed30d.amountUsd !== null
+                ? row.billed30d
+                : missingBilledWindow()
+        }));
+    const committedRows = [
+        ...(finalSubscription?.agents ?? []).map((agent) => agent.committedUsdPerMonth),
+        ...providerSubscriptionRows.map((row) => row.committedUsdPerMonth)
+    ];
+    const pricedRows = committedRows.filter((amount) => amount !== null);
     return activitySnapshotSchema.parse({
         kind: "aibill.activity_snapshot",
-        schemaVersion: 1,
+        schemaVersion: 2,
         currency: "USD",
         asOf: new Date(asOfMs).toISOString(),
         generatedAt,
@@ -569,24 +649,80 @@ export function buildActivitySnapshot(input) {
         lastSuccessAt: generatedAt,
         refresh: { status: "ok" },
         mode,
-        subscription: mode === "metered" || mode === "unresolved" || mode === "empty"
-            ? null
-            : subscription,
+        subscription: finalSubscription,
         metered: mode === "subscription" || mode === "unresolved" || mode === "empty"
             ? null
             : metered,
         unresolved,
+        providers: providerSubscriptionRows.length > 0 ? providerSubscriptionRows : null,
+        committedTotal: {
+            amountUsd: pricedRows.length > 0
+                ? roundUsd(pricedRows.reduce((total, amount) => total + amount, 0))
+                : null,
+            pricedSubs: pricedRows.length,
+            totalSubs: committedRows.length
+        },
         overage: mode === "metered" || mode === "mixed" ? overage : null,
         coverage,
         networkUploaded: false
     });
 }
+/** Detected-plan list price (subscriptionPlans); null when unpriced. */
+function committedPriceForPlanId(planId) {
+    if (!planId)
+        return null;
+    return subscriptionPlans.find((plan) => plan.id === planId)?.monthlyUsd ?? null;
+}
+function missingBilledWindow() {
+    return {
+        amountUsd: null,
+        recordCount: 0,
+        basis: "provider_billed",
+        financialEvidence: "missing",
+        coverage: "missing"
+    };
+}
+/**
+ * The v1 dual-write payload (C-lane §2.1 fleet back-compat): today's fields
+ * only, so an already-installed v1 runner keeps rendering fresh data instead
+ * of decaying into permanent staleness. Exact v1 key set; no v2 fields.
+ */
+export function activitySnapshotV1Payload(snapshot) {
+    return {
+        kind: snapshot.kind,
+        schemaVersion: 1,
+        currency: snapshot.currency,
+        asOf: snapshot.asOf,
+        generatedAt: snapshot.generatedAt,
+        lastAttemptAt: snapshot.lastAttemptAt,
+        lastSuccessAt: snapshot.lastSuccessAt,
+        refresh: snapshot.refresh,
+        mode: snapshot.mode,
+        subscription: snapshot.subscription
+            ? {
+                agents: snapshot.subscription.agents.map((agent) => ({
+                    agent: agent.agent,
+                    billing: agent.billing,
+                    planId: agent.planId,
+                    apiEquivalent: agent.apiEquivalent,
+                    limits: agent.limits,
+                    pressure: agent.pressure
+                }))
+            }
+            : null,
+        metered: snapshot.metered,
+        unresolved: snapshot.unresolved,
+        overage: snapshot.overage,
+        coverage: snapshot.coverage,
+        networkUploaded: snapshot.networkUploaded
+    };
+}
 /** A bounded no-evidence state for an initial failed refresh. */
 export function createActivitySnapshotError(attemptedAt, errorCode) {
     const timestamp = new Date(parseTimestamp(attemptedAt, "attemptedAt")).toISOString();
     return activitySnapshotSchema.parse({
         kind: "aibill.activity_snapshot",
-        schemaVersion: 1,
+        schemaVersion: 2,
         currency: "USD",
         asOf: timestamp,
         generatedAt: timestamp,
@@ -597,6 +733,8 @@ export function createActivitySnapshotError(attemptedAt, errorCode) {
         subscription: null,
         metered: null,
         unresolved: null,
+        providers: null,
+        committedTotal: { amountUsd: null, pricedSubs: 0, totalSubs: 0 },
         overage: null,
         coverage: {
             agents: [],
@@ -650,6 +788,7 @@ function activitySubscriptionAgents(records, calls, allCalls, plans, scans, trus
             agent,
             billing: "subscription",
             planId: isKnownPlanId(plan.planId) ? plan.planId : null,
+            committedUsdPerMonth: committedPriceForPlanId(plan.planId),
             apiEquivalent: buildApiWindows(agentRecords, allCalls.filter((call) => call.agent === agent), trustedProviderIds, asOfMs, localCoverageForAgent(agent, scans)),
             limits: latestReportedLimits(agentCalls, asOfMs),
             pressure: plan.limitSignal === "extra-usage credits exhausted"

package/dist/activitySnapshotCache.d.ts

@@ -1,6 +1,13 @@
 import { type ActivitySnapshot, type ActivitySnapshotRefreshErrorCode } from "./activitySnapshot.js";
 export declare const activitySnapshotCacheEnvironmentVariable = "AIBILL_CACHE_DIR";
-export declare const activitySnapshotCacheFileName = "statusline-v1.json";
+/** The v2 snapshot cache (C-lane §2.1). */
+export declare const activitySnapshotCacheFileName = "statusline-v2.json";
+/**
+ * Deprecation-window dual-write target: installed v1 runners are frozen
+ * copies that read only this file, so every v2 write also refreshes a v1
+ * payload here (today's fields only) instead of stranding them stale.
+ */
+export declare const activitySnapshotLegacyCacheFileName = "statusline-v1.json";
 export declare const activitySnapshotCacheMaxBytes: number;
 export type ActivitySnapshotCacheOptions = {
     /** Test/embedding override. Production defaults to ~/.aibill/cache. */

package/dist/activitySnapshotCache.js

@@ -1,18 +1,30 @@
 import { constants } from "node:fs";
+import { execFile as execFileCallback } from "node:child_process";
 import { open, lstat, mkdir, chmod, realpath, rename, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
-import { activitySnapshotSchema, createActivitySnapshotError } from "./activitySnapshot.js";
+import { promisify } from "node:util";
+import { activitySnapshotSchema, activitySnapshotV1Payload, createActivitySnapshotError } from "./activitySnapshot.js";
 export const activitySnapshotCacheEnvironmentVariable = "AIBILL_CACHE_DIR";
-export const activitySnapshotCacheFileName = "statusline-v1.json";
+/** The v2 snapshot cache (C-lane §2.1). */
+export const activitySnapshotCacheFileName = "statusline-v2.json";
+/**
+ * Deprecation-window dual-write target: installed v1 runners are frozen
+ * copies that read only this file, so every v2 write also refreshes a v1
+ * payload here (today's fields only) instead of stranding them stale.
+ */
+export const activitySnapshotLegacyCacheFileName = "statusline-v1.json";
 export const activitySnapshotCacheMaxBytes = 64 * 1_024;
+// The lock name is shared with pre-v2 writers on purpose: during the fleet
+// deprecation window both CLI generations serialize through one lock.
 const lockFileName = ".statusline-v1.lock";
 const defaultLockTimeoutMs = 2_000;
 const staleLockMs = 15_000;
 const lockPollMs = 20;
 const lockMetadataMaxBytes = 512;
+const execFile = promisify(execFileCallback);
 export class ActivitySnapshotCacheError extends Error {
     code;
     constructor(code, message) {
@@ -207,7 +219,7 @@ async function readSnapshotFile(directory) {
         catch {
             return { status: "error", code: "malformed" };
         }
-        if (isRecord(value) && value.schemaVersion !== undefined && value.schemaVersion !== 1) {
+        if (isRecord(value) && value.schemaVersion !== undefined && value.schemaVersion !== 2) {
             return { status: "error", code: "unsupported_version" };
         }
         const parsed = activitySnapshotSchema.safeParse(value);
@@ -225,11 +237,17 @@ async function readSnapshotFile(directory) {
     }
 }
 async function atomicWriteSnapshot(directory, snapshot) {
-    const contents = `${JSON.stringify(snapshot)}\n`;
+    await atomicWriteCacheFile(directory, activitySnapshotCacheFileName, `${JSON.stringify(snapshot)}\n`);
+    // C-lane §2.1 fleet back-compat: dual-write the v1 payload so an
+    // already-installed v1 runner keeps rendering fresh data during the
+    // deprecation window instead of decaying into permanent staleness.
+    await atomicWriteCacheFile(directory, activitySnapshotLegacyCacheFileName, `${JSON.stringify(activitySnapshotV1Payload(snapshot))}\n`);
+}
+async function atomicWriteCacheFile(directory, fileName, contents) {
     if (Buffer.byteLength(contents, "utf8") > activitySnapshotCacheMaxBytes) {
         throw new ActivitySnapshotCacheError("invalid_snapshot", "Activity snapshot exceeds the 64 KiB cache limit.");
     }
-    const filePath = join(directory, activitySnapshotCacheFileName);
+    const filePath = join(directory, fileName);
     const existing = await lstat(filePath).catch((error) => {
         if (isNodeError(error, "ENOENT"))
             return undefined;
@@ -238,7 +256,7 @@ async function atomicWriteSnapshot(directory, snapshot) {
     if (existing?.isSymbolicLink() || (existing && !existing.isFile())) {
         throw new ActivitySnapshotCacheError("unsafe_file", "Activity snapshot cache path is not a regular file.");
     }
-    const temporaryPath = join(directory, `.${activitySnapshotCacheFileName}.${process.pid}.${randomUUID()}.tmp`);
+    const temporaryPath = join(directory, `.${fileName}.${process.pid}.${randomUUID()}.tmp`);
     let handle;
     try {
         handle = await open(temporaryPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollowFlag(), 0o600);
@@ -329,6 +347,84 @@ async function ensureDefaultParent(homeDirectory, create) {
     }
     if (create)
         await chmod(parent, 0o700);
+    await ensureDefaultCacheGitPrivacy(parent, create);
+}
+/**
+ * When a synthetic or real HOME is itself inside a Git worktree, protect the
+ * complete top-level private state directory before any cache child is
+ * created. Explicit AIBILL_CACHE_DIR/cacheDirectory overrides intentionally
+ * remain caller-owned and never receive repository files from this helper.
+ */
+async function ensureDefaultCacheGitPrivacy(aibillDirectory, create) {
+    const gitRoot = await findEnclosingGitRoot(aibillDirectory);
+    if (!gitRoot)
+        return;
+    const marker = join(aibillDirectory, ".gitignore");
+    let handle;
+    try {
+        handle = await open(marker, constants.O_RDONLY | noFollowFlag());
+    }
+    catch (error) {
+        if (!isNodeError(error, "ENOENT"))
+            throw error;
+        if (!create) {
+            const missing = new Error("Private aibill Git privacy marker does not exist.");
+            missing.code = "ENOENT";
+            throw missing;
+        }
+        handle = await open(marker, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollowFlag(), 0o600);
+        await handle.writeFile("*\n", "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = await open(marker, constants.O_RDONLY | noFollowFlag());
+    }
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || !hasPrivatePermissions(info.mode) || info.size !== 2) {
+            throw new ActivitySnapshotCacheError("unsafe_directory", "Private aibill Git privacy marker is unsafe.");
+        }
+        const buffer = Buffer.alloc(2);
+        const { bytesRead } = await handle.read(buffer, 0, 2, 0);
+        if (bytesRead !== 2 || buffer.toString("utf8") !== "*\n") {
+            throw new ActivitySnapshotCacheError("unsafe_directory", "Private aibill Git privacy marker is invalid.");
+        }
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+    const relativeDirectory = relative(gitRoot, aibillDirectory);
+    const tracked = await execFile("git", ["-C", gitRoot, "ls-files", "--", relativeDirectory], {
+        encoding: "utf8",
+        maxBuffer: 64 * 1024
+    }).then(({ stdout }) => stdout.trim()).catch(() => {
+        throw new ActivitySnapshotCacheError("unsafe_directory", "Private aibill cache tracking status could not be verified.");
+    });
+    if (tracked) {
+        throw new ActivitySnapshotCacheError("unsafe_directory", "Private aibill cache is already tracked by Git.");
+    }
+    const ignored = await execFile("git", [
+        "-C", gitRoot, "check-ignore", "--quiet", "--no-index", "--",
+        join(relativeDirectory, "cache", "privacy-probe.json")
+    ]).then(() => true).catch(() => false);
+    if (!ignored) {
+        throw new ActivitySnapshotCacheError("unsafe_directory", "Private aibill cache is not proven ignored by Git.");
+    }
+}
+async function findEnclosingGitRoot(path) {
+    let current = resolve(path);
+    while (true) {
+        const gitEntry = await lstat(join(current, ".git")).catch((error) => {
+            if (isNodeError(error, "ENOENT") || isNodeError(error, "ENOTDIR"))
+                return undefined;
+            throw error;
+        });
+        if (gitEntry)
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
 }
 function configuredCacheDirectory(options) {
     const configured = options.cacheDirectory?.trim() ||

package/dist/agentDraftToken.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The `ab1.` agent-draft token: how a conversationally drafted improve plan
+ * travels from `draft_improve_command` (MCP, read-only) to `aibill improve
+ * --draft` (terminal, human-approved) as ONE argv token.
+ *
+ * Design: AGENT_NATIVE_LOOP_DESIGN.md §2a (REV 2, QA-PASSED). The base64url
+ * alphabet contains no shell metacharacter, quote, or whitespace, so the
+ * token cannot break out of its argv slot in sh/bash/zsh/fish/pwsh and
+ * cannot be mangled by smart quotes, wrapping, or locale. Decoding NEVER
+ * throws — every failure is a tagged reason so a bad draft is set aside
+ * with copy, not a crash.
+ */
+/**
+ * AUTHORITATIVE bound (m11): the whole token is at most 20,000 characters,
+ * which implies decoded JSON ≤ ~15,000 bytes. There is no separate
+ * decoded-byte cap.
+ */
+export declare const MAX_AGENT_DRAFT_TOKEN_CHARS = 20000;
+export type AgentDraftV1 = {
+    v: 1;
+    experimentId: string;
+    revisionId: string;
+    change: string;
+    rollback: string;
+    canary: string;
+};
+export type AgentDraftDecodeFailureReason = "not_a_token" | "token_too_long" | "not_base64url_json" | "not_a_plain_object" | "unexpected_keys" | "unsupported_version" | "invalid_experiment_id" | "invalid_revision_id" | "invalid_sentence";
+export type AgentDraftDecodeResult = {
+    ok: true;
+    draft: AgentDraftV1;
+} | {
+    ok: false;
+    reason: AgentDraftDecodeFailureReason;
+};
+/** Cheap argv-time shape check shared with parseArgs (full decode comes later). */
+export declare function looksLikeAgentDraftToken(value: string): boolean;
+/**
+ * Decode and structurally validate an `ab1.` token. Hardening (m11, exact
+ * spec): the payload must JSON.parse to a plain object; keys are compared
+ * as a strict SET against the six expected keys (`Object.keys` DOES surface
+ * `__proto__` as an own key after JSON.parse, so `__proto__`/`constructor`/
+ * any extra key fails the set check); values are copied field-by-field onto
+ * a fresh null-prototype object before any further use. JSON duplicate keys
+ * are last-win in JSON.parse and undetectable post-parse: the decoded
+ * object is declared authoritative, and every value still passes the
+ * classifier gate afterwards.
+ */
+export declare function decodeAgentDraftTokenV1(token: string): AgentDraftDecodeResult;
+export type AgentDraftEncodeResult = {
+    ok: true;
+    token: string;
+} | {
+    ok: false;
+    reason: AgentDraftDecodeFailureReason;
+};
+/**
+ * Compose an `ab1.` token from validated fields. The only sanctioned caller
+ * is `draft_improve_command`; encoding enforces the same structural rules as
+ * decoding so a composing bug cannot emit an undecodable token.
+ */
+export declare function encodeAgentDraftTokenV1(draft: Omit<AgentDraftV1, "v">): AgentDraftEncodeResult;
+export type AgentDraftSentenceVerdict = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The ONE screening path a drafted plan sentence takes, used verbatim by
+ * `draft_improve_command` at composition and by `improve --draft` before a
+ * prefill can render: sanitize exactly like typed input, then classify with
+ * the shared hardened prose classifier. Because both surfaces call this
+ * function, MCP-preview and CLI-gate verdicts cannot diverge (QA 12).
+ *
+ * Rejection reasons are the terminal's own reprompt copy; credential
+ * rejections never echo the text.
+ */
+export declare function screenAgentDraftSentence(sentence: string): AgentDraftSentenceVerdict;
+//# sourceMappingURL=agentDraftToken.d.ts.map

package/dist/agentDraftToken.js

@@ -0,0 +1,188 @@
+/**
+ * The `ab1.` agent-draft token: how a conversationally drafted improve plan
+ * travels from `draft_improve_command` (MCP, read-only) to `aibill improve
+ * --draft` (terminal, human-approved) as ONE argv token.
+ *
+ * Design: AGENT_NATIVE_LOOP_DESIGN.md §2a (REV 2, QA-PASSED). The base64url
+ * alphabet contains no shell metacharacter, quote, or whitespace, so the
+ * token cannot break out of its argv slot in sh/bash/zsh/fish/pwsh and
+ * cannot be mangled by smart quotes, wrapping, or locale. Decoding NEVER
+ * throws — every failure is a tagged reason so a bad draft is set aside
+ * with copy, not a crash.
+ */
+import { classifyGuidedAnswer, looksLikeCredential } from "./guidedAnswer.js";
+import { sanitizeLocalActivityText } from "./localAgentLogs.js";
+/** `ab1` = aibill draft v1; `.` is outside base64url so the prefix is unambiguous. */
+const TOKEN_PREFIX = "ab1.";
+/**
+ * AUTHORITATIVE bound (m11): the whole token is at most 20,000 characters,
+ * which implies decoded JSON ≤ ~15,000 bytes. There is no separate
+ * decoded-byte cap.
+ */
+export const MAX_AGENT_DRAFT_TOKEN_CHARS = 20_000;
+const TOKEN_SHAPE = /^ab1\.[A-Za-z0-9_-]{16,}$/;
+const EXPERIMENT_ID_SHAPE = /^tre_v0_[a-f0-9]{64}$/;
+// The design sketched {1,64}, but real revision ids are `trev_v0_<64hex>`
+// (72 chars, actionVerification.ts L124) — widened to 128, same charset.
+const REVISION_ID_SHAPE = /^[A-Za-z0-9_-]{1,128}$/;
+/** Single-line plain text: no C0/C1 controls (same refine the MCP schema uses). */
+const CONTROL_CHARACTERS = /[\u0000-\u001F\u007F-\u009F]/;
+const MAX_SENTENCE_CHARS = 1_000;
+const EXPECTED_KEYS = [
+    "canary", "change", "experimentId", "revisionId", "rollback", "v"
+];
+/** Cheap argv-time shape check shared with parseArgs (full decode comes later). */
+export function looksLikeAgentDraftToken(value) {
+    return value.length <= MAX_AGENT_DRAFT_TOKEN_CHARS && TOKEN_SHAPE.test(value);
+}
+function validSentence(value) {
+    return typeof value === "string" &&
+        value.length >= 1 &&
+        value.length <= MAX_SENTENCE_CHARS &&
+        !CONTROL_CHARACTERS.test(value);
+}
+/**
+ * Decode and structurally validate an `ab1.` token. Hardening (m11, exact
+ * spec): the payload must JSON.parse to a plain object; keys are compared
+ * as a strict SET against the six expected keys (`Object.keys` DOES surface
+ * `__proto__` as an own key after JSON.parse, so `__proto__`/`constructor`/
+ * any extra key fails the set check); values are copied field-by-field onto
+ * a fresh null-prototype object before any further use. JSON duplicate keys
+ * are last-win in JSON.parse and undetectable post-parse: the decoded
+ * object is declared authoritative, and every value still passes the
+ * classifier gate afterwards.
+ */
+export function decodeAgentDraftTokenV1(token) {
+    if (typeof token !== "string" || !token.startsWith(TOKEN_PREFIX)) {
+        return { ok: false, reason: "not_a_token" };
+    }
+    if (token.length > MAX_AGENT_DRAFT_TOKEN_CHARS) {
+        return { ok: false, reason: "token_too_long" };
+    }
+    if (!TOKEN_SHAPE.test(token)) {
+        return { ok: false, reason: "not_a_token" };
+    }
+    let parsed;
+    try {
+        const payload = Buffer.from(token.slice(TOKEN_PREFIX.length), "base64url");
+        parsed = JSON.parse(payload.toString("utf8"));
+    }
+    catch {
+        return { ok: false, reason: "not_base64url_json" };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, reason: "not_a_plain_object" };
+    }
+    const keys = Object.keys(parsed).sort();
+    if (keys.length !== EXPECTED_KEYS.length ||
+        keys.some((key, index) => key !== EXPECTED_KEYS[index])) {
+        return { ok: false, reason: "unexpected_keys" };
+    }
+    // Field-by-field copy onto a null-prototype object; the parsed object is
+    // never spread or merged into a prototyped object.
+    const record = parsed;
+    const draft = Object.assign(Object.create(null), {
+        v: 1,
+        experimentId: "",
+        revisionId: "",
+        change: "",
+        rollback: "",
+        canary: ""
+    });
+    if (record.v !== 1)
+        return { ok: false, reason: "unsupported_version" };
+    if (typeof record.experimentId !== "string" ||
+        !EXPERIMENT_ID_SHAPE.test(record.experimentId)) {
+        return { ok: false, reason: "invalid_experiment_id" };
+    }
+    if (typeof record.revisionId !== "string" ||
+        !REVISION_ID_SHAPE.test(record.revisionId)) {
+        return { ok: false, reason: "invalid_revision_id" };
+    }
+    if (!validSentence(record.change) || !validSentence(record.rollback) ||
+        !validSentence(record.canary)) {
+        return { ok: false, reason: "invalid_sentence" };
+    }
+    draft.experimentId = record.experimentId;
+    draft.revisionId = record.revisionId;
+    draft.change = record.change;
+    draft.rollback = record.rollback;
+    draft.canary = record.canary;
+    return { ok: true, draft };
+}
+/**
+ * Compose an `ab1.` token from validated fields. The only sanctioned caller
+ * is `draft_improve_command`; encoding enforces the same structural rules as
+ * decoding so a composing bug cannot emit an undecodable token.
+ */
+export function encodeAgentDraftTokenV1(draft) {
+    if (!EXPERIMENT_ID_SHAPE.test(draft.experimentId)) {
+        return { ok: false, reason: "invalid_experiment_id" };
+    }
+    if (!REVISION_ID_SHAPE.test(draft.revisionId)) {
+        return { ok: false, reason: "invalid_revision_id" };
+    }
+    if (!validSentence(draft.change) || !validSentence(draft.rollback) ||
+        !validSentence(draft.canary)) {
+        return { ok: false, reason: "invalid_sentence" };
+    }
+    const payload = JSON.stringify({
+        v: 1,
+        experimentId: draft.experimentId,
+        revisionId: draft.revisionId,
+        change: draft.change,
+        rollback: draft.rollback,
+        canary: draft.canary
+    });
+    const token = TOKEN_PREFIX + Buffer.from(payload, "utf8").toString("base64url");
+    if (token.length > MAX_AGENT_DRAFT_TOKEN_CHARS) {
+        return { ok: false, reason: "token_too_long" };
+    }
+    return { ok: true, token };
+}
+/**
+ * The ONE screening path a drafted plan sentence takes, used verbatim by
+ * `draft_improve_command` at composition and by `improve --draft` before a
+ * prefill can render: sanitize exactly like typed input, then classify with
+ * the shared hardened prose classifier. Because both surfaces call this
+ * function, MCP-preview and CLI-gate verdicts cannot diverge (QA 12).
+ *
+ * Rejection reasons are the terminal's own reprompt copy; credential
+ * rejections never echo the text.
+ */
+export function screenAgentDraftSentence(sentence) {
+    // A credential anywhere in the RAW draft sets the whole field aside (the
+    // never-echoed A3 fallback path). Sanitizing it away and accepting the
+    // mutated remainder would record a sentence nobody wrote under the
+    // "Drafted with your agent" label (impl QA m-1).
+    if (looksLikeCredential(sentence)) {
+        return {
+            ok: false,
+            reason: "That draft contains something credential-shaped. aibill never stores credentials — the draft was set aside."
+        };
+    }
+    // Sanitize before classification so no rejection reason can echo raw
+    // fragments. An over-long sentence is rejected by the classifier's own
+    // length rule, with its own copy — never silently truncated.
+    const sanitized = sanitizeLocalActivityText(sentence).trim();
+    const verdict = classifyGuidedAnswer("prose", sanitized);
+    if (verdict.outcome === "accept") {
+        // `keep` is a terminal-only escape hatch, meaningless in a draft.
+        if (verdict.value === "keep") {
+            return {
+                ok: false,
+                reason: "That is aibill's own reserved vocabulary, not a plan sentence."
+            };
+        }
+        return { ok: true, value: verdict.value };
+    }
+    if (verdict.outcome === "reject") {
+        return { ok: false, reason: verdict.message };
+    }
+    // navigate/skip: the sentence collided with reserved navigation words.
+    return {
+        ok: false,
+        reason: "That is aibill's own navigation vocabulary (back/cancel), not a plan sentence."
+    };
+}
+//# sourceMappingURL=agentDraftToken.js.map