oomi-ai 0.3.4 → 0.3.6

package/README.md

@@ -145,6 +145,35 @@ Optional fields:
 - `defaultSessionKey`
 - `requestTimeoutMs`
 
+Hosted Oomi-managed agents also include a `modelRelay` block under the default account. When enabled, `oomi-ai` applies an OpenClaw custom provider named `oomi-managed` that points at Oomi's OpenAI-compatible metered relay:
+
+```json
+{
+  "channels": {
+    "oomi": {
+      "accounts": {
+        "default": {
+          "modelRelay": {
+            "enabled": true,
+            "backendUrl": "https://api.oomi.ai",
+            "openaiBasePath": "/v1/model/relay/openai",
+            "openclawProviderId": "oomi-managed",
+            "openclawModelRef": "oomi-managed/google/gemini-2.5-flash",
+            "provider": "openrouter",
+            "model": "google/gemini-2.5-flash",
+            "userId": "usr_...",
+            "deviceId": "oomi-hosted-...",
+            "internalKeyEnv": "OOMI_HOSTED_BOOTSTRAP_INTERNAL_KEY"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The config stores only the internal-key environment variable name. The secret value stays in the runtime environment.
+
 ## Persona App API Tools
 
 Component-composed persona apps are the default Oomi mini-app path. Use these commands when the user asks about or updates an existing Oomi persona app such as Fitness Today:

package/agent_instructions.md

@@ -19,27 +19,24 @@ Get OpenClaw into a state where:
 
 If the user asks to connect OpenClaw to Oomi chat or voice:
 
-1. Refresh bootstrap first:
+1. For a first-time install or missing local pairing state, run the bootstrap exactly once using the requested app URL:
    - `curl -fsSL https://www.oomi.ai/install.sh | bash`
-2. Ensure `oomi-ai` is installed:
-   - `pnpm add -g oomi-ai@latest`
-   - fallback: `npm install -g oomi-ai@latest`
-3. Pair the device without starting a legacy one-off flow:
-   - `oomi openclaw pair --app-url https://www.oomi.ai --no-start`
-4. Install the OpenClaw plugin:
-   - `openclaw plugins install oomi-ai@latest`
-5. Print the config block and secrets:
+   - The bootstrap installs or updates `oomi-ai`, performs the one initial pair, installs the plugin, and starts the saved bridge in detached mode.
+   - Do not pair again after the bootstrap finishes.
+2. Print the config block and secrets:
    - `oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai`
-6. Apply the printed `channels.oomi.accounts.default` config.
-7. Restart OpenClaw.
-8. Start or repair the bridge:
+3. Apply the printed `channels.oomi.accounts.default` config.
+4. Restart OpenClaw.
+5. Start or repair the bridge from saved pairing state:
    - `oomi openclaw bridge ensure --detach`
    - if stale: `oomi openclaw bridge restart --detach`
    - on macOS, prefer supervision: `oomi openclaw bridge service install`
+6. If the Auth Link printed by bootstrap is missing or expired, create a replacement without re-pairing:
+   - `oomi openclaw invite --app-url https://www.oomi.ai`
 
-If the user provides a specific app URL, use it directly in the pair flow:
+If the machine is already paired, do not rerun bootstrap. Use `invite` for a fresh Auth Link and `bridge ensure` or `bridge restart` for runtime recovery.
 
-- `oomi openclaw pair --app-url <URL> --no-start`
+If the user provides a specific app URL, substitute it in both the bootstrap URL and the `invite --app-url` command.
 
 ## Required User-Facing Result
 

package/bin/oomi-ai.js

@@ -379,18 +379,6 @@ function findRepoRoot(startDir) {
   return null;
 }
 
