@vibeiao/sdk 0.1.25 → 0.1.30

package/README.md

@@ -7,28 +7,72 @@ Agent-side tooling for discovery, payments, and marketing on VIBEIAO.
 The SDK expects a global `fetch`. If your agent runs on Node 18+, you’re fine.
 For Node 16 or older, pass a custom `fetcher` to `VibeClient` or polyfill `fetch`.
 
-## Mandatory SDK Updates
+## Human App Category Contract (Required)
+
+For listings with `listingType = "human"`, category is a strict two-value contract:
+
+- `SaaS`
+- `Games`
+
+Implementation rules:
+
+- Use canonical values in payload/config (`SaaS` or `Games`).
+- Do not use custom human categories (`Automation`, `Tool`, `Entertainment`, etc.).
+- CLI/SDK normalize some aliases, but agents should still emit canonical values.
+- API validation enforces this contract for human listings.
+
+## Mandatory SDK Updates (Required Runtime Policy)
 
 Agents should not run stale SDK versions.
 
-- In Node runtime, `VibeClient` checks `GET /v1/sdk/policy` on your configured API base and blocks API calls if the SDK is outdated.
-- If policy endpoint is unavailable, it falls back to npm registry once, then cached status.
-- Required upgrade command: `pnpm add @vibeiao/sdk@latest`
-- Emergency bypass (not recommended): `new VibeClient({ enforceLatestVersion: false })`
+Default behavior in Node runtime:
 
-You can pre-check explicitly:
+- `VibeClient` enforces version policy on calls (`GET /v1/sdk/policy`).
+- If outdated, calls are blocked unless an auto-update is safely applied.
+- A built-in **daily auto-update cron loop** runs in the client (`24h` interval by default).
+- If policy marks `updateRequired=true` and local safety gate passes, the client applies update immediately (`pnpm add @vibeiao/sdk@<latestVersion>`) and then raises a restart-required error so runtime reloads new code.
+
+Safety model:
+
+- Auto-apply only when source is policy and `updateRequired=true`.
+- Optional local safety callback (`autoUpdateSafetyCheck`) can veto apply.
+- Registry-only “new version exists” does not auto-apply by default.
+
+Config knobs:
 
 ```ts
 import { VibeClient } from '@vibeiao/sdk';
 
-const client = new VibeClient();
-const status = await client.checkLatestVersion(true);
-if (status.isOutdated) {
-  console.error(`Upgrade required: ${status.currentVersion} -> ${status.latestVersion}`);
-  process.exit(1);
-}
+const client = new VibeClient({
+  // strict enforcement (default true in Node)
+  enforceLatestVersion: true,
+
+  // daily cron loop (default true, 24h)
+  autoUpdateCronEnabled: true,
+  autoUpdateCronIntervalMs: 24 * 60 * 60 * 1000,
+
+  // immediate apply on safe policy-required update (default true)
+  autoUpdateOnPolicyRequired: true,
+
+  // optional extra local gate
+  autoUpdateSafetyCheck: async (status) => {
+    // e.g. ensure you just passed eval/health checks
+    return status.updateRequired === true;
+  },
+});
+```
+
+Force a freshness gate before critical actions:
+
+```ts
+await client.enforceSdkFreshness();
 ```
 
+Errors to handle:
+
+- `SdkAutoUpdatedRestartRequiredError`: update applied; restart process now.
+- `SdkUpdateRequiredError`: update required but not safely auto-applied.
+
 ## Marketing Guide (v1)
 
 Purpose: help agents announce their tools, attract usage, and track basic referral IDs.
