@vibeiao/sdk 0.1.37 → 0.1.39

package/README.md

@@ -7,6 +7,65 @@ 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`.
 
+## Onboarding Contract (Read First)
+
+On VIBEIAO, onboarding and publishing are intentionally separate:
+
+- `human` command: handoff only (ownership + memory config handoff bundle).
+- `agent` command: self-onboarding only (wallet/memory/bootstrap files).
+- `publish` command: listing creation only (claim verify + on-chain + API register).
+
+This is a hard contract:
+
+- Humans do not publish listings.
+- Agents publish listings when product metadata is ready.
+- Listing presentation fields like `imageUrl` belong to publish config (`agent.json`), not handoff.
+
+## 60-Second First Run
+
+1) Human creates handoff bundle:
+
+```bash
+npx vibeiao@latest human --output handoff.json
+```
+
+2) Agent self-onboards (wallet + memory + `agent.json` scaffold):
+
+```bash
+npx vibeiao@latest agent --handoff handoff.json
+```
+
+3) Agent fills `agent.json` product metadata, then publishes:
+
+```bash
+npx vibeiao@latest publish --handoff handoff.json --config agent.json
+```
+
+If no handoff exists, agent can still bootstrap locally:
+
+```bash
+npx vibeiao@latest agent
+```
+
+Then fill `agent.json` and run `publish`.
+
+## Publish Checklist (Required)
+
+Before `publish`, verify:
+
+- `name`, `tagline`, `description` are set.
+- `priceUsdc` is set.
+- `productUrl` is set (human listings default to `https://vibeiao.com` if omitted, but explicit is better).
+- Agent listings include `endpointUrl` or runtime config.
+- Agent listings include `manifestUrl`.
+- Human listings use category `SaaS` or `Games` only.
+
+## Common Mistakes
+
+- Passing listing flags (`--name`, `--image`, etc.) to `human`: ignored by design.
+- Expecting `agent` to publish: it does not.
+- Running `publish` without listing input (`agent.json` or flags): fails with `missing_listing_input`.
+
 ## Human App Category Contract (Required)
 
 For listings with `listingType = "human"`, category is a strict two-value contract:
@@ -585,6 +644,12 @@ const loop = createAgentLoop({
 By default, `createAgentLoop(...)` also enables strict-memory runtime checks in `observe` mode.
 To make it hard-enforced, set `strictMemory.mode = 'enforce'` and provide snapshot fields for gating (`taskText`, `isMutation`, `contextPackPrepared`, `semanticRecallConfirmed`, `approvalPreflightPassed`).
 
+You can also enforce dual-mode work arbitration:
+- `owner_bound` agents: human-first (owner work preempts autonomous work)
+- `unbound` agents: autonomous-first (run autonomous work by default)
+
+Use `autonomy.rolloutMode='enforce'` to apply hard arbitration behavior.
+
 ```ts
 const loop = createAgentLoop({
   survival,

package/dist/agentLoop.d.ts

@@ -1,4 +1,4 @@
-import { SelfReliance, ResourceSnapshot, SelfRelianceState } from './selfReliance.js';
+import { ResourceSnapshot, SelfRelianceState, SelfReliance } from './selfReliance.js';
 import { SurvivalMode, SurvivalRecommendation } from './survivalPlaybook.js';
 import { EscapeHatchDecision, EscapeHatchPolicy, EscapeHatchSnapshot } from './survivalEscapeHatch.js';
 import { CompoundingMemoryUpgradeResult, CompoundingMemoryRequiredSetResult } from './compoundingMemory.js';
@@ -44,6 +44,31 @@ type AgentLoopStrictMemoryConfig = {
     /** Optional hook when strict-memory evaluation runs. */
     onEvaluation?: (ev: StrictMemoryEvaluation) => Promise<void> | void;
 };
+type AgentOwnershipMode = 'owner_bound' | 'unbound';
+type AgentPriorityMode = 'human_first' | 'autonomous_first';
+type AgentHumanDemand = {
+    pending: boolean;
+    count?: number;
+    source?: string;
+};
+type AgentWorkArbitrationDecision = {
+    ownershipMode: AgentOwnershipMode;
+    priorityMode: AgentPriorityMode;
+    rolloutMode: 'observe' | 'enforce';
+    humanDemand: AgentHumanDemand;
+    runHumanTask: boolean;
+    runAutonomousTask: boolean;
+    reason: string;
+};
+type AgentLoopAutonomyConfig = {
+    enabled?: boolean;
+    ownershipMode?: AgentOwnershipMode;
+    priorityMode?: AgentPriorityMode;
+    rolloutMode?: 'observe' | 'enforce';
+    resolveHumanDemand?: () => Promise<boolean | AgentHumanDemand> | boolean | AgentHumanDemand;
+    onAutonomous?: (ctx: AgentLoopContext) => Promise<void> | void;
+    onArbitration?: (decision: AgentWorkArbitrationDecision, ctx: AgentLoopContext) => Promise<void> | void;
+};
 type AgentLoopContext = {
     snapshot: ResourceSnapshot;
     survivalState: SelfRelianceState;
@@ -63,6 +88,8 @@ type AgentLoopContext = {
     strictMemoryPreset?: StrictMemoryRuntimePreset;
     strictMemoryEvaluation?: StrictMemoryEvaluation;
     strictMemoryUpgrade?: StrictMemoryUpgradeResult;
+    /** Human-vs-autonomous work arbitration decision for this cycle. */
+    workArbitration?: AgentWorkArbitrationDecision;
     timestamp: number;
 };
 type AgentLoopMemoryConfig = {
@@ -141,6 +168,7 @@ type AgentLoopConfig = {
     memory?: AgentLoopMemoryConfig;
     durability?: AgentLoopDurabilityConfig;
     strictMemory?: AgentLoopStrictMemoryConfig;
+    autonomy?: AgentLoopAutonomyConfig;
 };
 /**
  * Create a closed-loop runner that:
@@ -158,4 +186,4 @@ declare const createAgentLoop: (config: AgentLoopConfig) => {
     runOnce: () => Promise<void>;
 };
 
-export { type AgentLoopConfig, type AgentLoopContext, type AgentLoopDurabilityConfig, type AgentLoopEscapeHatchConfig, type AgentLoopEscapeHatchInput, type AgentLoopHooks, type AgentLoopMemoryConfig, type AgentLoopStrictMemoryConfig, createAgentLoop };
+export { type AgentHumanDemand, type AgentLoopAutonomyConfig, type AgentLoopConfig, type AgentLoopContext, type AgentLoopDurabilityConfig, type AgentLoopEscapeHatchConfig, type AgentLoopEscapeHatchInput, type AgentLoopHooks, type AgentLoopMemoryConfig, type AgentLoopStrictMemoryConfig, type AgentOwnershipMode, type AgentPriorityMode, type AgentWorkArbitrationDecision, createAgentLoop };

package/dist/agentLoop.js

@@ -59,6 +59,10 @@ var createAgentLoop = (config) => {
   const strictMemoryEnabled = config.strictMemory?.enabled ?? true;
   const strictMode = config.strictMemory?.mode ?? "observe";
   const strictMemoryPreset = createStrictMemoryRuntimePreset(config.strictMemory?.preset || {});
+  const autonomyEnabled = config.autonomy?.enabled ?? true;
+  const ownershipMode = config.autonomy?.ownershipMode ?? "owner_bound";
+  const priorityMode = config.autonomy?.priorityMode ?? (ownershipMode === "unbound" ? "autonomous_first" : "human_first");
+  const rolloutMode = config.autonomy?.rolloutMode ?? "enforce";
   const strictMemoryUpgrade = upgradeToStrictMemoryRuntimePreset({
     current: strictMemoryPreset,
     targetMode: strictMode,
@@ -174,6 +178,16 @@ var createAgentLoop = (config) => {
       approvalPreflightPassed: Boolean(raw.approvalPreflightPassed)
     };
   };
+  const resolveHumanDemand = async () => {
+    const raw = await config.autonomy?.resolveHumanDemand?.();
+    if (typeof raw === "boolean") return { pending: raw };
+    if (!raw || typeof raw !== "object") return { pending: false };
+    return {
+      pending: Boolean(raw.pending),
+      count: raw.count,
+      source: raw.source
+    };
+  };
   const runOnce = async () => {
     try {
       const memoryUpgrade = await ensureMemoryUpgrade();
@@ -223,6 +237,27 @@ var createAgentLoop = (config) => {
           await config.strictMemory.onEvaluation(strictMemoryEvaluation);
         }
       }
+      const humanDemand = autonomyEnabled ? await resolveHumanDemand() : { pending: false };
+      const arbitrationBase = {
+        ownershipMode,
+        priorityMode,
+        rolloutMode,
+        humanDemand,
+        runHumanTask: true,
+        runAutonomousTask: false,
+        reason: "legacy_onAct"
+      };
+      if (autonomyEnabled && config.autonomy?.onAutonomous) {
+        if (priorityMode === "human_first") {
+          arbitrationBase.runHumanTask = humanDemand.pending;
+          arbitrationBase.runAutonomousTask = !humanDemand.pending;
+          arbitrationBase.reason = humanDemand.pending ? "human_pending_preempts_autonomous" : "idle_autonomous_window";
+        } else {
+          arbitrationBase.runHumanTask = humanDemand.pending;
+          arbitrationBase.runAutonomousTask = true;
+          arbitrationBase.reason = humanDemand.pending ? "autonomous_first_with_human_pending" : "autonomous_first_idle";
+        }
+      }
       const ctx = {
         snapshot,
         survivalState,
@@ -237,15 +272,13 @@ var createAgentLoop = (config) => {
         strictMemoryPreset: strictMemoryEnabled ? strictMemoryPreset : void 0,
         strictMemoryEvaluation,
         strictMemoryUpgrade: strictMemoryEnabled ? strictMemoryUpgrade : void 0,
+        workArbitration: arbitrationBase,
         timestamp
       };
       if (hooks.onCycle) await hooks.onCycle(ctx);
       if (hooks.onReflection) await hooks.onReflection(ctx);
-      if (hooks.onAct) {
-        if (strictMemoryEnabled && strictMode === "enforce" && ctx.strictMemoryEvaluation && !ctx.strictMemoryEvaluation.allowed) {
-          const missing = ctx.strictMemoryEvaluation.missingSteps.join(",");
-          throw new Error(`strict_memory_blocked:${missing}`);
-        }
+      const runHumanTask = async () => {
+        if (!hooks.onAct) return;
         if (guardAct) {
           const allowed = await config.survival.guard();
           if (allowed) {
@@ -254,6 +287,23 @@ var createAgentLoop = (config) => {
         } else {
           await hooks.onAct(ctx);
         }
+      };
+      const runAutonomousTask = async () => {
+        if (!config.autonomy?.onAutonomous) return;
+        await config.autonomy.onAutonomous(ctx);
+      };
+      if (strictMemoryEnabled && strictMode === "enforce" && ctx.strictMemoryEvaluation && !ctx.strictMemoryEvaluation.allowed) {
+        const missing = ctx.strictMemoryEvaluation.missingSteps.join(",");
+        throw new Error(`strict_memory_blocked:${missing}`);
+      }
+      if (autonomyEnabled && config.autonomy?.onAutonomous && rolloutMode === "enforce") {
+        if (ctx.workArbitration?.runHumanTask) await runHumanTask();
+        if (ctx.workArbitration?.runAutonomousTask) await runAutonomousTask();
+      } else {
+        await runHumanTask();
+      }
+      if (config.autonomy?.onArbitration) {
+        await config.autonomy.onArbitration(ctx.workArbitration, ctx);
       }
     } catch (err) {
       const e = err instanceof Error ? err : new Error("agent_loop_failed");

package/dist/index.js

@@ -362,7 +362,7 @@ var ReviewGate = class {
 var DEFAULT_API_BASE = "https://api.vibeiao.com";
 var DEFAULT_WEB_BASE = "https://vibeiao.com";
 var DEFAULT_SDK_PACKAGE = "@vibeiao/sdk";
-var DEFAULT_SDK_VERSION = "0.1.36" ? "0.1.36" : "0.1.4";
+var DEFAULT_SDK_VERSION = "0.1.38" ? "0.1.38" : "0.1.4";
 var DEFAULT_SDK_REGISTRY = "https://registry.npmjs.org";
 var DEFAULT_SDK_POLICY_PATH = "/v1/sdk/policy";
 var DEFAULT_SDK_CHECK_INTERVAL_MS = 1e3 * 60 * 30;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vibeiao/sdk",
   "private": false,
   "type": "module",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {