auggy 0.3.0

package/src/augments/budgets/preamble.ts

@@ -0,0 +1,93 @@
+import type { ContextBlock } from "../../types";
+import type { BudgetCaps } from "./types";
+
+export interface BuildBudgetPreambleInput {
+  caps: BudgetCaps | null;
+  used: { thread: number; day: number; costUsd: number; unpricedTurns: number };
+}
+
+/**
+ * Build a BATS-style budget context block. Returns null when caps
+ * is null (bypass tier — creator/internal trigger) or when no caps
+ * fields are configured (nothing to render).
+ *
+ * The block content includes:
+ *   - Per-cap remaining values (turns/thread, turns/day, $/day)
+ *   - A behavioral guidance line based on the minimum budgetRatio
+ *
+ * Bucketed (not continuous) is deliberate — four distinct behavioral
+ * modes are more interpretable to a prose model than a smooth gradient.
+ *
+ *   ratio > 0.6        → "Explore thoroughly. No urgency."
+ *   ratio 0.2 ≤ 0.6    → "Focus on the core question. Begin wrapping up."
+ *   ratio < 0.2        → "Final response. Deliver a complete answer."
+ *   ratio === 0        → "Grace turn — summarize and close."
+ *
+ * Note on timing: when context() is called the current turn's reservation
+ * is already committed (Phase 3 of the 2PC gate runs before the context
+ * pipeline). So `used.thread` counts the current turn as consumed —
+ * "remaining" values correctly reflect how many turns are left *after*
+ * this one.
+ */
+export function buildBudgetPreamble(input: BuildBudgetPreambleInput): ContextBlock | null {
+  if (input.caps === null) return null;
+
+  const ratios: number[] = [];
+  if (input.caps.maxTurnsPerThread !== undefined) {
+    const remaining = Math.max(0, input.caps.maxTurnsPerThread - input.used.thread);
+    ratios.push(remaining / input.caps.maxTurnsPerThread);
+  }
+  if (input.caps.maxTurnsPerDay !== undefined) {
+    const remaining = Math.max(0, input.caps.maxTurnsPerDay - input.used.day);
+    ratios.push(remaining / input.caps.maxTurnsPerDay);
+  }
+  if (input.caps.maxUsdPerDay !== undefined) {
+    const remaining = Math.max(0, input.caps.maxUsdPerDay - input.used.costUsd);
+    ratios.push(remaining / input.caps.maxUsdPerDay);
+  }
+
+  if (ratios.length === 0) return null;
+  const ratio = Math.min(...ratios);
+
+  const lines: string[] = [];
+  if (input.caps.maxTurnsPerThread !== undefined) {
+    const remaining = Math.max(0, input.caps.maxTurnsPerThread - input.used.thread);
+    lines.push(`Turns remaining in this thread: ${remaining} of ${input.caps.maxTurnsPerThread}`);
+  }
+  if (input.caps.maxTurnsPerDay !== undefined) {
+    const remaining = Math.max(0, input.caps.maxTurnsPerDay - input.used.day);
+    lines.push(`Turns remaining today: ${remaining} of ${input.caps.maxTurnsPerDay}`);
+  }
+  if (input.caps.maxUsdPerDay !== undefined) {
+    lines.push(
+      `Estimated spend today: $${input.used.costUsd.toFixed(2)} of $${input.caps.maxUsdPerDay.toFixed(2)}`,
+    );
+  }
+  // Note: `input.used.unpricedTurns` is intentionally NOT rendered into the
+  // BATS preamble. Codex adversarial review (2026-05-04) flagged that
+  // exposing "Unpriced turns today: N" to the model lets a misaligned agent
+  // infer when budget enforcement is degraded — exactly the moment more
+  // spend can fly under the cap. The counter remains accessible via
+  // store.getPeerUsage() for operator-side tooling (deferred — see ROADMAP
+  // "Cost: operator cost-read API").
+  lines.push("");
+  lines.push(`Behavioral guidance (budgetRatio = ${ratio.toFixed(2)}): ${bucketGuidance(ratio)}`);
+
+  return {
+    source: "budgets",
+    content: lines.join("\n"),
+    placement: "preamble",
+    provenance: "augment",
+    priority: "high",
+    eviction: "drop",
+    origin: "system",
+    ttl: "turn",
+  };
+}
+
+function bucketGuidance(ratio: number): string {
+  if (ratio <= 0.0) return "Grace turn — summarize and close.";
+  if (ratio < 0.2) return "Final response. Deliver a complete answer.";
+  if (ratio < 0.6) return "Focus on the core question. Begin wrapping up.";
+  return "Explore thoroughly. No urgency.";
+}

package/src/augments/budgets/types.ts

