@vibeiao/sdk 0.1.25 → 0.1.29

package/README.md

@@ -7,28 +7,58 @@ 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
+## 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 +352,135 @@ const snapshot = await getResourceSnapshot({
 });
 ```
 
-## Memory Versioning & Upgrades
+## Treasury Top-up Procedure (First-Use Requirement)
+
+When using treasury-proxy runtime as primary path, agents should complete a one-time top-up procedure handshake before route usage:
+
+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',
+});
+```
+
+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)
 
-Memory layout is versioned to allow future improvements without breaking older agents.
+`createAgentLoop(...)` now does two memory actions by default:
 
-- Current schema: `v1`
-- Upgrades are **non‑destructive** (files are only created if missing).
-- Use the CLI to upgrade in place:
+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,
+  },
+});
 ```
-vibeiao memory upgrade --memory-root memory
+
+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 +542,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/package.json

@@ -2,7 +2,7 @@
   "name": "@vibeiao/sdk",
   "private": false,
   "type": "module",
-  "version": "0.1.25",
+  "version": "0.1.29",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -10,7 +10,12 @@
     "./solana": "./dist/solana.js",
     "./self-reliance": "./dist/selfReliance.js",
     "./memory": "./dist/memory.js",
-    "./reflection": "./dist/reflection.js"
+    "./compounding-memory": "./dist/compoundingMemory.js",
+    "./reflection": "./dist/reflection.js",
+    "./survival-escape-hatch": "./dist/survivalEscapeHatch.js",
+    "./agent-loop": "./dist/agentLoop.js",
+    "./market-discovery": "./dist/marketDiscovery.js",
+    "./treasury-guardian": "./dist/treasuryGuardian.js"
   },
   "files": [
     "dist",
@@ -20,7 +25,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/memory.ts src/selfReliance.ts src/solana.ts src/reflection.ts src/survivalPlaybook.ts src/survivalIntegration.ts src/agentLoop.ts src/marketDiscovery.ts --format esm --dts --tsconfig tsconfig.json --out-dir dist --define.__VIBEIAO_SDK_VERSION__=\\\"$npm_package_version\\\"",
+    "build": "tsup src/index.ts src/memory.ts src/compoundingMemory.ts src/selfReliance.ts src/solana.ts src/reflection.ts src/survivalPlaybook.ts src/survivalIntegration.ts src/survivalEscapeHatch.ts src/agentLoop.ts src/marketDiscovery.ts src/treasuryGuardian.ts --format esm --dts --tsconfig tsconfig.json --out-dir dist --define.__VIBEIAO_SDK_VERSION__=\\\"$npm_package_version\\\"",
     "test:e2e-memory": "pnpm build && node --test test/memory.e2e.test.mjs"
   },
   "dependencies": {
@@ -29,6 +34,7 @@
     "bn.js": "^5.2.1"
   },
   "devDependencies": {
+    "@types/node": "^22.13.10",
     "tsup": "^8.5.1"
   }
 }