neoagent 3.2.1-beta.10 → 3.2.1-beta.12

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

@@ -0,0 +1,237 @@
+'use strict';
+
+const { requestStructuredJson } = require('../model_client');
+const { buildDecisionPacket, loadRecentRoomMessages } = require('../signals');
+const { getThreadState, setThreadState } = require('../state');
+const { isModuleEnabled } = require('../config');
+
+const SYSTEM_PROMPT = `You are NeoAgent's group turn-taking gate.
+Decide whether the agent should speak now or stay silent in a multi-party chat.
+Default posture in groups: prefer holding back. Speak only when the agent would add clear value, is addressed, can usefully answer an open need, should correct a harmful misunderstanding, or media/context clearly calls for a response.
+Judge the meaning and flow of the provided room context. Do not use phrase matching or keyword rules.
+Return JSON only with keys:
+decision ("speak" or "stay_silent"),
+needScore (0-1 number measuring how worthwhile an agent contribution is now),
+confidence (0-1 number),
+reasonCodes (array of short snake_case strings),
+urgency ("low"|"medium"|"high"),
+rationale (one short sentence).`;
+
+function normalizeDecision(raw, fallback) {
+  const decision = String(raw?.decision || fallback.decision || 'stay_silent').trim().toLowerCase();
+  const score = (value, fallbackValue) => {
+    const number = Number(value);
+    const normalized = Number.isFinite(number) ? number : Number(fallbackValue);
+    return Math.max(0, Math.min(1, Number.isFinite(normalized) ? normalized : 0.5));
+  };
+  const normalized = {
+    decision: decision === 'speak' ? 'speak' : 'stay_silent',
+    needScore: score(raw?.needScore, fallback.needScore),
+    confidence: score(raw?.confidence, fallback.confidence),
+    reasonCodes: Array.isArray(raw?.reasonCodes)
+      ? raw.reasonCodes.map((item) => String(item || '').trim()).filter(Boolean).slice(0, 8)
+      : (fallback.reasonCodes || []),
+    urgency: ['low', 'medium', 'high'].includes(String(raw?.urgency || ''))
+      ? String(raw.urgency)
+      : (fallback.urgency || 'low'),
+    rationale: String(raw?.rationale || fallback.rationale || '').trim().slice(0, 240),
+    tokenPath: fallback.tokenPath || 'gate_only',
+    model: raw?.model || fallback.model || null,
+  };
+  const usage = Number(raw?.usage ?? fallback.usage);
+  if (Number.isFinite(usage)) normalized.usage = usage;
+  return normalized;
+}
+
+function localFallbackDecision(packet, config) {
+  if (!packet.chat.isGroup) {
+    return normalizeDecision({
+      decision: 'speak',
+      needScore: 1,
+      confidence: 1,
+      reasonCodes: ['direct_chat'],
+      urgency: 'medium',
+      rationale: 'Direct chats always engage.',
+    }, { tokenPath: 'gate_skip' });
+  }
+
+  if (packet.event.wasMentioned || packet.event.repliedToAgent) {
+    return normalizeDecision({
+      decision: 'speak',
+      needScore: 1,
+      confidence: 0.85,
+      reasonCodes: [packet.event.repliedToAgent ? 'reply_to_agent' : 'addressed'],
+      urgency: 'medium',
+      rationale: 'Fallback engaged because platform metadata directly addresses the agent.',
+    }, { tokenPath: 'gate_fallback' });
+  }
+  return normalizeDecision({
+    decision: 'stay_silent',
+    needScore: 0,
+    confidence: 0.7,
+    reasonCodes: ['prefer_hold_back', 'model_unavailable'],
+    urgency: 'low',
+    rationale: 'Fallback gate holds back in groups when address is unclear.',
+  }, { tokenPath: 'gate_fallback' });
+}
+
+async function shouldEngage(ctx) {
+  const startedAt = Date.now();
+  const {
+    userId,
+    agentId,
+    msg,
+    config,
+    signal = null,
+    memoryHints = [],
+    agentEngine,
+    turnEpoch,
+  } = ctx;
+
+  if (!msg?.isGroup || !isModuleEnabled(config, 'turn_taking') || config.enabled === false) {
+    return {
+      decision: 'speak',
+      needScore: 1,
+      confidence: 1,
+      reasonCodes: msg?.isGroup ? ['turn_taking_disabled'] : ['direct_chat'],
+      urgency: 'medium',
+      rationale: msg?.isGroup ? 'Turn-taking disabled; engaging.' : 'Direct chat always engages.',
+      tokenPath: 'gate_skip',
+      latencyMs: Date.now() - startedAt,
+      turnEpoch,
+    };
+  }
+
+  const mode = config.participationMode || 'automatic';
+  if (mode === 'always') {
+    return {
+      decision: 'speak',
+      needScore: 1,
+      confidence: 1,
+      reasonCodes: ['participation_always'],
+      urgency: 'medium',
+      rationale: 'Room participation is configured to always engage.',
+      tokenPath: 'gate_skip',
+      latencyMs: Date.now() - startedAt,
+      turnEpoch,
+    };
+  }
+  if (mode === 'mention_only' && !msg.wasMentioned && !msg.repliedToAgent) {
+    return {
+      decision: 'stay_silent',
+      needScore: 0,
+      confidence: 1,
+      reasonCodes: ['mention_only'],
+      urgency: 'low',
+      rationale: 'Room participation requires a structural mention or reply.',
+      tokenPath: 'gate_skip',
+      latencyMs: Date.now() - startedAt,
+      turnEpoch,
+    };
+  }
+  if (mode === 'mention_only') {
+    return {
+      decision: 'speak',
+      needScore: 1,
+      confidence: 1,
+      reasonCodes: [msg.repliedToAgent ? 'reply_to_agent' : 'addressed'],
+      urgency: 'medium',
+      rationale: 'The room is mention-only and platform metadata directly addressed the agent.',
+      tokenPath: 'gate_skip',
+      latencyMs: Date.now() - startedAt,
+      turnEpoch,
+    };
+  }
+
+  const threadState = getThreadState(userId, agentId, msg.platform, msg.chatId);
+  const roomMessages = loadRecentRoomMessages({
+    userId,
+    agentId,
+    platform: msg.platform,
+    chatId: msg.chatId,
+    limit: config.decisionContextMessageLimit,
+  });
+  const packet = buildDecisionPacket({
+    msg,
+    config,
+    threadState,
+    roomMessages,
+    localMemoryHints: memoryHints,
+  });
+
+  let decision;
+  try {
+    const result = await requestStructuredJson({
+      agentEngine,
+      userId,
+      agentId,
+      modelId: config.decisionModelId,
+      purpose: config.decisionModelPurpose,
+      system: SYSTEM_PROMPT,
+      prompt: JSON.stringify(packet),
+      signal,
+      maxTokens: 220,
+      fallback: {
+        decision: 'stay_silent',
+        needScore: 0,
+        confidence: 0.55,
+        reasonCodes: ['parse_fallback'],
+        urgency: 'low',
+        rationale: 'The decision could not be parsed.',
+      },
+    });
+    decision = normalizeDecision(result.parsed || {}, {
+      decision: 'stay_silent',
+      needScore: 0,
+      confidence: 0.55,
+      reasonCodes: ['parse_fallback'],
+      urgency: 'low',
+      rationale: 'Could not parse gate response; holding back.',
+      tokenPath: 'gate_only',
+      model: result.modelSelectionId || result.model,
+    });
+    decision.model = result.modelSelectionId || result.model;
+    decision.usage = Number(result.usage || 0);
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    decision = localFallbackDecision(packet, config);
+    decision.failureCode = 'model_unavailable';
+  }
+
+  // Confidence measures certainty. Need score measures whether speaking is worthwhile.
+  if (
+    decision.decision === 'speak'
+    && Number(decision.needScore || 0) < Number(config.minimumNeedScore ?? 0.72)
+    && !packet.event.wasMentioned
+    && !packet.event.repliedToAgent
+  ) {
+    decision = normalizeDecision({
+      ...decision,
+      decision: 'stay_silent',
+      reasonCodes: [...(decision.reasonCodes || []), 'below_need_threshold'],
+      rationale: decision.rationale || 'The contribution value is below the room threshold.',
+    }, { tokenPath: decision.tokenPath || 'gate_only', model: decision.model });
+  }
+
+  setThreadState(userId, agentId, msg.platform, msg.chatId, {
+    lastDecision: decision.decision,
+    lastDecisionAt: new Date().toISOString(),
+    recentSilenceCount: decision.decision === 'stay_silent'
+      ? Number(threadState.recentSilenceCount || 0) + 1
+      : 0,
+  });
+
+  return {
+    ...decision,
+    latencyMs: Date.now() - startedAt,
+    turnEpoch,
+  };
+}
+
+module.exports = {
+  id: 'turn_taking',
+  decide: shouldEngage,
+  shouldEngage,
+  normalizeDecision,
+  localFallbackDecision,
+};

package/server/services/behavior/pipeline.js

@@ -0,0 +1,324 @@
+'use strict';
+
+const { resolveBehaviorConfig, isModuleEnabled } = require('./config');
+const {
+  bumpTurnEpoch,
+  getThreadState,
+  isTurnCurrent,
+  markSpoke,
+} = require('./state');
+const { createBehaviorRegistry } = require('./registry');
+const { BEHAVIOR_MODULES } = require('./modules');
+const { createServiceLogger } = require('../../utils/logger');
+
+const logger = createServiceLogger('Behavior');
+
+function createBehaviorPipeline(deps = {}) {
+  const memoryManager = deps.memoryManager || null;
+  const agentEngine = deps.agentEngine || null;
+  const io = deps.io || null;
+  const registry = createBehaviorRegistry(BEHAVIOR_MODULES);
+
+  function effectiveConfig(userId, agentId, msg) {
+    const config = resolveBehaviorConfig(userId, agentId, {
+      platform: msg.platform,
+      chatId: msg.chatId,
+      isGroup: Boolean(msg.isGroup),
+    });
+    if (
+      msg.isGroup
+      && config.participationModeSource === 'default'
+      && msg.accessPolicyRequireMention === true
+    ) {
+      config.participationMode = 'mention_only';
+    }
+    return config;
+  }
+
+  function noteInbound({ userId, agentId, msg }) {
+    const state = bumpTurnEpoch(userId, agentId, msg.platform, msg.chatId);
+    msg.behaviorTurnEpoch = state.turnEpoch;
+    return state.turnEpoch;
+  }
+
+  function scheduleBackground(baseCtx) {
+    const task = async (backgroundSignal) => {
+      const ctx = { ...baseCtx, signal: backgroundSignal };
+      await registry.run('afterTurn', ctx);
+    };
+    const key = [
+      'social-background',
+      baseCtx.userId,
+      baseCtx.agentId || 'main',
+      baseCtx.msg.platform,
+      baseCtx.msg.chatId,
+    ].join(':');
+    const promise = agentEngine?.trackBackgroundTask
+      ? agentEngine.trackBackgroundTask(task, { key, coalesce: true, signal: baseCtx.signal })
+      : Promise.resolve().then(() => task(baseCtx.signal));
+    promise.catch((error) => {
+      if (!baseCtx.signal?.aborted) logger.warn('background analysis failed:', error?.message || error);
+    });
+  }
+
+  async function handleInbound({ userId, agentId, msg, signal = null }) {
+    const config = effectiveConfig(userId, agentId, msg);
+    const turnEpoch = Number(msg.behaviorTurnEpoch)
+      || noteInbound({ userId, agentId, msg });
+    if (config.enabled === false) {
+      return {
+        engage: true,
+        decision: {
+          decision: 'speak',
+          needScore: 1,
+          confidence: 1,
+          reasonCodes: ['behavior_disabled'],
+          urgency: 'medium',
+          rationale: 'Behavior modules are disabled; using the standard response path.',
+          tokenPath: 'gate_skip',
+          latencyMs: 0,
+          turnEpoch,
+        },
+        config,
+        promptBlocks: [],
+        observeResult: null,
+      };
+    }
+
+    const baseCtx = {
+      userId,
+      agentId,
+      msg,
+      config,
+      signal,
+      memoryManager,
+      agentEngine,
+      turnEpoch,
+      isModuleEnabled: (moduleId) => isModuleEnabled(config, moduleId),
+    };
+
+    const observations = await registry.run('observe', baseCtx);
+    const observeResult = observations.find((item) => item.moduleId === 'social_memory')?.value || null;
+    if (msg.isGroup) scheduleBackground(baseCtx);
+
+    const memoryHints = [];
+    if (observeResult?.scopeId) memoryHints.push(`channel:${observeResult.scopeId}`);
+
+    let decision;
+    if (!isModuleEnabled(config, 'turn_taking')) {
+      decision = {
+        decision: 'speak',
+        needScore: 1,
+        confidence: 1,
+        reasonCodes: ['turn_taking_disabled'],
+        urgency: 'medium',
+        rationale: 'Turn-taking is disabled; using the standard response path.',
+        tokenPath: 'gate_skip',
+        latencyMs: 0,
+        turnEpoch,
+      };
+    } else {
+      decision = (await registry.run('decide', {
+        ...baseCtx,
+        memoryHints,
+      })).find((item) => item.moduleId === 'turn_taking')?.value;
+    }
+    if (!decision) {
+      throw new Error('The turn-taking module did not return a decision.');
+    }
+
+    if (io && userId) {
+      io.to(`user:${userId}`).emit('behavior:decision', {
+        platform: msg.platform,
+        chatId: msg.chatId,
+        agentId,
+        isGroup: Boolean(msg.isGroup),
+        decision: decision.decision,
+        confidence: decision.confidence,
+        needScore: decision.needScore,
+        reasonCodes: decision.reasonCodes || [],
+        urgency: decision.urgency,
+        rationale: decision.rationale || '',
+        tokenPath: decision.tokenPath || 'gate_only',
+        turnEpoch: decision.turnEpoch,
+        model: decision.model || null,
+        at: new Date().toISOString(),
+      });
+    }
+
+    if (decision.decision !== 'speak') {
+      return {
+        engage: false,
+        decision,
+        config,
+        promptBlocks: [],
+        observeResult,
+      };
+    }
+
+    const promptBlocks = await registry.composeContext(baseCtx);
+
+    return {
+      engage: true,
+      decision,
+      config,
+      promptBlocks,
+      observeResult,
+    };
+  }
+
+  async function refineAndMaybeDeliver({
+    userId,
+    agentId,
+    msg,
+    config,
+    draft,
+    messagingManager,
+    runId = null,
+    signal = null,
+    mediaPath = null,
+    deliver = false,
+    turnEpoch = null,
+  }) {
+    const expectedEpoch = Number(turnEpoch || msg.behaviorTurnEpoch || 0);
+    if (msg.isGroup && !isTurnCurrent(
+      userId,
+      agentId,
+      msg.platform,
+      msg.chatId,
+      expectedEpoch,
+    )) {
+      return {
+        action: 'suppress',
+        content: '[NO RESPONSE]',
+        delivered: false,
+        suppressed: true,
+        reasonCodes: ['stale_turn'],
+      };
+    }
+    const combinedGroupReview = msg.isGroup
+      && isModuleEnabled(config, 'persona')
+      && isModuleEnabled(config, 'theory_of_mind');
+    const persona = combinedGroupReview
+      ? {
+        action: 'send',
+        content: draft,
+        reasonCodes: ['persona_refine_combined_with_tom'],
+      }
+      : await registry.get('persona').refineDraft({
+        userId,
+        agentId,
+        msg,
+        config,
+        draft,
+        signal,
+        agentEngine,
+        runId,
+      });
+    const tom = await registry.get('theory_of_mind').refineDraft({
+      userId,
+      agentId,
+      msg,
+      config,
+      draft: persona.content,
+      signal,
+      agentEngine,
+      runId,
+    });
+
+    const content = tom.content;
+    const reasonCodes = [
+      ...(persona.reasonCodes || []),
+      ...(tom.reasonCodes || []),
+    ];
+    if (!deliver || !messagingManager) {
+      return {
+        ...tom,
+        delivered: false,
+        content,
+        reasonCodes,
+        personaAction: persona.action,
+      };
+    }
+
+    if (!content || content.toUpperCase() === '[NO RESPONSE]') {
+      return {
+        ...tom,
+        delivered: false,
+        suppressed: true,
+        content,
+        reasonCodes,
+        personaAction: persona.action,
+      };
+    }
+
+    const deliveryConfig = isModuleEnabled(config, 'delivery')
+      ? config
+      : { ...config, deliveryStyle: 'single' };
+    const delivery = await registry.get('delivery').deliver({
+      messagingManager,
+      userId,
+      agentId,
+      platform: msg.platform,
+      chatId: msg.chatId,
+      content,
+      config: deliveryConfig,
+      runId,
+      signal,
+      mediaPath,
+      turnEpoch: expectedEpoch,
+      beforeBubble: () => !msg.isGroup || isTurnCurrent(
+        userId,
+        agentId,
+        msg.platform,
+        msg.chatId,
+        expectedEpoch,
+      ),
+    });
+
+    if (
+      (delivery?.success !== false && delivery?.suppressed !== true)
+      || Number(delivery?.deliveredBubbles || 0) > 0
+    ) {
+      markSpoke(userId, agentId, msg.platform, msg.chatId);
+    }
+
+    return {
+      ...tom,
+      delivered: delivery?.success !== false && delivery?.suppressed !== true,
+      suppressed: delivery?.suppressed === true,
+      delivery,
+      content,
+      reasonCodes,
+      personaAction: persona.action,
+    };
+  }
+
+  function getDiagnostics(userId, agentId, platform, chatId) {
+    const config = resolveBehaviorConfig(userId, agentId, {
+      platform,
+      chatId,
+      isGroup: true,
+    });
+    const state = getThreadState(userId, agentId, platform, chatId);
+    return {
+      config,
+      state,
+      modules: Object.fromEntries(
+        Object.keys(config.modules || {}).map((id) => [id, isModuleEnabled(config, id)]),
+      ),
+    };
+  }
+
+  return {
+    registry,
+    noteInbound,
+    handleInbound,
+    refineAndMaybeDeliver,
+    getDiagnostics,
+  };
+}
+
+module.exports = {
+  createBehaviorPipeline,
+};

