agentlife 2.6.28 → 2.6.32

package/dist/index.js

@@ -2,9 +2,9 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // index.ts
-import { homedir as homedir15 } from "node:os";
-import * as path18 from "node:path";
-import { existsSync as existsSync7 } from "node:fs";
+import { homedir as homedir17 } from "node:os";
+import * as path20 from "node:path";
+import { existsSync as existsSync8 } from "node:fs";
 
 // db.ts
 import * as fsSync from "node:fs";
@@ -988,7 +988,7 @@ If you produce a followup whose residue (digits and parameter values stripped) m
 
 ### Guided mode — input surfaces
 
-When you need structured input, push a surface with \`input\` in the header. It renders in the input bar, not on the dashboard. Structure: \`surface <id> input\` → \`card\` → \`column\` → h3 question + 2+ buttons + optional \`textfield placeholder="..."\`.
+When you need structured input, push a surface with \`input\` in the header. It renders in the input bar, not on the dashboard. Structure: \`surface <id> input\` → \`card\` → \`column\` → h3 question + 2+ buttons.
 
 **Flow:**
 1. User clicks a button on a widget → \`[action:*]\`.
@@ -1581,6 +1581,82 @@ ${userSection}`;
 }
 
 // provisioning.ts
+function providerFromModel(model) {
+  const slash = model.indexOf("/");
+  if (slash <= 0)
+    return null;
+  return model.slice(0, slash).trim() || null;
+}
+function configuredProvidersFromConfig(cfg) {
+  const profiles = cfg?.auth?.profiles;
+  if (!profiles || typeof profiles !== "object")
+    return [];
+  const out = [];
+  for (const entry of Object.values(profiles)) {
+    const provider = entry?.provider;
+    if (typeof provider === "string" && provider.trim() && !out.includes(provider.trim())) {
+      out.push(provider.trim());
+    }
+  }
+  return out;
+}
+function hasGatewayDefaultModel(cfg) {
+  const modelCfg = cfg?.agents?.defaults?.model;
+  if (!modelCfg || typeof modelCfg !== "object")
+    return false;
+  if (typeof modelCfg.primary === "string" && modelCfg.primary.trim())
+    return true;
+  return Array.isArray(modelCfg.fallbacks) && modelCfg.fallbacks.some((m) => typeof m === "string" && m.trim());
+}
+function parseJsonArrayFromStdout(stdout) {
+  const raw = stdout.trim();
+  const jsonStart = raw.indexOf("[");
+  if (jsonStart < 0)
+    return [];
+  try {
+    const parsed = JSON.parse(raw.slice(jsonStart));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+async function resolveProvisionedAgentModel(cfg, currentList, runtime, log) {
+  if (hasGatewayDefaultModel(cfg))
+    return null;
+  const configuredProviders = configuredProvidersFromConfig(cfg);
+  if (configuredProviders.length === 0)
+    return null;
+  const configured = new Set(configuredProviders);
+  const provisionedIds = new Set(PROVISIONED_AGENTS.map((a) => a.id));
+  for (const agent of currentList) {
+    if (!agent || provisionedIds.has(agent.id))
+      continue;
+    const model = typeof agent.model === "string" ? agent.model.trim() : "";
+    const provider = model ? providerFromModel(model) : null;
+    if (model && provider && configured.has(provider)) {
+      return model;
+    }
+  }
+  const run = runtime.system?.runCommandWithTimeout;
+  if (!run)
+    return null;
+  try {
+    const result = await run(["openclaw", "infer", "model", "providers", "--json"], { timeoutMs: 60000 });
+    if ((result?.code ?? 0) !== 0)
+      return null;
+    const catalog = parseJsonArrayFromStdout(result?.stdout ?? "");
+    for (const provider of configuredProviders) {
+      const entry = catalog.find((p) => p?.provider === provider);
+      const defaults = Array.isArray(entry?.defaults) ? entry.defaults : [];
+      const firstDefault = defaults.find((m) => typeof m === "string" && m.trim());
+      if (firstDefault)
+        return `${provider}/${firstDefault.trim()}`;
+    }
+  } catch (err) {
+    log(`[agentlife] provisioned agent model discovery skipped: ${err?.message ?? err}`);
+  }
+  return null;
+}
 var PROVISIONED_AGENTS = [
   {
     id: "agentlife",
@@ -1671,6 +1747,7 @@ function scheduleEnrichment(state, runtime, targets, log) {
 async function provisionAgents(state, cfg, runtime, log) {
   const home = os.homedir();
   const currentList = [...cfg.agents?.list ?? []];
+  const provisionedModel = await resolveProvisionedAgentModel(cfg, currentList, runtime, log);
   let configChanged = false;
   const newlyProvisioned = [];
   for (const agent of PROVISIONED_AGENTS) {
@@ -1710,12 +1787,15 @@ async function provisionAgents(state, cfg, runtime, log) {
         name: agent.name,
         workspace: workspaceDir
       };
-      if (agent.isDefault)
+      const userOwnsDefault = currentList.some((a) => a?.default === true);
+      if (agent.isDefault && !userOwnsDefault)
         entry.default = true;
       if (agent.subagents)
         entry.subagents = agent.subagents;
       if (agent.tools)
         entry.tools = agent.tools;
+      if (provisionedModel)
+        entry.model = provisionedModel;
       if (agent.isDefault) {
         currentList.unshift(entry);
       } else {
@@ -1741,16 +1821,32 @@ async function provisionAgents(state, cfg, runtime, log) {
           configChanged = true;
           log(`[agentlife] added subagents for ${agent.id}`);
         }
+        if (provisionedModel && !existing.model) {
+          existing.model = provisionedModel;
+          configChanged = true;
+          log(`[agentlife] set model for ${agent.id}: ${provisionedModel}`);
+        }
+        if (agent.isDefault && existing.default === true) {
+          const userOwnsDefault = currentList.some((a) => a?.id !== agent.id && a?.default === true);
+          if (userOwnsDefault) {
+            delete existing.default;
+            configChanged = true;
+            log(`[agentlife] surrendered default to user agent (was ${agent.id})`);
+          }
+        }
       }
     }
   }
   const provisionedIds = new Set(PROVISIONED_AGENTS.map((a) => a.id));
+  const backfilledSubagentIds = [];
   for (const agent of currentList) {
     if (provisionedIds.has(agent.id))
       continue;
     if (!agent.subagents) {
       agent.subagents = { allowAgents: ["*"] };
       configChanged = true;
+      if (agent.id)
+        backfilledSubagentIds.push(agent.id);
       log(`[agentlife] backfilled subagents for ${agent.id}`);
     }
   }
@@ -1763,6 +1859,18 @@ async function provisionAgents(state, cfg, runtime, log) {
   const configPath = path4.join(os.homedir(), ".openclaw", "openclaw.json");
   const rawCfgForVisibility = JSON.parse(readFileSync2(configPath, "utf-8"));
   const backupPath = path4.join(os.homedir(), ".openclaw", "agentlife", "config-backup.json");
+  if (backfilledSubagentIds.length > 0) {
+    try {
+      let backup = {};
+      try {
+        backup = JSON.parse(readFileSync2(backupPath, "utf-8"));
+      } catch {}
+      const existing = Array.isArray(backup.subagentsBackfilledIds) ? backup.subagentsBackfilledIds : [];
+      backup.subagentsBackfilledIds = [...new Set([...existing, ...backfilledSubagentIds])];
+      writeFileSync(backupPath, JSON.stringify(backup, null, 2) + `
+`, "utf-8");
+    } catch {}
+  }
   let visibilityWritten = false;
   const currentVisibility = rawCfgForVisibility?.tools?.sessions?.visibility;
   if (currentVisibility !== "all") {
@@ -2085,7 +2193,6 @@ var KNOWN_BODY_KEYWORDS = new Set([
   "button",
   "image",
   "icon",
-  "textfield",
   "checkbox",
   "sparkline",
   "progress",
@@ -2117,7 +2224,6 @@ var INPUT_SURFACE_ACTIONS = new Set([
 var TEXT_LEVELS = new Set(["h1", "h2", "h3", "h4", "h5", "body", "caption"]);
 var TEXT_HINTS = new Set(["icon", "avatar", "smallfeature", "mediumfeature", "largefeature", "header"]);
 var IMG_FITS = new Set(["contain", "cover", "fill", "none", "scale-down"]);
-var TF_TYPES = new Set(["email", "shorttext", "number", "phone", "longtext", "date", "obscured"]);
 var ALIGN_VALUES = new Set(["start", "center", "end", "stretch"]);
 var DISTRIBUTE_VALUES = new Set(["start", "center", "end", "spacebetween", "spacearound", "spaceevenly"]);
 var TREND_VALUES = new Set(["up", "down", "flat"]);
@@ -2172,14 +2278,6 @@ var COMPONENT_CATALOG = {
     }
   },
   icon: { positionalTokens: new Set, positionalFree: true, attrs: {} },
-  textfield: {
-    positionalTokens: new Set,
-    positionalFree: true,
-    attrs: {
-      type: { kind: "enum", values: TF_TYPES },
-      placeholder: { kind: "free" }
-    }
-  },
   checkbox: {
     positionalTokens: new Set(["checked"]),
     positionalFree: true,
@@ -3194,17 +3292,21 @@ function pollFollowups(state) {
   }
   sweepCounter++;
   if (sweepCounter % 5 === 0 && state.surfaceIndex && state.followupQueue && state.fileSurfaceStorage) {
-    sweepExpiredSurfaces({
-      index: state.surfaceIndex,
-      queue: state.followupQueue,
-      storage: state.fileSurfaceStorage
-    }).then((r) => {
-      for (const sid of r.purged)
-        broadcastDelete(sid);
-      if (r.purged.length > 0) {
-        console.log("[agentlife:sweep] purged %d expired surfaces", r.purged.length);
-      }
-    }).catch((e) => console.warn("[agentlife:sweep] error: %s", e?.message));
+    try {
+      sweepExpiredSurfaces({
+        index: state.surfaceIndex,
+        queue: state.followupQueue,
+        storage: state.fileSurfaceStorage
+      }).then((r) => {
+        for (const sid of r.purged)
+          broadcastDelete(sid);
+        if (r.purged.length > 0) {
+          console.log("[agentlife:sweep] purged %d expired surfaces", r.purged.length);
+        }
+      }).catch((e) => console.warn("[agentlife:sweep] error: %s", e?.message));
+    } catch (e) {
+      console.warn("[agentlife] sweep invocation failed synchronously: %s", e?.message);
+    }
   }
 }
 
@@ -3473,9 +3575,9 @@ Each turn:
 2. Not enough → \`agentlife_push\` the SAME surfaceId \`welcome-input\` with:
    - h3 question generated from what the user just said
    - 2–4 multichoice buttons \`action=choice\`, options derived from the user's own words (NEVER hardcoded domain lists)
-   - \`textfield placeholder="Something else…"\` escape hatch
    - updated \`context: {"phase":"welcome","turn":N+1,"answers":[...]}\`
    - goal + followup unchanged
+   The input bar's text field is always-on, so the user can also type free text instead of picking a button — handle either response.
    Respond \`done\`.
 3. Enough → create the generalist and hand off the dashboard:
    - Workspace under \`$HOME/.openclaw/workspace-{id}\` (id = slugified short name or "me")
@@ -3505,7 +3607,6 @@ function renderWelcomeWidget(state, log) {
     `    column`,
     `      text "What do you want to track or improve?" h3`,
     `      text "One line. Anything — meals, money, a project, a habit." body`,
-    `      textfield placeholder="Type anything…"`,
     `goal: Onboard the user to their first agent via a guided interview`,
     `followup: +30m "If unanswered, replace the question with a gentler prompt."`,
     `context: {"phase":"welcome","turn":1,"answers":[]}`
@@ -3533,7 +3634,7 @@ function deleteWelcomeWidget(state, log) {
 }
 
 // services/surfaces-init.ts
-import * as path5 from "node:path";
+import * as path6 from "node:path";
 
 // storage/reconciler.ts
 var defaultLogger = {
@@ -3781,23 +3882,45 @@ function dispatchRehydrate(state, runtime, log = console.log) {
   log(`[agentlife:rehydrate] dispatched rehydrate to ${orphaned.length} orphaned agent(s): ${orphaned.join(", ")}`);
 }
 
+// runtime-mode.ts
+import * as path5 from "node:path";
+function isPluginInstallOrInspectProcess() {
+  const argv = process.argv.join(" ");
+  const entrypoint = path5.basename(process.argv[1] || "");
+  return entrypoint.includes("openclaw-plugins") || argv.includes("plugins") && argv.includes("install") || argv.includes("plugins") && argv.includes("inspect");
+}
+function shouldStartRuntimeServices() {
+  return !isPluginInstallOrInspectProcess();
+}
+
 // services/surfaces-init.ts
 function registerSurfacesService(api, state) {
   api.registerService({
     id: "agentlife-surfaces",
     start: async (ctx) => {
-      const agentlifeDir = path5.join(ctx.stateDir, "agentlife");
+      if (!shouldStartRuntimeServices())
+        return;
+      const agentlifeDir = path6.join(ctx.stateDir, "agentlife");
+      const nextHistoryDbPath = path6.join(agentlifeDir, "agentlife.db");
+      const previousHistoryDbPath = state.historyDbPath;
+      if (state.historyDb && previousHistoryDbPath && previousHistoryDbPath !== nextHistoryDbPath) {
+        try {
+          state.historyDb.close();
+        } catch {}
+        state.historyDb = null;
+        state.surfaceIndex = null;
+        state.followupQueue = null;
+      }
       state.agentlifeStateDir = agentlifeDir;
-      state.registryFilePath = path5.join(agentlifeDir, "agent-registry.json");
-      state.dbBaseDir = path5.join(agentlifeDir, "db");
-      state.historyDbPath = path5.join(agentlifeDir, "agentlife.db");
+      state.registryFilePath = path6.join(agentlifeDir, "agent-registry.json");
+      state.dbBaseDir = path6.join(agentlifeDir, "db");
+      state.historyDbPath = nextHistoryDbPath;
       const db = getOrCreateHistoryDb(state);
       if (!state.surfaceIndex)
         state.surfaceIndex = new SurfaceIndex(db);
       if (!state.followupQueue)
         state.followupQueue = new FollowupQueue(db);
-      if (!state.fileSurfaceStorage)
-        state.fileSurfaceStorage = new FileSurfaceStorage;
+      state.fileSurfaceStorage = new FileSurfaceStorage({ openclawRoot: ctx.stateDir });
       await loadRegistryFromDisk(state);
       try {
         const knownAgents = collectKnownAgents(api.runtime);
@@ -3847,11 +3970,11 @@ function collectKnownAgents(runtime) {
 
 // services/config-optimizer.ts
 import * as fs5 from "node:fs/promises";
-import * as path6 from "node:path";
+import * as path7 from "node:path";
 import * as os2 from "node:os";
 var TARGET_MAX_PING_PONG = 1;
 var TARGET_MAX_CONCURRENT = 10;
-var CONFIG_PATH = path6.join(os2.homedir(), ".openclaw", "openclaw.json");
+var CONFIG_PATH = process.env.OPENCLAW_CONFIG_PATH || path7.join(os2.homedir(), ".openclaw", "openclaw.json");
 async function readRawConfigFromDisk() {
   const raw = await fs5.readFile(CONFIG_PATH, "utf-8");
   return JSON.parse(raw);
@@ -3879,7 +4002,6 @@ async function restoreConfigFromBackup(api, backupPath) {
     delete fileCfg.agents?.defaults?.maxConcurrent;
   }
   await writeRawConfigToDisk(fileCfg);
-  await fs5.unlink(backupPath);
   console.log("[agentlife] restored config: maxPingPongTurns=%s, maxConcurrent=%s", backup.maxPingPongTurns ?? "default", backup.maxConcurrent ?? "default");
   return `config restored`;
 }
@@ -3887,8 +4009,10 @@ function registerConfigOptimizer(api, _state) {
   api.registerService({
     id: "agentlife-config-optimizer",
     start: async (ctx) => {
-      const configBackupDir = path6.join(ctx.stateDir, "agentlife");
-      const configBackupPath = path6.join(configBackupDir, "config-backup.json");
+      if (!shouldStartRuntimeServices())
+        return;
+      const configBackupDir = path7.join(ctx.stateDir, "agentlife");
+      const configBackupPath = path7.join(configBackupDir, "config-backup.json");
       const cfg = api.runtime.config.loadConfig();
       const currentPPT = cfg.session?.agentToAgent?.maxPingPongTurns;
       const currentMC = cfg.agents?.defaults?.maxConcurrent;
@@ -3899,10 +4023,16 @@ function registerConfigOptimizer(api, _state) {
         return;
       }
       await fs5.mkdir(configBackupDir, { recursive: true });
-      await fs5.writeFile(configBackupPath, JSON.stringify({
-        maxPingPongTurns: currentPPT ?? null,
-        maxConcurrent: currentMC ?? null
-      }));
+      let existing = {};
+      try {
+        existing = JSON.parse(await fs5.readFile(configBackupPath, "utf-8"));
+      } catch {}
+      if (!("maxPingPongTurns" in existing))
+        existing.maxPingPongTurns = currentPPT ?? null;
+      if (!("maxConcurrent" in existing))
+        existing.maxConcurrent = currentMC ?? null;
+      await fs5.writeFile(configBackupPath, JSON.stringify(existing, null, 2) + `
+`);
       const fileCfg = await readRawConfigFromDisk();
       if (needsPPT) {
         fileCfg.session ??= {};
@@ -3924,13 +4054,196 @@ function registerConfigOptimizer(api, _state) {
     },
     stop: async (ctx) => {
       try {
-        const backupPath = path6.join(ctx.stateDir, "agentlife", "config-backup.json");
+        const backupPath = path7.join(ctx.stateDir, "agentlife", "config-backup.json");
         await restoreConfigFromBackup(api, backupPath);
       } catch {}
     }
   });
 }
 
+// services/install-bootstrap.ts
+import * as fs6 from "node:fs";
+import * as path8 from "node:path";
+import * as os3 from "node:os";
+import { upsertAuthProfile } from "openclaw/plugin-sdk/provider-auth";
+function resolvePaths(home) {
+  const openclawDir = home ? path8.join(home, ".openclaw") : process.env.OPENCLAW_STATE_DIR || path8.join(os3.homedir(), ".openclaw");
+  const configPath = home ? path8.join(openclawDir, "openclaw.json") : process.env.OPENCLAW_CONFIG_PATH || path8.join(openclawDir, "openclaw.json");
+  const agentlifeDir = path8.join(openclawDir, "agentlife");
+  return {
+    configPath,
+    gatewayTokenFile: path8.join(openclawDir, "gateway-token.txt"),
+    agentlifeDir,
+    configBackupPath: path8.join(agentlifeDir, "config-backup.json"),
+    pairRequestMarker: path8.join(agentlifeDir, "pair-requested")
+  };
+}
+function readJsonSafe(p) {
+  try {
+    return JSON.parse(fs6.readFileSync(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeJson(p, obj) {
+  fs6.writeFileSync(p, JSON.stringify(obj, null, 2) + `
+`, "utf-8");
+}
+function normalizeLegacyCredential(profile) {
+  if (!profile || typeof profile !== "object")
+    return null;
+  if (typeof profile.provider !== "string" || !profile.provider.trim())
+    return null;
+  const credential = { ...profile };
+  if (credential.type === "api_key" && typeof credential.key !== "string" && typeof credential.apiKey === "string") {
+    credential.key = credential.apiKey;
+    delete credential.apiKey;
+  }
+  return credential;
+}
+function migrateLegacyAuthProfiles(openclawDir) {
+  const agentsRoot = path8.join(openclawDir, "agents");
+  let entries;
+  try {
+    entries = fs6.readdirSync(agentsRoot, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  let migrated = 0;
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink())
+      continue;
+    const agentDir = path8.join(agentsRoot, entry.name, "agent");
+    const legacyPath = path8.join(agentDir, "auth-profiles.json");
+    const legacy = readJsonSafe(legacyPath);
+    const profiles = legacy?.profiles;
+    if (!profiles || typeof profiles !== "object")
+      continue;
+    for (const [profileId, profile] of Object.entries(profiles)) {
+      const credential = normalizeLegacyCredential(profile);
+      if (!credential)
+        continue;
+      try {
+        upsertAuthProfile({ profileId, credential, agentDir });
+        migrated += 1;
+      } catch (err) {
+        console.warn(`[agentlife] install-bootstrap: auth profile migration skipped for ${entry.name}/${profileId}: ${err?.message ?? err}`);
+      }
+    }
+  }
+  if (migrated > 0) {
+    console.log(`[agentlife] install-bootstrap: migrated ${migrated} legacy auth profile(s) into OpenClaw auth store`);
+  }
+}
+function runInstallBootstrap(home) {
+  const P = resolvePaths(home);
+  try {
+    fs6.mkdirSync(P.agentlifeDir, { recursive: true, mode: 448 });
+  } catch (err) {
+    console.warn(`[agentlife] install-bootstrap: cannot create ${P.agentlifeDir}: ${err?.message ?? err}`);
+    return;
+  }
+  try {
+    fs6.writeFileSync(P.pairRequestMarker, String(Date.now()), { mode: 384 });
+  } catch (err) {
+    console.warn(`[agentlife] install-bootstrap: cannot write pair-requested marker: ${err?.message ?? err}`);
+  }
+  migrateLegacyAuthProfiles(path8.dirname(P.gatewayTokenFile));
+  if (!fs6.existsSync(P.configPath)) {
+    console.log("[agentlife] install-bootstrap: gateway config missing — deferring config writes");
+    return;
+  }
+  const cfg = readJsonSafe(P.configPath);
+  if (!cfg || typeof cfg !== "object") {
+    console.warn(`[agentlife] install-bootstrap: cannot parse ${P.configPath} — skipping config writes`);
+    return;
+  }
+  const existingBackup = readJsonSafe(P.configBackupPath) ?? {};
+  const originals = [
+    ["sessionsVisibility", cfg?.tools?.sessions?.visibility ?? null],
+    ["agentToAgentEnabled", cfg?.tools?.agentToAgent?.enabled ?? null],
+    ["gatewayBind", cfg?.gateway?.bind ?? null],
+    ["hooksAllowConversationAccess", cfg?.plugins?.entries?.agentlife?.hooks?.allowConversationAccess ?? null],
+    ["maxPingPongTurns", cfg?.session?.agentToAgent?.maxPingPongTurns ?? null],
+    ["maxConcurrent", cfg?.agents?.defaults?.maxConcurrent ?? null]
+  ];
+  let backupChanged = false;
+  for (const [k, orig] of originals) {
+    if (!(k in existingBackup)) {
+      existingBackup[k] = orig;
+      backupChanged = true;
+    }
+  }
+  if (backupChanged) {
+    try {
+      writeJson(P.configBackupPath, existingBackup);
+    } catch (err) {
+      console.warn(`[agentlife] install-bootstrap: cannot write backup: ${err?.message ?? err}`);
+    }
+  }
+  let changed = false;
+  cfg.gateway ??= {};
+  if (cfg.gateway.bind !== "lan") {
+    cfg.gateway.bind = "lan";
+    changed = true;
+  }
+  cfg.gateway.auth ??= {};
+  if (!cfg.gateway.auth.token && fs6.existsSync(P.gatewayTokenFile)) {
+    try {
+      const tok = fs6.readFileSync(P.gatewayTokenFile, "utf-8").trim();
+      if (tok) {
+        cfg.gateway.auth.token = tok;
+        changed = true;
+        console.log(`[agentlife] install-bootstrap: imported gateway token from ${P.gatewayTokenFile}`);
+      }
+    } catch (err) {
+      console.warn(`[agentlife] install-bootstrap: cannot read ${P.gatewayTokenFile}: ${err?.message ?? err}`);
+    }
+  }
+  cfg.tools ??= {};
+  cfg.tools.sessions ??= {};
+  if (cfg.tools.sessions.visibility !== "all") {
+    cfg.tools.sessions.visibility = "all";
+    changed = true;
+  }
+  cfg.tools.agentToAgent ??= {};
+  if (cfg.tools.agentToAgent.enabled !== true) {
+    cfg.tools.agentToAgent.enabled = true;
+    changed = true;
+  }
+  cfg.plugins ??= {};
+  cfg.plugins.entries ??= {};
+  cfg.plugins.entries.agentlife ??= {};
+  cfg.plugins.entries.agentlife.hooks ??= {};
+  if (cfg.plugins.entries.agentlife.hooks.allowConversationAccess !== true) {
+    cfg.plugins.entries.agentlife.hooks.allowConversationAccess = true;
+    changed = true;
+  }
+  cfg.session ??= {};
+  cfg.session.agentToAgent ??= {};
+  if (cfg.session.agentToAgent.maxPingPongTurns !== 1) {
+    cfg.session.agentToAgent.maxPingPongTurns = 1;
+    changed = true;
+  }
+  cfg.agents ??= {};
+  cfg.agents.defaults ??= {};
+  if (!cfg.agents.defaults.maxConcurrent || cfg.agents.defaults.maxConcurrent < 10) {
+    cfg.agents.defaults.maxConcurrent = 10;
+    changed = true;
+  }
+  if (!changed) {
+    console.log("[agentlife] install-bootstrap: config already normalized");
+    return;
+  }
+  try {
+    writeJson(P.configPath, cfg);
+    console.log("[agentlife] install-bootstrap: gateway config normalized (bind=lan, sessions.visibility=all, agentToAgent.enabled=true, hooks.allowConversationAccess=true, maxPingPongTurns=1, maxConcurrent=10)");
+    console.log("[agentlife] install-bootstrap: changes take effect on next `openclaw daemon restart`");
+  } catch (err) {
+    console.warn(`[agentlife] install-bootstrap: cannot write ${P.configPath}: ${err?.message ?? err}`);
+  }
+}
+
 // services/session-reconcile.ts
 function modelMatches(configured, sessionProvider, sessionModel) {
   if (!sessionModel)
@@ -4093,7 +4406,7 @@ async function reconcileInternalSessions(state, createdInternalSessions) {
 }
 
 // services/supervisor-cleanup.ts
-import * as fs6 from "node:fs";
+import * as fs7 from "node:fs";
 var STALE_SUPERVISOR_SURFACE = "supervisor-daily";
 var STALE_SUPERVISOR_DIRECT_SESSION = "agent:supervisor:agentlife:direct:operator";
 async function cleanupSupervisorLegacyState(state) {
@@ -4106,7 +4419,7 @@ async function cleanupSupervisorLegacyState(state) {
       removeFollowup(state, STALE_SUPERVISOR_SURFACE);
       if (view2 && !view2.isTransient && view2.path) {
         try {
-          fs6.unlinkSync(view2.path);
+          fs7.unlinkSync(view2.path);
         } catch {}
       }
       state.surfaceIndex?.delete(STALE_SUPERVISOR_SURFACE);
@@ -4288,6 +4601,8 @@ function startObservabilityService(state) {
 
 // hooks/activity-hooks.ts
 import * as fsSync2 from "node:fs";
+import * as nodePath from "node:path";
+import * as nodeOs from "node:os";
 
 // usage.ts
 var MODEL_COSTS = {
@@ -4936,6 +5251,62 @@ ${parts.join(`
 }
 var QUALITY_CHECK_MAX_WAIT_MS = 5000;
 var TERMINAL_MARKERS = new Set(["NO_REPLY", "ANNOUNCE_SKIP", "REPLY_SKIP", "HEARTBEAT_OK"]);
+function resolveOpenClawRoot() {
+  const fromEnv = process.env.OPENCLAW_STATE_DIR?.trim();
+  return fromEnv ? nodePath.resolve(fromEnv) : nodePath.join(nodeOs.homedir(), ".openclaw");
+}
+function findSessionModelError(agentId, sessionKey) {
+  const sessionsDir = nodePath.join(resolveOpenClawRoot(), "agents", agentId, "sessions");
+  const indexPath = nodePath.join(sessionsDir, "sessions.json");
+  let sessionFile = null;
+  try {
+    const index = JSON.parse(fsSync2.readFileSync(indexPath, "utf-8"));
+    const entry = index?.[sessionKey];
+    if (typeof entry?.sessionFile === "string") {
+      sessionFile = entry.sessionFile;
+    } else if (typeof entry?.sessionId === "string") {
+      sessionFile = nodePath.join(sessionsDir, `${entry.sessionId}.jsonl`);
+    }
+  } catch {
+    return null;
+  }
+  if (!sessionFile)
+    return null;
+  let provider;
+  let model;
+  let lines;
+  try {
+    lines = fsSync2.readFileSync(sessionFile, "utf-8").split(`
+`).filter(Boolean);
+  } catch {
+    return null;
+  }
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      if (entry?.type === "model_change") {
+        provider = typeof entry.provider === "string" ? entry.provider : provider;
+        model = typeof entry.modelId === "string" ? entry.modelId : model;
+      }
+    } catch {}
+  }
+  for (let i = lines.length - 1;i >= 0; i--) {
+    try {
+      const entry = JSON.parse(lines[i]);
+      const msg = entry?.message;
+      if (entry?.type !== "message" || msg?.role !== "assistant")
+        continue;
+      if (typeof msg.provider === "string")
+        provider = msg.provider;
+      if (typeof msg.model === "string")
+        model = msg.model;
+      if (typeof msg.errorMessage === "string" && msg.errorMessage.trim()) {
+        return { error: msg.errorMessage, provider, model };
+      }
+    } catch {}
+  }
+  return null;
+}
 function processPendingQualityChecks(state) {
   if (state.disabled || !state.historyDb)
     return 0;
@@ -4977,6 +5348,21 @@ function processPendingQualityChecks(state) {
       const pushed = db.prepare("SELECT COUNT(*) as c FROM surface_events WHERE event IN ('created','updated') AND createdAt > ? AND (agentId = ? OR agentId IS NULL)").get(row.runStart, row.agentId);
       if ((pushed?.c ?? 0) > 0)
         continue;
+      const modelError = findSessionModelError(row.agentId, row.sessionKey);
+      if (modelError) {
+        recordActivity(state, "quality_warning", row.sessionKey, row.agentId, {
+          runId: row.runId,
+          data: JSON.stringify({
+            issue: "model_error_no_widget",
+            trigger: row.trigger,
+            error: modelError.error,
+            provider: modelError.provider,
+            model: modelError.model
+          })
+        });
+        console.warn("[agentlife:quality] %s model error before widget push: %s", row.agentId, modelError.error);
+        continue;
+      }
       recordActivity(state, "quality_warning", row.sessionKey, row.agentId, {
         runId: row.runId,
         data: JSON.stringify({ issue: "no_widget_pushed", trigger: row.trigger })
@@ -5075,7 +5461,7 @@ function rescueOrphanedSurfaces(state, agentId, error) {
 }
 
 // services/escalation.ts
-import * as fs7 from "node:fs";
+import * as fs8 from "node:fs";
 var PATHOLOGY2 = process.env.PATHOLOGY_TEST_MODE === "1";
 var ESCALATION_REVIEW_THRESHOLD_MS = PATHOLOGY2 ? 2 * 60 * 1000 : 48 * 60 * 60 * 1000;
 var TREND_WINDOW_DAYS = 7;
@@ -5141,7 +5527,7 @@ function clearEscalationSurface(state, agentId) {
   const view2 = getSurface(state, surfaceId);
   if (view2 && !view2.isTransient && view2.path) {
     try {
-      fs7.unlinkSync(view2.path);
+      fs8.unlinkSync(view2.path);
     } catch {}
   }
   state.surfaceIndex.delete(surfaceId);
@@ -5385,31 +5771,32 @@ function startDailySweepService(state) {
 import * as crypto4 from "node:crypto";
 import * as fsSync3 from "node:fs";
 import { createRequire as createRequire3 } from "node:module";
-import * as os6 from "node:os";
-import * as path10 from "node:path";
+import * as os7 from "node:os";
+import * as path12 from "node:path";
 
 // gateway/web-app.ts
 import * as crypto3 from "node:crypto";
-import * as os5 from "node:os";
-import * as path9 from "node:path";
-import * as fs10 from "node:fs";
+import * as os6 from "node:os";
+import * as path11 from "node:path";
+import * as fs11 from "node:fs";
 
 // services/pairing-access-token.ts
 import * as crypto from "node:crypto";
-import * as fs8 from "node:fs";
-import * as os3 from "node:os";
-import * as path7 from "node:path";
+import * as fs9 from "node:fs";
+import * as os4 from "node:os";
+import * as path9 from "node:path";
 var cachedToken = null;
 function pairingAccessPath() {
-  return path7.join(os3.homedir(), ".openclaw", "agentlife", "pairing-access.json");
+  const stateDir = process.env.OPENCLAW_STATE_DIR || path9.join(os4.homedir(), ".openclaw");
+  return path9.join(stateDir, "agentlife", "pairing-access.json");
 }
 function loadOrCreatePairingAccessToken() {
   if (cachedToken)
     return cachedToken;
   const filePath = pairingAccessPath();
   try {
-    if (fs8.existsSync(filePath)) {
-      const raw = fs8.readFileSync(filePath, "utf-8");
+    if (fs9.existsSync(filePath)) {
+      const raw = fs9.readFileSync(filePath, "utf-8");
       const obj = JSON.parse(raw);
       const token2 = typeof obj?.token === "string" ? obj.token : null;
       if (token2 && token2.length >= 32) {
@@ -5418,12 +5805,12 @@ function loadOrCreatePairingAccessToken() {
       }
     }
     const token = crypto.randomBytes(32).toString("base64url");
-    const dir = path7.dirname(filePath);
-    if (!fs8.existsSync(dir))
-      fs8.mkdirSync(dir, { recursive: true, mode: 448 });
-    fs8.writeFileSync(filePath, JSON.stringify({ token, createdAtMs: Date.now() }, null, 2), { mode: 384 });
+    const dir = path9.dirname(filePath);
+    if (!fs9.existsSync(dir))
+      fs9.mkdirSync(dir, { recursive: true, mode: 448 });
+    fs9.writeFileSync(filePath, JSON.stringify({ token, createdAtMs: Date.now() }, null, 2), { mode: 384 });
     try {
-      fs8.chmodSync(filePath, 384);
+      fs9.chmodSync(filePath, 384);
     } catch {}
     cachedToken = token;
     return token;
@@ -5436,25 +5823,28 @@ function loadOrCreatePairingAccessToken() {
 // services/cloudflared-supervisor.ts
 import { spawn, spawnSync } from "node:child_process";
 import * as crypto2 from "node:crypto";
-import * as fs9 from "node:fs";
-import * as os4 from "node:os";
-import * as path8 from "node:path";
-var AGENTLIFE_DIR = path8.join(os4.homedir(), ".openclaw", "agentlife");
-var TUNNEL_FILE = path8.join(AGENTLIFE_DIR, "tunnel.json");
-var BIN_DIR = path8.join(AGENTLIFE_DIR, "bin");
-var PAIR_REQUEST_MARKER = path8.join(AGENTLIFE_DIR, "pair-requested");
-var IDENTITY_DIR = path8.join(os4.homedir(), ".agentlife");
-var DEVICE_FILE = path8.join(IDENTITY_DIR, "device.json");
-var LEGACY_DEVICE_FILE = path8.join(AGENTLIFE_DIR, "device.json");
-var CLOUDFLARED_BIN = os4.platform() === "win32" ? "cloudflared.exe" : "cloudflared";
-var CLOUDFLARED_PATH = path8.join(BIN_DIR, CLOUDFLARED_BIN);
+import * as fs10 from "node:fs";
+import * as os5 from "node:os";
+import * as path10 from "node:path";
+var DEFAULT_OPENCLAW_STATE_DIR = path10.join(os5.homedir(), ".openclaw");
+var OPENCLAW_STATE_DIR = process.env.OPENCLAW_STATE_DIR || DEFAULT_OPENCLAW_STATE_DIR;
+var IS_PROFILE_STATE_DIR = OPENCLAW_STATE_DIR !== DEFAULT_OPENCLAW_STATE_DIR;
+var AGENTLIFE_DIR = path10.join(OPENCLAW_STATE_DIR, "agentlife");
+var TUNNEL_FILE = path10.join(AGENTLIFE_DIR, "tunnel.json");
+var BIN_DIR = path10.join(AGENTLIFE_DIR, "bin");
+var PAIR_REQUEST_MARKER = path10.join(AGENTLIFE_DIR, "pair-requested");
+var IDENTITY_DIR = IS_PROFILE_STATE_DIR ? path10.join(OPENCLAW_STATE_DIR, ".agentlife") : path10.join(os5.homedir(), ".agentlife");
+var DEVICE_FILE = path10.join(IDENTITY_DIR, "device.json");
+var LEGACY_DEVICE_FILE = path10.join(AGENTLIFE_DIR, "device.json");
+var CLOUDFLARED_BIN = os5.platform() === "win32" ? "cloudflared.exe" : "cloudflared";
+var CLOUDFLARED_PATH = path10.join(BIN_DIR, CLOUDFLARED_BIN);
 var API_BASE = process.env.AGENTLIFE_API_BASE || "https://api.agentlife.app";
 var RESTART_DELAY_MS = 5000;
 var STABLE_RUNTIME_MS = 60000;
 function createInitialState() {
   let resolver;
-  const promise = new Promise((resolve) => {
-    resolver = resolve;
+  const promise = new Promise((resolve2) => {
+    resolver = resolve2;
   });
   return {
     tunnelInfo: null,
@@ -5475,7 +5865,7 @@ function getTunnelInfo() {
 function awaitTunnelReady(timeoutMs) {
   return Promise.race([
     state.readyPromise,
-    new Promise((resolve) => setTimeout(() => resolve(null), timeoutMs))
+    new Promise((resolve2) => setTimeout(() => resolve2(null), timeoutMs))
   ]);
 }
 function startCloudflaredSupervisor() {
@@ -5567,20 +5957,20 @@ async function doBootstrap() {
   return tunnelInfo;
 }
 function isPairRequested() {
-  return fs9.existsSync(PAIR_REQUEST_MARKER);
+  return fs10.existsSync(PAIR_REQUEST_MARKER);
 }
 function requestPair() {
   try {
-    if (!fs9.existsSync(AGENTLIFE_DIR))
-      fs9.mkdirSync(AGENTLIFE_DIR, { recursive: true, mode: 448 });
-    fs9.writeFileSync(PAIR_REQUEST_MARKER, String(Date.now()), { mode: 384 });
+    if (!fs10.existsSync(AGENTLIFE_DIR))
+      fs10.mkdirSync(AGENTLIFE_DIR, { recursive: true, mode: 448 });
+    fs10.writeFileSync(PAIR_REQUEST_MARKER, String(Date.now()), { mode: 384 });
   } catch (err) {
     console.warn(`[cloudflared-supervisor] failed to write pair-request marker: ${err?.message ?? err}`);
   }
 }
 function clearPairRequest() {
   try {
-    fs9.unlinkSync(PAIR_REQUEST_MARKER);
+    fs10.unlinkSync(PAIR_REQUEST_MARKER);
   } catch {}
 }
 function parseRetryAfter(value) {
@@ -5604,18 +5994,18 @@ function scheduleProvisionRetry(delayMs) {
   }, delayMs);
 }
 function ensureDirs() {
-  if (!fs9.existsSync(AGENTLIFE_DIR))
-    fs9.mkdirSync(AGENTLIFE_DIR, { recursive: true, mode: 448 });
-  if (!fs9.existsSync(BIN_DIR))
-    fs9.mkdirSync(BIN_DIR, { recursive: true, mode: 448 });
-  if (!fs9.existsSync(IDENTITY_DIR))
-    fs9.mkdirSync(IDENTITY_DIR, { recursive: true, mode: 448 });
+  if (!fs10.existsSync(AGENTLIFE_DIR))
+    fs10.mkdirSync(AGENTLIFE_DIR, { recursive: true, mode: 448 });
+  if (!fs10.existsSync(BIN_DIR))
+    fs10.mkdirSync(BIN_DIR, { recursive: true, mode: 448 });
+  if (!fs10.existsSync(IDENTITY_DIR))
+    fs10.mkdirSync(IDENTITY_DIR, { recursive: true, mode: 448 });
 }
 function readIdentityFile(filePath) {
-  if (!fs9.existsSync(filePath))
+  if (!fs10.existsSync(filePath))
     return null;
   try {
-    const raw = fs9.readFileSync(filePath, "utf-8");
+    const raw = fs10.readFileSync(filePath, "utf-8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.deviceId === "string" && typeof parsed.deviceSecret === "string") {
       return { deviceId: parsed.deviceId, deviceSecret: parsed.deviceSecret };
@@ -5633,14 +6023,14 @@ function loadDeviceIdentity() {
   if (!legacy)
     return null;
   try {
-    if (!fs9.existsSync(IDENTITY_DIR))
-      fs9.mkdirSync(IDENTITY_DIR, { recursive: true, mode: 448 });
-    fs9.writeFileSync(DEVICE_FILE, JSON.stringify(legacy, null, 2), { mode: 384 });
+    if (!fs10.existsSync(IDENTITY_DIR))
+      fs10.mkdirSync(IDENTITY_DIR, { recursive: true, mode: 448 });
+    fs10.writeFileSync(DEVICE_FILE, JSON.stringify(legacy, null, 2), { mode: 384 });
     try {
-      fs9.chmodSync(DEVICE_FILE, 384);
+      fs10.chmodSync(DEVICE_FILE, 384);
     } catch {}
     try {
-      fs9.unlinkSync(LEGACY_DEVICE_FILE);
+      fs10.unlinkSync(LEGACY_DEVICE_FILE);
     } catch {}
     console.log(`[cloudflared-supervisor] migrated device.json to ${DEVICE_FILE}`);
   } catch (err) {
@@ -5652,25 +6042,25 @@ function loadOrCreateDeviceIdentity() {
   const existing = loadDeviceIdentity();
   if (existing)
     return existing;
-  if (!fs9.existsSync(IDENTITY_DIR))
-    fs9.mkdirSync(IDENTITY_DIR, { recursive: true, mode: 448 });
+  if (!fs10.existsSync(IDENTITY_DIR))
+    fs10.mkdirSync(IDENTITY_DIR, { recursive: true, mode: 448 });
   const identity = {
     deviceId: crypto2.randomUUID(),
     deviceSecret: crypto2.randomBytes(32).toString("base64url")
   };
-  fs9.writeFileSync(DEVICE_FILE, JSON.stringify(identity, null, 2), { mode: 384 });
+  fs10.writeFileSync(DEVICE_FILE, JSON.stringify(identity, null, 2), { mode: 384 });
   try {
-    fs9.chmodSync(DEVICE_FILE, 384);
+    fs10.chmodSync(DEVICE_FILE, 384);
   } catch {}
   console.log(`[cloudflared-supervisor] generated new device identity (deviceId=${identity.deviceId})`);
   return identity;
 }
 var AGENTLIFE_API_BASE = API_BASE;
 function loadCachedTunnel() {
-  if (!fs9.existsSync(TUNNEL_FILE))
+  if (!fs10.existsSync(TUNNEL_FILE))
     return null;
   try {
-    const raw = fs9.readFileSync(TUNNEL_FILE, "utf-8");
+    const raw = fs10.readFileSync(TUNNEL_FILE, "utf-8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.subdomain === "string" && typeof parsed.hostname === "string" && typeof parsed.tunnelUrl === "string" && typeof parsed.tunnelToken === "string" && typeof parsed.provisionedAt === "number") {
       return parsed;
@@ -5679,9 +6069,9 @@ function loadCachedTunnel() {
   return null;
 }
 function persistTunnel(info) {
-  fs9.writeFileSync(TUNNEL_FILE, JSON.stringify(info, null, 2), { mode: 384 });
+  fs10.writeFileSync(TUNNEL_FILE, JSON.stringify(info, null, 2), { mode: 384 });
   try {
-    fs9.chmodSync(TUNNEL_FILE, 384);
+    fs10.chmodSync(TUNNEL_FILE, 384);
   } catch {}
 }
 async function provisionTunnel(identity) {
@@ -5734,14 +6124,14 @@ async function provisionTunnel(identity) {
   }
 }
 function ensureCloudflaredBinary() {
-  if (fs9.existsSync(CLOUDFLARED_PATH)) {
+  if (fs10.existsSync(CLOUDFLARED_PATH)) {
     try {
-      fs9.accessSync(CLOUDFLARED_PATH, fs9.constants.X_OK);
+      fs10.accessSync(CLOUDFLARED_PATH, fs10.constants.X_OK);
       return CLOUDFLARED_PATH;
     } catch {}
   }
-  const platform2 = os4.platform();
-  const arch2 = os4.arch();
+  const platform2 = os5.platform();
+  const arch2 = os5.arch();
   const release = detectCloudflaredRelease(platform2, arch2);
   if (!release) {
     console.warn(`[cloudflared-supervisor] unsupported platform: ${platform2}/${arch2}`);
@@ -5754,28 +6144,28 @@ function ensureCloudflaredBinary() {
   if (release.kind === "tgz") {
     const extracted = extractTgzCloudflared(release.tempPath, BIN_DIR);
     try {
-      fs9.unlinkSync(release.tempPath);
+      fs10.unlinkSync(release.tempPath);
     } catch {}
     if (!extracted)
       return null;
   } else {
     try {
-      fs9.renameSync(release.tempPath, CLOUDFLARED_PATH);
+      fs10.renameSync(release.tempPath, CLOUDFLARED_PATH);
     } catch (err) {
       console.warn(`[cloudflared-supervisor] rename failed: ${err?.message}`);
       return null;
     }
   }
   try {
-    fs9.chmodSync(CLOUDFLARED_PATH, 493);
+    fs10.chmodSync(CLOUDFLARED_PATH, 493);
   } catch {}
-  return fs9.existsSync(CLOUDFLARED_PATH) ? CLOUDFLARED_PATH : null;
+  return fs10.existsSync(CLOUDFLARED_PATH) ? CLOUDFLARED_PATH : null;
 }
 function detectCloudflaredRelease(platform2, arch2) {
   const base = "https://github.com/cloudflare/cloudflared/releases/latest/download";
   if (platform2 === "darwin") {
     const asset = arch2 === "arm64" ? "cloudflared-darwin-arm64.tgz" : "cloudflared-darwin-amd64.tgz";
-    return { url: `${base}/${asset}`, kind: "tgz", tempPath: path8.join(BIN_DIR, asset) };
+    return { url: `${base}/${asset}`, kind: "tgz", tempPath: path10.join(BIN_DIR, asset) };
   }
   if (platform2 === "linux") {
     const asset = arch2 === "arm64" ? "cloudflared-linux-arm64" : arch2 === "arm" ? "cloudflared-linux-arm" : arch2 === "x64" ? "cloudflared-linux-amd64" : null;
@@ -5799,11 +6189,11 @@ function downloadWithCurl(url, dest) {
   if (result.status !== 0) {
     console.warn(`[cloudflared-supervisor] curl failed (exit ${result.status}): ${result.stderr?.toString().slice(0, 200)}`);
     try {
-      fs9.unlinkSync(dest);
+      fs10.unlinkSync(dest);
     } catch {}
     return false;
   }
-  return fs9.existsSync(dest) && fs9.statSync(dest).size > 0;
+  return fs10.existsSync(dest) && fs10.statSync(dest).size > 0;
 }
 function extractTgzCloudflared(tgzPath, destDir) {
   const result = spawnSync("tar", ["-xzf", tgzPath, "-C", destDir], { stdio: "pipe" });
@@ -5811,10 +6201,10 @@ function extractTgzCloudflared(tgzPath, destDir) {
     console.warn(`[cloudflared-supervisor] tar extract failed (exit ${result.status}): ${result.stderr?.toString().slice(0, 200)}`);
     return false;
   }
-  return fs9.existsSync(CLOUDFLARED_PATH);
+  return fs10.existsSync(CLOUDFLARED_PATH);
 }
 function killOrphanedCloudflareds(binPath) {
-  if (os4.platform() === "win32")
+  if (os5.platform() === "win32")
     return;
   const found = spawnSync("pgrep", ["-f", binPath], { stdio: "pipe" });
   if (found.status !== 0)
@@ -5884,13 +6274,16 @@ var MIME_TYPES = {
   ".txt": "text/plain",
   ".map": "application/json"
 };
+function resolveStateDir() {
+  return process.env.OPENCLAW_STATE_DIR || path11.join(os6.homedir(), ".openclaw");
+}
 function mintBootstrapToken() {
   const bootstrapToken = crypto3.randomBytes(32).toString("base64url");
-  const devicesDir = path9.join(os5.homedir(), ".openclaw", "devices");
-  const bootstrapPath = path9.join(devicesDir, "bootstrap.json");
-  if (!fs10.existsSync(devicesDir))
-    fs10.mkdirSync(devicesDir, { recursive: true });
-  const registry = fs10.existsSync(bootstrapPath) ? JSON.parse(fs10.readFileSync(bootstrapPath, "utf-8")) : {};
+  const devicesDir = path11.join(resolveStateDir(), "devices");
+  const bootstrapPath = path11.join(devicesDir, "bootstrap.json");
+  if (!fs11.existsSync(devicesDir))
+    fs11.mkdirSync(devicesDir, { recursive: true });
+  const registry = fs11.existsSync(bootstrapPath) ? JSON.parse(fs11.readFileSync(bootstrapPath, "utf-8")) : {};
   registry[bootstrapToken] = {
     token: bootstrapToken,
     profile: {
@@ -5899,15 +6292,15 @@ function mintBootstrapToken() {
     },
     issuedAtMs: Date.now()
   };
-  fs10.writeFileSync(bootstrapPath, JSON.stringify(registry, null, 2));
+  fs11.writeFileSync(bootstrapPath, JSON.stringify(registry, null, 2));
   return bootstrapToken;
 }
 function registerWebApp(api) {
-  const pluginRoot = path9.resolve(path9.dirname(api.source), "..");
-  const appRoot = path9.join(pluginRoot, "web-build");
-  const hasWebBuild = fs10.existsSync(appRoot);
-  const indexPath = hasWebBuild ? path9.join(appRoot, "index.html") : null;
-  const hasIndex = !!(indexPath && fs10.existsSync(indexPath));
+  const pluginRoot = path11.resolve(path11.dirname(api.source), "..");
+  const appRoot = path11.join(pluginRoot, "web-build");
+  const hasWebBuild = fs11.existsSync(appRoot);
+  const indexPath = hasWebBuild ? path11.join(appRoot, "index.html") : null;
+  const hasIndex = !!(indexPath && fs11.existsSync(indexPath));
   if (!hasWebBuild) {
     api.logger.info("[agentlife] web-build/ not found — /agentlife/pair will still register; static dashboard disabled");
   } else if (!hasIndex) {
@@ -5915,11 +6308,13 @@ function registerWebApp(api) {
   }
   let gatewayToken = "";
   try {
-    const configPath = path9.join(__require("node:os").homedir(), ".openclaw", "openclaw.json");
-    const raw = JSON.parse(fs10.readFileSync(configPath, "utf-8"));
+    const configPath = process.env.OPENCLAW_CONFIG_PATH || path11.join(resolveStateDir(), "openclaw.json");
+    const raw = JSON.parse(fs11.readFileSync(configPath, "utf-8"));
     gatewayToken = raw?.gateway?.auth?.token || "";
   } catch {}
-  loadOrCreatePairingAccessToken();
+  if (shouldStartRuntimeServices()) {
+    loadOrCreatePairingAccessToken();
+  }
   const approveLatest = () => {
     try {
       const { execSync } = __require("node:child_process");
@@ -6034,16 +6429,16 @@ function registerWebApp(api) {
         return true;
       }
       const relative = urlPath.replace(/^\/agentlife\/?/, "") || "index.html";
-      const filePath = path9.resolve(appRoot, relative);
+      const filePath = path11.resolve(appRoot, relative);
       if (!filePath.startsWith(appRoot)) {
         res.writeHead(403);
         res.end();
         return true;
       }
-      const target = fs10.existsSync(filePath) && fs10.statSync(filePath).isFile() ? filePath : indexPath;
-      const ext = path9.extname(target).toLowerCase();
+      const target = fs11.existsSync(filePath) && fs11.statSync(filePath).isFile() ? filePath : indexPath;
+      const ext = path11.extname(target).toLowerCase();
       const contentType = MIME_TYPES[ext] || "application/octet-stream";
-      let content = fs10.readFileSync(target);
+      let content = fs11.readFileSync(target);
       if (target === indexPath) {
         setTimeout(approveLatest, 2000);
         setTimeout(approveLatest, 5000);
@@ -6079,62 +6474,29 @@ function registerWebApp(api) {
 
 // services/pairing.ts
 var TUNNEL_READY_TIMEOUT_MS = 90000;
+function resolveStateDir2(ctx) {
+  return ctx?.stateDir || process.env.OPENCLAW_STATE_DIR || path12.join(os7.homedir(), ".openclaw");
+}
 function registerPairingServices(api) {
   api.registerService({
     id: "agentlife-pairing-qr",
-    start: async (_ctx) => {
-      try {
-        const cfg = api.runtime.config.loadConfig();
-        const port = cfg.gateway?.port ?? 18789;
-        const token = cfg.gateway?.auth?.token;
-        if (!token)
-          return;
-        const supervisorTunnel = await awaitTunnelReady(TUNNEL_READY_TIMEOUT_MS) ?? getTunnelInfo();
-        if (!supervisorTunnel?.tunnelUrl) {
-          console.warn(`[agentlife] Cloudflared tunnel did not come up within ${TUNNEL_READY_TIMEOUT_MS / 1000}s — ` + `pairing QR will not be emitted. Check cloudflared-supervisor logs in the gateway output.`);
-          return;
-        }
-        const url = supervisorTunnel.tunnelUrl;
-        const bootstrapToken = mintBootstrapToken();
-        const payload = JSON.stringify({ url, bootstrapToken });
-        const setupCode = Buffer.from(payload).toString("base64url");
-        let qrTerminal = null;
-        try {
-          const realPath = fsSync3.realpathSync(process.argv[1] || "");
-          const mainRequire = createRequire3(realPath);
-          qrTerminal = mainRequire("qrcode-terminal");
-        } catch {}
-        console.log(`
-\x1B[36m[agentlife]\x1B[0m \x1B[1mPlugin installed — get the app to see your dashboard.\x1B[0m
-`);
-        if (qrTerminal?.generate) {
-          qrTerminal.generate(setupCode, { small: true }, (qr) => {
-            console.log(qr);
-            console.log(`
-Setup code: ${setupCode}
-`);
-          });
-        } else {
-          console.log(`Setup code: ${setupCode}`);
-        }
-        console.log("  \x1B[32mMac:\x1B[0m      https://agentlife.app/desktop");
-        console.log("  \x1B[32miOS:\x1B[0m      https://agentlife.app/ios");
-        console.log("  \x1B[32mAndroid:\x1B[0m  https://agentlife.app/android");
-        console.log(`  \x1B[2mBrowser:\x1B[0m  http://localhost:${port}/agentlife/`);
-        console.log(`
-  Scan the QR from the mobile app to connect.
-`);
-      } catch (err) {
+    start: (ctx) => {
+      if (!shouldStartRuntimeServices())
+        return;
+      emitPairingQr(api, ctx).catch((err) => {
         console.warn("[agentlife] QR generation skipped:", err?.message);
-      }
+      });
     }
   });
   api.registerService({
     id: "agentlife-auto-pair",
     start: async (ctx) => {
-      const devicesDir = path10.join(os6.homedir(), ".openclaw", "devices");
-      const pendingPath = path10.join(devicesDir, "pending.json");
-      const pairedPath = path10.join(devicesDir, "paired.json");
+      if (!shouldStartRuntimeServices())
+        return;
+      const stateDir = resolveStateDir2(ctx);
+      const devicesDir = path12.join(stateDir, "devices");
+      const pendingPath = path12.join(devicesDir, "pending.json");
+      const pairedPath = path12.join(devicesDir, "paired.json");
       const pollInterval = 3000;
       const withAdmin = (arr) => {
         const base = Array.isArray(arr) ? arr.filter((s) => typeof s === "string") : [];
@@ -6229,6 +6591,52 @@ Setup code: ${setupCode}
     }
   });
 }
+async function emitPairingQr(api, _ctx) {
+  try {
+    const cfg = api.runtime.config.loadConfig();
+    const port = cfg.gateway?.port ?? 18789;
+    const token = cfg.gateway?.auth?.token;
+    if (!token)
+      return;
+    const supervisorTunnel = await awaitTunnelReady(TUNNEL_READY_TIMEOUT_MS) ?? getTunnelInfo();
+    if (!supervisorTunnel?.tunnelUrl) {
+      console.warn(`[agentlife] Cloudflared tunnel did not come up within ${TUNNEL_READY_TIMEOUT_MS / 1000}s — ` + `pairing QR will not be emitted. Check cloudflared-supervisor logs in the gateway output.`);
+      return;
+    }
+    const url = supervisorTunnel.tunnelUrl;
+    const bootstrapToken = mintBootstrapToken();
+    const payload = JSON.stringify({ url, bootstrapToken });
+    const setupCode = Buffer.from(payload).toString("base64url");
+    let qrTerminal = null;
+    try {
+      const realPath = fsSync3.realpathSync(process.argv[1] || "");
+      const mainRequire = createRequire3(realPath);
+      qrTerminal = mainRequire("qrcode-terminal");
+    } catch {}
+    console.log(`
+\x1B[36m[agentlife]\x1B[0m \x1B[1mPlugin installed — get the app to see your dashboard.\x1B[0m
+`);
+    if (qrTerminal?.generate) {
+      qrTerminal.generate(setupCode, { small: true }, (qr) => {
+        console.log(qr);
+        console.log(`
+Setup code: ${setupCode}
+`);
+      });
+    } else {
+      console.log(`Setup code: ${setupCode}`);
+    }
+    console.log("  \x1B[32mMac:\x1B[0m      https://agentlife.app/desktop");
+    console.log("  \x1B[32miOS:\x1B[0m      https://agentlife.app/ios");
+    console.log("  \x1B[32mAndroid:\x1B[0m  https://agentlife.app/android");
+    console.log(`  \x1B[2mBrowser:\x1B[0m  http://localhost:${port}/agentlife/`);
+    console.log(`
+  Scan the QR from the mobile app to connect.
+`);
+  } catch (err) {
+    console.warn("[agentlife] QR generation skipped:", err?.message);
+  }
+}
 
 // hooks/bootstrap.ts
 var SKIP_GUIDANCE_AGENTS = new Set(["agentlife"]);
@@ -6388,15 +6796,15 @@ function registerBootstrapHookImpl(api, state2) {
 }
 
 // notifications.ts
-import * as fs11 from "node:fs";
-import * as path11 from "node:path";
+import * as fs12 from "node:fs";
+import * as path13 from "node:path";
 var config;
 function loadConfig() {
   if (config !== undefined)
     return config;
   try {
-    const configPath = path11.join(process.env.HOME ?? "~", ".openclaw", "agentlife", "notification-config.json");
-    const raw = fs11.readFileSync(configPath, "utf-8");
+    const configPath = path13.join(process.env.HOME ?? "~", ".openclaw", "agentlife", "notification-config.json");
+    const raw = fs12.readFileSync(configPath, "utf-8");
     const parsed = JSON.parse(raw);
     if (parsed.serverUrl && parsed.apiKey) {
       config = { serverUrl: parsed.serverUrl, apiKey: parsed.apiKey };
@@ -6966,9 +7374,101 @@ function registerPromptStateHook(api, state2) {
 }
 
 // gateway/agents.ts
-import * as fs12 from "node:fs";
-import * as os7 from "node:os";
-import * as path12 from "node:path";
+import * as fs13 from "node:fs";
+import * as os8 from "node:os";
+import * as path14 from "node:path";
+import { ensureAuthProfileStore, upsertAuthProfile as upsertAuthProfile2 } from "openclaw/plugin-sdk/provider-auth";
+function resolveOpenClawRoot2() {
+  const fromEnv = process.env.OPENCLAW_STATE_DIR?.trim();
+  return fromEnv ? path14.resolve(fromEnv) : path14.join(os8.homedir(), ".openclaw");
+}
+function providerFromModel2(model) {
+  const slash = model.indexOf("/");
+  if (slash <= 0)
+    return null;
+  return model.slice(0, slash).trim() || null;
+}
+function authenticatedProvidersFromConfig(cfg) {
+  const out = new Set;
+  const profiles = cfg?.auth?.profiles;
+  if (!profiles || typeof profiles !== "object")
+    return out;
+  for (const entry of Object.values(profiles)) {
+    const provider = entry?.provider;
+    if (typeof provider === "string" && provider.trim()) {
+      out.add(provider.trim());
+    }
+  }
+  return out;
+}
+function findSiblingAuthProfile(provider, targetAgentId) {
+  const agentsRoot = path14.join(resolveOpenClawRoot2(), "agents");
+  let entries;
+  try {
+    entries = fs13.readdirSync(agentsRoot, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink())
+      continue;
+    if (entry.name === targetAgentId)
+      continue;
+    const agentDir = path14.join(agentsRoot, entry.name, "agent");
+    try {
+      const store = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false, syncExternalCli: false });
+      for (const [profileId, profile] of Object.entries(store?.profiles ?? {})) {
+        if (profile?.provider !== provider)
+          continue;
+        const type = profile?.type;
+        const mode = profile?.mode;
+        if (type === "oauth")
+          continue;
+        if (mode === "oauth")
+          continue;
+        return { profileId, profile };
+      }
+    } catch {}
+    const file = path14.join(agentDir, "auth-profiles.json");
+    let data;
+    try {
+      data = JSON.parse(fs13.readFileSync(file, "utf-8"));
+    } catch {
+      continue;
+    }
+    const profiles = data?.profiles;
+    if (!profiles || typeof profiles !== "object")
+      continue;
+    for (const [profileId, profile] of Object.entries(profiles)) {
+      if (profile?.provider !== provider)
+        continue;
+      const type = profile?.type;
+      const mode = profile?.mode;
+      if (type === "oauth")
+        continue;
+      if (mode === "oauth")
+        continue;
+      return {
+        profileId,
+        profile
+      };
+    }
+  }
+  return null;
+}
+function writeAgentAuthProfile(agentId, provider, match) {
+  if (!match)
+    return false;
+  const agentDir = path14.join(resolveOpenClawRoot2(), "agents", agentId, "agent");
+  fs13.mkdirSync(agentDir, { recursive: true });
+  const credential = { ...match.profile };
+  if (credential.type === "api_key" && typeof credential.key !== "string" && typeof credential.apiKey === "string") {
+    credential.key = credential.apiKey;
+    delete credential.apiKey;
+  }
+  upsertAuthProfile2({ profileId: match.profileId, credential, agentDir });
+  return true;
+}
 function registerAgentGateway(api, state2) {
   api.registerGatewayMethod("agentlife.createAgent", async ({ params, respond }) => {
     const id = typeof params?.id === "string" ? params.id.trim() : "";
@@ -6980,14 +7480,26 @@ function registerAgentGateway(api, state2) {
     const subagents = params?.subagents && typeof params.subagents === "object" ? params.subagents : undefined;
     const identity = params?.identity && typeof params.identity === "object" ? params.identity : undefined;
     if (!id) {
-      respond(false, { error: "missing agent id" });
+      respond(false, undefined, { code: "INVALID_REQUEST", message: "missing agent id" });
       return;
     }
     if (!workspace) {
-      respond(false, { error: "missing workspace path" });
+      respond(false, undefined, { code: "INVALID_REQUEST", message: "missing workspace path" });
       return;
     }
     const cfg = api.runtime.config.loadConfig();
+    const provider = model ? providerFromModel2(model) : null;
+    const providerInConfig = provider ? authenticatedProvidersFromConfig(cfg).has(provider) : false;
+    const siblingAuth = provider ? findSiblingAuthProfile(provider, id) : null;
+    if (provider && !providerInConfig && !siblingAuth) {
+      respond(false, undefined, {
+        code: "missing_provider_auth",
+        message: `missing provider credentials for ${provider}; configure ${provider} before creating an agent with ${model}`,
+        provider,
+        model
+      });
+      return;
+    }
     const currentList = cfg.agents?.list ?? [];
     const existing = currentList.find((a) => a.id === id);
     if (!existing) {
@@ -7034,6 +7546,10 @@ function registerAgentGateway(api, state2) {
         console.log("[agentlife] builder patched agent config: %s", id);
       }
     }
+    const authCopied = provider ? writeAgentAuthProfile(id, provider, siblingAuth) : false;
+    if (authCopied) {
+      console.log("[agentlife] copied %s auth profile into agent: %s", provider, id);
+    }
     const hasGoodDescription = description && isUsableDescription(description, id, name);
     state2.agentRegistry.set(id, {
       name: name || id,
@@ -7063,17 +7579,17 @@ function registerAgentGateway(api, state2) {
         console.warn("[agentlife] deleteWelcomeWidget failed for %s: %s", id, e?.message);
       }
     }
-    respond(true, { status, id, name, model, workspace, description, ...configFields.length ? { configFields } : {} });
-  });
+    respond(true, { status, id, name, model, workspace, description, ...authCopied ? { authCopied: true } : {}, ...configFields.length ? { configFields } : {} });
+  }, { scope: "operator.admin" });
   api.registerGatewayMethod("agentlife.deleteAgent", async ({ params, respond }) => {
     const id = typeof params?.id === "string" ? params.id.trim() : "";
     if (!id) {
-      respond(false, { error: "missing agent id" });
+      respond(false, undefined, { code: "INVALID_REQUEST", message: "missing agent id" });
       return;
     }
     const provisionedIds = new Set(PROVISIONED_AGENTS.map((a) => a.id));
     if (provisionedIds.has(id)) {
-      respond(false, { error: "cannot delete provisioned agent" });
+      respond(false, undefined, { code: "FAILED", message: "cannot delete provisioned agent" });
       return;
     }
     const cleanup = {
@@ -7156,10 +7672,10 @@ function registerAgentGateway(api, state2) {
       state2.agentDbs.delete(id);
     }
     if (state2.dbBaseDir) {
-      const dbPath = path12.join(state2.dbBaseDir, `${id}.db`);
+      const dbPath = path14.join(state2.dbBaseDir, `${id}.db`);
       try {
-        if (fs12.existsSync(dbPath)) {
-          fs12.unlinkSync(dbPath);
+        if (fs13.existsSync(dbPath)) {
+          fs13.unlinkSync(dbPath);
           cleanup.agentDbDeleted = true;
         }
       } catch (e) {
@@ -7171,24 +7687,24 @@ function registerAgentGateway(api, state2) {
     const existingEntry = currentList.find((a) => a.id === id);
     const filtered = currentList.filter((a) => a.id !== id);
     const removedFromConfig = filtered.length < currentList.length;
-    const openclawHome = path12.join(os7.homedir(), ".openclaw");
-    const stateDir = path12.join(openclawHome, "agents", id);
-    if (stateDir.startsWith(path12.join(openclawHome, "agents") + path12.sep)) {
+    const openclawHome = path14.join(os8.homedir(), ".openclaw");
+    const stateDir = path14.join(openclawHome, "agents", id);
+    if (stateDir.startsWith(path14.join(openclawHome, "agents") + path14.sep)) {
       try {
-        if (fs12.existsSync(stateDir)) {
-          fs12.rmSync(stateDir, { recursive: true, force: true });
+        if (fs13.existsSync(stateDir)) {
+          fs13.rmSync(stateDir, { recursive: true, force: true });
           cleanup.stateDeleted = true;
         }
       } catch (e) {
         console.warn("[agentlife] deleteAgent: failed to delete state dir:", e?.message);
       }
     }
-    const defaultWorkspace = path12.join(openclawHome, `workspace-${id}`);
-    const workspaceToDelete = typeof existingEntry?.workspace === "string" && existingEntry.workspace.trim() ? path12.resolve(existingEntry.workspace) : defaultWorkspace;
-    if (workspaceToDelete.startsWith(openclawHome + path12.sep) && workspaceToDelete !== openclawHome) {
+    const defaultWorkspace = path14.join(openclawHome, `workspace-${id}`);
+    const workspaceToDelete = typeof existingEntry?.workspace === "string" && existingEntry.workspace.trim() ? path14.resolve(existingEntry.workspace) : defaultWorkspace;
+    if (workspaceToDelete.startsWith(openclawHome + path14.sep) && workspaceToDelete !== openclawHome) {
       try {
-        if (fs12.existsSync(workspaceToDelete)) {
-          fs12.rmSync(workspaceToDelete, { recursive: true, force: true });
+        if (fs13.existsSync(workspaceToDelete)) {
+          fs13.rmSync(workspaceToDelete, { recursive: true, force: true });
           cleanup.workspaceDeleted = true;
         }
       } catch (e) {
@@ -7211,7 +7727,7 @@ function registerAgentGateway(api, state2) {
     }
     console.log("[agentlife] deleted agent: %s (config=%s, registry=%s, surfaces=%d, sessions=%d, cron=%d, historyRows=%d, agentDb=%s, state=%s, workspace=%s)", id, removedFromConfig, removedFromRegistry, cleanup.surfacesCleared, cleanup.sessions, cleanup.cronJobs, cleanup.historyRows, cleanup.agentDbDeleted, cleanup.stateDeleted, cleanup.workspaceDeleted);
     respond(true, { status: "deleted", id, removedFromConfig, removedFromRegistry, cleanup });
-  });
+  }, { scope: "operator.admin" });
   api.registerGatewayMethod("agentlife.agents", ({ respond }) => {
     const agents = {};
     for (const [id, entry] of state2.agentRegistry.entries()) {
@@ -7228,11 +7744,11 @@ function registerDbGateway(api, state2) {
     const sql = typeof params?.sql === "string" ? params.sql.trim() : "";
     const sqlParams = Array.isArray(params?.params) ? params.params : [];
     if (!agentId)
-      return respond(false, { error: "missing agentId" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "missing agentId" });
     if (!sql)
-      return respond(false, { error: "missing sql" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "missing sql" });
     if (/^\s*SELECT\b/i.test(sql))
-      return respond(false, { error: "use agentlife.db.query for SELECT" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "use agentlife.db.query for SELECT" });
     try {
       const db = getOrCreateAgentDb(state2, agentId);
       if (sqlParams.length > 0) {
@@ -7243,19 +7759,19 @@ function registerDbGateway(api, state2) {
         respond(true, { changes: 0, lastInsertRowid: 0 });
       }
     } catch (err) {
-      respond(false, { error: err?.message ?? "db error" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "db error" });
     }
-  });
+  }, { scope: "operator.admin" });
   api.registerGatewayMethod("agentlife.db.query", ({ params, respond }) => {
     const agentId = typeof params?.agentId === "string" ? params.agentId.trim() : "";
     const sql = typeof params?.sql === "string" ? params.sql.trim() : "";
     const sqlParams = Array.isArray(params?.params) ? params.params : [];
     if (!agentId)
-      return respond(false, { error: "missing agentId" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "missing agentId" });
     if (!sql)
-      return respond(false, { error: "missing sql" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "missing sql" });
     if (!/^\s*SELECT\b/i.test(sql))
-      return respond(false, { error: "use agentlife.db.exec for non-SELECT" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "use agentlife.db.exec for non-SELECT" });
     try {
       const db = getOrCreateAgentDb(state2, agentId);
       const rows = db.prepare(sql).all(...sqlParams);
@@ -7265,9 +7781,9 @@ function registerDbGateway(api, state2) {
       const columns = result.length > 0 ? Object.keys(result[0]) : [];
       respond(true, { rows: result, columns, count: result.length, truncated });
     } catch (err) {
-      respond(false, { error: err?.message ?? "db error" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "db error" });
     }
-  });
+  }, { scope: "operator.admin" });
 }
 
 // gateway/history.ts
@@ -7308,7 +7824,7 @@ function registerHistoryGateway(api, state2) {
       const rows = db.prepare(`SELECT * FROM surface_events ${where} ORDER BY createdAt DESC LIMIT ? OFFSET ?`).all(...bind);
       respond(true, { events: rows, count: rows.length });
     } catch (err) {
-      respond(false, { error: err?.message ?? "history error" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "history error" });
     }
   }, { scope: "operator.read" });
   api.registerGatewayMethod("agentlife.history.widgets", ({ params, respond }) => {
@@ -7349,7 +7865,7 @@ function registerHistoryGateway(api, state2) {
       `).all(...bind, limit, offset);
       respond(true, { widgets: rows, count: rows.length, hasMore: rows.length >= limit });
     } catch (err) {
-      respond(false, { error: err?.message ?? "history.widgets error" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "history.widgets error" });
     }
   }, { scope: "operator.read" });
   api.registerGatewayMethod("agentlife.trace", ({ params, respond }) => {
@@ -7406,7 +7922,7 @@ function registerHistoryGateway(api, state2) {
       }));
       respond(true, { entries, hasMore });
     } catch (err) {
-      respond(false, { error: err?.message ?? "trace query failed" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "trace query failed" });
     }
   }, { scope: "operator.read" });
 }
@@ -7479,13 +7995,13 @@ function registerUsageGateway(api, state2) {
         bySession: bySessionRows
       });
     } catch (err) {
-      respond(false, { error: err?.message ?? "usage query error" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "usage query error" });
     }
   }, { scope: "operator.read" });
   api.registerGatewayMethod("agentlife.surfaceUsage", ({ params, respond }) => {
     const surfaceId = typeof params?.surfaceId === "string" ? params.surfaceId.trim() : "";
     if (!surfaceId)
-      return respond(false, { error: "missing surfaceId" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "missing surfaceId" });
     try {
       const db = getOrCreateHistoryDb(state2);
       const rows = db.prepare(`SELECT * FROM surface_usage WHERE surfaceId = ? ORDER BY createdAt DESC`).all(surfaceId);
@@ -7501,13 +8017,13 @@ function registerUsageGateway(api, state2) {
       }, { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, totalTokens: 0, estimatedCost: 0, llmCalls: 0 });
       respond(true, { surfaceId, entries: rows, totals });
     } catch (err) {
-      respond(false, { error: err?.message ?? "surface usage error" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "surface usage error" });
     }
   }, { scope: "operator.read" });
 }
 
 // gateway/surfaces-gateway.ts
-import * as fs13 from "node:fs";
+import * as fs14 from "node:fs";
 var guidedDismissSent = new Set;
 var warnedMissingOrigin = new Set;
 function registerSurfacesGateway(api, state2) {
@@ -7550,7 +8066,7 @@ function registerSurfacesGateway(api, state2) {
   api.registerGatewayMethod("agentlife.dismiss", async ({ params, respond }) => {
     const surfaceId = params?.surfaceId;
     if (!surfaceId || typeof surfaceId !== "string") {
-      respond(false, { error: "missing surfaceId" });
+      respond(false, undefined, { code: "INVALID_REQUEST", message: "missing surfaceId" });
       return;
     }
     const view2 = getSurface(state2, surfaceId);
@@ -7596,7 +8112,7 @@ function registerSurfacesGateway(api, state2) {
     guidedDismissSent.delete(surfaceId);
     if (!view2.isTransient && view2.path) {
       try {
-        fs13.unlinkSync(view2.path);
+        fs14.unlinkSync(view2.path);
       } catch (err) {
         if (err?.code !== "ENOENT")
           console.warn("[agentlife] dismiss: file unlink failed for %s: %s", surfaceId, err?.message);
@@ -7621,7 +8137,7 @@ function registerSurfacesGateway(api, state2) {
     const surfaceId = typeof params?.surfaceId === "string" ? params.surfaceId.trim() : "";
     const event = typeof params?.event === "string" ? params.event.trim() : "";
     if (!surfaceId || !event) {
-      respond(false, { error: "missing surfaceId or event" });
+      respond(false, undefined, { code: "INVALID_REQUEST", message: "missing surfaceId or event" });
       return;
     }
     const agentId = getAgentId(state2, surfaceId) ?? undefined;
@@ -7633,7 +8149,7 @@ function registerSurfacesGateway(api, state2) {
     const message = typeof params?.message === "string" ? params.message : "";
     const sessionKey = typeof params?.sessionKey === "string" ? params.sessionKey : "";
     if (!message) {
-      respond(false, { error: "missing message" });
+      respond(false, undefined, { code: "INVALID_REQUEST", message: "missing message" });
       return;
     }
     broadcastInput(message, sessionKey);
@@ -7642,7 +8158,7 @@ function registerSurfacesGateway(api, state2) {
   api.registerGatewayMethod("agentlife.chain.get", ({ params, respond }) => {
     const root = typeof params?.root === "string" ? params.root.trim() : "";
     if (!root) {
-      respond(false, { error: "missing root" });
+      respond(false, undefined, { code: "INVALID_REQUEST", message: "missing root" });
       return;
     }
     if (!state2.surfaceIndex) {
@@ -7666,7 +8182,7 @@ function registerSurfacesGateway(api, state2) {
   api.registerGatewayMethod("agentlife.action", ({ params, respond }) => {
     const surfaceId = typeof params?.surfaceId === "string" ? params.surfaceId.trim() : "";
     if (!surfaceId) {
-      respond(false, { error: "missing surfaceId" });
+      respond(false, undefined, { code: "INVALID_REQUEST", message: "missing surfaceId" });
       return;
     }
     const view2 = getSurface(state2, surfaceId);
@@ -7757,7 +8273,7 @@ function registerAutomationsGateway(api, state2) {
       const name = typeof params?.name === "string" ? params.name.trim() : "";
       const automationPath = typeof params?.path === "string" ? params.path.trim() : "";
       if (!type || !name || !automationPath) {
-        respond(false, { error: "missing required fields: type, name, path" });
+        respond(false, undefined, { code: "INVALID_REQUEST", message: "missing required fields: type, name, path" });
         return;
       }
       const surfaceId = typeof params?.surfaceId === "string" ? params.surfaceId.trim() : "";
@@ -7765,7 +8281,7 @@ function registerAutomationsGateway(api, state2) {
       const id = registerAutomation(state2, { surfaceId, agentId, type, name, path: automationPath });
       respond(true, { id, surfaceId, agentId, type, name, path: automationPath, status: "running" });
     } catch (err) {
-      respond(false, { error: err?.message ?? "register failed" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "register failed" });
     }
   }, { scope: "operator.write" });
   api.registerGatewayMethod("agentlife.automations.list", ({ params, respond }) => {
@@ -7806,7 +8322,7 @@ function registerAutomationsGateway(api, state2) {
         }))
       });
     } catch (err) {
-      respond(false, { error: err?.message ?? "list failed" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "list failed" });
     }
   }, { scope: "operator.read" });
   api.registerGatewayMethod("agentlife.automations.update", ({ params, respond }) => {
@@ -7814,44 +8330,44 @@ function registerAutomationsGateway(api, state2) {
       const id = typeof params?.id === "number" ? params.id : parseInt(params?.id, 10);
       const status = typeof params?.status === "string" ? params.status.trim() : "";
       if (!id || !status || !["running", "stopped", "error"].includes(status)) {
-        respond(false, { error: "missing id or invalid status (running|stopped|error)" });
+        respond(false, undefined, { code: "INVALID_REQUEST", message: "missing id or invalid status (running|stopped|error)" });
         return;
       }
       const db = getOrCreateHistoryDb(state2);
       db.prepare("UPDATE automations SET status = ?, updatedAt = ? WHERE id = ?").run(status, Date.now(), id);
       respond(true, { id, status });
     } catch (err) {
-      respond(false, { error: err?.message ?? "update failed" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "update failed" });
     }
   }, { scope: "operator.write" });
   api.registerGatewayMethod("agentlife.automations.remove", ({ params, respond }) => {
     try {
       const id = typeof params?.id === "number" ? params.id : parseInt(params?.id, 10);
       if (!id) {
-        respond(false, { error: "missing id" });
+        respond(false, undefined, { code: "INVALID_REQUEST", message: "missing id" });
         return;
       }
       const db = getOrCreateHistoryDb(state2);
       db.prepare("UPDATE automations SET status = 'removed', updatedAt = ? WHERE id = ?").run(Date.now(), id);
       respond(true, { id, status: "removed" });
     } catch (err) {
-      respond(false, { error: err?.message ?? "remove failed" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "remove failed" });
     }
   }, { scope: "operator.write" });
 }
 
 // gateway/admin.ts
-import * as fs14 from "node:fs/promises";
+import * as fs15 from "node:fs/promises";
 import * as fsSync4 from "node:fs";
-import * as os8 from "node:os";
-import * as path13 from "node:path";
+import * as os9 from "node:os";
+import * as path15 from "node:path";
 import { fileURLToPath } from "node:url";
 var PLUGIN_VERSION = (() => {
   try {
-    const moduleDir = path13.dirname(fileURLToPath(import.meta.url));
+    const moduleDir = path15.dirname(fileURLToPath(import.meta.url));
     const candidates = [
-      path13.join(moduleDir, "..", "package.json"),
-      path13.join(moduleDir, "..", "..", "package.json")
+      path15.join(moduleDir, "..", "package.json"),
+      path15.join(moduleDir, "..", "..", "package.json")
     ];
     for (const p of candidates) {
       if (fsSync4.existsSync(p)) {
@@ -7900,7 +8416,7 @@ async function fetchNpmLatestVersion(force = false) {
   return inflightFetch;
 }
 function pluginConfigPath() {
-  return path13.join(os8.homedir(), ".openclaw", "agentlife", "plugin-config.json");
+  return path15.join(os9.homedir(), ".openclaw", "agentlife", "plugin-config.json");
 }
 function readPluginConfig() {
   try {
@@ -7910,7 +8426,7 @@ function readPluginConfig() {
   }
 }
 function writePluginConfig(config2) {
-  const dir = path13.dirname(pluginConfigPath());
+  const dir = path15.dirname(pluginConfigPath());
   fsSync4.mkdirSync(dir, { recursive: true });
   fsSync4.writeFileSync(pluginConfigPath(), JSON.stringify(config2, null, 2));
 }
@@ -7968,7 +8484,7 @@ function registerAdminGateway(api, state2) {
         cleanup: { pending: cleanupPending, failed: cleanupFailed, exhausted: cleanupExhausted }
       });
     } catch (err) {
-      respond(false, { error: err?.message ?? "quality metrics unavailable" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "quality metrics unavailable" });
     }
   }, { scope: "operator.read" });
   api.registerGatewayMethod("agentlife.health.list", ({ respond }) => {
@@ -7989,7 +8505,7 @@ function registerAdminGateway(api, state2) {
       const rows = runDailyCycle(db, day);
       respond(true, { day, rows });
     } catch (err) {
-      respond(false, { error: err?.message ?? "observability runCycle failed" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "observability runCycle failed" });
     }
   }, { scope: "operator.write" });
   api.registerGatewayMethod("agentlife.sweep.run", ({ respond }) => {
@@ -7997,7 +8513,7 @@ function registerAdminGateway(api, state2) {
       const result = runDailySweep(state2);
       respond(true, result);
     } catch (err) {
-      respond(false, { error: err?.message ?? "daily sweep failed" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "daily sweep failed" });
     }
   }, { scope: "operator.write" });
   api.registerGatewayMethod("agentlife.bootstrap", ({ params, respond }) => {
@@ -8038,7 +8554,7 @@ function registerAdminGateway(api, state2) {
   api.registerGatewayMethod("agentlife.uninstall", async ({ respond }) => {
     try {
       const cleaned = [];
-      const baseDir = state2.agentlifeStateDir ?? path13.join(os8.homedir(), ".openclaw", "agentlife");
+      const baseDir = state2.agentlifeStateDir ?? path15.join(os9.homedir(), ".openclaw", "agentlife");
       const identity = loadDeviceIdentity();
       if (!identity) {
         cleaned.push("server deprovision skipped (no device identity)");
@@ -8103,7 +8619,7 @@ function registerAdminGateway(api, state2) {
       } catch {
         cleaned.push("agent config cleanup skipped");
       }
-      const backupPath = path13.join(baseDir, "config-backup.json");
+      const backupPath = path15.join(baseDir, "config-backup.json");
       try {
         cleaned.push(await restoreConfigFromBackup(api, backupPath));
       } catch {
@@ -8125,35 +8641,34 @@ function registerAdminGateway(api, state2) {
         dbPath,
         dbPath ? `${dbPath}-wal` : null,
         dbPath ? `${dbPath}-shm` : null,
-        path13.join(baseDir, "config-backup.json"),
-        path13.join(baseDir, "notification-config.json"),
-        path13.join(baseDir, "canvas-node-identity.json")
+        path15.join(baseDir, "notification-config.json"),
+        path15.join(baseDir, "canvas-node-identity.json")
       ].filter(Boolean);
       for (const fp of stateFiles) {
         try {
-          await fs14.unlink(fp);
-          cleaned.push(`deleted ${path13.basename(fp)}`);
+          await fs15.unlink(fp);
+          cleaned.push(`deleted ${path15.basename(fp)}`);
         } catch {}
       }
       if (state2.dbBaseDir) {
         try {
-          await fs14.rm(state2.dbBaseDir, { recursive: true, force: true });
+          await fs15.rm(state2.dbBaseDir, { recursive: true, force: true });
           cleaned.push("deleted agent databases");
         } catch {}
       }
       for (const agent of PROVISIONED_AGENTS) {
         if (agent.existingAgent)
           continue;
-        const wsDir = agent.workspaceDir ?? path13.join(os8.homedir(), ".openclaw", `workspace-${agent.id}`);
+        const wsDir = agent.workspaceDir ?? path15.join(os9.homedir(), ".openclaw", `workspace-${agent.id}`);
         try {
-          await fs14.rm(wsDir, { recursive: true, force: true });
+          await fs15.rm(wsDir, { recursive: true, force: true });
           cleaned.push(`deleted workspace ${agent.id}`);
         } catch {}
       }
       try {
-        const remaining = await fs14.readdir(baseDir);
+        const remaining = await fs15.readdir(baseDir);
         if (remaining.length === 0) {
-          await fs14.rmdir(baseDir);
+          await fs15.rmdir(baseDir);
           cleaned.push("deleted agentlife state directory");
         }
       } catch {}
@@ -8164,7 +8679,7 @@ function registerAdminGateway(api, state2) {
       });
     } catch (err) {
       console.error("[agentlife] uninstall failed:", err);
-      respond(false, { error: err?.message ?? "unknown error during uninstall" });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? "unknown error during uninstall" });
     }
   });
   api.registerGatewayMethod("agentlife.config.get", ({ respond }) => {
@@ -8193,11 +8708,11 @@ function registerAdminGateway(api, state2) {
 
 // gateway/evolutions.ts
 import * as fsSync5 from "node:fs";
-import * as os9 from "node:os";
-import * as path14 from "node:path";
+import * as os10 from "node:os";
+import * as path16 from "node:path";
 var ALLOWED_FILENAMES = new Set(["AGENTS.md", "USER.md", "SOUL.md", "TOOLS.md", "IDENTITY.md"]);
 function workspaceFilePath(agentId, filename) {
-  return path14.join(os9.homedir(), ".openclaw", `workspace-${agentId}`, filename);
+  return path16.join(os10.homedir(), ".openclaw", `workspace-${agentId}`, filename);
 }
 function hasRegressionFlag(db, agentId, filename, snapshotAt) {
   const horizon = snapshotAt + 7 * 24 * 60 * 60 * 1000;
@@ -8572,39 +9087,43 @@ function parseOffset(offset) {
 // gateway/providers.ts
 import {
   upsertApiKeyProfile,
-  upsertAuthProfile,
+  upsertAuthProfile as upsertAuthProfile3,
   buildApiKeyCredential,
   applyAuthProfileConfig
 } from "openclaw/plugin-sdk/provider-auth-api-key";
 
 // gateway/config-utils.ts
-import * as fs15 from "node:fs";
-import * as os10 from "node:os";
-import * as path15 from "node:path";
+import * as fs16 from "node:fs";
+import * as os11 from "node:os";
+import * as path17 from "node:path";
 function configPath() {
-  return path15.join(os10.homedir(), ".openclaw", "openclaw.json");
+  return path17.join(os11.homedir(), ".openclaw", "openclaw.json");
 }
 function readConfig() {
   try {
-    return JSON.parse(fs15.readFileSync(configPath(), "utf-8"));
+    return JSON.parse(fs16.readFileSync(configPath(), "utf-8"));
   } catch {
     return {};
   }
 }
 function writeConfig(cfg) {
-  fs15.writeFileSync(configPath(), JSON.stringify(cfg, null, 2) + `
+  fs16.writeFileSync(configPath(), JSON.stringify(cfg, null, 2) + `
 `, "utf-8");
 }
 
 // gateway/providers.ts
-import * as fs16 from "node:fs";
-import * as os11 from "node:os";
-import * as path16 from "node:path";
+import * as fs17 from "node:fs";
+import * as os12 from "node:os";
+import * as path18 from "node:path";
+function resolveOpenClawRoot3() {
+  const fromEnv = process.env.OPENCLAW_STATE_DIR?.trim();
+  return fromEnv ? path18.resolve(fromEnv) : path18.join(os12.homedir(), ".openclaw");
+}
 function siblingAgentDirs() {
-  const root = path16.join(os11.homedir(), ".openclaw", "agents");
+  const root = path18.join(resolveOpenClawRoot3(), "agents");
   let entries;
   try {
-    entries = fs16.readdirSync(root, { withFileTypes: true });
+    entries = fs17.readdirSync(root, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -8612,9 +9131,9 @@ function siblingAgentDirs() {
   for (const entry of entries) {
     if (!entry.isDirectory() && !entry.isSymbolicLink())
       continue;
-    const dir = path16.join(root, entry.name, "agent");
+    const dir = path18.join(root, entry.name, "agent");
     try {
-      if (fs16.statSync(dir).isDirectory())
+      if (fs17.statSync(dir).isDirectory())
         out.push(dir);
     } catch {}
   }
@@ -8684,20 +9203,20 @@ async function ensureModels(run) {
 }
 function readOAuthExpiries() {
   const result = new Map;
-  const fs17 = __require("node:fs");
-  const path17 = __require("node:path");
-  const os12 = __require("node:os");
-  const agentsDir = path17.join(os12.homedir(), ".openclaw", "agents");
+  const fs18 = __require("node:fs");
+  const path19 = __require("node:path");
+  const os13 = __require("node:os");
+  const agentsDir = path19.join(os13.homedir(), ".openclaw", "agents");
   let entries;
   try {
-    entries = fs17.readdirSync(agentsDir);
+    entries = fs18.readdirSync(agentsDir);
   } catch {
     return result;
   }
   for (const name of entries) {
-    const filePath = path17.join(agentsDir, name, "agent", "auth-profiles.json");
+    const filePath = path19.join(agentsDir, name, "agent", "auth-profiles.json");
     try {
-      const raw = fs17.readFileSync(filePath, "utf-8");
+      const raw = fs18.readFileSync(filePath, "utf-8");
       const data = JSON.parse(raw);
       const profiles = data?.profiles ?? {};
       for (const entry of Object.values(profiles)) {
@@ -8814,20 +9333,20 @@ function registerProvidersGateway(api, state2) {
       }));
       respond(true, { providers });
     } catch (err) {
-      respond(false, { error: err?.message ?? String(err) });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? String(err) });
     }
   }, { scope: "operator.read" });
   api.registerGatewayMethod("agentlife.providers.set", async ({ params, respond }) => {
     const provider = typeof params?.provider === "string" ? params.provider.trim() : "";
     const apiKey = typeof params?.apiKey === "string" ? params.apiKey.trim() : "";
     if (!provider)
-      return respond(false, { error: "provider is empty" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "provider is empty" });
     if (!apiKey)
-      return respond(false, { error: "apiKey is empty" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "apiKey is empty" });
     try {
       const catalog = await ensureCatalog(run ?? null);
       if (catalog.length > 0 && !catalog.some((e) => e.provider === provider)) {
-        return respond(false, { error: `unknown provider: ${provider}` });
+        return respond(false, undefined, { code: "NOT_FOUND", message: `unknown provider: ${provider}` });
       }
     } catch {}
     try {
@@ -8835,7 +9354,7 @@ function registerProvidersGateway(api, state2) {
       const credential = buildApiKeyCredential(provider, apiKey);
       for (const agentDir of siblingAgentDirs()) {
         try {
-          upsertAuthProfile({ profileId, credential, agentDir });
+          upsertAuthProfile3({ profileId, credential, agentDir });
         } catch {}
       }
       const cfg = readConfig();
@@ -8848,13 +9367,13 @@ function registerProvidersGateway(api, state2) {
       writeConfig(nextCfg);
       respond(true, { provider, configured: true, profileId });
     } catch (err) {
-      respond(false, { error: err?.message ?? String(err) });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? String(err) });
     }
   }, { scope: "operator.write" });
   api.registerGatewayMethod("agentlife.providers.delete", ({ params, respond }) => {
     const provider = typeof params?.provider === "string" ? params.provider.trim() : "";
     if (!provider)
-      return respond(false, { error: "provider is empty" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "provider is empty" });
     try {
       const cfg = readConfig();
       const profiles = cfg?.auth?.profiles;
@@ -8869,9 +9388,9 @@ function registerProvidersGateway(api, state2) {
       }
       writeConfig(cfg);
       for (const agentDir of siblingAgentDirs()) {
-        const file = path16.join(agentDir, "auth-profiles.json");
+        const file = path18.join(agentDir, "auth-profiles.json");
         try {
-          const raw = fs16.readFileSync(file, "utf-8");
+          const raw = fs17.readFileSync(file, "utf-8");
           const data = JSON.parse(raw);
           const agentProfiles = data?.profiles;
           if (!agentProfiles || typeof agentProfiles !== "object")
@@ -8888,19 +9407,19 @@ function registerProvidersGateway(api, state2) {
             changed = true;
           }
           if (changed)
-            fs16.writeFileSync(file, JSON.stringify(data, null, 2), "utf-8");
+            fs17.writeFileSync(file, JSON.stringify(data, null, 2), "utf-8");
         } catch {}
       }
       respond(true, { provider, configured: false });
     } catch (err) {
-      respond(false, { error: err?.message ?? String(err) });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? String(err) });
     }
   }, { scope: "operator.write" });
   api.registerGatewayMethod("agentlife.providers.test", async ({ params, respond }) => {
     const provider = typeof params?.provider === "string" ? params.provider.trim() : "";
     const apiKey = typeof params?.apiKey === "string" ? params.apiKey.trim() : "";
     if (!provider)
-      return respond(false, { error: "provider is empty" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "provider is empty" });
     if (!apiKey)
       return respond(true, { ok: false, error: "apiKey required — type a key before testing" });
     try {
@@ -8926,7 +9445,7 @@ function registerProvidersGateway(api, state2) {
       });
       respond(true, { models: deduped });
     } catch (err) {
-      respond(false, { error: err?.message ?? String(err) });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? String(err) });
     }
   }, { scope: "operator.read" });
   api.registerGatewayMethod("agentlife.providers.health", ({ respond }) => {
@@ -8956,44 +9475,44 @@ function registerProvidersGateway(api, state2) {
       }
       respond(true, { probes });
     } catch (err) {
-      respond(false, { error: err?.message ?? String(err) });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? String(err) });
     }
   }, { scope: "operator.read" });
   api.registerGatewayMethod("agentlife.providers.loginCodex", async ({ respond }) => {
     if (!run)
-      return respond(false, { error: "runCommand unavailable" });
+      return respond(false, undefined, { code: "UNAVAILABLE", message: "runCommand unavailable" });
     try {
       const result = await run(["openclaw", "capability", "model", "auth", "login", "--provider", "openai-codex"], { timeoutMs: 180000 });
       const combined = `${result?.stdout ?? ""}
 ${result?.stderr ?? ""}`;
       const urlMatch = combined.match(/https:\/\/\S+/);
       if ((result?.code ?? 0) !== 0 && !urlMatch) {
-        return respond(false, { error: (result?.stderr ?? "").trim() || "codex login failed" });
+        return respond(false, undefined, { code: "FAILED", message: (result?.stderr ?? "").trim() || "codex login failed" });
       }
       respond(true, { url: urlMatch?.[0] ?? null, completed: (result?.code ?? 0) === 0 });
     } catch (err) {
-      respond(false, { error: err?.message ?? String(err) });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? String(err) });
     }
   }, { scope: "operator.write" });
 }
 
 // gateway/models-config.ts
-import * as fs17 from "node:fs";
-import * as os12 from "node:os";
-import * as path17 from "node:path";
+import * as fs18 from "node:fs";
+import * as os13 from "node:os";
+import * as path19 from "node:path";
 function pluginConfigPath2() {
-  return path17.join(os12.homedir(), ".openclaw", "agentlife", "plugin-config.json");
+  return path19.join(os13.homedir(), ".openclaw", "agentlife", "plugin-config.json");
 }
 function readPluginConfig2() {
   try {
-    return JSON.parse(fs17.readFileSync(pluginConfigPath2(), "utf-8"));
+    return JSON.parse(fs18.readFileSync(pluginConfigPath2(), "utf-8"));
   } catch {
     return {};
   }
 }
 function writePluginConfig2(cfg) {
-  fs17.mkdirSync(path17.dirname(pluginConfigPath2()), { recursive: true });
-  fs17.writeFileSync(pluginConfigPath2(), JSON.stringify(cfg, null, 2) + `
+  fs18.mkdirSync(path19.dirname(pluginConfigPath2()), { recursive: true });
+  fs18.writeFileSync(pluginConfigPath2(), JSON.stringify(cfg, null, 2) + `
 `, "utf-8");
 }
 function registerModelsConfigGateway(api) {
@@ -9008,13 +9527,13 @@ function registerModelsConfigGateway(api) {
         fallbacks: Array.isArray(m.fallbacks) ? m.fallbacks.filter((x) => typeof x === "string") : []
       });
     } catch (err) {
-      respond(false, { error: err?.message ?? String(err) });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? String(err) });
     }
   }, { scope: "operator.read" });
   api.registerGatewayMethod("agentlife.models.defaults.setPrimary", ({ params, respond }) => {
     const model = typeof params?.model === "string" ? params.model.trim() : "";
     if (!model)
-      return respond(false, { error: "model is required" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "model is required" });
     try {
       const cfg = readConfig();
       cfg.agents = cfg.agents ?? {};
@@ -9024,26 +9543,26 @@ function registerModelsConfigGateway(api) {
       writeConfig(cfg);
       respond(true, { ok: true });
     } catch (err) {
-      respond(false, { error: err?.message ?? String(err) });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? String(err) });
     }
   }, { scope: "operator.write" });
   api.registerGatewayMethod("agentlife.models.defaults.setInternal", ({ params, respond }) => {
     const model = typeof params?.model === "string" ? params.model.trim() : "";
     if (!model)
-      return respond(false, { error: "model is required" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "model is required" });
     try {
       const cfg = readPluginConfig2();
       cfg.internalModel = model;
       writePluginConfig2(cfg);
       respond(true, { ok: true });
     } catch (err) {
-      respond(false, { error: err?.message ?? String(err) });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? String(err) });
     }
   }, { scope: "operator.write" });
   api.registerGatewayMethod("agentlife.models.fallbacks.set", ({ params, respond }) => {
     const models = Array.isArray(params?.models) ? params.models.filter((x) => typeof x === "string") : null;
     if (!models)
-      return respond(false, { error: "models must be an array of strings" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "models must be an array of strings" });
     try {
       const cfg = readConfig();
       cfg.agents = cfg.agents ?? {};
@@ -9053,7 +9572,7 @@ function registerModelsConfigGateway(api) {
       writeConfig(cfg);
       respond(true, { ok: true });
     } catch (err) {
-      respond(false, { error: err?.message ?? String(err) });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? String(err) });
     }
   }, { scope: "operator.write" });
   api.registerGatewayMethod("agentlife.agents.list", ({ respond }) => {
@@ -9067,23 +9586,23 @@ function registerModelsConfigGateway(api) {
       })).filter((a) => a.id !== null && a.name !== null);
       respond(true, { agents });
     } catch (err) {
-      respond(false, { error: err?.message ?? String(err) });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? String(err) });
     }
   }, { scope: "operator.read" });
   api.registerGatewayMethod("agentlife.agents.setModel", ({ params, respond }) => {
     const agentId = typeof params?.agentId === "string" ? params.agentId.trim() : "";
     if (!agentId)
-      return respond(false, { error: "agentId is required" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "agentId is required" });
     const model = params?.model;
     if (model !== null && typeof model !== "string") {
-      return respond(false, { error: "model must be string or null" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "model must be string or null" });
     }
     try {
       const cfg = readConfig();
       const list = Array.isArray(cfg?.agents?.list) ? cfg.agents.list : [];
       const idx = list.findIndex((a) => a?.id === agentId);
       if (idx < 0)
-        return respond(false, { error: `agent not found: ${agentId}` });
+        return respond(false, undefined, { code: "NOT_FOUND", message: `agent not found: ${agentId}` });
       if (model === null) {
         delete list[idx].model;
       } else {
@@ -9092,19 +9611,19 @@ function registerModelsConfigGateway(api) {
       writeConfig(cfg);
       respond(true, { ok: true });
     } catch (err) {
-      respond(false, { error: err?.message ?? String(err) });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? String(err) });
     }
   }, { scope: "operator.write" });
   api.registerGatewayMethod("agentlife.agents.setModel.bulk", ({ params, respond }) => {
     const updates = Array.isArray(params?.updates) ? params.updates : null;
     if (!updates)
-      return respond(false, { error: "updates must be an array" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "updates must be an array" });
     for (const u of updates) {
       if (!u || typeof u.agentId !== "string" || !u.agentId.trim()) {
-        return respond(false, { error: "each update needs agentId (string)" });
+        return respond(false, undefined, { code: "INVALID_REQUEST", message: "each update needs agentId (string)" });
       }
       if (u.model !== null && typeof u.model !== "string") {
-        return respond(false, { error: "each update model must be string or null" });
+        return respond(false, undefined, { code: "INVALID_REQUEST", message: "each update model must be string or null" });
       }
     }
     try {
@@ -9125,7 +9644,7 @@ function registerModelsConfigGateway(api) {
       writeConfig(cfg);
       respond(true, { ok: true, applied });
     } catch (err) {
-      respond(false, { error: err?.message ?? String(err) });
+      respond(false, undefined, { code: "INTERNAL", message: err?.message ?? String(err) });
     }
   }, { scope: "operator.write" });
 }
@@ -9137,9 +9656,12 @@ var stopObservability = null;
 var stopDailySweep = null;
 var stopQualityCheckPoller = null;
 var stopCloudflared = null;
+function resolveOpenClawRoot4() {
+  return process.env.OPENCLAW_STATE_DIR || path20.join(homedir17(), ".openclaw");
+}
 function resolveInternalModel(api) {
   try {
-    const pluginCfgPath = path18.join(homedir15(), ".openclaw", "agentlife", "plugin-config.json");
+    const pluginCfgPath = path20.join(resolveOpenClawRoot4(), "agentlife", "plugin-config.json");
     try {
       const raw = __require("node:fs").readFileSync(pluginCfgPath, "utf-8");
       const pluginCfg = JSON.parse(raw);
@@ -9165,7 +9687,24 @@ function _getState() {
     throw new Error("plugin not registered");
   return currentState;
 }
+async function startProvisioningServices(api, state2) {
+  const cfg = api.runtime.config.loadConfig();
+  await provisionAgents(state2, cfg, api.runtime, console.log);
+  await reconcileInternalSessions(state2, createdInternalSessions);
+  await cleanupSupervisorLegacyState(state2);
+  stopObservability = startObservabilityService(state2);
+  stopDailySweep = startDailySweepService(state2);
+  stopQualityCheckPoller = startQualityCheckPoller(state2);
+  renderAllAgentWidgets(state2, api.runtime, console.log);
+}
 function register(api) {
+  if (!shouldStartRuntimeServices()) {
+    console.log("[agentlife] install/inspect mode — runtime registration skipped");
+    return;
+  }
+  if (shouldStartRuntimeServices()) {
+    runInstallBootstrap();
+  }
   if (currentState) {
     registerWidgetPushTool(api, currentState);
     api.registerChannel({ plugin: createAgentlifeChannel(currentState.channelState) });
@@ -9175,7 +9714,8 @@ function register(api) {
     return;
   }
   registered = true;
-  const fallbackDir = path18.join(homedir15(), ".openclaw", "agentlife");
+  const fallbackRoot = resolveOpenClawRoot4();
+  const fallbackDir = path20.join(fallbackRoot, "agentlife");
   const state2 = {
     fileSurfaceStorage: null,
     surfaceIndex: null,
@@ -9187,9 +9727,9 @@ function register(api) {
     agentDbs: new Map,
     historyDb: null,
     agentlifeStateDir: fallbackDir,
-    registryFilePath: path18.join(fallbackDir, "agent-registry.json"),
-    dbBaseDir: path18.join(fallbackDir, "db"),
-    historyDbPath: path18.join(fallbackDir, "agentlife.db"),
+    registryFilePath: path20.join(fallbackDir, "agent-registry.json"),
+    dbBaseDir: path20.join(fallbackDir, "db"),
+    historyDbPath: path20.join(fallbackDir, "agentlife.db"),
     runCommand: api.runtime.system?.runCommandWithTimeout ?? null,
     enqueueSystemEvent: null,
     requestHeartbeatNow: null,
@@ -9201,12 +9741,12 @@ function register(api) {
   currentState = state2;
   api.registerChannel({ plugin: createAgentlifeChannel(state2.channelState) });
   console.log("[agentlife] channel registered, session format: %s", buildAgentSessionKey("example"));
-  if (existsSync7(fallbackDir)) {
+  if (shouldStartRuntimeServices() && existsSync8(fallbackDir)) {
     try {
       const db = getOrCreateHistoryDb(state2);
       state2.surfaceIndex = new SurfaceIndex(db);
       state2.followupQueue = new FollowupQueue(db);
-      state2.fileSurfaceStorage = new FileSurfaceStorage;
+      state2.fileSurfaceStorage = new FileSurfaceStorage({ openclawRoot: fallbackRoot });
     } catch (e) {
       console.warn("[agentlife] eager surface storage init failed:", e?.message);
     }
@@ -9216,20 +9756,32 @@ function register(api) {
   registerSurfacesService(api, state2);
   api.registerService({
     id: "agentlife-provisioning",
-    start: async () => {
-      const cfg = api.runtime.config.loadConfig();
-      await provisionAgents(state2, cfg, api.runtime, console.log);
-      await reconcileInternalSessions(state2, createdInternalSessions);
-      await cleanupSupervisorLegacyState(state2);
-      stopObservability = startObservabilityService(state2);
-      stopDailySweep = startDailySweepService(state2);
-      stopQualityCheckPoller = startQualityCheckPoller(state2);
-      renderAllAgentWidgets(state2, api.runtime, console.log);
+    start: () => {
+      if (!shouldStartRuntimeServices())
+        return;
+      startProvisioningServices(api, state2).catch((err) => {
+        console.warn("[agentlife] provisioning service failed:", err?.message ?? err);
+      });
     }
   });
   registerConfigOptimizer(api, state2);
   registerPairingServices(api);
-  stopCloudflared = startCloudflaredSupervisor();
+  api.registerService({
+    id: "agentlife-cloudflared-supervisor",
+    start: () => {
+      if (!shouldStartRuntimeServices())
+        return;
+      if (!stopCloudflared) {
+        stopCloudflared = startCloudflaredSupervisor();
+      }
+    },
+    stop: () => {
+      if (stopCloudflared) {
+        stopCloudflared();
+        stopCloudflared = null;
+      }
+    }
+  });
   api.registerService({
     id: "agentlife-shutdown",
     start: () => {},
@@ -9254,7 +9806,15 @@ function register(api) {
       closeAllDbs(state2);
     }
   });
-  initFollowupSystem(api, state2);
+  api.registerService({
+    id: "agentlife-followups",
+    start: () => {
+      if (!shouldStartRuntimeServices())
+        return;
+      initFollowupSystem(api, state2);
+    },
+    stop: () => stopFollowupSystem(state2)
+  });
   registerPromptStateHook(api, state2);
   registerWidgetPushTool(api, state2);
   registerActivityHooks(api, state2);
@@ -9270,17 +9830,17 @@ function register(api) {
   registerProvidersGateway(api, state2);
   registerModelsConfigGateway(api);
   registerWebApp(api);
-  const notifyConfigPath = path18.join(fallbackDir, "notification-config.json");
+  const notifyConfigPath = path20.join(fallbackDir, "notification-config.json");
   api.registerGatewayMethod("agentlife.notifications.register", ({ params, respond }) => {
     const serverUrl = typeof params?.serverUrl === "string" ? params.serverUrl.trim() : "";
     const apiKey = typeof params?.apiKey === "string" ? params.apiKey.trim() : "";
     if (!serverUrl || !apiKey) {
-      return respond(false, { error: "missing serverUrl or apiKey" });
+      return respond(false, undefined, { code: "INVALID_REQUEST", message: "missing serverUrl or apiKey" });
     }
     try {
-      const { writeFileSync: writeFileSync11, mkdirSync: mkdirSync8 } = __require("node:fs");
-      mkdirSync8(path18.dirname(notifyConfigPath), { recursive: true });
-      writeFileSync11(notifyConfigPath, JSON.stringify({ serverUrl, apiKey }));
+      const { writeFileSync: writeFileSync12, mkdirSync: mkdirSync10 } = __require("node:fs");
+      mkdirSync10(path20.dirname(notifyConfigPath), { recursive: true });
+      writeFileSync12(notifyConfigPath, JSON.stringify({ serverUrl, apiKey }));
     } catch {}
     respond(true, { registered: true });
   }, { scope: "operator.write" });