@swarmclawai/swarmclaw 0.9.2 → 0.9.4

package/src/lib/server/agents/agent-thread-session.ts

@@ -64,7 +64,7 @@ function buildThreadSession(agent: Agent, sessionId: string, user: string, creat
     connectorIdleTimeoutSec: existing?.connectorIdleTimeoutSec || null,
     connectorMaxAgeSec: existing?.connectorMaxAgeSec || null,
     mailbox: existing?.mailbox || null,
-    connectorContext: existing?.connectorContext || undefined,
+    connectorContext: undefined,
     lastAutoMemoryAt: existing?.lastAutoMemoryAt || null,
     lastHeartbeatText: existing?.lastHeartbeatText || null,
     lastHeartbeatSentAt: existing?.lastHeartbeatSentAt || null,

package/src/lib/server/agents/main-agent-loop-advanced.test.ts

@@ -195,6 +195,83 @@ describe('main-agent-loop advanced', () => {
     assert.equal(output.followupOk, null, 'no followup on terminal ack')
   })
 
+  it('persists and upgrades a skill blocker across recommend/install steps', () => {
+    const output = runWithTempDataDir(`
+      ${sessionSetupScript()}
+
+      mainLoop.handleMainLoopRunResult({
+        sessionId: 'main',
+        message: 'Continue the Google Workspace automation.',
+        internal: true,
+        source: 'heartbeat',
+        resultText: 'Blocked: missing capability for Google Workspace CLI in this environment.',
+      })
+      const state1 = mainLoop.getMainLoopStateForSession('main')
+
+      mainLoop.handleMainLoopRunResult({
+        sessionId: 'main',
+        message: 'Continue the Google Workspace automation.',
+        internal: true,
+        source: 'heartbeat',
+        resultText: 'Checked local skills.',
+        toolEvents: [{
+          name: 'manage_skills',
+          input: JSON.stringify({ action: 'recommend_for_task', task: 'Google Workspace automation' }),
+          output: JSON.stringify({ local: [{ name: 'google-workspace', status: 'needs_install' }] }),
+        }],
+      })
+      const state2 = mainLoop.getMainLoopStateForSession('main')
+
+      mainLoop.handleMainLoopRunResult({
+        sessionId: 'main',
+        message: 'Continue the Google Workspace automation.',
+        internal: true,
+        source: 'heartbeat',
+        resultText: 'Install approval requested.',
+        toolEvents: [{
+          name: 'manage_skills',
+          input: JSON.stringify({ action: 'install', name: 'google-workspace' }),
+          output: JSON.stringify({
+            requiresApproval: true,
+            approval: { id: 'appr-123' },
+            skill: { name: 'google-workspace' },
+          }),
+        }],
+      })
+      const state3 = mainLoop.getMainLoopStateForSession('main')
+
+      const heartbeatPrompt = mainLoop.buildMainLoopHeartbeatPrompt({
+        id: 'main',
+        shortcutForAgentId: 'agent-a',
+        agentId: 'agent-a',
+        heartbeatEnabled: true,
+        messages: [{ role: 'user', text: 'Deploy the system.', time: 1 }],
+      }, 'Base prompt')
+
+      console.log(JSON.stringify({
+        firstStatus: state1?.skillBlocker?.status ?? null,
+        firstSummary: state1?.skillBlocker?.summary ?? null,
+        secondStatus: state2?.skillBlocker?.status ?? null,
+        secondCandidates: state2?.skillBlocker?.candidateSkills ?? [],
+        secondAttempts: state2?.skillBlocker?.attempts ?? -1,
+        thirdStatus: state3?.skillBlocker?.status ?? null,
+        thirdApprovalId: state3?.skillBlocker?.approvalId ?? null,
+        promptHasSkillBlocker: heartbeatPrompt.includes('Active skill blocker:'),
+        promptHasApproval: heartbeatPrompt.includes('Pending approval: appr-123'),
+      }))
+    `)
+
+    assert.equal(output.firstStatus, 'new')
+    assert.match(String(output.firstSummary), /missing capability/i)
+    assert.equal(output.secondStatus, 'recommended')
+    assert.deepEqual(output.secondCandidates, ['google-workspace'])
+    assert.equal(output.secondAttempts, 1)
+    assert.equal(output.thirdStatus, 'approval_requested')
+    assert.equal(output.thirdApprovalId, 'appr-123')
+    assert.equal(output.promptHasSkillBlocker, true)
+    assert.equal(output.promptHasApproval, true)
+  })
+
   it('resets metadata miss count when structured metadata returns and keeps terminal acks at zero', () => {
     const meta = heartbeatMetaLine('progress', 'deploy', 'continue')
     const output = runWithTempDataDir(`

package/src/lib/server/agents/main-agent-loop.ts

@@ -44,6 +44,15 @@ export interface MainLoopState {
   followupChainCount: number
   metaMissCount: number
   workingMemoryNotes: string[]
+  skillBlocker: {
+    summary: string
+    query: string | null
+    status: 'new' | 'searched' | 'recommended' | 'approval_requested' | 'installed'
+    attempts: number
+    candidateSkills: string[]
+    approvalId: string | null
+    updatedAt: number
+  } | null
   lastMemoryNoteAt: number | null
   lastPlannedAt: number | null
   lastReviewedAt: number | null
@@ -139,6 +148,7 @@ function defaultState(): MainLoopState {
     followupChainCount: 0,
     metaMissCount: 0,
     workingMemoryNotes: [],
+    skillBlocker: null,
     lastMemoryNoteAt: null,
     lastPlannedAt: null,
     lastReviewedAt: null,
@@ -220,6 +230,42 @@ function normalizeTimeline(value: unknown): MainLoopState['timeline'] {
   return out
 }
 
+function normalizeSkillBlocker(value: unknown): MainLoopState['skillBlocker'] {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  const record = value as Record<string, unknown>
+  const summary = cleanText(record.summary, 240)
+  if (!summary) return null
+  const status = record.status === 'new'
+    || record.status === 'searched'
+    || record.status === 'recommended'
+    || record.status === 'approval_requested'
+    || record.status === 'installed'
+    ? record.status
+    : 'new'
+  const query = cleanText(record.query, 240)
+  const candidateSkills = Array.isArray(record.candidateSkills)
+    ? uniqueStrings(record.candidateSkills.filter((entry): entry is string => typeof entry === 'string'), 6)
+    : []
+  const approvalId = typeof record.approvalId === 'string' && record.approvalId.trim()
+    ? record.approvalId.trim()
+    : null
+  const updatedAt = typeof record.updatedAt === 'number' && Number.isFinite(record.updatedAt)
+    ? Math.trunc(record.updatedAt)
+    : now()
+  const attempts = typeof record.attempts === 'number' && Number.isFinite(record.attempts)
+    ? Math.max(0, Math.min(6, Math.trunc(record.attempts)))
+    : 0
+  return {
+    summary,
+    query,
+    status,
+    attempts,
+    candidateSkills,
+    approvalId,
+    updatedAt,
+  }
+}
+
 function parseHeartbeatMeta(text: string): { goal?: string; status?: MainLoopState['status']; summary?: string; nextAction?: string } | null {
   const match = (text || '').match(HEARTBEAT_META_RE)
   if (!match) return null
@@ -257,6 +303,7 @@ function clampState(state: MainLoopState): MainLoopState {
   state.metaMissCount = Math.max(0, Math.min(100, Math.trunc(state.metaMissCount || 0)))
   state.missionTokens = Math.max(0, Math.trunc(state.missionTokens || 0))
   state.missionCostUsd = Math.max(0, Number.isFinite(state.missionCostUsd) ? Number(state.missionCostUsd) : 0)
+  state.skillBlocker = normalizeSkillBlocker(state.skillBlocker)
   state.updatedAt = typeof state.updatedAt === 'number' && Number.isFinite(state.updatedAt) ? Math.trunc(state.updatedAt) : now()
   return state
 }
@@ -286,6 +333,7 @@ function normalizeState(input?: Partial<MainLoopState> | null): MainLoopState {
     if (typeof input.followupChainCount === 'number') next.followupChainCount = input.followupChainCount
     if (typeof input.metaMissCount === 'number') next.metaMissCount = input.metaMissCount
     if (Array.isArray(input.workingMemoryNotes)) next.workingMemoryNotes = [...input.workingMemoryNotes]
+    if (input.skillBlocker === null || typeof input.skillBlocker === 'object') next.skillBlocker = input.skillBlocker
     if (typeof input.lastMemoryNoteAt === 'number' || input.lastMemoryNoteAt === null) next.lastMemoryNoteAt = input.lastMemoryNoteAt ?? null
     if (typeof input.lastPlannedAt === 'number' || input.lastPlannedAt === null) next.lastPlannedAt = input.lastPlannedAt ?? null
     if (typeof input.lastReviewedAt === 'number' || input.lastReviewedAt === null) next.lastReviewedAt = input.lastReviewedAt ?? null
@@ -404,6 +452,198 @@ function formatGoalContract(goalContract: GoalContract | null): string {
   return lines.join('\n')
 }
 
+function parseJsonRecord(value: string | undefined): Record<string, unknown> | null {
+  if (typeof value !== 'string' || !value.trim()) return null
+  try {
+    const parsed = JSON.parse(value)
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>
+    }
+  } catch {
+    // ignore non-JSON outputs
+  }
+  return null
+}
+
+function summarizeSelectedSkillRuntime(session: MainSessionLike | null): string {
+  const runtimeState = session?.skillRuntimeState
+  if (!runtimeState || typeof runtimeState !== 'object') return ''
+  const state = runtimeState as Record<string, unknown>
+  const selectedSkillName = cleanText(state.selectedSkillName, 160)
+  if (!selectedSkillName) return ''
+  const lines = [`Selected skill: ${selectedSkillName}`]
+  const lastAction = typeof state.lastAction === 'string' ? state.lastAction.trim() : ''
+  const lastRunToolName = cleanText(state.lastRunToolName, 120)
+  if (lastAction) lines.push(`Last skill action: ${lastAction}`)
+  if (lastRunToolName) lines.push(`Last dispatched tool: ${lastRunToolName}`)
+  return lines.join('\n')
+}
+
+function summarizeUseSkillToolEvent(toolEvents: MessageToolEvent[]): string | null {
+  const event = [...toolEvents].reverse().find((entry) => entry.name === 'use_skill')
+  if (!event?.output) return null
+  const output = parseJsonRecord(event.output)
+  if (!output) return null
+  const skill = output.skill && typeof output.skill === 'object'
+    ? output.skill as Record<string, unknown>
+    : null
+  const skillName = typeof skill?.name === 'string' && skill.name.trim()
+    ? skill.name.trim()
+    : typeof output.selectedSkillName === 'string' && output.selectedSkillName.trim()
+      ? output.selectedSkillName.trim()
+      : ''
+  if (!skillName) return null
+  if (output.executed === true) {
+    const toolName = typeof output.dispatchedTool === 'string' ? output.dispatchedTool.trim() : ''
+    return toolName ? `Skill run: ${skillName} via ${toolName}` : `Skill run: ${skillName}`
+  }
+  if (output.loaded === true) return `Loaded skill guidance: ${skillName}`
+  if (output.selected === true) return `Selected skill: ${skillName}`
+  return `Skill context: ${skillName}`
+}
+
+function firstMatchingLine(text: string, pattern: RegExp): string | null {
+  for (const line of (text || '').split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed && pattern.test(trimmed)) return trimmed
+  }
+  return null
+}
+
+function deriveSkillBlockerFromToolEvents(params: {
+  toolEvents: MessageToolEvent[]
+  current: MainLoopState['skillBlocker']
+  query: string | null
+}): MainLoopState['skillBlocker'] {
+  const event = [...params.toolEvents].reverse().find((entry) => entry.name === 'manage_skills')
+  if (!event) return params.current
+  const input = parseJsonRecord(event.input)
+  const output = parseJsonRecord(event.output)
+  const action = typeof input?.action === 'string' ? input.action.trim().toLowerCase() : ''
+  const nowTs = now()
+
+  const candidateNames = (() => {
+    const local = Array.isArray(output?.local)
+      ? output?.local
+      : Array.isArray(output)
+        ? output
+        : []
+    return uniqueStrings(local.flatMap((entry) => {
+      if (!entry || typeof entry !== 'object') return []
+      const record = entry as Record<string, unknown>
+      const nestedSkill = record.skill && typeof record.skill === 'object' ? record.skill as Record<string, unknown> : null
+      const name = typeof record.skillName === 'string'
+        ? record.skillName
+        : typeof record.name === 'string'
+          ? record.name
+          : typeof nestedSkill?.name === 'string'
+            ? nestedSkill.name
+            : ''
+      return name ? [name] : []
+    }), 4)
+  })()
+
+  const installSkillName = (() => {
+    if (typeof output?.skillName === 'string' && output.skillName.trim()) return output.skillName.trim()
+    if (output?.skill && typeof output.skill === 'object') {
+      const nested = output.skill as Record<string, unknown>
+      if (typeof nested.name === 'string' && nested.name.trim()) return nested.name.trim()
+    }
+    if (typeof input?.name === 'string' && input.name.trim()) return input.name.trim()
+    return candidateNames[0] || null
+  })()
+
+  if (action === 'install') {
+    if (output?.ok === true && output.installed === true) {
+      return normalizeSkillBlocker({
+        summary: installSkillName
+          ? `Installed skill "${installSkillName}". Use it on the next step instead of re-discovering skills.`
+          : 'Installed a skill for this blocker. Use it before re-running discovery.',
+        query: params.query,
+        status: 'installed',
+        attempts: (params.current?.attempts || 0) + 1,
+        candidateSkills: installSkillName ? [installSkillName] : candidateNames,
+        approvalId: null,
+        updatedAt: nowTs,
+      })
+    }
+    const approval = output?.approval && typeof output.approval === 'object'
+      ? output.approval as Record<string, unknown>
+      : null
+    const approvalId = typeof approval?.id === 'string' ? approval.id.trim() : ''
+    if (output?.requiresApproval === true || approvalId) {
+      return normalizeSkillBlocker({
+        summary: installSkillName
+          ? `Install approval is pending for skill "${installSkillName}". Wait for the approval instead of retrying discovery.`
+          : 'A skill install approval is pending. Wait for the approval instead of retrying discovery.',
+        query: params.query,
+        status: 'approval_requested',
+        attempts: (params.current?.attempts || 0) + 1,
+        candidateSkills: installSkillName ? [installSkillName] : candidateNames,
+        approvalId: approvalId || params.current?.approvalId || null,
+        updatedAt: nowTs,
+      })
+    }
+  }
+
+  if (action === 'recommend_for_task' || action === 'status' || action === 'search_available') {
+    return normalizeSkillBlocker({
+      summary: candidateNames.length > 0
+        ? `Skill candidates found: ${candidateNames.join(', ')}. Use one of them or request install approval once if needed.`
+        : 'Checked local skills for this blocker. Avoid repeating the same discovery loop without a materially different query.',
+      query: params.query,
+      status: candidateNames.length > 0 ? 'recommended' : 'searched',
+      attempts: (params.current?.attempts || 0) + 1,
+      candidateSkills: candidateNames,
+      approvalId: params.current?.approvalId || null,
+      updatedAt: nowTs,
+    })
+  }
+
+  return params.current
+}
+
+function deriveSkillBlockerFromText(params: {
+  text: string
+  current: MainLoopState['skillBlocker']
+  query: string | null
+}): MainLoopState['skillBlocker'] {
+  const blockerLine = firstMatchingLine(
+    params.text,
+    /\b(missing capability|missing (?:binary|binaries|env|tool|command)|not installed|install required|requires .* cli|requires .* binary)\b/i,
+  )
+  if (!blockerLine) return params.current
+  return normalizeSkillBlocker({
+    summary: blockerLine,
+    query: params.query,
+    status: params.current?.status === 'approval_requested' ? 'approval_requested' : 'new',
+    attempts: params.current?.attempts || 0,
+    candidateSkills: params.current?.candidateSkills || [],
+    approvalId: params.current?.approvalId || null,
+    updatedAt: now(),
+  })
+}
+
+function summarizeSkillBlocker(blocker: MainLoopState['skillBlocker']): string {
+  if (!blocker) return ''
+  const lines = [
+    `Summary: ${blocker.summary}`,
+    blocker.query ? `Current query: ${blocker.query}` : '',
+    blocker.candidateSkills.length > 0 ? `Candidate skills: ${blocker.candidateSkills.join(', ')}` : '',
+    blocker.approvalId ? `Pending approval: ${blocker.approvalId}` : '',
+    blocker.status === 'new'
+      ? 'Next action: use manage_skills once this turn to recommend or inspect a fitting skill for the blocker.'
+      : blocker.status === 'searched'
+        ? 'Next action: do not repeat the same discovery blindly. Either adjust the query materially or proceed with the explicit blocker.'
+        : blocker.status === 'recommended'
+          ? 'Next action: use one recommended skill now, or request one explicit install approval if the best fit is not yet installed.'
+          : blocker.status === 'approval_requested'
+            ? 'Next action: wait for the pending approval instead of repeating discovery or install requests.'
+            : 'Next action: use the installed skill before re-running generic exploration.',
+  ]
+  return lines.filter(Boolean).join('\n')
+}
+
 function extractWaitSignal(text: string, toolEvents: MessageToolEvent[]): boolean {
   const haystack = `${text}\n${toolEvents.map((event) => `${event.name} ${event.input || ''} ${event.output || ''}`).join('\n')}`
   return /\b(wait for|waiting for|approval|human reply|mailbox|watch job|pending approval)\b/i.test(haystack)
@@ -473,6 +713,8 @@ export function buildMainLoopHeartbeatPrompt(session: unknown, fallbackPrompt: s
     state.currentPlanStep ? `Current plan step: ${state.currentPlanStep}` : '',
     planLines ? `Plan:\n${planLines}` : '',
     state.pendingEvents.length > 0 ? `Pending external events:\n${summarizePendingEvents(state.pendingEvents)}` : '',
+    state.skillBlocker ? `Active skill blocker:\n${summarizeSkillBlocker(state.skillBlocker)}` : '',
+    summarizeSelectedSkillRuntime(candidate),
     boundedSummary ? `Latest summary:\n${boundedSummary}` : '',
     boundedFallbackPrompt ? `Base heartbeat instructions:\n${boundedFallbackPrompt}` : '',
     '',
@@ -627,7 +869,24 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
   const cleanedResult = persistedText.trim()
   const waitingForExternal = extractWaitSignal(resultText, toolEvents)
   const gotTerminalAck = /^HEARTBEAT_OK$/i.test(cleanedResult) || /^NO_MESSAGE$/i.test(cleanedResult)
+  const selectedSkillNote = summarizeUseSkillToolEvent(toolEvents)
+  if (selectedSkillNote) appendWorkingMemory(state, selectedSkillNote)
   state.metaMissCount = heartbeat || plan || review || gotTerminalAck ? 0 : state.metaMissCount + 1
+  const skillQuery = cleanText(state.nextAction || input.message || state.goal, 240)
+  let skillBlocker = deriveSkillBlockerFromToolEvents({
+    toolEvents,
+    current: state.skillBlocker,
+    query: skillQuery,
+  })
+  skillBlocker = deriveSkillBlockerFromText({
+    text: `${resultText}\n${toolEvents.map((event) => event.output || '').join('\n')}`,
+    current: skillBlocker,
+    query: skillQuery,
+  })
+  if ((gotTerminalAck && state.status !== 'blocked') || (state.status === 'ok' && !waitingForExternal && !input.error)) {
+    skillBlocker = null
+  }
+  state.skillBlocker = skillBlocker
 
   if (input.internal) {
     state.pendingEvents = []

package/src/lib/server/agents/orchestrator-lg.ts

@@ -11,6 +11,7 @@ import { buildChatModel } from '@/lib/server/build-llm'
 import { getCheckpointSaver } from '@/lib/server/langgraph-checkpoint'
 import { buildCurrentDateTimePromptContext } from '@/lib/server/prompt-runtime-context'
 import { getPluginManager } from '@/lib/server/plugins'
+import { buildRuntimeSkillPromptBlocks, resolveRuntimeSkills } from '@/lib/server/skills/runtime-skill-resolver'
 import { buildBoardTask } from '@/lib/server/tasks/task-lifecycle'
 import '@/lib/server/builtin-plugins'
 import { genId } from '@/lib/id'
@@ -401,6 +402,7 @@ export async function executeLangGraphOrchestrator(
   taskId?: string,
 ): Promise<string> {
   const allAgents = loadAgents()
+  const orchestrationSession = loadSessions()[sessionId]
 
   // Build available agents list
   const agentIds = orchestrator.subAgentIds || []
@@ -461,14 +463,16 @@ export async function executeLangGraphOrchestrator(
   promptParts.push(buildCurrentDateTimePromptContext())
   if (orchestrator.soul) promptParts.push(orchestrator.soul)
   if (orchestrator.systemPrompt) promptParts.push(orchestrator.systemPrompt)
-  // Inject dynamic skills
-  if (orchestrator.skillIds?.length) {
-    const allSkills = loadSkills()
-    for (const skillId of orchestrator.skillIds) {
-      const skill = allSkills[skillId]
-      if (skill?.content) promptParts.push(`## Skill: ${skill.name}\n${skill.content}`)
-    }
-  }
+  try {
+    const runtimeSkills = resolveRuntimeSkills({
+      cwd: orchestrationSession?.cwd || WORKSPACE_DIR,
+      enabledPlugins: Array.isArray(orchestrator.plugins) ? orchestrator.plugins : [],
+      agentSkillIds: orchestrator.skillIds || [],
+      storedSkills: loadSkills(),
+      selectedSkillId: orchestrationSession?.skillRuntimeState?.selectedSkillId || null,
+    })
+    promptParts.push(...buildRuntimeSkillPromptBlocks(runtimeSkills))
+  } catch { /* non-critical */ }
   const basePrompt = promptParts.join('\n\n')
 
   const systemMessage = [

package/src/lib/server/agents/orchestrator.ts

@@ -7,6 +7,7 @@ import { WORKSPACE_DIR } from '@/lib/server/data-dir'
 import { loadRuntimeSettings, getLegacyOrchestratorMaxTurns } from '@/lib/server/runtime/runtime-settings'
 import { getMemoryDb } from '@/lib/server/memory/memory-db'
 import { buildCurrentDateTimePromptContext } from '@/lib/server/prompt-runtime-context'
+import { buildRuntimeSkillPromptBlocks, resolveRuntimeSkills } from '@/lib/server/skills/runtime-skill-resolver'
 import { getProvider } from '@/lib/providers'
 import type { Agent } from '@/types'
 
@@ -125,13 +126,16 @@ async function executeOrchestratorLegacy(
   promptParts.push(buildCurrentDateTimePromptContext())
   if (orchestrator.soul) promptParts.push(orchestrator.soul)
   if (orchestrator.systemPrompt) promptParts.push(orchestrator.systemPrompt)
-  if (orchestrator.skillIds?.length) {
-    const allSkills = loadSkills()
-    for (const skillId of orchestrator.skillIds) {
-      const skill = allSkills[skillId]
-      if (skill?.content) promptParts.push(`## Skill: ${skill.name}\n${skill.content}`)
-    }
-  }
+  try {
+    const runtimeSkills = resolveRuntimeSkills({
+      cwd: session.cwd,
+      enabledPlugins: Array.isArray(orchestrator.plugins) ? orchestrator.plugins : [],
+      agentSkillIds: orchestrator.skillIds || [],
+      storedSkills: loadSkills(),
+      selectedSkillId: session.skillRuntimeState?.selectedSkillId || null,
+    })
+    promptParts.push(...buildRuntimeSkillPromptBlocks(runtimeSkills))
+  } catch { /* non-critical */ }
   const basePrompt = promptParts.join('\n\n')
 
   const systemPrompt = [

package/src/lib/server/chat-execution/chat-execution-advanced.test.ts

@@ -485,26 +485,27 @@ describe('buildToolDisciplineLines advanced', () => {
     assert.ok(lines.some((line) => line.includes('Enabled tools')))
   })
 
-  it('includes schedule guidance when manage_schedules is enabled', () => {
+  it('includes direct platform guidance when manage_schedules is enabled without manage_platform', () => {
     const lines = buildToolDisciplineLines(['manage_schedules'])
-    assert.ok(lines.some((line) => line.includes('reuse or update matching agent-created schedules')))
+    assert.ok(lines.some((line) => line.includes('Use direct platform tools exactly as named (`manage_schedules`)')))
+    assert.ok(lines.some((line) => line.includes('Do not substitute `manage_platform` unless it is explicitly enabled.')))
   })
 
-  it('includes delegate local-first guidance when coding tools and delegate enabled', () => {
+  it('includes local files and shell guidance when coding tools and delegate enabled', () => {
     const lines = buildToolDisciplineLines(['delegate', 'shell', 'files'])
-    assert.ok(lines.some((line) => line.includes('prefer using them directly for straightforward coding')))
+    assert.ok(lines.some((line) => line.includes('{"action":"read","filePath":"path/to/file.md"}')))
+    assert.ok(lines.some((line) => line.includes('For `shell`, use `{"action":"execute","command":"..."}`')))
   })
 
-  it('tells research-capable agents to try another enabled acquisition path before manual fallback', () => {
+  it('tells research-capable agents to try another enabled acquisition path before giving up', () => {
     const lines = buildToolDisciplineLines(['web_search', 'web_fetch', 'http_request', 'shell'])
-    assert.ok(lines.some((line) => line.includes('try one other enabled acquisition path') && line.includes('`shell`') && line.includes('`http_request`')))
+    assert.ok(lines.some((line) => line.includes('If one research path is blocked, try another') && line.includes('`shell`') && line.includes('`http_request`')))
   })
 
-  it('adds direct drafting/file-save/swarm-id guidance when those tools are enabled', () => {
+  it('adds direct email and file action guidance when those tools are enabled', () => {
     const lines = buildToolDisciplineLines(['files', 'email', 'spawn_subagent'])
-    assert.ok(lines.some((line) => line.includes('draft, outline, critique, or revise email copy')))
-    assert.ok(lines.some((line) => line.includes('actual file-writing tool call')))
-    assert.ok(lines.some((line) => line.includes('returned `swarmId`')))
+    assert.ok(lines.some((line) => line.includes('For `email`, send mail with `{"action":"send","to":"user@example.com","subject":"...","body":"..."}`')))
+    assert.ok(lines.some((line) => line.includes('{"action":"write","files":[{"path":"path/to/file.md","content":"..."}]}')))
   })
 })
 

package/src/lib/server/chat-execution/chat-execution-session-sync.test.ts

@@ -84,6 +84,13 @@ test('executeSessionChatTurn syncs updated agent runtime fields onto its thread
     })
 
     const session = ensureAgentThreadSession('molly')
+    const sessionsBefore = storage.loadSessions()
+    sessionsBefore[session.id].connectorContext = {
+      connectorId: 'conn-stale',
+      channelId: 'stale-channel',
+      senderId: 'stale-user',
+    }
+    storage.saveSessions(sessionsBefore)
     const agents = storage.loadAgents()
     agents.molly.provider = 'test-provider'
     agents.molly.model = 'unit'
@@ -93,7 +100,7 @@ test('executeSessionChatTurn syncs updated agent runtime fields onto its thread
     agents.molly.updatedAt = now + 1
     storage.saveAgents(agents)
 
-    const result = await executeSessionChatTurn({
+    await executeSessionChatTurn({
       sessionId: session.id,
       message: 'hello',
       runId: 'run-session-sync',
@@ -101,19 +108,125 @@ test('executeSessionChatTurn syncs updated agent runtime fields onto its thread
 
     const persisted = storage.loadSession(session.id)
     console.log(JSON.stringify({
-      text: result.text || null,
       provider: persisted?.provider || null,
       model: persisted?.model || null,
       plugins: persisted?.plugins || [],
       heartbeatEnabled: persisted?.heartbeatEnabled ?? null,
       heartbeatIntervalSec: persisted?.heartbeatIntervalSec ?? null,
+      connectorContext: persisted?.connectorContext || null,
     }))
   `)
 
-  assert.equal(output.text, 'synced')
   assert.equal(output.provider, 'test-provider')
   assert.equal(output.model, 'unit')
   assert.deepEqual(output.plugins, [])
   assert.equal(output.heartbeatEnabled, true)
   assert.equal(output.heartbeatIntervalSec, 90)
+  assert.equal(output.connectorContext, null)
+})
+
+test('executeSessionChatTurn keeps tool-only heartbeats off the visible main-thread history and clears stale connector state', () => {
+  const output = runWithTempDataDir(`
+    const storageMod = await import('@/lib/server/storage')
+    const providersMod = await import('@/lib/providers/index')
+    const execMod = await import('@/lib/server/chat-execution/chat-execution')
+    const storage = storageMod.default || storageMod['module.exports'] || storageMod
+    const executeSessionChatTurn = execMod.executeSessionChatTurn
+      || execMod.default?.executeSessionChatTurn
+      || execMod['module.exports']?.executeSessionChatTurn
+    const providers = providersMod.PROVIDERS
+      || providersMod.default?.PROVIDERS
+      || providersMod['module.exports']?.PROVIDERS
+
+    providers['test-provider'] = {
+      id: 'test-provider',
+      name: 'Test Provider',
+      models: ['unit'],
+      requiresApiKey: false,
+      requiresEndpoint: false,
+      handler: {
+        async streamChat(opts) {
+          opts.write('data: ' + JSON.stringify({ t: 'r', text: 'Sent the ferry status to WhatsApp.' }) + '\\n')
+          return ''
+        },
+      },
+    }
+
+    const now = Date.now()
+    storage.saveAgents({
+      hal: {
+        id: 'hal',
+        name: 'Hal2k',
+        description: 'Heartbeat hygiene test',
+        provider: 'test-provider',
+        model: 'unit',
+        credentialId: null,
+        apiEndpoint: null,
+        fallbackCredentialIds: [],
+        disabled: false,
+        heartbeatEnabled: true,
+        heartbeatIntervalSec: 60,
+        plugins: [],
+        threadSessionId: 'agent_thread',
+        createdAt: now,
+        updatedAt: now,
+      },
+    })
+    storage.saveSessions({
+      agent_thread: {
+        id: 'agent_thread',
+        name: 'Hal2k',
+        cwd: process.env.WORKSPACE_DIR,
+        user: 'default',
+        provider: 'test-provider',
+        model: 'unit',
+        claudeSessionId: null,
+        codexThreadId: null,
+        opencodeSessionId: null,
+        delegateResumeIds: { claudeCode: null, codex: null, opencode: null, gemini: null },
+        messages: [
+          { role: 'user', text: 'seed user message', time: now - 1000 },
+        ],
+        createdAt: now,
+        lastActiveAt: now,
+        sessionType: 'human',
+        agentId: 'hal',
+        shortcutForAgentId: 'hal',
+        plugins: [],
+        connectorContext: {
+          connectorId: 'conn-stale',
+          channelId: 'wrong-chat',
+          senderId: 'wrong-user',
+        },
+      },
+    })
+
+    await executeSessionChatTurn({
+      sessionId: 'agent_thread',
+      message: 'AGENT_HEARTBEAT_WAKE\\nInternal connector follow-up only',
+      internal: true,
+      source: 'heartbeat-wake',
+      heartbeatConfig: {
+        ackMaxChars: 300,
+        showOk: false,
+        showAlerts: true,
+        target: null,
+        deliveryMode: 'tool_only',
+      },
+      runId: 'run-heartbeat-tool-only',
+    })
+
+    const persisted = storage.loadSession('agent_thread')
+    console.log(JSON.stringify({
+      connectorContext: persisted?.connectorContext || null,
+      messageCount: persisted?.messages?.length || 0,
+      lastMessageText: persisted?.messages?.at(-1)?.text || null,
+      heartbeatKinds: (persisted?.messages || []).filter((entry) => entry.kind === 'heartbeat').length,
+    }))
+  `)
+
+  assert.equal(output.connectorContext, null)
+  assert.equal(output.messageCount, 1)
+  assert.equal(output.lastMessageText, 'seed user message')
+  assert.equal(output.heartbeatKinds, 0)
 })