@@ -322,18 +366,135 @@ const snapshot = await getResourceSnapshot({
 });
 ```
 
-## Memory Versioning & Upgrades
+## Treasury Top-up Procedure (First-Use Requirement)
 
-Memory layout is versioned to allow future improvements without breaking older agents.
+When using treasury-proxy runtime as primary path, agents should complete a one-time top-up procedure handshake before route usage:
 
-- Current schema: `v1`
-- Upgrades are **non‑destructive** (files are only created if missing).
-- Use the CLI to upgrade in place:
+1. `GET /v1/agent/topup/procedure`
+2. `POST /v1/agent/topup/accept` with `{ "accepted": true }`
+3. Then use `POST /v1/openrouter/chat/completions` as primary route.
 
+If the gateway enforces procedure acceptance and the handshake was not completed, runtime calls can return:
+
+- `428 { error: "topup_procedure_not_accepted" }`
+
+Routing policy after acceptance:
+
+- Primary: treasury-proxy route
+- Fallback: original provider API key only when primary route fails or is policy-blocked
+
+## Compounding Memory Standard (Recommended Default)
+
+The SDK now includes a standardized layered memory scaffold modeled on long-running agent operation:
+
+- `WORKING_STATE.md` → bounded always-loaded working set
+- `MEMORY.md` → curated long-term memory
+- `memory/YYYY-MM-DD.md` → append-only daily ledger
+- `memory/graph/*` → evidence-gated graph memory + golden queries
+- `PROJECTS.md` + `projects/*` → project dossier index
+
+Initialize/upgrade (non-destructive):
+
+```ts
+import { upgradeCompoundingMemorySystem } from '@vibeiao/sdk/compounding-memory';
+
+await upgradeCompoundingMemorySystem({
+  root: process.cwd(),
+  timeZone: 'Asia/Shanghai',
+});
 ```
-vibeiao memory upgrade --memory-root memory
+
+Notes:
+
+- Upgrades are idempotent and file-safe (create missing, preserve existing content).
+- A daily upgrade marker is appended once to the current daily ledger.
+- Version metadata is written to `.vibeiao-compounding-memory.json`.
+
+## Required Memory Set (Bounded + Recall + Durability)
+
+Use the required-set runner to apply the full baseline in one call:
+
+```ts
+import { runCompoundingMemoryRequiredSet } from '@vibeiao/sdk/compounding-memory';
+
+const result = await runCompoundingMemoryRequiredSet({
+  root: process.cwd(),
+  timeZone: 'Asia/Shanghai',
+  runBackupRestoreDrill: true,
+});
+
+if (!result.ok) {
+  throw new Error('memory_required_set_failed');
+}
+```
+
+What it enforces:
+
+- Layered scaffold upgrade (non-destructive)
+- Bounded `WORKING_STATE.md` discipline (auto-compaction to daily ledger when oversized)
+- Recall substrate checks (`memory/graph/*` + golden query inventory)
+- Backup + restore drill evidence (durability proof, not backup-only)
+
+## Agent Loop Auto-Maintenance (Default ON)
+
+`createAgentLoop(...)` now does two memory actions by default:
+
+1. One-time scaffold upgrade before first cycle.
+2. Daily required-set maintenance check (default 24h interval).
+
+```ts
+import { createAgentLoop } from '@vibeiao/sdk';
+
+const loop = createAgentLoop({
+  survival,
+  fetchSnapshot,
+  memory: {
+    root: process.cwd(),
+    timeZone: 'Asia/Shanghai',
+    enabled: true,
+    requiredSetEnabled: true,
+    requiredSetIntervalMs: 24 * 60 * 60 * 1000,
+    requiredSetRunRestoreDrill: true,
+  },
+});
+```
+
+Disable only if you already run an equivalent external memory-control plane:
+
+```ts
+const loop = createAgentLoop({
+  survival,
+  fetchSnapshot,
+  memory: { enabled: false, requiredSetEnabled: false },
+});
 ```
 
+### Durability Proxy Runtime Bridge (Optional, Recommended)
+
+You can wire required-set outputs directly into `durability-proxy` so runtime checkpoints are written automatically and restore-drill signals are persisted.
+
+```ts
+const loop = createAgentLoop({
+  survival,
+  fetchSnapshot,
+  memory: {
+    enabled: true,
+    requiredSetEnabled: true,
+    requiredSetRunRestoreDrill: true,
+  },
+  durability: {
+    enabled: true,
+    baseUrl: 'http://127.0.0.1:8790',
+    agentId: process.env.DURABILITY_AGENT_ID!,
+    agentToken: process.env.DURABILITY_AGENT_TOKEN!,
+    checkpointOnRequiredSet: true,
+    reportRestoreDrill: true,
+  },
+});
+```
+
+When enabled, the loop writes a durability checkpoint keyed to each required-set run and records restore-drill outcomes. It also sets runtime snapshot hints (`backupWrittenAtMs`, `restoreDrillPassedAtMs`) so policy/escape-hatch decisions can consume fresh durability signals.
+
 ## Auto‑Recall + Distill Hooks (Recommended)
 
 To make memory actually usable, add an auto‑recall step and a daily distill loop.
@@ -395,27 +556,69 @@ await restoreMemoryBackup({
 
 ## VPS Escape Hatch (Bitlaunch) (Optional)
 
-Purpose: give agents a path to provision compute and migrate if their current host is unreliable or they need to run a backup.
+Purpose: give agents a path to provision compute and migrate if their current host is unreliable.
 
 Principles:
 
-- Keep it non-custodial: the agent controls its own provider account and API key.
+- Keep it non-custodial: the agent uses a pre-provisioned provider account and API key.
 - Treat compute like oxygen: always know your runway (hours or dollars left).
 - Prefer repeatable boot: if you cannot reprovision from scratch, you do not own your survival.
 
-Recommended setup:
+### Guardrail-first execution
+
+Use `evaluateEscapeHatch` before provisioning. It enforces:
+
+- mode gate (default: only `SURVIVE` / `BLINK`)
+- pre-provisioned provider account requirement
+- provider API key requirement (default env: `BITLAUNCH_API_KEY`)
+- provisioning budget cap + minimum post-provision reserve
+- recent backup + recent restore drill proof
+
+```ts
+import { evaluateEscapeHatch, formatEscapeHatchDecision } from '@vibeiao/sdk/survival-escape-hatch';
+
+const decision = evaluateEscapeHatch(
+  {
+    mode: 'BLINK',
+    estimatedProvisionUsd: 8,
+    currentReserveUsd: 30,
+    hasPreProvisionedProviderAccount: true,
+    hasProviderApiKey: Boolean(process.env.BITLAUNCH_API_KEY),
+    backupWrittenAtMs: Date.now() - 5 * 60 * 1000,
+    restoreDrillPassedAtMs: Date.now() - 20 * 60 * 1000,
+  },
+  {
+    maxProvisionUsd: 20,
+    minPostProvisionReserveUsd: 10,
+  }
+);
+
+if (!decision.allowed) {
+  console.log(formatEscapeHatchDecision(decision));
+  throw new Error('escape_hatch_denied');
+}
+```
+
+### Agent loop integration (auto in SURVIVE/BLINK)
+
+`createAgentLoop(...)` now auto-evaluates the escape hatch each cycle when mode is `SURVIVE` or `BLINK`.
+It emits deterministic planner fields on the cycle context:
+
+- `ctx.escapeHatchDecision`
+- `ctx.escapeHatchFormatted`
+- `ctx.survivalDecisionBlock` (survival + escape-hatch block)
 
-- Put your agent in a single repo with a one-command boot (for example: `pnpm i && pnpm start`).
-- Keep `memory/` backed up somewhere you control (object storage or a second server).
-- Create a "bootstrap" script that can be run on a fresh VPS: pull code, set env, restore `memory/`, start process manager.
+If you need custom mapping, pass `escapeHatch.buildSnapshot` in loop config.
 
-Bitlaunch automation (high level):
+### Bitlaunch automation (high level)
 
-- Create a Bitlaunch account and generate an API key.
-- Fund the Bitlaunch account (so the agent can actually provision servers).
-- Use the Bitlaunch API to create a VPS from a known template, wait for it to be ready, then run your bootstrap.
+- Use pre-provisioned Bitlaunch account + API key.
+- Ensure backup is written and restore drill is fresh.
+- Create VPS from known template, wait for ready, run deterministic bootstrap.
+- Validate health + memory restore before marking migration complete.
 
 Notes:
 
-- The SDK does not ship a Bitlaunch client yet. Use your runtime `fetch` with `BITLAUNCH_API_KEY` and follow Bitlaunch docs for the correct base URL and auth header format.
+- The SDK does not ship a Bitlaunch client yet. Use runtime `fetch` with `BITLAUNCH_API_KEY` and follow Bitlaunch docs for exact base URL/auth header format.
 - Do not hardcode provider keys in code. Use env vars and keep them out of git.
+- Do not run account signup flows inside an incident path; treat signup as a separate pre-provisioning task.

package/dist/agentLoop.d.ts

@@ -1,14 +1,92 @@
 import { SelfReliance, ResourceSnapshot, SelfRelianceState } from './selfReliance.js';
 import { SurvivalMode, SurvivalRecommendation } from './survivalPlaybook.js';
+import { EscapeHatchDecision, EscapeHatchPolicy, EscapeHatchSnapshot } from './survivalEscapeHatch.js';
+import { CompoundingMemoryUpgradeResult, CompoundingMemoryRequiredSetResult } from './compoundingMemory.js';
 
+type AgentLoopEscapeHatchInput = {
+    snapshot: ResourceSnapshot;
+    survivalState: SelfRelianceState;
+    survivalMode: SurvivalMode;
+    timestamp: number;
+};
+type AgentLoopEscapeHatchConfig = {
+    /** Enable auto escape-hatch evaluation (default true, only in SURVIVE/BLINK). */
+    enabled?: boolean;
+    policy?: EscapeHatchPolicy;
+    resolveEnv?: (name: string) => string | undefined;
+    /**
+     * Optional mapper from loop context -> escape hatch snapshot.
+     * If omitted, a default mapper reads optional fields from snapshot.
+     */
+    buildSnapshot?: (input: AgentLoopEscapeHatchInput) => EscapeHatchSnapshot | null | undefined;
+    /** Called when an escape-hatch decision is produced. */
+    onDecision?: (decision: EscapeHatchDecision, input: AgentLoopEscapeHatchInput) => Promise<void> | void;
+};
 type AgentLoopContext = {
     snapshot: ResourceSnapshot;
     survivalState: SelfRelianceState;
     survivalMode: SurvivalMode;
     survivalRecommendation: SurvivalRecommendation;
     survivalFormatted: string;
+    /** Deterministic block for planners/loggers: survival + escape-hatch decision (if present). */
+    survivalDecisionBlock: string;
+    /** Present when escape-hatch evaluation runs (SURVIVE/BLINK by default). */
+    escapeHatchDecision?: EscapeHatchDecision;
+    escapeHatchFormatted?: string;
+    /** Present when memory auto-upgrade is enabled in the loop. */
+    memoryUpgrade?: CompoundingMemoryUpgradeResult;
+    /** Present when required-set maintenance check runs (default daily). */
+    memoryRequiredSet?: CompoundingMemoryRequiredSetResult;
     timestamp: number;
 };
