neoagent 3.2.1-beta.8 → 3.3.0

package/server/services/behavior/config.js

@@ -0,0 +1,251 @@
+'use strict';
+
+const db = require('../../db/database');
+const { isMainAgent } = require('../agents/manager');
+const { MODULE_IDS, cloneDefaults, DEFAULT_MODULE_CONFIG } = require('./defaults');
+
+const SETTINGS_KEY = 'behavior_modules_config';
+const PARTICIPATION_MODES = new Set(['automatic', 'mention_only', 'always']);
+const MODEL_PURPOSES = new Set(['fast', 'general']);
+const DELIVERY_STYLES = new Set(['single', 'natural_bubbles']);
+
+function clampNumber(value, min, max, fallback) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(max, Math.max(min, number));
+}
+
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function normalizeModules(rawModules, fallbackEnabled = true, sparse = false) {
+  const source = asObject(rawModules);
+  const modules = {};
+  for (const id of MODULE_IDS) {
+    if (sparse && !Object.prototype.hasOwnProperty.call(source, id)) continue;
+    const entry = asObject(source[id]);
+    modules[id] = {
+      enabled: entry.enabled == null ? fallbackEnabled : entry.enabled !== false,
+    };
+  }
+  return modules;
+}
+
+function normalizeOptionalString(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || null;
+}
+
+function normalizeLeafConfig(raw = {}, base = cloneDefaults(), sparse = false) {
+  const input = asObject(raw);
+  const output = {};
+  const assign = (key, value) => {
+    if (!sparse || Object.prototype.hasOwnProperty.call(input, key)) output[key] = value;
+  };
+  const enabled = input.enabled == null ? base.enabled !== false : input.enabled !== false;
+  assign('enabled', enabled);
+  if (!sparse || Object.prototype.hasOwnProperty.call(input, 'modules')) {
+    output.modules = normalizeModules(input.modules, enabled, sparse);
+  }
+  assign(
+    'participationMode',
+    PARTICIPATION_MODES.has(String(input.participationMode || ''))
+      ? String(input.participationMode)
+      : (base.participationMode || DEFAULT_MODULE_CONFIG.participationMode),
+  );
+  assign('minimumNeedScore', clampNumber(
+    input.minimumNeedScore,
+    0,
+    1,
+    base.minimumNeedScore ?? DEFAULT_MODULE_CONFIG.minimumNeedScore,
+  ));
+  assign('batchWindowMs', Math.round(clampNumber(
+    input.batchWindowMs,
+    0,
+    5000,
+    base.batchWindowMs ?? DEFAULT_MODULE_CONFIG.batchWindowMs,
+  )));
+  assign('decisionContextMessageLimit', Math.round(clampNumber(
+    input.decisionContextMessageLimit,
+    4,
+    30,
+    base.decisionContextMessageLimit ?? DEFAULT_MODULE_CONFIG.decisionContextMessageLimit,
+  )));
+  assign(
+    'decisionModelId',
+    normalizeOptionalString(input.decisionModelId, base.decisionModelId || null),
+  );
+  assign(
+    'decisionModelPurpose',
+    MODEL_PURPOSES.has(String(input.decisionModelPurpose || ''))
+      ? String(input.decisionModelPurpose)
+      : (base.decisionModelPurpose || DEFAULT_MODULE_CONFIG.decisionModelPurpose),
+  );
+  assign(
+    'deliveryStyle',
+    DELIVERY_STYLES.has(String(input.deliveryStyle || ''))
+      ? String(input.deliveryStyle)
+      : (base.deliveryStyle || DEFAULT_MODULE_CONFIG.deliveryStyle),
+  );
+  assign('maxBubbles', Math.round(clampNumber(
+    input.maxBubbles,
+    1,
+    5,
+    base.maxBubbles ?? DEFAULT_MODULE_CONFIG.maxBubbles,
+  )));
+  assign('bubbleGapMs', Math.round(clampNumber(
+    input.bubbleGapMs,
+    0,
+    5000,
+    base.bubbleGapMs ?? DEFAULT_MODULE_CONFIG.bubbleGapMs,
+  )));
+  assign('normsRefreshMessageGap', Math.round(clampNumber(
+    input.normsRefreshMessageGap,
+    3,
+    200,
+    base.normsRefreshMessageGap ?? DEFAULT_MODULE_CONFIG.normsRefreshMessageGap,
+  )));
+  assign('observabilityIntervalMinutes', Math.round(clampNumber(
+    input.observabilityIntervalMinutes,
+    30,
+    10080,
+    base.observabilityIntervalMinutes ?? DEFAULT_MODULE_CONFIG.observabilityIntervalMinutes,
+  )));
+  return output;
+}
+
+function normalizeStoredConfig(raw) {
+  const base = cloneDefaults();
+  const input = asObject(raw);
+  const normalized = {
+    schemaVersion: DEFAULT_MODULE_CONFIG.schemaVersion,
+    ...normalizeLeafConfig(input, base),
+  };
+  const platformOverrides = {};
+  for (const [platform, value] of Object.entries(asObject(input.platformOverrides))) {
+    const key = String(platform || '').trim();
+    if (!key) continue;
+    platformOverrides[key] = normalizeLeafConfig(value, normalized, true);
+  }
+  const roomOverrides = {};
+  const rawRoomOverrides = Object.keys(asObject(input.roomOverrides)).length
+    ? asObject(input.roomOverrides)
+    : asObject(input.groupOverrides);
+  for (const [roomKey, value] of Object.entries(rawRoomOverrides)) {
+    const key = String(roomKey || '').trim();
+    if (!key) continue;
+    roomOverrides[key] = normalizeLeafConfig(value, normalized, true);
+  }
+  return {
+    ...normalized,
+    platformOverrides,
+    roomOverrides,
+  };
+}
+
+function readSettingRow(userId, agentId) {
+  const row = db.prepare(
+    'SELECT value FROM agent_settings WHERE user_id = ? AND agent_id = ? AND key = ?',
+  ).get(userId, agentId, SETTINGS_KEY);
+  if (row?.value != null) return row.value;
+  if (isMainAgent(userId, agentId)) {
+    const legacy = db.prepare(
+      'SELECT value FROM user_settings WHERE user_id = ? AND key = ?',
+    ).get(userId, SETTINGS_KEY);
+    return legacy?.value;
+  }
+  return null;
+}
+
+function parseStoredValue(value) {
+  if (value == null || value === '') return cloneDefaults();
+  if (typeof value === 'object') return normalizeStoredConfig(value);
+  try {
+    return normalizeStoredConfig(JSON.parse(value));
+  } catch {
+    return cloneDefaults();
+  }
+}
+
+function getBehaviorConfig(userId, agentId = null) {
+  return parseStoredValue(readSettingRow(userId, agentId));
+}
+
+function setBehaviorConfig(userId, agentId, config) {
+  const normalized = normalizeStoredConfig(config);
+  db.prepare(
+    `INSERT INTO agent_settings (user_id, agent_id, key, value)
+     VALUES (?, ?, ?, ?)
+     ON CONFLICT(user_id, agent_id, key) DO UPDATE SET value = excluded.value`,
+  ).run(userId, agentId, SETTINGS_KEY, JSON.stringify(normalized));
+  return normalized;
+}
+
+function roomConfigKey(platform, chatId) {
+  return `${String(platform || '').trim()}::${String(chatId || '').trim()}`;
+}
+
+function mergeConfigs(base, override) {
+  if (!override) return base;
+  return {
+    ...base,
+    ...override,
+    modules: {
+      ...asObject(base.modules),
+      ...asObject(override.modules),
+    },
+  };
+}
+
+function resolveBehaviorConfig(userId, agentId, { platform = null, chatId = null, isGroup = false } = {}) {
+  const storedValue = readSettingRow(userId, agentId);
+  const stored = parseStoredValue(storedValue);
+  let effective = normalizeLeafConfig(stored, cloneDefaults());
+  let participationModeSource = storedValue == null ? 'default' : 'agent';
+  const platformKey = String(platform || '').trim();
+  if (platformKey && stored.platformOverrides?.[platformKey]) {
+    effective = mergeConfigs(effective, stored.platformOverrides[platformKey]);
+    if (Object.prototype.hasOwnProperty.call(stored.platformOverrides[platformKey], 'participationMode')) {
+      participationModeSource = 'platform';
+    }
+  }
+  if (isGroup && platformKey && chatId) {
+    const key = roomConfigKey(platformKey, chatId);
+    if (stored.roomOverrides?.[key]) {
+      effective = mergeConfigs(effective, stored.roomOverrides[key]);
+      if (Object.prototype.hasOwnProperty.call(stored.roomOverrides[key], 'participationMode')) {
+        participationModeSource = 'room';
+      }
+    }
+  }
+  effective.modules = normalizeModules(effective.modules, effective.enabled !== false);
+  effective.platformOverrides = stored.platformOverrides || {};
+  effective.roomOverrides = stored.roomOverrides || {};
+  effective.participationModeSource = participationModeSource;
+  effective.scope = {
+    platform: platformKey || null,
+    chatId: chatId ? String(chatId) : null,
+    isGroup: Boolean(isGroup),
+    roomKey: isGroup && platformKey && chatId ? roomConfigKey(platformKey, chatId) : null,
+  };
+  return effective;
+}
+
+function isModuleEnabled(config, moduleId) {
+  if (!config || config.enabled === false) return false;
+  const entry = config.modules?.[moduleId];
+  if (!entry) return false;
+  return entry.enabled !== false;
+}
+
+module.exports = {
+  SETTINGS_KEY,
+  getBehaviorConfig,
+  setBehaviorConfig,
+  resolveBehaviorConfig,
+  normalizeStoredConfig,
+  roomConfigKey,
+  isModuleEnabled,
+};