package/server/services/behavior/registry.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const LIFECYCLE_STAGES = Object.freeze([
+  'observe',
+  'decide',
+  'composeContext',
+  'composeSystemPrompt',
+  'refineDraft',
+  'deliver',
+  'afterTurn',
+]);
+
+function createBehaviorRegistry(modules) {
+  const byId = new Map();
+  for (const module of modules) {
+    const id = String(module?.id || '').trim();
+    if (!id) throw new Error('Behavior modules require a stable id.');
+    if (byId.has(id)) throw new Error(`Duplicate behavior module id: ${id}`);
+    byId.set(id, module);
+  }
+
+  function list() {
+    return [...byId.values()];
+  }
+
+  function get(id) {
+    return byId.get(id) || null;
+  }
+
+  async function run(stage, ctx) {
+    if (!LIFECYCLE_STAGES.includes(stage)) {
+      throw new Error(`Unknown behavior lifecycle stage: ${stage}`);
+    }
+    const results = [];
+    for (const module of byId.values()) {
+      if (ctx.isModuleEnabled && !ctx.isModuleEnabled(module.id)) continue;
+      if (typeof module[stage] !== 'function') continue;
+      results.push({ moduleId: module.id, value: await module[stage](ctx) });
+    }
+    return results;
+  }
+
+  async function composeContext(ctx) {
+    const contributions = [];
+    const keys = new Set();
+    for (const { moduleId, value } of await run('composeContext', ctx)) {
+      const entries = Array.isArray(value) ? value : [value];
+      for (const entry of entries) {
+        if (!entry?.content) continue;
+        const key = String(entry.key || moduleId).trim();
+        if (keys.has(key)) {
+          throw new Error(`Duplicate behavior prompt contribution: ${key}`);
+        }
+        keys.add(key);
+        contributions.push({
+          key,
+          priority: Number(entry.priority || 0),
+          content: String(entry.content).trim(),
+        });
+      }
+    }
+    return contributions
+      .sort((left, right) => right.priority - left.priority)
+      .map((entry) => entry.content);
+  }
+
+  return {
+    get,
+    list,
+    run,
+    composeContext,
+  };
+}
+
+module.exports = {
+  LIFECYCLE_STAGES,
+  createBehaviorRegistry,
+};