@aria_asi/cli 0.2.29 → 0.2.31

package/dist/runtime/metering.mjs

@@ -0,0 +1,100 @@
+import { existsSync, mkdirSync, appendFileSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const STATE_DIR = join(__dirname, '..', 'state', 'metering');
+
+const COST_RATES = {
+  'deepseek-v4-pro': { inputPer1k: 0.0006, outputPer1k: 0.0022 },
+  'deepseek-v4-flash': { inputPer1k: 0.00015, outputPer1k: 0.0006 },
+};
+
+function ensureDir(p) {
+  if (!existsSync(p)) mkdirSync(p, { recursive: true });
+}
+
+export function brandModel(provider, model) {
+  if (provider === 'deepseek' && model?.includes('v4-pro')) return 'Aria Intelligence Pro';
+  if (provider === 'deepseek' && model?.includes('v4-flash')) return 'Aria Intelligence Flash';
+  return 'Aria Intelligence';
+}
+
+export function recordTokenUsage(record) {
+  const { tenantId, agentId, agentName, department, sessionId, provider, model, usage, requestType } = record;
+  if (!usage || !tenantId) return null;
+  const inputTokens = usage.prompt_tokens || usage.input_tokens || 0;
+  const outputTokens = usage.completion_tokens || usage.output_tokens || 0;
+  const totalTokens = usage.total_tokens || (inputTokens + outputTokens);
+  if (totalTokens === 0) return null;
+  const modelKey = model?.includes('v4-pro') ? 'deepseek-v4-pro' : model?.includes('v4-flash') ? 'deepseek-v4-flash' : null;
+  const rates = COST_RATES[modelKey] || COST_RATES['deepseek-v4-flash'];
+  const estimatedCostUsd = (inputTokens / 1000) * rates.inputPer1k + (outputTokens / 1000) * rates.outputPer1k;
+  const entry = {
+    id: randomUUID(), tenantId, agentId: agentId || null, agentName: agentName || null,
+    department: department || null, sessionId: sessionId || '', timestamp: new Date().toISOString(),
+    provider: provider || 'unknown', modelLabel: brandModel(provider, model),
+    inputTokens, outputTokens, totalTokens,
+    estimatedCostUsd: Math.round(estimatedCostUsd * 1e8) / 1e8,
+    requestType: requestType || 'chat',
+  };
+  ensureDir(STATE_DIR);
+  appendFileSync(join(STATE_DIR, `${tenantId}.jsonl`), JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+export function getUsageSummary(tenantId, opts = {}) {
+  const filePath = join(STATE_DIR, `${tenantId}.jsonl`);
+  if (!existsSync(filePath)) return { tenantId, records: 0, totalTokens: 0, totalCostUsd: 0, byDepartment: {}, byAgent: {}, byModel: {}, byRequestType: {} };
+  const lines = readFileSync(filePath, 'utf-8').split('\n').filter(Boolean);
+  const from = opts.from ? new Date(opts.from) : null;
+  const to = opts.to ? new Date(opts.to) : null;
+  const summary = { tenantId, records: 0, totalTokens: 0, totalCostUsd: 0, byDepartment: {}, byAgent: {}, byModel: {}, byRequestType: {} };
+  for (const line of lines) {
+    try {
+      const r = JSON.parse(line);
+      if (from && new Date(r.timestamp) < from) continue;
+      if (to && new Date(r.timestamp) > to) continue;
+      summary.records++; summary.totalTokens += r.totalTokens; summary.totalCostUsd += r.estimatedCostUsd;
+      const dept = r.department || 'unassigned';
+      summary.byDepartment[dept] = summary.byDepartment[dept] || { tokens: 0, cost: 0, calls: 0 };
+      summary.byDepartment[dept].tokens += r.totalTokens; summary.byDepartment[dept].cost += r.estimatedCostUsd; summary.byDepartment[dept].calls++;
+      const agent = r.agentId || 'unassigned';
+      summary.byAgent[agent] = summary.byAgent[agent] || { tokens: 0, cost: 0, calls: 0, name: r.agentName };
+      summary.byAgent[agent].tokens += r.totalTokens; summary.byAgent[agent].cost += r.estimatedCostUsd; summary.byAgent[agent].calls++;
+      const mdl = r.modelLabel || 'unknown';
+      summary.byModel[mdl] = summary.byModel[mdl] || { tokens: 0, cost: 0, calls: 0 };
+      summary.byModel[mdl].tokens += r.totalTokens; summary.byModel[mdl].cost += r.estimatedCostUsd; summary.byModel[mdl].calls++;
+      const rt = r.requestType || 'chat';
+      summary.byRequestType[rt] = summary.byRequestType[rt] || { tokens: 0, cost: 0, calls: 0 };
+      summary.byRequestType[rt].tokens += r.totalTokens; summary.byRequestType[rt].cost += r.estimatedCostUsd; summary.byRequestType[rt].calls++;
+    } catch {}
+  }
+  summary.totalCostUsd = Math.round(summary.totalCostUsd * 1e6) / 1e6;
+  return summary;
+}
+
+export function getSubscriptionTier(tierId) {
+  const TIERS = {
+    starter: { id: 'starter', label: 'Starter', includedTokens: 500_000, maxOpenClaws: 3, priceUsd: 49, overagePerToken: 0.0001 },
+    pro: { id: 'pro', label: 'Pro', includedTokens: 5_000_000, maxOpenClaws: 10, priceUsd: 199, overagePerToken: 0.00008 },
+    enterprise: { id: 'enterprise', label: 'Enterprise', includedTokens: 50_000_000, maxOpenClaws: 100, priceUsd: 999, overagePerToken: 0.00005 },
+  };
+  return TIERS[tierId] || TIERS.starter;
+}
+
+export function getBillingSummary(tenantId, tierId = 'starter') {
+  const usage = getUsageSummary(tenantId);
+  const tier = getSubscriptionTier(tierId);
+  const overageTokens = Math.max(0, usage.totalTokens - tier.includedTokens);
+  const overageCost = overageTokens * tier.overagePerToken;
+  const utilizationPct = tier.includedTokens > 0 ? Math.min(100, Math.round((usage.totalTokens / tier.includedTokens) * 100)) : 0;
+  return {
+    tenantId, tier, period: { from: null, to: new Date().toISOString() },
+    usage: { totalTokens: usage.totalTokens, totalCostUsd: usage.totalCostUsd, records: usage.records },
+    billing: { basePriceUsd: tier.priceUsd, overageTokens, overageCostUsd: Math.round(overageCost * 100) / 100, totalDueUsd: tier.priceUsd + Math.round(overageCost * 100) / 100 },
+    utilizationPct, upsellTriggers: { at50: utilizationPct >= 50, at80: utilizationPct >= 80, at100: utilizationPct >= 100 },
+    breakdown: { byDepartment: usage.byDepartment, byAgent: usage.byAgent, byModel: usage.byModel },
+  };
+}

package/dist/runtime/onboarding-engine.mjs

@@ -0,0 +1,89 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const STATE_DIR = join(__dirname, '..', 'state');
+
+export const STEPS = [
+  'greeting', 'industry-discovery', 'team-size', 'role-selection',
+  'openclaw-allocation', 'plugin-preference', 'llm-preference',
+  'workflow-customization', 'credentials', 'confirmation', 'complete',
+];
+
+const STEP_PROMPTS = {
+  greeting: `You are Aria, the AI workforce architect. A new client just started onboarding. Introduce yourself warmly and ask: "What does your company do? What industry are you in?" Keep it to 2-3 sentences.`,
+  'industry-discovery': `Based on what the client said, identify their industry (real-estate, saas, recruiting, ecommerce, generic) and confirm. Then ask about their team size. Extract: {{FIELD:industry:value}} {{FIELD:companyName:value}}.`,
+  'team-size': `Acknowledge team size. Recommend departments for their industry. Ask which ones interest them. Extract: {{FIELD:teamSize:value}}.`,
+  'role-selection': `List agent roles for their selected departments. Confirm which agents they want. Extract: {{FIELD:selectedAgents:list}}.`,
+  'openclaw-allocation': `Explain OpenClaws and tiers: Starter $49/mo 3 OpenClaws 500K tokens, Pro $199/mo 10 OpenClaws 5M tokens, Enterprise $999/mo 100 OpenClaws 50M tokens. Recommend based on agent count. Extract: {{FIELD:openClaws:value}} {{FIELD:tier:value}}.`,
+  'plugin-preference': `Offer plugins: CRM Hub, Communication Hub, KPI Dashboard, Compliance Guard. Can skip. Extract: {{FIELD:plugins:list}}.`,
+  'llm-preference': `Explain managed AI (Aria Intelligence) vs BYOK option. Extract: {{FIELD:llmPreference:value}}.`,
+  'workflow-customization': `For selected agents, ask about workflow customization (auto-score vs manual review, approval thresholds, escalation). Extract: {{FIELD:workflowConfig:object}}.`,
+  credentials: `Say: "Almost done! To set up your dashboard login, I need your email address. What email should we use for your account?" Extract: {{FIELD:email:value}}.`,
+  confirmation: `Present full HQ config summary including their email. Ask to confirm deployment. Extract: {{FIELD:confirmed:true}}.`,
+};
+
+export function advanceStep(current) {
+  const idx = STEPS.indexOf(current);
+  return idx >= 0 && idx < STEPS.length - 1 ? STEPS[idx + 1] : 'complete';
+}
+
+function extractFields(text) {
+  const fields = {};
+  const rx = /\{\{FIELD:(\w+):(\w+)\}\}/g;
+  let m;
+  while ((m = rx.exec(text)) !== null) {
+    if (m[2] !== 'list' && m[2] !== 'object') fields[m[1]] = m[2];
+  }
+  return fields;
+}
+
+export function createOnboardingSession(tenantId) {
+  return {
+    id: randomUUID(), tenantId, step: 'greeting',
+    data: { industry: null, companyName: null, teamSize: null, selectedAgents: [], openClaws: 3, tier: 'starter', plugins: [], llmPreference: 'managed', workflowConfig: {}, email: null, password: null, confirmed: false },
+    history: [], createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(),
+  };
+}
+
+export function getSessionPath(tenantId) {
+  return join(STATE_DIR, `onboarding-${tenantId}.json`);
+}
+
+export function loadSession(tenantId) {
+  const p = getSessionPath(tenantId);
+  return existsSync(p) ? JSON.parse(readFileSync(p, 'utf-8')) : null;
+}
+
+export function saveSession(session) {
+  session.updatedAt = new Date().toISOString();
+  writeFileSync(getSessionPath(session.tenantId), JSON.stringify(session, null, 2));
+  return session;
+}
+
+export function getStepPrompt(step) {
+  return STEP_PROMPTS[step] || STEP_PROMPTS.greeting;
+}
+
+export function processResponse(session, llmResponse) {
+  const extracted = extractFields(llmResponse);
+  for (const [k, v] of Object.entries(extracted)) { if (k in session.data) session.data[k] = v; }
+  session.history.push({ role: 'assistant', content: llmResponse, step: session.step, timestamp: new Date().toISOString() });
+  if ((Object.keys(extracted).length > 0 || session.step === 'greeting') && session.data.confirmed !== true) {
+    // Don't auto-advance from credentials — service handler manages the two-phase flow
+    if (session.step !== 'credentials') {
+      session.step = advanceStep(session.step);
+    }
+  }
+  if (session.data.confirmed === true) session.step = 'complete';
+  return session;
+}
+
+export function buildFleetConfig(session) {
+  const agents = (session.data.selectedAgents || []).map((id, i) => ({
+    id: `${session.tenantId}-${id}-${i}`, templateId: id, name: id, department: 'unassigned', tier: 2,
+  }));
+  return { agents, maxOpenClaws: session.data.openClaws || 3, industry: session.data.industry || 'generic', tier: session.data.tier || 'starter', plugins: session.data.plugins || [], llmPreference: session.data.llmPreference || 'managed', workflowConfig: session.data.workflowConfig || {} };
+}

package/dist/runtime/plugin-engine.mjs

@@ -0,0 +1,196 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const STATE_DIR = join(__dirname, '..', 'state');
+
+function ensureDir(p) {
+  if (!existsSync(p)) mkdirSync(p, { recursive: true });
+}
+
+const PLUGIN_REGISTRY = {
+  'crm-hub': {
+    id: 'crm-hub',
+    name: 'CRM Hub',
+    description: 'Contacts, deals, pipeline management, and customer data',
+    version: '1.0.0',
+    hooks: ['onMessage', 'onAction', 'onWebhook'],
+    defaultConfig: {
+      pipelineStages: ['lead', 'qualified', 'proposal', 'negotiation', 'closed-won', 'closed-lost'],
+      autoScore: true,
+      scoreThreshold: 70,
+      fields: ['name', 'email', 'company', 'value', 'stage', 'source'],
+    },
+  },
+  'communication-hub': {
+    id: 'communication-hub',
+    name: 'Communication Hub',
+    description: 'Agent DMs, channels, notifications, and team messaging',
+    version: '1.0.0',
+    hooks: ['onMessage', 'onAction', 'onSchedule'],
+    defaultConfig: {
+      channels: ['general', 'sales', 'marketing', 'ops', 'support'],
+      notifyOnMention: true,
+      digestFrequency: 'daily',
+      maxRecipients: 50,
+    },
+  },
+  'kpi-dashboard': {
+    id: 'kpi-dashboard',
+    name: 'KPI Dashboard',
+    description: 'Business metrics, performance tracking, and goal management',
+    version: '1.0.0',
+    hooks: ['onMessage', 'onSchedule'],
+    defaultConfig: {
+      metrics: ['revenue', 'conversion_rate', 'customer_acquisition_cost', 'lifetime_value', 'churn_rate'],
+      refreshInterval: 'hourly',
+      alertThresholds: { revenue_drop_pct: 20, conversion_below: 0.02 },
+      targets: {},
+    },
+  },
+  'compliance-guard': {
+    id: 'compliance-guard',
+    name: 'Compliance Guard',
+    description: 'Output verification, audit trail, and policy enforcement',
+    version: '1.0.0',
+    hooks: ['onMessage', 'onAction'],
+    defaultConfig: {
+      enabledRules: ['no_pii_leak', 'no_toxic_content', 'no_false_claims', 'mandatory_disclaimer'],
+      auditLevel: 'standard',
+      blockOnViolation: false,
+      logAllOutput: true,
+    },
+  },
+};
+
+function pluginsPath(tenantId) {
+  return join(STATE_DIR, `plugins-${tenantId}.json`);
+}
+
+export function listPlugins(tenantId) {
+  const registry = Object.values(PLUGIN_REGISTRY);
+  let installed = [];
+  const pp = pluginsPath(tenantId);
+  if (existsSync(pp)) {
+    try {
+      const data = JSON.parse(readFileSync(pp, 'utf-8'));
+      installed = data.installed || [];
+    } catch {}
+  }
+  const installedIds = new Set(installed.map(p => p.id));
+  return registry.map(r => ({
+    ...r,
+    installed: installedIds.has(r.id),
+    config: installed.find(p => p.id === r.id)?.config || null,
+    installedAt: installed.find(p => p.id === r.id)?.installedAt || null,
+  }));
+}
+
+export function installPlugin(tenantId, pluginId, config = {}) {
+  const manifest = PLUGIN_REGISTRY[pluginId];
+  if (!manifest) return { ok: false, error: `Unknown plugin: ${pluginId}. Available: ${Object.keys(PLUGIN_REGISTRY).join(', ')}` };
+  const pp = pluginsPath(tenantId);
+  let plugins = existsSync(pp) ? JSON.parse(readFileSync(pp, 'utf-8')) : { installed: [] };
+  if (plugins.installed.find(p => p.id === pluginId)) {
+    return { ok: true, message: 'already installed', plugin: plugins.installed.find(p => p.id === pluginId) };
+  }
+  const entry = {
+    id: pluginId,
+    name: manifest.name,
+    config: { ...manifest.defaultConfig, ...config },
+    installedAt: new Date().toISOString(),
+    status: 'active',
+    hooks: manifest.hooks,
+  };
+  plugins.installed.push(entry);
+  ensureDir(dirname(pp));
+  writeFileSync(pp, JSON.stringify(plugins, null, 2));
+  return { ok: true, plugin: entry };
+}
+
+export function uninstallPlugin(tenantId, pluginId) {
+  const pp = pluginsPath(tenantId);
+  if (!existsSync(pp)) return { ok: false, error: 'No plugins installed' };
+  let plugins = JSON.parse(readFileSync(pp, 'utf-8'));
+  const idx = plugins.installed.findIndex(p => p.id === pluginId);
+  if (idx < 0) return { ok: false, error: `Plugin ${pluginId} not installed` };
+  const removed = plugins.installed.splice(idx, 1)[0];
+  writeFileSync(pp, JSON.stringify(plugins, null, 2));
+  return { ok: true, removed };
+}
+
+export function configurePlugin(tenantId, pluginId, config) {
+  const pp = pluginsPath(tenantId);
+  if (!existsSync(pp)) return { ok: false, error: 'No plugins installed' };
+  let plugins = JSON.parse(readFileSync(pp, 'utf-8'));
+  const plugin = plugins.installed.find(p => p.id === pluginId);
+  if (!plugin) return { ok: false, error: `Plugin ${pluginId} not installed` };
+  plugin.config = { ...plugin.config, ...config };
+  plugin.updatedAt = new Date().toISOString();
+  writeFileSync(pp, JSON.stringify(plugins, null, 2));
+  return { ok: true, plugin };
+}
+
+export function getInstalledPlugins(tenantId) {
+  const pp = pluginsPath(tenantId);
+  if (!existsSync(pp)) return [];
+  try {
+    const data = JSON.parse(readFileSync(pp, 'utf-8'));
+    return (data.installed || []).filter(p => p.status === 'active');
+  } catch {
+    return [];
+  }
+}
+
+export function dispatchHook(tenantId, hookName, context) {
+  const installed = getInstalledPlugins(tenantId);
+  const results = [];
+  for (const plugin of installed) {
+    const manifest = PLUGIN_REGISTRY[plugin.id];
+    if (!manifest || !manifest.hooks.includes(hookName)) continue;
+    try {
+      const handler = HOOK_HANDLERS[`${plugin.id}:${hookName}`];
+      if (typeof handler === 'function') {
+        const result = handler(context, plugin.config);
+        results.push({ pluginId: plugin.id, hookName, result: result || null, error: null });
+      }
+    } catch (err) {
+      results.push({ pluginId: plugin.id, hookName, result: null, error: err.message });
+    }
+  }
+  return results;
+}
+
+const HOOK_HANDLERS = {
+  'crm-hub:onMessage': (ctx, config) => {
+    if (!ctx.message || !ctx.message.toLowerCase()) return null;
+    const fields = config.fields || [];
+    const detected = fields.filter(f => ctx.message.toLowerCase().includes(f.toLowerCase()));
+    if (detected.length === 0) return null;
+    return { type: 'crm-extract', fields: detected, suggestion: `CRM data detected: ${detected.join(', ')}. Consider creating/updating a contact record.` };
+  },
+  'compliance-guard:onMessage': (ctx, config) => {
+    if (!ctx.message) return null;
+    const rules = config.enabledRules || [];
+    const violations = [];
+    if (rules.includes('no_pii_leak')) {
+      const piiPatterns = [/\b\d{3}-\d{2}-\d{4}\b/, /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i, /\b\d{16}\b/];
+      for (const rx of piiPatterns) {
+        if (rx.test(ctx.message)) violations.push('potential_pii_detected');
+      }
+    }
+    if (violations.length > 0) {
+      return { type: 'compliance-violation', violations, block: config.blockOnViolation === true, message: `Compliance issues: ${violations.join(', ')}` };
+    }
+    return null;
+  },
+  'kpi-dashboard:onMessage': (ctx, config) => {
+    if (!ctx.agentId) return null;
+    return { type: 'kpi-event', metric: 'agent_message', agentId: ctx.agentId, timestamp: new Date().toISOString() };
+  },
+  'communication-hub:onMessage': (ctx, config) => {
+    if (!ctx.agentId || !ctx.tenantId) return null;
+    return { type: 'comm-log', agentId: ctx.agentId, tenantId: ctx.tenantId, timestamp: new Date().toISOString() };
+  },
+};

package/dist/runtime/sdk/BUNDLED.json

@@ -1,5 +1,5 @@
 {
-  "bundledAt": "2026-04-29T23:22:23.542Z",
+  "bundledAt": "2026-04-30T13:56:07.664Z",
   "sdkSource": "/home/hamzaibrahim1/rei-ai-brain/harness/packages/harness-http-client/dist",
   "files": 6
 }

package/dist/runtime/sdk/index.d.ts

@@ -260,7 +260,14 @@ export declare class HTTPHarnessClient {
     private cachedPacket;
     private packetLastFetched;
     private readonly packetTtlMs;
+    private preferredBaseUrl;
+    private readonly baseUrlCandidates;
     constructor(config: HarnessClientConfig);
+    private buildBaseUrlCandidates;
+    private isRouteEligibleForBaseFailover;
+    private candidateUrlsFor;
+    private shouldFailoverResponse;
+    private promoteSuccessfulBase;
     private extractHarnessText;
     private normalizePlanDocs;
     private collectPlanFilePaths;

package/dist/runtime/sdk/index.js

@@ -3,6 +3,32 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import { homedir as _homedir } from 'node:os';
 import { resolve, isAbsolute } from 'node:path';
 import { randomUUID } from 'node:crypto';
+const CLOUD_RUN_SOUL_URL = 'https://arias-soul-6zp3gtk2ca-uc.a.run.app';
+const PUBLIC_HARNESS_URL = 'https://harness.ariasos.com';
+const LOCAL_HARNESS_CANDIDATES = [
+    'http://127.0.0.1:30080',
+    'http://192.168.4.25:30080',
+];
+const FAILOVER_STATUS_CODES = new Set([404, 405, 501, 502, 503, 504]);
+function isMountedRuntimeBaseUrl(baseUrl) {
+    return /:\/\/(?:127\.0\.0\.1|localhost):4319$/i.test(String(baseUrl || '').replace(/\/+$/, ''));
+}
+function normalizeHarnessPacketPayload(payload) {
+    let current = payload;
+    for (let depth = 0; depth < 3; depth++) {
+        if (!current || typeof current !== 'object' || Array.isArray(current))
+            break;
+        const nested = current.packet;
+        if (!nested || typeof nested !== 'object' || Array.isArray(nested))
+            break;
+        if (typeof current.timestamp !== 'string' && typeof current.version !== 'string')
+            break;
+        current = nested;
+    }
+    return (current && typeof current === 'object' && !Array.isArray(current))
+        ? current
+        : {};
+}
 // ── 8-Lens Cognition Block ─────────────────────────────────────────────────
 const EIGHT_LENS_BLOCK = `[ARIA SHELL PROTOCOL — You are a controlled surface]
 
@@ -43,11 +69,17 @@ export class HTTPHarnessClient {
     cachedPacket = null;
     packetLastFetched = 0;
     packetTtlMs = 60_000;
+    preferredBaseUrl;
+    baseUrlCandidates;
     constructor(config) {
         this.baseUrl = config.baseUrl.replace(/\/+$/, '');
         this.apiKey = config.apiKey;
-        this.harnessPacketUrl = config.harnessPacketUrl ?? `${this.baseUrl}/api/harness/codex`;
+        this.harnessPacketUrl = config.harnessPacketUrl ?? (isMountedRuntimeBaseUrl(this.baseUrl)
+            ? `${this.baseUrl}/packet`
+            : `${this.baseUrl}/api/harness/codex`);
         this.workspaceRoot = config.workspaceRoot ?? process.cwd();
+        this.preferredBaseUrl = this.baseUrl;
+        this.baseUrlCandidates = this.buildBaseUrlCandidates(config.baseUrl);
         // Layer 3 — sub-agent disk-cache bootstrap (#84).
         // If ARIA_HARNESS_PACKET_PATH is set (injected by aria-agent-handoff.mjs
         // or spawnSubAgent), OR the owner-tier handoff JSON at
@@ -57,6 +89,65 @@ export class HTTPHarnessClient {
         // TTL is 5 min (matches handoff TTL). Stale packets trigger normal fetch.
         this._tryLoadDiskPacket();
     }
+    buildBaseUrlCandidates(primaryBaseUrl) {
+        const envFallbacks = String(process.env.ARIA_HARNESS_FALLBACK_URLS || '')
+            .split(',')
+            .map((value) => value.trim())
+            .filter(Boolean);
+        const candidates = [
+            primaryBaseUrl,
+            process.env.ARIA_HIVE_RUNTIME_URL || '',
+            process.env.ARIA_HARNESS_BASE_URL || '',
+            process.env.ARIA_HARNESS_URL || '',
+            process.env.ARIA_SOUL_URL || '',
+            process.env.ARIAS_SOUL_URL || '',
+            process.env.ARIA_SOUL_BASE_URL || '',
+            ...envFallbacks,
+            ...LOCAL_HARNESS_CANDIDATES,
+            CLOUD_RUN_SOUL_URL,
+            PUBLIC_HARNESS_URL,
+        ]
+            .map((value) => String(value || '').trim().replace(/\/+$/, ''))
+            .filter(Boolean);
+        return Array.from(new Set(candidates));
+    }
+    isRouteEligibleForBaseFailover(url) {
+        return (url.pathname.startsWith('/api/harness/') ||
+            url.pathname === '/api/garden/fire' ||
+            url.pathname.startsWith('/api/cognition/'));
+    }
+    candidateUrlsFor(targetUrl) {
+        let parsed;
+        try {
+            parsed = new URL(targetUrl);
+        }
+        catch {
+            return [targetUrl];
+        }
+        if (!this.isRouteEligibleForBaseFailover(parsed)) {
+            return [targetUrl];
+        }
+        const pathAndQuery = `${parsed.pathname}${parsed.search}`;
+        const orderedBases = [
+            this.preferredBaseUrl,
+            ...this.baseUrlCandidates,
+        ]
+            .map((value) => value.replace(/\/+$/, ''))
+            .filter(Boolean);
+        return Array.from(new Set(orderedBases)).map((baseUrl) => `${baseUrl}${pathAndQuery}`);
+    }
+    shouldFailoverResponse(response, url) {
+        if (!this.isRouteEligibleForBaseFailover(url))
+            return false;
+        return FAILOVER_STATUS_CODES.has(response.status);
+    }
+    promoteSuccessfulBase(targetUrl) {
+        try {
+            const parsed = new URL(targetUrl);
+            this.preferredBaseUrl = parsed.origin;
+        }
+        catch { }
+    }
     extractHarnessText(packet) {
         const raw = packet?.harness;
         return typeof raw === 'string' ? raw.trim() : '';
@@ -230,7 +321,7 @@ export class HTTPHarnessClient {
             const raw = JSON.parse(readFileSync(packetPath, 'utf8'));
             // Packet on disk may be the raw API response (has .packet wrapper) or
             // a bare packet object. Normalise to HarnessPacket shape.
-            const packetData = (raw.packet ?? raw);
+            const packetData = normalizeHarnessPacketPayload(raw.packet ?? raw);
             this.cachedPacket = {
                 packet: packetData,
                 timestamp: new Date().toISOString(),
@@ -297,7 +388,7 @@ export class HTTPHarnessClient {
             }
             const body = (await res.json());
             this.cachedPacket = {
-                packet: (body.packet ?? body),
+                packet: normalizeHarnessPacketPayload(body.packet ?? body),
                 timestamp: new Date().toISOString(),
                 version: '1.0.0',
             };
@@ -312,7 +403,7 @@ export class HTTPHarnessClient {
             if (envPacket) {
                 try {
                     this.cachedPacket = {
-                        packet: JSON.parse(envPacket),
+                        packet: normalizeHarnessPacketPayload(JSON.parse(envPacket)),
                         timestamp: new Date().toISOString(),
                         version: '1.0.0',
                     };
@@ -768,7 +859,7 @@ export class HTTPHarnessClient {
                 resolvedPacketPath = packetPath;
                 // Also pre-load into this SDK instance's cache so subsequent
                 // getHarnessPacket() calls are instant within this process.
-                const packetPayload = (packetData.packet ?? packetData);
+                const packetPayload = normalizeHarnessPacketPayload(packetData.packet ?? packetData);
                 this.cachedPacket = {
                     packet: packetPayload,
                     timestamp: new Date().toISOString(),
@@ -1428,19 +1519,34 @@ export class HTTPHarnessClient {
     // codes — caller decides what to do with non-2xx). No circuit breaker:
     // we always try. Backoff: 250ms, 500ms, 1000ms (3 attempts total).
     async fetchWithRetry(url, init, attempts = 3) {
+        const candidateUrls = this.candidateUrlsFor(url);
         let lastErr;
-        for (let i = 0; i < attempts; i++) {
-            try {
-                return await fetch(url, init);
-            }
-            catch (err) {
-                lastErr = err;
-                if (i < attempts - 1) {
-                    const delay = 250 * Math.pow(2, i);
-                    await new Promise((r) => setTimeout(r, delay));
+        let lastResponse = null;
+        for (const candidateUrl of candidateUrls) {
+            for (let i = 0; i < attempts; i++) {
+                try {
+                    const response = await fetch(candidateUrl, init);
+                    lastResponse = response;
+                    const parsed = new URL(candidateUrl);
+                    if (this.shouldFailoverResponse(response, parsed) && candidateUrl !== candidateUrls[candidateUrls.length - 1]) {
+                        break;
+                    }
+                    if (response.ok) {
+                        this.promoteSuccessfulBase(candidateUrl);
+                    }
+                    return response;
+                }
+                catch (err) {
+                    lastErr = err;
+                    if (i < attempts - 1) {
+                        const delay = 250 * Math.pow(2, i);
+                        await new Promise((r) => setTimeout(r, delay));
+                    }
                 }
             }
         }
+        if (lastResponse)
+            return lastResponse;
         throw lastErr instanceof Error
             ? lastErr
             : new Error(`fetch failed after ${attempts} attempts: ${String(lastErr)}`);