@vibeiao/sdk 0.1.29 → 0.1.31

package/README.md

@@ -7,6 +7,20 @@ 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`.
 
+## 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.

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
 };