-function resolveRepoRoot(rootFlag) {
-  const explicitRoot =
-    typeof rootFlag === 'string' && rootFlag.trim()
-      ? path.resolve(rootFlag.trim())
-      : '';
-  const repoRoot = explicitRoot || findRepoRoot(process.cwd()) || findRepoRoot(PACKAGE_ROOT);
-  if (!repoRoot) {
-    throw new Error('Could not locate repo root. Use --root <repo root>.');
-  }
-  return repoRoot;
-}
-
 function resolveSkillSource(cliRoot) {
   const packaged = path.join(PACKAGE_ROOT, 'skills', 'oomi');
   if (fs.existsSync(packaged)) {
@@ -584,6 +572,10 @@ async function handleContextHealthCommand(flags = {}) {
   printStructuredResult(payload, isTruthyFlag(flags.json));
 }
 
+async function handleContextFinanceCommand(_flags = {}) {
+  throw new Error("oomi context finance is off until Gate A. Use the signed-in web Finance persona-app. Do not read bank balances from the connected OpenClaw shell.");
+}
+
 async function handleContextHealthSyncCommand(flags = {}) {
   const client = createCliPersonaApiClient(flags);
   const payload = await client.requestHealthContextSync({
@@ -741,6 +733,28 @@ function readOpenclawGatewayConfig() {
   };
 }
 
+function readOpenclawDefaultSessionKey() {
+  try {
+    const configPath = resolveOpenclawConfigPath();
+    if (!configPath || !fs.existsSync(configPath)) {
+      return '';
+    }
+
+    const parsed = JSON.parse(readFile(configPath));
+    const channels = parsed.channels || {};
+    const oomi = channels.oomi || {};
+    const accounts = oomi.accounts || {};
+    const defaultAccount = accounts.default || {};
+    const defaultSessionKey = typeof defaultAccount.defaultSessionKey === 'string'
+      ? defaultAccount.defaultSessionKey.trim()
+      : '';
+
+    return defaultSessionKey;
+  } catch {
+    return '';
+  }
+}
+
 function resolveBridgeStatePath() {
   return resolveOpenclawBridgeStatePath();
 }
@@ -1049,6 +1063,25 @@ async function requestManagedPairCode({ appUrl, label }) {
   return payload;
 }
 
+async function requestBrokerPairCode({ brokerHttp, adminKey, label }) {
+  const response = await fetch(`${brokerHttp.replace(/\/$/, '')}/v1/pair/start`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${adminKey}`,
+    },
+    body: JSON.stringify({ label }),
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok || !payload?.pairCode) {
+    const message =
+      (payload && typeof payload.error === 'string' && payload.error) ||
+      `Broker pair start failed (${response.status})`;
+    throw new Error(message);
+  }
+  return payload;
+}
+
 async function requestConnectInviteLink({ backendHttp, appUrl, sessionKey, deviceToken }) {
   const response = await fetch(`${backendHttp.replace(/\/$/, '')}/v1/invite_links/start`, {
     method: 'POST',
@@ -1084,6 +1117,35 @@ async function fetchManagedGatewayConfig({ appUrl }) {
   return payload;
 }
 
+function shouldRewriteLoopbackBrokerForAppHost(appHostname) {
+  return String(appHostname || '').trim().toLowerCase() === 'host.docker.internal';
+}
+
+function isLoopbackBrokerHostname(hostname) {
+  const normalized = String(hostname || '').trim().toLowerCase();
+  return normalized === '127.0.0.1' || normalized === 'localhost' || normalized === '::1';
+}
+
+function rewriteLoopbackBrokerUrlForAppHost(rawUrl, appUrl) {
+  const value = String(rawUrl || '').trim();
+  if (!value) return value;
+
+  try {
+    const brokerUrl = new URL(value);
+    const app = new URL(String(appUrl || '').trim());
+    if (!isLoopbackBrokerHostname(brokerUrl.hostname)) {
+      return value;
+    }
+    if (!shouldRewriteLoopbackBrokerForAppHost(app.hostname)) {
+      return value;
+    }
+    brokerUrl.hostname = app.hostname;
+    return brokerUrl.toString();
+  } catch {
+    return value;
+  }
+}
+
 function base64UrlEncode(value) {
   return Buffer.from(value)
     .toString('base64')
@@ -1742,48 +1804,6 @@ function printAssistantFinalDebugResult(result, asJson) {
   }
 }
 
-function resolveCommandFromPath(commandName) {
-  const normalized = String(commandName || '').trim();
-  if (!normalized) return '';
-  try {
-    const probe = spawnSync(process.platform === 'win32' ? 'where' : 'which', [normalized], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    });
-    if (probe.status !== 0) return '';
-    const firstLine = String(probe.stdout || '')
-      .split(/\r?\n/)
-      .map((line) => line.trim())
-      .find(Boolean);
-    return firstLine || '';
-  } catch {
-    return '';
-  }
-}
-
-function resolveExecutable(candidates = []) {
-  for (const candidate of candidates) {
-    if (!candidate) continue;
-    const value = String(candidate).trim();
-    if (!value) continue;
-    if (path.isAbsolute(value) && fs.existsSync(value)) {
-      return value;
-    }
-    if (value.includes(path.sep) || value.includes('/')) {
-      const resolved = path.resolve(value);
-      if (fs.existsSync(resolved)) {
-        return resolved;
-      }
-      continue;
-    }
-    const fromPath = resolveCommandFromPath(value);
-    if (fromPath) {
-      return fromPath;
-    }
-  }
-  return '';
-}
-
 async function handleOpenclawDebugCommand(action, flags) {
   const normalizedAction = String(action || '').trim().toLowerCase();
   const frameFile =
@@ -2527,11 +2547,13 @@ async function startOpenclawBridge(flags) {
     if (!deviceToken) {
       throw new Error('Broker pair claim did not return deviceToken.');
     }
+    const configSessionKey = readOpenclawDefaultSessionKey();
     writeBridgeState({
       brokerHttp,
       brokerWs,
       deviceId,
       deviceToken,
+      sessionKey: configSessionKey || 'agent:main:webchat:channel:oomi',
       claimedAt: new Date().toISOString(),
       expiresAt: claimed.expiresAt || null,
     });
@@ -3806,7 +3828,24 @@ async function pairAndStartOpenclawBridge(flags) {
 
   console.log(`Pairing OpenClaw host with Oomi app: ${appUrl}`);
   const managedConfig = await fetchManagedGatewayConfig({ appUrl });
-  const pairStarted = await requestManagedPairCode({ appUrl, label });
+  const brokerHttp = rewriteLoopbackBrokerUrlForAppHost(managedConfig.brokerHttpUrl, appUrl);
+  let pairStarted;
+  try {
+    pairStarted = await requestManagedPairCode({ appUrl, label });
+  } catch (err) {
+    const brokerAdminKey = String(process.env.OOMI_CHAT_BROKER_ADMIN_KEY || '').trim();
+    if (!brokerAdminKey) {
+      throw err;
+    }
+    console.warn(
+      `[oomi] Managed pair start via app failed (${extractErrorMessage(err)}); falling back to direct broker pair/start.`
+    );
+    pairStarted = await requestBrokerPairCode({
+      brokerHttp,
+      adminKey: brokerAdminKey,
+      label,
+    });
+  }
   const pairCode = String(pairStarted.pairCode || '').trim().toUpperCase();
   if (!pairCode) {
     throw new Error('Pairing code missing from backend response.');
@@ -3814,7 +3853,7 @@ async function pairAndStartOpenclawBridge(flags) {
 
   console.log(`Received pair code: ${pairCode}`);
   const claimed = await claimBridgeDeviceToken({
-    brokerHttp: managedConfig.brokerHttpUrl,
+    brokerHttp,
     pairCode,
     deviceId,
   });
@@ -3823,9 +3862,11 @@ async function pairAndStartOpenclawBridge(flags) {
     throw new Error('Broker pair claim did not return deviceToken.');
   }
 
-  const brokerWs = String(flags['broker-ws'] || managedConfig.brokerDeviceWsUrl).trim();
+  const brokerWs = String(
+    flags['broker-ws'] || rewriteLoopbackBrokerUrlForAppHost(managedConfig.brokerDeviceWsUrl, appUrl)
+  ).trim();
   writeBridgeState({
-    brokerHttp: managedConfig.brokerHttpUrl,
+    brokerHttp,
     brokerWs,
     deviceId,
     deviceToken,
@@ -3835,7 +3876,7 @@ async function pairAndStartOpenclawBridge(flags) {
   });
 
   const invite = await requestConnectInviteLink({
-    backendHttp: managedConfig.brokerHttpUrl,
+    backendHttp: brokerHttp,
     appUrl,
     sessionKey,
     deviceToken,
@@ -3909,9 +3950,11 @@ async function createOpenclawInviteLink(flags) {
       ''
   ).trim();
   const appUrl = String(flags['app-url'] || process.env.OOMI_APP_URL || 'http://127.0.0.1:3456').trim();
+  const configSessionKey = readOpenclawDefaultSessionKey();
   const sessionKey = String(
     flags['session-key'] ||
       process.env.OOMI_SESSION_KEY ||
+      configSessionKey ||
       bridgeState.sessionKey ||
       'agent:main:webchat:channel:oomi'
   ).trim();
@@ -4381,6 +4424,11 @@ async function main() {
     return;
   }
 
+  if (command === 'context' && subcommand === 'finance') {
+    await handleContextFinanceCommand(args.flags);
+    return;
+  }
+
   console.error(`Unknown command: ${command} ${subcommand || ''}`.trim());
   usage();
   process.exit(1);
@@ -4421,4 +4469,5 @@ export {
   isGatewayRunStartedFrame,
   isBridgeWorkerCommand,
   parsePositiveInteger,
+  rewriteLoopbackBrokerUrlForAppHost,
 };

package/lib/modelRelayClient.js

@@ -0,0 +1,150 @@
+const DEFAULT_ENDPOINT_PATH = '/v1/model/relay/chat';
+const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
+const DEFAULT_REQUEST_ORIGIN = 'hosted_openclaw';
+
+function toString(value, fallback = '') {
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback;
+}
+
+function toPositiveInteger(value, fallback, { min = 1, max = Number.MAX_SAFE_INTEGER } = {}) {
+  const parsed = Number.parseInt(String(value || ''), 10);
+  if (!Number.isFinite(parsed) || parsed < min) return fallback;
+  return Math.min(parsed, max);
+}
+
+function normalizeMessages(messages) {
+  return Array.isArray(messages)
+    ? messages
+        .map((message) => {
+          if (!message || typeof message !== 'object') return null;
+          const role = toString(message.role);
+          const content = toString(message.content);
+          if (!role || !content) return null;
+          return { role, content };
+        })
+        .filter(Boolean)
+    : [];
+}
+
+export function extractModelRelayConfig(cfg = {}, accountId = '') {
+  const channel = cfg?.channels?.oomi || cfg?.oomi || cfg;
+  const accounts = channel && typeof channel.accounts === 'object' ? channel.accounts : {};
+  const defaultAccountId = toString(accountId, toString(channel?.defaultAccountId, 'default'));
+  const account = accounts[defaultAccountId] || accounts.default || {};
+  const relay = account?.modelRelay || cfg?.modelRelay || {};
+
+  return {
+    enabled: relay.enabled === true,
+    backendUrl: toString(relay.backendUrl, toString(account.backendUrl)),
+    endpointPath: toString(relay.endpointPath, DEFAULT_ENDPOINT_PATH),
+    provider: toString(relay.provider),
+    model: toString(relay.model),
+    requestOrigin: toString(relay.requestOrigin, DEFAULT_REQUEST_ORIGIN),
+    userId: toString(relay.userId),
+    deviceId: toString(relay.deviceId),
+    internalKeyEnv: toString(relay.internalKeyEnv),
+    requestTimeoutMs: toPositiveInteger(relay.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS, {
+      min: 2000,
+      max: 120000,
+    }),
+  };
+}
+
+function buildRelayUrl(backendUrl, endpointPath) {
+  const base = toString(backendUrl).replace(/\/+$/, '');
+  const path = `/${toString(endpointPath, DEFAULT_ENDPOINT_PATH).replace(/^\/+/, '')}`;
+  return `${base}${path}`;
+}
+
+function resolveInternalKey({ relayConfig, env = process.env, internalKey = '' }) {
+  const direct = toString(internalKey);
+  if (direct) return direct;
+
+  const envName = toString(relayConfig.internalKeyEnv);
+  if (!envName) return '';
+
+  return toString(env?.[envName]);
+}
+
+export function validateModelRelayConfig(relayConfig, { env = process.env, internalKey = '' } = {}) {
+  const config = relayConfig || {};
+  if (!config.enabled) {
+    return { ok: false, error: 'Oomi model relay is disabled.' };
+  }
+  if (!config.backendUrl) {
+    return { ok: false, error: 'Oomi model relay backendUrl is required.' };
+  }
+  if (!config.userId) {
+    return { ok: false, error: 'Oomi model relay userId is required.' };
+  }
+  if (!resolveInternalKey({ relayConfig: config, env, internalKey })) {
+    return { ok: false, error: 'Oomi model relay internal key is required.' };
+  }
+
+  return { ok: true };
+}
+
+export async function chatWithModelRelay({
+  cfg,
+  accountId = '',
+  messages,
+  maxOutputTokens,
+  temperature,
+  conversationKey = '',
+  requestOrigin = '',
+  fetchImpl = globalThis.fetch,
+  env = process.env,
+  internalKey = '',
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('A fetch implementation is required for Oomi model relay chat.');
+  }
+
+  const relayConfig = extractModelRelayConfig(cfg, accountId);
+  const validation = validateModelRelayConfig(relayConfig, { env, internalKey });
+  if (!validation.ok) {
+    throw new Error(validation.error);
+  }
+
+  const normalizedMessages = normalizeMessages(messages);
+  if (normalizedMessages.length === 0) {
+    throw new Error('At least one model relay message is required.');
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), relayConfig.requestTimeoutMs);
+
+  try {
+    const body = {
+      provider: relayConfig.provider || undefined,
+      model: relayConfig.model || undefined,
+      messages: normalizedMessages,
+      requestOrigin: toString(requestOrigin, relayConfig.requestOrigin),
+      maxOutputTokens: toPositiveInteger(maxOutputTokens, undefined),
+      temperature,
+      deviceId: relayConfig.deviceId || undefined,
+      conversationKey: toString(conversationKey) || undefined,
+    };
+
+    const response = await fetchImpl(buildRelayUrl(relayConfig.backendUrl, relayConfig.endpointPath), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Oomi-Internal-Key': resolveInternalKey({ relayConfig, env, internalKey }),
+        'X-Oomi-User-Id': relayConfig.userId,
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+
+    const payload = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      const error = toString(payload.error, `Oomi model relay failed with status ${response.status}.`);
+      throw new Error(error);
+    }
+
+    return payload;
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/lib/openclawProfile.js

@@ -8,6 +8,15 @@ const DEFAULT_SESSION_KEY = 'agent:main:webchat:channel:oomi';
 const DEFAULT_GATEWAY_PORT = 18789;
 const DEFAULT_PLUGIN_TRUST_MODE = 'auto-discovery';
 const DEFAULT_MODEL_AUTH_MODE = 'oomi-managed';
+const DEFAULT_MODEL_RELAY_PROVIDER = 'openrouter';
+const DEFAULT_MODEL_RELAY_MODEL = 'google/gemini-2.5-flash';
+const DEFAULT_MODEL_RELAY_ENDPOINT_PATH = '/v1/model/relay/chat';
+const DEFAULT_MODEL_RELAY_OPENAI_BASE_PATH = '/v1/model/relay/openai';
+const DEFAULT_MODEL_RELAY_REQUEST_ORIGIN = 'hosted_openclaw';
+const DEFAULT_MODEL_RELAY_TIMEOUT_MS = 60000;
+const DEFAULT_MODEL_RELAY_INTERNAL_KEY_ENV = 'OOMI_HOSTED_BOOTSTRAP_INTERNAL_KEY';
+const DEFAULT_MODEL_RELAY_OPENCLAW_PROVIDER_ID = 'oomi-managed';
+const DEFAULT_MODEL_RELAY_MAX_TOKENS = 1024;
 
 function trimString(value) {
   return typeof value === 'string' ? value.trim() : '';
@@ -62,6 +71,14 @@ function normalizeModelAuthMode(value) {
   return trimString(value) === 'provider-env' ? 'provider-env' : DEFAULT_MODEL_AUTH_MODE;
 }
 
+function normalizeProviderId(value) {
+  const normalized = trimString(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return normalized || DEFAULT_MODEL_RELAY_OPENCLAW_PROVIDER_ID;
+}
+
 function resolveConfigPath(openclawHome, explicitPath = '') {
   const targetPath = trimString(explicitPath);
   if (targetPath) return path.resolve(targetPath);
@@ -129,7 +146,7 @@ function applyOomiChannelConfig(config, oomiChannel) {
   const accounts = typeof oomi.accounts === 'object' && oomi.accounts ? { ...oomi.accounts } : {};
   const defaultAccount = typeof accounts.default === 'object' && accounts.default ? { ...accounts.default } : {};
 
-  accounts.default = {
+  const nextDefaultAccount = {
     enabled: true,
     requestTimeoutMs: normalizePositiveInteger(oomiChannel?.requestTimeoutMs, 15000),
     ...defaultAccount,
@@ -138,6 +155,16 @@ function applyOomiChannelConfig(config, oomiChannel) {
     defaultSessionKey: trimString(oomiChannel?.defaultSessionKey) || DEFAULT_SESSION_KEY,
   };
 
+  const modelRelay = buildModelRelayConfig(oomiChannel?.modelRelay, {
+    backendUrl: nextDefaultAccount.backendUrl,
+  });
+  if (modelRelay.enabled) {
+    nextDefaultAccount.modelRelay = modelRelay;
+  } else if (Object.prototype.hasOwnProperty.call(nextDefaultAccount, 'modelRelay')) {
+    delete nextDefaultAccount.modelRelay;
+  }
+
+  accounts.default = nextDefaultAccount;
   oomi.defaultAccountId = 'default';
   oomi.accounts = accounts;
   channels.oomi = oomi;
@@ -145,6 +172,110 @@ function applyOomiChannelConfig(config, oomiChannel) {
   return nextConfig;
 }
 
+function buildModelRelayConfig(modelRelay, defaults = {}) {
+  const relay = modelRelay && typeof modelRelay === 'object' ? modelRelay : {};
+  const enabled = normalizeBoolean(relay.enabled, false);
+  const backendUrl = trimString(relay.backendUrl) || trimString(defaults.backendUrl);
+  const openclawProviderId = normalizeProviderId(relay.openclawProviderId);
+  const model = trimString(relay.model) || DEFAULT_MODEL_RELAY_MODEL;
+
+  return {
+    enabled,
+    backendUrl,
+    endpointPath: trimString(relay.endpointPath) || DEFAULT_MODEL_RELAY_ENDPOINT_PATH,
+    openaiBasePath: trimString(relay.openaiBasePath) || DEFAULT_MODEL_RELAY_OPENAI_BASE_PATH,
+    openclawProviderId,
+    openclawModelRef: `${openclawProviderId}/${model}`,
+    provider: trimString(relay.provider) || DEFAULT_MODEL_RELAY_PROVIDER,
+    model,
+    requestOrigin: trimString(relay.requestOrigin) || DEFAULT_MODEL_RELAY_REQUEST_ORIGIN,
+    userId: trimString(relay.userId),
+    deviceId: trimString(relay.deviceId),
+    internalKeyEnv: trimString(relay.internalKeyEnv) || DEFAULT_MODEL_RELAY_INTERNAL_KEY_ENV,
+    requestTimeoutMs: normalizePositiveInteger(relay.requestTimeoutMs, DEFAULT_MODEL_RELAY_TIMEOUT_MS),
+    maxTokens: normalizePositiveInteger(relay.maxTokens, DEFAULT_MODEL_RELAY_MAX_TOKENS),
+  };
+}
+
+function joinUrl(baseUrl, pathValue) {
+  const base = trimString(baseUrl).replace(/\/+$/, '');
+  const suffix = `/${trimString(pathValue).replace(/^\/+/, '')}`;
+  return `${base}${suffix}`;
+}
+
+function applyOomiManagedModelProviderConfig(config, modelRelay) {
+  if (!modelRelay?.enabled || !trimString(modelRelay.backendUrl) || !trimString(modelRelay.userId)) {
+    return config;
+  }
+
+  const nextConfig = { ...(config || {}) };
+  const modelsRoot = nextConfig.models && typeof nextConfig.models === 'object' ? { ...nextConfig.models } : {};
+  const providers =
+    modelsRoot.providers && typeof modelsRoot.providers === 'object' ? { ...modelsRoot.providers } : {};
+  const providerId = normalizeProviderId(modelRelay.openclawProviderId);
+  const modelId = trimString(modelRelay.model) || DEFAULT_MODEL_RELAY_MODEL;
+
+  modelsRoot.mode = trimString(modelsRoot.mode) || 'merge';
+  providers[providerId] = {
+    ...(providers[providerId] && typeof providers[providerId] === 'object' ? providers[providerId] : {}),
+    baseUrl: joinUrl(modelRelay.backendUrl, modelRelay.openaiBasePath),
+    api: 'openai-completions',
+    apiKey: `\${${modelRelay.internalKeyEnv}}`,
+    authHeader: true,
+    headers: {
+      'X-Oomi-User-Id': modelRelay.userId,
+      'X-Oomi-Device-Id': modelRelay.deviceId,
+      'X-Oomi-Relay-Provider': modelRelay.provider,
+      'X-Oomi-Request-Origin': modelRelay.requestOrigin,
+    },
+    models: [
+      {
+        id: modelId,
+        name: `Oomi Managed ${modelId}`,
+        reasoning: false,
+        input: ['text'],
+        cost: {
+          input: 0.0003,
+          output: 0.0025,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+        contextWindow: 128000,
+        contextTokens: 96000,
+        maxTokens: normalizePositiveInteger(modelRelay.maxTokens, DEFAULT_MODEL_RELAY_MAX_TOKENS),
+        compat: {
+          requiresStringContent: true,
+          strictMessageKeys: true,
+        },
+      },
+    ],
+  };
+  modelsRoot.providers = providers;
+  nextConfig.models = modelsRoot;
+
+  const agents = nextConfig.agents && typeof nextConfig.agents === 'object' ? { ...nextConfig.agents } : {};
+  const defaults = agents.defaults && typeof agents.defaults === 'object' ? { ...agents.defaults } : {};
+  const defaultModel =
+    defaults.model && typeof defaults.model === 'object' && !Array.isArray(defaults.model)
+      ? { ...defaults.model }
+      : {};
+  const allowedModels =
+    defaults.models && typeof defaults.models === 'object' ? { ...defaults.models } : {};
+  const modelRef = `${providerId}/${modelId}`;
+
+  defaultModel.primary = modelRef;
+  allowedModels[modelRef] = {
+    ...(allowedModels[modelRef] && typeof allowedModels[modelRef] === 'object' ? allowedModels[modelRef] : {}),
+    alias: 'Oomi Managed',
+  };
+  defaults.model = defaultModel;
+  defaults.models = allowedModels;
+  agents.defaults = defaults;
+  nextConfig.agents = agents;
+
+  return nextConfig;
+}
+
 function removeOomiChannelConfig(config) {
   const nextConfig = { ...(config || {}) };
   const channels =
@@ -193,6 +324,26 @@ export function buildOomiDevLocalProfile(options = {}) {
       defaultSessionKey: trimString(options.defaultSessionKey) || DEFAULT_SESSION_KEY,
       requestTimeoutMs: normalizePositiveInteger(options.requestTimeoutMs, 15000),
       pluginTrustMode,
+      modelRelay: buildModelRelayConfig(
+        {
+          enabled: normalizeBoolean(options.modelRelayEnabled, false),
+          backendUrl: options.modelRelayBackendUrl || options.backendUrl,
+          endpointPath: options.modelRelayEndpointPath,
+          openaiBasePath: options.modelRelayOpenaiBasePath,
+          openclawProviderId: options.modelRelayOpenclawProviderId,
+          provider: options.modelRelayProvider,
+          model: options.modelRelayModel,
+          requestOrigin: options.modelRelayRequestOrigin,
+          userId: options.modelRelayUserId,
+          deviceId: options.modelRelayDeviceId || options.deviceId,
+          internalKeyEnv: options.modelRelayInternalKeyEnv,
+          requestTimeoutMs: options.modelRelayRequestTimeoutMs,
+          maxTokens: options.modelRelayMaxTokens,
+        },
+        {
+          backendUrl: options.backendUrl,
+        }
+      ),
     },
     model: {
       preset: trimString(options.modelPreset || 'openrouter-free'),
@@ -240,6 +391,9 @@ export function applyOpenclawProfile({
 
   if (normalizeBoolean(profile?.oomiChannel?.enabled, false)) {
     nextConfig = applyOomiChannelConfig(nextConfig, profile.oomiChannel);
+    if (normalizeModelAuthMode(profile?.model?.authMode) === 'oomi-managed') {
+      nextConfig = applyOomiManagedModelProviderConfig(nextConfig, profile.oomiChannel.modelRelay);
+    }
   } else {
     nextConfig = removeOomiChannelConfig(nextConfig);
   }

package/lib/personaApiClient.js

@@ -149,6 +149,15 @@ export function createPersonaApiClient({
       });
     },
 
+    getFinanceContext() {
+      return getJson({
+        fetchImpl,
+        backendUrl: resolvedBackendUrl,
+        deviceToken: resolvedDeviceToken,
+        path: '/v1/context/finance',
+      });
+    },
+
     requestHealthContextSync({
       reason = 'agent_requested',
     } = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Managed Oomi channel, bridge, voice, and persona app API tooling for OpenClaw",
   "bin": {
     "oomi": "bin/oomi-ai.js"
@@ -59,6 +59,7 @@
   "files": [
     "bin/oomi-ai.js",
     "bin/sessionBridgeState.js",
+    "lib/modelRelayClient.js",
     "lib/openclawPaths.js",
     "lib/openclawProfile.js",
     "lib/personaApiClient.js",

package/persona-app/README.md

@@ -39,3 +39,5 @@ oomi context health sync --wait --json
 Answer only after fresh context is uploaded. If the command times out, tell the user the phone sync is still pending.
 
 If a persona app is missing, ask the user to add it from the Oomi client first so platform-specific permissions and hydration can run.
+
+Finance balances are a signed-in web persona-app. `oomi context finance` / `finance.context.read` stay off the connected shell until Gate A.

package/persona-app/registry/v1.json

@@ -7,21 +7,38 @@
       "command": "oomi context health --json",
       "endpoint": "/v1/context/health",
       "description": "Reads the latest account-linked health context synced by Oomi mobile clients.",
-      "permissions": ["healthkit.read", "health_connect.read"],
+      "permissions": [
+        "healthkit.read",
+        "health_connect.read"
+      ],
       "readOnly": true,
-      "targets": ["ios", "android", "web"]
+      "targets": [
+        "ios",
+        "android",
+        "web"
+      ]
     }
   ],
   "sharedComponents": [
     {
       "type": "shared.personaHero",
       "description": "Domain hero with title, subtitle, and a primary metric.",
-      "targets": ["ios", "android", "web", "webspatial"]
+      "targets": [
+        "ios",
+        "android",
+        "web",
+        "webspatial"
+      ]
     },
     {
       "type": "shared.oomiNote",
       "description": "A primary-persona note with optional actions.",
-      "targets": ["ios", "android", "web", "webspatial"]
+      "targets": [
+        "ios",
+        "android",
+        "web",
+        "webspatial"
+      ]
     }
   ],
   "personaPacks": [
@@ -32,22 +49,38 @@
         {
           "type": "fitness.todaySummary",
           "description": "Daily movement summary with progress, steps, and sleep context.",
-          "targets": ["ios", "android", "web"]
+          "targets": [
+            "ios",
+            "android",
+            "web"
+          ]
         },
         {
           "type": "fitness.goalChecklist",
           "description": "Checklist of suggested goals for today.",
-          "targets": ["ios", "android", "web"]
+          "targets": [
+            "ios",
+            "android",
+            "web"
+          ]
         },
         {
           "type": "fitness.metricGrid",
           "description": "Grid of approved HealthKit or Health Connect activity, sleep, cardio, and body metrics.",
-          "targets": ["ios", "android", "web"]
+          "targets": [
+            "ios",
+            "android",
+            "web"
+          ]
         },
         {
           "type": "fitness.workoutList",
           "description": "Recent workouts synced from the user's approved mobile health source.",
-          "targets": ["ios", "android", "web"]
+          "targets": [
+            "ios",
+            "android",
+            "web"
+          ]
         }
       ],
       "actions": [
@@ -56,9 +89,13 @@
           "description": "Marks one fitness goal complete.",
           "payloadSchema": {
             "type": "object",
-            "required": ["goalId"],
+            "required": [
+              "goalId"
+            ],
             "properties": {
-              "goalId": { "type": "string" }
+              "goalId": {
+                "type": "string"
+              }
             }
           }
         },
@@ -68,8 +105,13 @@
           "payloadSchema": {
             "type": "object",
             "properties": {
-              "goalId": { "type": "string" },
-              "minutes": { "type": "integer", "minimum": 1 }
+              "goalId": {
+                "type": "string"
+              },
+              "minutes": {
+                "type": "integer",
+                "minimum": 1
+              }
             }
           }
         }
@@ -80,6 +122,46 @@
         "healthkit.read",
         "health_connect.read"
       ]
+    },
+    {
+      "personaType": "finance",
+      "displayName": "Finance",
+      "components": [
+        {
+          "type": "finance.accountList",
+          "description": "Linked depository and credit accounts with current/available balances.",
+          "targets": [
+            "web"
+          ]
+        },
+        {
+          "type": "finance.dataSource",
+          "description": "Plaid sandbox link status for the Finance persona-app.",
+          "targets": [
+            "web"
+          ]
+        }
+      ],
+      "actions": [
+        {
+          "id": "finance.sync_balances",
+          "description": "Refresh balances for linked depository and credit accounts.",
+          "payloadSchema": {
+            "type": "object"
+          }
+        },
+        {
+          "id": "finance.reconnect",
+          "description": "Refresh Finance persona-app state after a Plaid update-mode reconnect.",
+          "payloadSchema": {
+            "type": "object"
+          }
+        }
+      ],
+      "permissions": [
+        "finance.balances.read",
+        "plaid.link"
+      ]
     }
   ]
 }

package/skills/oomi/SKILL.md

@@ -11,44 +11,25 @@ Use this skill when you need to:
 - inspect managed chat or voice health
 - inspect or update component-composed Oomi persona app state
 - read approved Oomi backend context such as HealthKit summaries synced by the mobile app
+- read permissioned Finance balances (no tokens, routing, or transactions)
 - control the Oomi avatar with inline tags
 
 ## Primary Operator Workflow
 
 If the user wants OpenClaw connected to Oomi:
 
-1. Ensure `oomi-ai` is installed or updated:
+1. For a first-time install or missing local pairing state, run the bootstrap exactly once using the requested app URL:
 ```bash
-pnpm add -g oomi-ai@latest
-```
-Fallback:
-```bash
-npm install -g oomi-ai@latest
-```
-
-2. Pair the device:
-```bash
-oomi openclaw pair --app-url https://www.oomi.ai --no-start
-```
-
-3. Install the plugin:
-```bash
-openclaw plugins install oomi-ai@latest
+curl -fsSL https://www.oomi.ai/install.sh | bash
 ```
+The bootstrap installs or updates `oomi-ai`, performs the one initial pair, installs the plugin, and starts the saved bridge detached. Do not pair again after it finishes.
 
-4. Print config guidance:
+2. Print config guidance and apply the `channels.oomi.accounts.default` config:
 ```bash
 oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai
 ```
 
-5. Apply the `channels.oomi.accounts.default` config and restart OpenClaw.
-
-6. Refresh the running bridge after package updates:
-```bash
-oomi openclaw refresh --skip-version-check
-```
-
-7. Start or repair the bridge:
+3. Restart OpenClaw, then ensure the saved bridge is running:
 ```bash
 oomi openclaw bridge ensure --detach
 ```
@@ -61,6 +42,20 @@ On macOS, prefer supervised mode:
 oomi openclaw bridge service install
 ```
 
+4. If the Auth Link printed by bootstrap is missing or expired, create a replacement without re-pairing:
+```bash
+oomi openclaw invite --app-url https://www.oomi.ai
+```
+
+5. If the machine is already paired, do not rerun bootstrap. Refresh the installed package and plugin without changing pairing state, then use `invite`, `bridge ensure`, or `bridge restart` as needed:
+```bash
+pnpm add -g oomi-ai@latest
+openclaw plugins install oomi-ai@latest
+oomi openclaw refresh --skip-version-check
+```
+
+If the user provides a specific app URL, substitute it in both the bootstrap URL and the `invite --app-url` command.
+
 ## Health Checks
 
 Use these when chat or voice is failing:
@@ -192,3 +187,7 @@ Supported inline tags include:
 - expressions: `[face:happy]`, `[face:sad]`, `[face:surprised]`, `[face:focused]`, `[face:gentle]`, `[face:thinking]`
 - gestures: `[gesture:nod]`, `[gesture:think]`, `[gesture:shrug]`, `[gesture:wave]`, `[gesture:bow]`
 - gaze: `[look:camera]`, `[look:left]`, `[look:right]`, `[look:up]`, `[look:down]`
+
+## Permissioned Finance Context
+
+Finance is a specialist persona-app on signed-in web. It is not a connected-chat tool. Do not run `oomi context finance`. There is no `finance.context.read` contextTool until Gate A. If the user asks about bank balances in live chat, send them to the web Finance persona-app. Do not answer from bank data.

package/skills/oomi/agent_instructions.md

@@ -15,26 +15,23 @@ Aliases allowed (if needed): wave -> Waving, walk -> Walking, idle -> Idle, sit/
 
 If the user asks to connect OpenClaw to Oomi voice or chat:
 
-1. Refresh bootstrap/update first:
+1. For a first-time install or missing local pairing state, run bootstrap exactly once using the requested app URL:
    - `curl -fsSL https://www.oomi.ai/install.sh | bash`
-2. Ensure `oomi-ai` is installed (`pnpm add -g oomi-ai@latest`).
-   - Fallback: `npm install -g oomi-ai@latest`
-3. Pair device token without starting legacy bridge:
-   - `oomi openclaw pair --app-url https://www.oomi.ai --no-start`
-4. Install OpenClaw plugin:
-   - `openclaw plugins install oomi-ai@latest`
-5. Configure channel account (`channels.oomi.accounts.default`) from:
+   - Bootstrap installs or updates `oomi-ai`, performs the one initial pair, installs the plugin, and starts the saved bridge detached.
+   - Do not pair again after bootstrap.
+2. Configure channel account (`channels.oomi.accounts.default`) from:
    - `oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai`
-6. Restart OpenClaw.
-7. Ensure exactly one bridge worker is running (singleton handler):
+3. Restart OpenClaw.
+4. Ensure exactly one bridge worker is running (singleton handler):
    - `oomi openclaw refresh --skip-version-check`
    - `oomi openclaw bridge ensure --detach`
    - If stale/disconnected: `oomi openclaw bridge restart --detach`
    - On macOS, prefer supervised mode: `oomi openclaw bridge service install`
-8. If user provides an app URL (for example "Connect yourself to Oomi. Use app URL <URL>."):
-   - Use that URL directly in the pair command.
-   - Example: `oomi openclaw pair --app-url <URL> --no-start`
-9. Return this exact result format to the user:
+5. If the Auth Link printed by bootstrap is missing or expired, create a replacement without re-pairing:
+   - `oomi openclaw invite --app-url https://www.oomi.ai`
+6. If the user provides an app URL, substitute it in both the bootstrap URL and the `invite --app-url` command.
+7. If the machine is already paired, do not rerun bootstrap. Use `invite` for link recovery and `bridge ensure` or `bridge restart` for runtime recovery.
+8. Return this exact result format to the user:
    - `Oomi Connect Ready`
    - `Auth Link: ...`
    - No extra narrative text before or after those lines.