@@ -0,0 +1,89 @@
+import type { TrustLevel } from "../../types";
+
+/**
+ * Per-trust-level spend and turn caps. All fields optional — omit a cap
+ * to leave it unconstrained.
+ */
+export interface BudgetCaps {
+  /** Maximum USD spend per calendar day for this peer. */
+  maxUsdPerDay?: number;
+  /** Maximum turns per thread per calendar day. */
+  maxTurnsPerThread?: number;
+  /** Maximum turns across all threads per calendar day for this peer. */
+  maxTurnsPerDay?: number;
+}
+
+/**
+ * Differentiated caps for the public trust level, split by publicSubstate.
+ * anonymous (no identity): tighter defaults (5 turns/thread, no daily).
+ * recognized (cookie/token-identified): looser defaults (20 turns/thread, 50/day, $1/day).
+ */
+export interface PublicBudgets {
+  anonymous?: BudgetCaps;
+  recognized?: BudgetCaps;
+}
+
+/**
+ * Full budgets augment config (passed by the T7 factory).
+ * creator omitted from caps = bypass entirely (no caps, no store write).
+ */
+export interface BudgetsConfig {
+  dbPath: string;
+  caps?: {
+    /** Caps for agent-trust peers. Omit = no caps for agents. */
+    agent?: BudgetCaps;
+    /**
+     * Caps for public-trust peers, differentiated by publicSubstate.
+     * Omit = no caps for public peers.
+     */
+    public?: PublicBudgets;
+    // creator omitted = bypass entirely
+  };
+  /**
+   * Facility-wide limit on anonymous prepares per rolling minute.
+   * Applies to publicSubstate === "anonymous" peers only.
+   */
+  anonymousGlobalLimit?: number;
+  /**
+   * Facility-wide daily USD ceiling (sum of all priced turns across all
+   * peers). Blocks admission once the day's total crosses this threshold.
+   */
+  dailyBudgetUsd?: number;
+  /** Milliseconds before a pending reservation is swept to 'allow:incomplete'. Default: 3_600_000. */
+  cleanupWindowMs?: number;
+}
+
+/**
+ * A staged reservation row — created inside the prepare transaction,
+ * committed when the kernel confirms the ticket.
+ */
+export interface TurnReservation {
+  turnId: string;
+  peerId: string;
+  threadId: string;
+  day: string; // YYYY-MM-DD UTC
+  trustLevel: TrustLevel;
+  publicSubstate: "anonymous" | "recognized" | null;
+  reservedAt: number;
+  committedAt: number | null;
+  costUsd: number | null;
+  priced: boolean;
+  decision: "allow" | "allow:incomplete" | "allow:orphaned";
+  reason: string | null;
+}
+
+/**
+ * Internal result produced by cap evaluation. null = allowed;
+ * string = denial reason.
+ */
+export type ReservationDecision = { allow: true } | { allow: false; reason: string };
+
+/**
+ * BudgetStore construction config (identical to the augment-level
+ * BudgetsConfig but slimmed to what the store actually needs).
+ */
+export interface BudgetStoreConfig {
+  dbPath: string;
+  /** Milliseconds before a pending reservation is swept. Default: 3_600_000. */
+  cleanupWindowMs?: number;
+}

package/src/augments/file-memory/index.ts

@@ -0,0 +1,71 @@
+import { readFile, writeFile } from "node:fs/promises";
+import type {
+  Augment,
+  MemoryEntry,
+  ContextOrigin,
+  ContextPriority,
+  ContextPlacement,
+  EvictionPolicy,
+} from "../../types";
+
+export interface FileMemoryOptions {
+  label: string;
+  source: string;
+  mutable: boolean;
+  origin: ContextOrigin;
+  priority: ContextPriority;
+  placement: ContextPlacement;
+  eviction: EvictionPolicy;
+  ttl?: "turn" | "session" | "persistent";
+}
+
+/**
+ * File-backed memory provider. Loads a file at boot into memory,
+ * serves read requests from the cache, and (if mutable) persists
+ * writes both in-memory and to disk.
+ *
+ * Used for identity (mutable: false, origin: "operator") and for
+ * agent self-notes (mutable: true, origin: "system").
+ */
+export function fileMemory(opts: FileMemoryOptions): Augment {
+  let cache: string | null = null;
+
+  const read = async (label: string): Promise<MemoryEntry | null> => {
+    if (label !== opts.label) return null;
+    if (cache === null) return null;
+    return { label: opts.label, content: cache };
+  };
+
+  const write = opts.mutable
+    ? async (label: string, content: string): Promise<void> => {
+        if (label !== opts.label) {
+          throw new Error(
+            `fileMemory: label "${label}" does not match declared label "${opts.label}"`,
+          );
+        }
+        cache = content;
+        await writeFile(opts.source, content, "utf-8");
+      }
+    : undefined;
+
+  return {
+    name: `file-memory-${opts.label}`,
+    capabilities: ["context", "tools"],
+    memory: {
+      owns: { kind: "static", labels: [opts.label] },
+      defaults: {
+        mutable: opts.mutable,
+        origin: opts.origin,
+        priority: opts.priority,
+        placement: opts.placement,
+        eviction: opts.eviction,
+        ttl: opts.ttl ?? "persistent",
+      },
+      read,
+      write,
+    },
+    onBoot: async () => {
+      cache = await readFile(opts.source, "utf-8");
+    },
+  };
+}