package/server/services/behavior/defaults.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const MODULE_IDS = Object.freeze([
+  'turn_taking',
+  'social_memory',
+  'norms',
+  'persona',
+  'agent_identity',
+  'channel_style',
+  'theory_of_mind',
+  'social_signals',
+  'social_observability',
+  'delivery',
+]);
+
+const DEFAULT_MODULE_CONFIG = Object.freeze({
+  schemaVersion: 1,
+  enabled: true,
+  participationMode: 'automatic',
+  minimumNeedScore: 0.72,
+  batchWindowMs: 900,
+  decisionContextMessageLimit: 12,
+  decisionModelId: null,
+  decisionModelPurpose: 'general',
+  deliveryStyle: 'natural_bubbles',
+  maxBubbles: 4,
+  bubbleGapMs: 650,
+  normsRefreshMessageGap: 18,
+  observabilityIntervalMinutes: 360,
+});
+
+function cloneDefaults() {
+  return {
+    schemaVersion: DEFAULT_MODULE_CONFIG.schemaVersion,
+    enabled: DEFAULT_MODULE_CONFIG.enabled,
+    modules: {
+      turn_taking: { enabled: true },
+      social_memory: { enabled: true },
+      norms: { enabled: true },
+      persona: { enabled: true },
+      agent_identity: { enabled: true },
+      channel_style: { enabled: true },
+      theory_of_mind: { enabled: true },
+      social_signals: { enabled: true },
+      social_observability: { enabled: true },
+      delivery: { enabled: true },
+    },
+    participationMode: DEFAULT_MODULE_CONFIG.participationMode,
+    minimumNeedScore: DEFAULT_MODULE_CONFIG.minimumNeedScore,
+    batchWindowMs: DEFAULT_MODULE_CONFIG.batchWindowMs,
+    decisionContextMessageLimit: DEFAULT_MODULE_CONFIG.decisionContextMessageLimit,
+    decisionModelId: DEFAULT_MODULE_CONFIG.decisionModelId,
+    decisionModelPurpose: DEFAULT_MODULE_CONFIG.decisionModelPurpose,
+    deliveryStyle: DEFAULT_MODULE_CONFIG.deliveryStyle,
+    maxBubbles: DEFAULT_MODULE_CONFIG.maxBubbles,
+    bubbleGapMs: DEFAULT_MODULE_CONFIG.bubbleGapMs,
+    normsRefreshMessageGap: DEFAULT_MODULE_CONFIG.normsRefreshMessageGap,
+    observabilityIntervalMinutes: DEFAULT_MODULE_CONFIG.observabilityIntervalMinutes,
+    platformOverrides: {},
+    roomOverrides: {},
+  };
+}
+
+module.exports = {
+  MODULE_IDS,
+  DEFAULT_MODULE_CONFIG,
+  cloneDefaults,
+};

package/server/services/behavior/delivery.js

@@ -0,0 +1,176 @@
+'use strict';
+
+const {
+  splitOutgoingMessageForPlatform,
+  normalizeOutgoingMessageForPlatform,
+} = require('../messaging/formatting_guides');
+
+function sleep(ms, signal = null) {
+  const delay = Math.max(0, Number(ms) || 0);
+  if (!delay) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, delay);
+    const onAbort = () => {
+      cleanup();
+      const error = new Error('Delivery aborted.');
+      error.name = 'AbortError';
+      reject(error);
+    };
+    const cleanup = () => {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort', onAbort);
+    };
+    if (signal) {
+      if (signal.aborted) {
+        cleanup();
+        const error = new Error('Delivery aborted.');
+        error.name = 'AbortError';
+        reject(error);
+        return;
+      }
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+  });
+}
+
+function splitIntoNaturalBubbles(platform, content, { maxBubbles = 4 } = {}) {
+  const normalized = normalizeOutgoingMessageForPlatform(platform, content, {
+    stripNoResponseMarker: false,
+  });
+  if (!normalized) return [];
+  if (normalized.toUpperCase() === '[NO RESPONSE]') return [normalized];
+
+  const paragraphChunks = splitOutgoingMessageForPlatform(platform, normalized);
+  const bubbles = [];
+  for (const chunk of paragraphChunks) {
+    const bubble = String(chunk).trim();
+    if (bubble) bubbles.push(bubble);
+  }
+
+  const limited = [];
+  for (const bubble of bubbles) {
+    if (!bubble) continue;
+    if (limited.length < maxBubbles) {
+      limited.push(bubble);
+    } else {
+      limited[limited.length - 1] = `${limited[limited.length - 1]} ${bubble}`.trim();
+    }
+  }
+  return limited.length ? limited : [normalized];
+}
+
+async function deliverSocialReply({
+  messagingManager,
+  userId,
+  agentId,
+  platform,
+  chatId,
+  content,
+  config,
+  runId = null,
+  signal = null,
+  mediaPath = null,
+  turnEpoch = null,
+  beforeBubble = null,
+}) {
+  const style = config?.deliveryStyle === 'single' ? 'single' : 'natural_bubbles';
+  if (style === 'single' || mediaPath) {
+    if (beforeBubble && !(await beforeBubble(0))) {
+      return { success: false, suppressed: true, reason: 'stale_turn', turnEpoch };
+    }
+    return messagingManager.sendMessage(userId, platform, chatId, content, {
+      agentId,
+      runId,
+      mediaPath,
+      signal,
+      deliveryKind: 'final',
+      idempotencyKey: runId ? `${runId}:social:0` : undefined,
+    });
+  }
+
+  const bubbles = splitIntoNaturalBubbles(platform, content, {
+    maxBubbles: config?.maxBubbles ?? 4,
+  });
+  if (bubbles.length <= 1) {
+    if (beforeBubble && !(await beforeBubble(0))) {
+      return { success: false, suppressed: true, reason: 'stale_turn', turnEpoch };
+    }
+    return messagingManager.sendMessage(userId, platform, chatId, bubbles[0] || content, {
+      agentId,
+      runId,
+      signal,
+      deliveryKind: 'final',
+      idempotencyKey: runId ? `${runId}:social:0` : undefined,
+    });
+  }
+
+  try {
+    let lastResult = null;
+    for (let index = 0; index < bubbles.length; index += 1) {
+      if (signal?.aborted) {
+        const error = new Error('Delivery aborted.');
+        error.name = 'AbortError';
+        throw error;
+      }
+      if (index > 0) {
+        await sleep(config?.bubbleGapMs ?? 650, signal);
+      }
+      if (beforeBubble && !(await beforeBubble(index))) {
+        return {
+          success: false,
+          suppressed: true,
+          reason: 'stale_turn',
+          turnEpoch,
+          deliveredBubbles: index,
+        };
+      }
+      try {
+        await messagingManager.sendTyping?.(userId, platform, chatId, true, { agentId, runId, signal });
+      } catch {
+        // typing is best-effort
+      }
+      lastResult = await messagingManager.sendMessage(userId, platform, chatId, bubbles[index], {
+        agentId,
+        runId,
+        signal,
+        idempotencyKey: runId ? `${runId}:social:${index}` : undefined,
+        deliveryKind: index === bubbles.length - 1 ? 'final' : 'partial',
+        metadata: {
+          socialDelivery: true,
+          bubbleIndex: index,
+          bubbleCount: bubbles.length,
+        },
+      });
+      if (lastResult?.success === false || lastResult?.suppressed === true) {
+        return {
+          success: false,
+          error: lastResult?.error || lastResult?.reason || 'Messaging platform rejected delivery.',
+          result: lastResult,
+          deliveredBubbles: index,
+        };
+      }
+    }
+    return {
+      success: true,
+      bubbled: true,
+      bubbleCount: bubbles.length,
+      result: lastResult,
+    };
+  } finally {
+    try {
+      await messagingManager.sendTyping?.(userId, platform, chatId, false, { agentId, runId, signal });
+    } catch {
+      // typing is best-effort
+    }
+  }
+}
+
+module.exports = {
+  id: 'delivery',
+  deliver: deliverSocialReply,
+  splitIntoNaturalBubbles,
+  deliverSocialReply,
+};

package/server/services/behavior/index.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const {
+  getBehaviorConfig,
+  setBehaviorConfig,
+  resolveBehaviorConfig,
+  normalizeStoredConfig,
+  roomConfigKey,
+  isModuleEnabled,
+  SETTINGS_KEY,
+} = require('./config');
+const { MODULE_IDS, cloneDefaults, DEFAULT_MODULE_CONFIG } = require('./defaults');
+const { createBehaviorPipeline } = require('./pipeline');
+const {
+  getThreadState,
+  setThreadState,
+  isTurnCurrent,
+  markSpoke,
+} = require('./state');
+const { createBehaviorRegistry, LIFECYCLE_STAGES } = require('./registry');
+const { splitIntoNaturalBubbles, deliverSocialReply } = require('./delivery');
+
+module.exports = {
+  MODULE_IDS,
+  DEFAULT_MODULE_CONFIG,
+  SETTINGS_KEY,
+  cloneDefaults,
+  getBehaviorConfig,
+  setBehaviorConfig,
+  resolveBehaviorConfig,
+  normalizeStoredConfig,
+  roomConfigKey,
+  isModuleEnabled,
+  createBehaviorPipeline,
+  createBehaviorRegistry,
+  LIFECYCLE_STAGES,
+  getThreadState,
+  setThreadState,
+  isTurnCurrent,
+  markSpoke,
+  splitIntoNaturalBubbles,
+  deliverSocialReply,
+};

package/server/services/behavior/model_client.js

@@ -0,0 +1,35 @@
+'use strict';
+
+async function requestStructuredJson({
+  agentEngine,
+  userId,
+  agentId,
+  modelId = null,
+  purpose = 'fast',
+  system,
+  prompt,
+  signal = null,
+  maxTokens = 220,
+  fallback = {},
+}) {
+  if (!agentEngine || typeof agentEngine.inferStructured !== 'function') {
+    const error = new Error('Behavior inference requires the central AI engine.');
+    error.code = 'BEHAVIOR_ENGINE_UNAVAILABLE';
+    throw error;
+  }
+  return agentEngine.inferStructured({
+    userId,
+    agentId,
+    modelId,
+    purpose,
+    system,
+    prompt,
+    maxTokens,
+    fallback,
+    signal,
+  });
+}
+
+module.exports = {
+  requestStructuredJson,
+};

package/server/services/behavior/modules/agent_identity.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const db = require('../../../db/database');
+const { buildAgentRosterPrompt } = require('../../agents/manager');
+const { isModuleEnabled } = require('../config');
+
+function clamp(text, maxChars) {
+  const value = String(text || '').trim();
+  if (!value || value.length <= maxChars) return value;
+  return `${value.slice(0, maxChars)}\n...[trimmed]`;
+}
+
+function buildSystemPromptContribution(ctx) {
+  if (!ctx.agentId || !isModuleEnabled(ctx.config, 'agent_identity')) return '';
+  const agent = db.prepare(
+    `SELECT display_name, slug, description, responsibilities, instructions
+     FROM agents
+     WHERE user_id = ? AND id = ?`,
+  ).get(ctx.userId, ctx.agentId);
+  if (!agent) return '';
+  const active = [
+    '## Active Agent',
+    `Name: ${agent.display_name} (${agent.slug})`,
+    agent.description ? `Description: ${clamp(agent.description, 600)}` : '',
+    agent.responsibilities ? `Responsibilities: ${clamp(agent.responsibilities, 1000)}` : '',
+    agent.instructions ? `Agent instructions: ${clamp(agent.instructions, 1600)}` : '',
+  ].filter(Boolean).join('\n');
+  const roster = ctx.triggerSource === 'agent_delegation'
+    ? ''
+    : buildAgentRosterPrompt(ctx.userId, ctx.agentId);
+  return [active, roster].filter(Boolean).join('\n\n');
+}
+
+module.exports = {
+  id: 'agent_identity',
+  composeSystemPrompt: buildSystemPromptContribution,
+};

package/server/services/behavior/modules/channel_style.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const { isModuleEnabled } = require('../config');
+
+function buildSystemPromptContribution(ctx) {
+  if (!isModuleEnabled(ctx.config, 'channel_style')) return '';
+  if (ctx.widgetId) {
+    return 'CHANNEL RESPONSE GUIDE: Widget refreshes should produce structured snapshot data, not conversational filler.';
+  }
+  if (ctx.triggerSource === 'voice_live' || ctx.latencyProfile === 'voice') {
+    return 'CHANNEL RESPONSE GUIDE: Voice replies should usually fit in one or two concise spoken sentences unless detail is necessary.';
+  }
+  if (ctx.triggerSource === 'messaging' && ctx.audience === 'shared') {
+    return 'CHANNEL RESPONSE GUIDE: The turn-taking gate already decided this shared room needs a response. Make one brief, natural contribution, address the relevant participant or room rather than the owner, and do not dominate or send progress chatter.';
+  }
+  if (ctx.triggerSource === 'messaging') {
+    return 'CHANNEL RESPONSE GUIDE: Text like a natural contact. Prefer one concise reply, or a few short bubbles when the thought genuinely benefits from separate beats. A blank line marks an intentional bubble break, so do not add one mechanically. Keep dense information and lists together, and expand only when the task needs detail.';
+  }
+  if (ctx.triggerSource === 'wearable') {
+    return 'CHANNEL RESPONSE GUIDE: Wearable replies should be one or two short sentences with the result first.';
+  }
+  return 'CHANNEL RESPONSE GUIDE: Web chat may use short paragraphs and compact lists. Avoid padding and lead with the result.';
+}
+
+module.exports = {
+  id: 'channel_style',
+  composeSystemPrompt: buildSystemPromptContribution,
+};

package/server/services/behavior/modules/index.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const turnTaking = require('./turn_taking');
+const socialMemory = require('./social_memory');
+const norms = require('./norms');
+const persona = require('./persona');
+const agentIdentity = require('./agent_identity');
+const channelStyle = require('./channel_style');
+const theoryOfMind = require('./theory_of_mind');
+const socialSignals = require('./social_signals');
+const socialObservability = require('./social_observability');
+const delivery = require('../delivery');
+
+const BEHAVIOR_MODULES = Object.freeze([
+  turnTaking,
+  socialMemory,
+  norms,
+  persona,
+  agentIdentity,
+  channelStyle,
+  theoryOfMind,
+  socialSignals,
+  socialObservability,
+  delivery,
+]);
+
+module.exports = {
+  BEHAVIOR_MODULES,
+};