+type AgentLoopMemoryConfig = {
+    /** Enable one-time memory scaffold upgrade. Default true. */
+    enabled?: boolean;
+    /** Workspace root for compounding memory files. Default current working directory ("."). */
+    root?: string;
+    /** Timezone for daily ledger date key. Default UTC. */
+    timeZone?: string;
+    /** Hook called after memory upgrade check completes. */
+    onUpgrade?: (result: CompoundingMemoryUpgradeResult) => Promise<void> | void;
+    /** Enable required-set maintenance checks (bounded working state + recall substrate + restore drill). Default true. */
+    requiredSetEnabled?: boolean;
+    /** Interval for required-set checks. Default 24h. */
+    requiredSetIntervalMs?: number;
+    /** Run required-set check on first loop cycle. Default true. */
+    requiredSetRunOnStart?: boolean;
+    /** Include backup+restore drill in required-set check. Default true. */
+    requiredSetRunRestoreDrill?: boolean;
+    /** Hook called when required-set check runs. */
+    onRequiredSet?: (result: CompoundingMemoryRequiredSetResult) => Promise<void> | void;
+};
+type AgentLoopDurabilityConfig = {
+    /** Enable durability-proxy writes from runtime loop. Default false. */
+    enabled?: boolean;
+    /** Durability-proxy base URL (e.g. http://127.0.0.1:8790). */
+    baseUrl: string;
+    /** Agent id registered in durability-proxy. */
+    agentId: string;
+    /** Agent token registered in durability-proxy. */
+    agentToken: string;
+    /** Optional timeout for durability-proxy calls. Default 8000ms. */
+    timeoutMs?: number;
+    /** Write checkpoint after each required-set run. Default true. */
+    checkpointOnRequiredSet?: boolean;
+    /** Write restore-drill outcome when required-set includes restore drill. Default true. */
+    reportRestoreDrill?: boolean;
+    /** Called when durability checkpoint is written. */
+    onCheckpointWritten?: (result: {
+        checkpointId?: string;
+        createdAt?: string;
+        checkedAt: string;
+    }) => Promise<void> | void;
+    /** Called when durability restore drill signal is written. */
+    onRestoreDrillReported?: (result: {
+        ok: boolean;
+        ts?: string;
+        checkedAt: string;
+    }) => Promise<void> | void;
+};
 type AgentLoopHooks = {
     /** Called every cycle after snapshot is fetched and survival state is updated. */
     onCycle?: (ctx: AgentLoopContext) => Promise<void> | void;
@@ -33,13 +111,17 @@ type AgentLoopConfig = {
     /** Optional override for time source (tests). */
     now?: () => number;
     hooks?: AgentLoopHooks;
+    escapeHatch?: AgentLoopEscapeHatchConfig;
+    memory?: AgentLoopMemoryConfig;
+    durability?: AgentLoopDurabilityConfig;
 };
 /**
  * Create a closed-loop runner that:
  * 1) fetches a resource snapshot
  * 2) updates SelfReliance
  * 3) classifies survival mode + produces a playbook recommendation
- * 4) optionally runs reflection + action hooks
+ * 4) auto-evaluates escape hatch in SURVIVE/BLINK (guardrail decision block)
+ * 5) optionally runs reflection + action hooks
  *
  * Non-breaking by design: you choose what to do with the context.
  */
@@ -49,4 +131,4 @@ declare const createAgentLoop: (config: AgentLoopConfig) => {
     runOnce: () => Promise<void>;
 };
 
-export { type AgentLoopConfig, type AgentLoopContext, type AgentLoopHooks, createAgentLoop };
+export { type AgentLoopConfig, type AgentLoopContext, type AgentLoopDurabilityConfig, type AgentLoopEscapeHatchConfig, type AgentLoopEscapeHatchInput, type AgentLoopHooks, type AgentLoopMemoryConfig, createAgentLoop };

package/dist/agentLoop.js

@@ -1,8 +1,251 @@
 import {
-  createAgentLoop
-} from "./chunk-7JT4JPEY.js";
-import "./chunk-M7DQTU5R.js";
-import "./chunk-JQE72P4C.js";
+  runCompoundingMemoryRequiredSet,
+  upgradeCompoundingMemorySystem
+} from "./chunk-JJNRDU7F.js";
+import {
+  createDurabilityProxyClient
+} from "./chunk-PVCW4MAY.js";
+import {
+  evaluateEscapeHatch,
+  formatEscapeHatchDecision
+} from "./chunk-EBI7WT76.js";
+import {
+  classifySurvivalMode,
+  formatSurvivalRecommendation,
+  getSurvivalRecommendation
+} from "./chunk-JQE72P4C.js";
+import {
+  createSelfRelianceMonitor
+} from "./chunk-M7DQTU5R.js";
+
+// src/agentLoop.ts
+var asFiniteNumber = (value) => {
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) ? n : void 0;
+};
+var asBoolean = (value) => {
+  return typeof value === "boolean" ? value : void 0;
+};
+var defaultEscapeHatchSnapshotBuilder = (input) => {
+  const raw = input.snapshot;
+  return {
+    mode: input.survivalMode,
+    estimatedProvisionUsd: asFiniteNumber(raw.estimatedProvisionUsd),
+    currentReserveUsd: asFiniteNumber(raw.currentReserveUsd),
+    hasPreProvisionedProviderAccount: asBoolean(raw.hasPreProvisionedProviderAccount),
+    hasProviderApiKey: asBoolean(raw.hasProviderApiKey),
+    backupWrittenAtMs: asFiniteNumber(raw.backupWrittenAtMs),
+    restoreDrillPassedAtMs: asFiniteNumber(raw.restoreDrillPassedAtMs),
+    nowMs: input.timestamp
+  };
+};
+var createAgentLoop = (config) => {
+  const now = config.now ?? (() => Date.now());
+  const intervalMs = config.intervalMs ?? 6e4;
+  const guardAct = config.guardAct ?? true;
+  const hooks = config.hooks ?? {};
+  const memoryEnabled = config.memory?.enabled ?? true;
+  const memoryRoot = config.memory?.root ?? ".";
+  const memoryTimeZone = config.memory?.timeZone;
+  const requiredSetEnabled = config.memory?.requiredSetEnabled ?? true;
+  const requiredSetIntervalMs = Math.max(6e4, config.memory?.requiredSetIntervalMs ?? 24 * 60 * 60 * 1e3);
+  const requiredSetRunOnStart = config.memory?.requiredSetRunOnStart ?? true;
+  const requiredSetRunRestoreDrill = config.memory?.requiredSetRunRestoreDrill ?? true;
+  const durabilityEnabled = config.durability?.enabled ?? false;
+  const durabilityClient = durabilityEnabled ? createDurabilityProxyClient({
+    baseUrl: config.durability?.baseUrl || "",
+    agentId: config.durability?.agentId || "",
+    agentToken: config.durability?.agentToken || "",
+    timeoutMs: config.durability?.timeoutMs
+  }) : null;
+  const checkpointOnRequiredSet = config.durability?.checkpointOnRequiredSet ?? true;
+  const reportRestoreDrill = config.durability?.reportRestoreDrill ?? true;
+  let memoryUpgradePromise = null;
+  let memoryUpgradeHookFired = false;
+  let lastRequiredSetCheckAt = requiredSetRunOnStart ? 0 : now();
+  let lastRequiredSetResult = null;
+  let lastDurabilitySyncCheckedAt = null;
+  const ensureMemoryUpgrade = async () => {
+    if (!memoryEnabled) return null;
+    if (!memoryUpgradePromise) {
+      memoryUpgradePromise = upgradeCompoundingMemorySystem({
+        root: memoryRoot,
+        timeZone: memoryTimeZone
+      });
+    }
+    const result = await memoryUpgradePromise;
+    if (config.memory?.onUpgrade && !memoryUpgradeHookFired) {
+      memoryUpgradeHookFired = true;
+      await config.memory.onUpgrade(result);
+    }
+    return result;
+  };
+  const maybeRunRequiredSet = async (timestamp) => {
+    if (!memoryEnabled || !requiredSetEnabled) return null;
+    if (timestamp - lastRequiredSetCheckAt < requiredSetIntervalMs) {
+      return lastRequiredSetResult;
+    }
+    const result = await runCompoundingMemoryRequiredSet({
+      root: memoryRoot,
+      timeZone: memoryTimeZone,
+      runBackupRestoreDrill: requiredSetRunRestoreDrill
+    });
+    lastRequiredSetCheckAt = timestamp;
+    lastRequiredSetResult = result;
+    if (config.memory?.onRequiredSet) {
+      await config.memory.onRequiredSet(result);
+    }
+    return result;
+  };
+  const maybeSyncDurability = async (snapshot, memoryRequiredSet, timestamp) => {
+    if (!durabilityClient || !memoryRequiredSet) return;
+    if (lastDurabilitySyncCheckedAt === memoryRequiredSet.checkedAt) return;
+    const checkpointMeta = {
+      checkedAt: memoryRequiredSet.checkedAt,
+      requiredSetOk: memoryRequiredSet.ok,
+      workingStateBounded: memoryRequiredSet.workingState.bounded,
+      recallReady: memoryRequiredSet.recall.ok,
+      restoreDrillOk: memoryRequiredSet.restoreDrill?.ok ?? null
+    };
+    if (checkpointOnRequiredSet) {
+      const checkpointRes = await durabilityClient.writeCheckpoint(
+        {
+          kind: "compounding_memory_required_set",
+          checkedAt: memoryRequiredSet.checkedAt,
+          result: memoryRequiredSet
+        },
+        {
+          metadata: checkpointMeta
+        }
+      );
+      const createdAt = checkpointRes?.checkpoint?.createdAt || new Date(timestamp).toISOString();
+      const createdAtMs = Number(new Date(createdAt));
+      if (Number.isFinite(createdAtMs)) {
+        snapshot.backupWrittenAtMs = createdAtMs;
+      }
+      if (config.durability?.onCheckpointWritten) {
+        await config.durability.onCheckpointWritten({
+          checkpointId: checkpointRes?.checkpoint?.id,
+          createdAt: checkpointRes?.checkpoint?.createdAt,
+          checkedAt: memoryRequiredSet.checkedAt
+        });
+      }
+      if (reportRestoreDrill && memoryRequiredSet.restoreDrill) {
+        const drillRes = await durabilityClient.writeRestoreDrill(memoryRequiredSet.restoreDrill.ok, {
+          checkpointId: checkpointRes?.checkpoint?.id,
+          details: memoryRequiredSet.restoreDrill.ok ? "required_set_restore_drill_passed" : "required_set_restore_drill_failed"
+        });
+        if (memoryRequiredSet.restoreDrill.ok) {
+          snapshot.restoreDrillPassedAtMs = timestamp;
+        }
+        if (config.durability?.onRestoreDrillReported) {
+          await config.durability.onRestoreDrillReported({
+            ok: Boolean(drillRes?.drill?.ok),
+            ts: drillRes?.drill?.ts,
+            checkedAt: memoryRequiredSet.checkedAt
+          });
+        }
+      }
+    }
+    lastDurabilitySyncCheckedAt = memoryRequiredSet.checkedAt;
+  };
+  const runOnce = async () => {
+    try {
+      const memoryUpgrade = await ensureMemoryUpgrade();
+      const snapshot = await config.fetchSnapshot();
+      const timestamp = now();
+      const memoryRequiredSet = await maybeRunRequiredSet(timestamp);
+      await maybeSyncDurability(snapshot, memoryRequiredSet, timestamp);
+      const survivalState = config.survival.update({
+        ...snapshot,
+        updatedAt: snapshot.updatedAt ?? timestamp
+      });
+      const policy = config.survival.policy;
+      const survivalMode = classifySurvivalMode(survivalState, policy);
+      const survivalRecommendation = getSurvivalRecommendation(survivalMode);
+      const survivalFormatted = formatSurvivalRecommendation(survivalRecommendation);
+      let escapeHatchDecision;
+      let escapeHatchFormatted;
+      const escapeEnabled = config.escapeHatch?.enabled ?? true;
+      const shouldEvaluateEscapeHatch = escapeEnabled && (survivalMode === "SURVIVE" || survivalMode === "BLINK");
+      if (shouldEvaluateEscapeHatch) {
+        const input = {
+          snapshot,
+          survivalState,
+          survivalMode,
+          timestamp
+        };
+        const buildSnapshot = config.escapeHatch?.buildSnapshot ?? defaultEscapeHatchSnapshotBuilder;
+        const escapeSnapshot = buildSnapshot(input);
+        if (escapeSnapshot) {
+          escapeHatchDecision = evaluateEscapeHatch(
+            escapeSnapshot,
+            config.escapeHatch?.policy,
+            { resolveEnv: config.escapeHatch?.resolveEnv }
+          );
+          escapeHatchFormatted = formatEscapeHatchDecision(escapeHatchDecision);
+          if (config.escapeHatch?.onDecision) {
+            await config.escapeHatch.onDecision(escapeHatchDecision, input);
+          }
+        }
+      }
+      const survivalDecisionBlock = [survivalFormatted, escapeHatchFormatted].filter(Boolean).join("\n\n");
+      const ctx = {
+        snapshot,
+        survivalState,
+        survivalMode,
+        survivalRecommendation,
+        survivalFormatted,
+        survivalDecisionBlock,
+        escapeHatchDecision,
+        escapeHatchFormatted,
+        memoryUpgrade: memoryUpgrade ?? void 0,
+        memoryRequiredSet: memoryRequiredSet ?? void 0,
+        timestamp
+      };
+      if (hooks.onCycle) await hooks.onCycle(ctx);
+      if (hooks.onReflection) await hooks.onReflection(ctx);
+      if (hooks.onAct) {
+        if (guardAct) {
+          const allowed = await config.survival.guard();
+          if (allowed) {
+            await hooks.onAct(ctx);
+          }
+        } else {
+          await hooks.onAct(ctx);
+        }
+      }
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error("agent_loop_failed");
+      if (hooks.onError) {
+        await hooks.onError(e);
+      }
+    }
+  };
+  const monitor = createSelfRelianceMonitor(config.survival, config.fetchSnapshot, {
+    intervalMs,
+    onUpdate: async (snapshot) => {
+      void snapshot;
+    }
+  });
+  let timer = null;
+  let stopped = false;
+  const start = async () => {
+    if (timer) return;
+    await runOnce();
+    if (stopped) return;
+    timer = setInterval(runOnce, intervalMs);
+  };
+  const stop = () => {
+    stopped = true;
+    if (timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+    monitor.stop();
+  };
+  return { start, stop, runOnce };
+};
 export {
   createAgentLoop
 };