@swarmclawai/swarmclaw 1.2.3 → 1.2.5

package/src/lib/server/execution-brief.test.ts

@@ -0,0 +1,167 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+
+import { buildExecutionBrief, buildExecutionBriefContextBlock, serializeExecutionBriefForDelegation } from './execution-brief'
+import type { Mission, Session, SessionWorkingState } from '@/types'
+
+test('buildExecutionBrief prefers working state and folds in mission and run-context fallback data', () => {
+  const session = {
+    id: 's1',
+    name: 'Main Session',
+    cwd: '/tmp/project',
+    user: 'tester',
+    provider: 'openai',
+    model: 'gpt-test',
+    claudeSessionId: null,
+    messages: [],
+    createdAt: 1,
+    lastActiveAt: 1,
+    runContext: {
+      objective: 'Fallback objective',
+      constraints: ['Do not change the API'],
+      keyFacts: ['The build already passes locally.'],
+      discoveries: ['The failing path is only used in staging.'],
+      failedApproaches: ['Restarting the worker did not help.'],
+      currentPlan: ['Fallback step'],
+      completedSteps: [],
+      blockers: ['Waiting on staging credentials.'],
+      parentContext: 'Parent asked for a contained fix.',
+      updatedAt: 1,
+      version: 1,
+    },
+  } satisfies Partial<Session> as Session
+
+  const mission = {
+    id: 'm1',
+    source: 'chat',
+    objective: 'Ship the release fix',
+    status: 'active',
+    phase: 'executing',
+    currentStep: 'Verify staging auth',
+    successCriteria: ['Restore staging deploys'],
+    waitState: {
+      kind: 'approval',
+      reason: 'Waiting for deploy approval.',
+    },
+    createdAt: 1,
+    updatedAt: 1,
+  } satisfies Partial<Mission> as Mission
+
+  const workingState = {
+    sessionId: 's1',
+    missionId: 'm1',
+    objective: 'Ship the release fix safely',
+    summary: 'Auth mismatch isolated to staging.',
+    constraints: ['Do not change the API'],
+    successCriteria: ['Restore staging deploys'],
+    status: 'progress',
+    nextAction: 'Request deploy approval',
+    planSteps: [
+      { id: 'p1', text: 'Request deploy approval', status: 'active', createdAt: 1, updatedAt: 1 },
+      { id: 'p2', text: 'Roll staging credentials', status: 'resolved', createdAt: 1, updatedAt: 1 },
+    ],
+    confirmedFacts: [
+      { id: 'f1', statement: 'Auth mismatch isolated to staging.', source: 'tool', status: 'active', createdAt: 1, updatedAt: 1 },
+    ],
+    artifacts: [
+      { id: 'a1', label: 'deploy.log', kind: 'file', path: '/tmp/project/deploy.log', status: 'active', createdAt: 1, updatedAt: 1 },
+    ],
+    decisions: [],
+    blockers: [
+      { id: 'b1', summary: 'Deploy approval is pending.', kind: 'approval', nextAction: 'Request deploy approval', status: 'active', createdAt: 1, updatedAt: 1 },
+    ],
+    openQuestions: [],
+    hypotheses: [],
+    evidenceRefs: [
+      { id: 'e1', type: 'tool', summary: 'Checked deploy logs', value: '403 from staging auth', sessionId: 's1', createdAt: 1 },
+    ],
+    createdAt: 1,
+    updatedAt: 1,
+  } satisfies SessionWorkingState
+
+  const brief = buildExecutionBrief({ session, mission, workingState })
+
+  assert.equal(brief.objective, 'Ship the release fix safely')
+  assert.equal(brief.summary, 'Auth mismatch isolated to staging.')
+  assert.equal(brief.status, 'progress')
+  assert.equal(brief.nextAction, 'Request deploy approval')
+  assert.equal(brief.plan[0]?.text, 'Request deploy approval')
+  assert.equal(brief.blockers[0], 'Deploy approval is pending. | next: Request deploy approval')
+  assert.ok(brief.blockers.some((entry) => /waiting for deploy approval/i.test(entry)))
+  assert.ok(brief.facts.some((entry) => /auth mismatch isolated to staging/i.test(entry)))
+  assert.ok(brief.artifacts.some((entry) => /deploy\.log/i.test(entry)))
+  assert.equal(brief.parentContext, 'Parent asked for a contained fix.')
+  assert.equal(brief.missionPhase, 'executing')
+})
+
+test('buildExecutionBriefContextBlock renders a single canonical state block', () => {
+  const brief = buildExecutionBrief({
+    session: {
+      id: 's2',
+      name: 'Session',
+      cwd: '/tmp',
+      user: 'tester',
+      provider: 'openai',
+      model: 'gpt-test',
+      claudeSessionId: null,
+      messages: [],
+      createdAt: 1,
+      lastActiveAt: 1,
+    } satisfies Partial<Session> as Session,
+    workingState: {
+      sessionId: 's2',
+      objective: 'Finish the rollout',
+      summary: 'Everything is ready except final verification.',
+      constraints: ['No schema changes'],
+      successCriteria: ['Verify production traffic'],
+      status: 'progress',
+      nextAction: 'Run the final smoke test',
+      planSteps: [{ id: 'p1', text: 'Run the final smoke test', status: 'active', createdAt: 1, updatedAt: 1 }],
+      confirmedFacts: [{ id: 'f1', statement: 'Staging already passed.', source: 'tool', status: 'active', createdAt: 1, updatedAt: 1 }],
+      artifacts: [],
+      decisions: [],
+      blockers: [],
+      openQuestions: [],
+      hypotheses: [],
+      evidenceRefs: [],
+      createdAt: 1,
+      updatedAt: 1,
+    },
+  })
+
+  const block = buildExecutionBriefContextBlock(brief)
+  assert.match(block, /## Execution Brief/)
+  assert.match(block, /Objective: Finish the rollout/)
+  assert.match(block, /Next action: Run the final smoke test/)
+  assert.match(block, /Staging already passed\./)
+})
+
+test('serializeExecutionBriefForDelegation creates a bounded handoff summary', () => {
+  const text = serializeExecutionBriefForDelegation({
+    sessionId: 's3',
+    missionId: 'm3',
+    objective: 'Repair the deployment pipeline',
+    summary: 'The regression is isolated to the release job.',
+    status: 'blocked',
+    nextAction: 'Fix the release job',
+    plan: [
+      { text: 'Fix the release job', status: 'active' },
+      { text: 'Verify deploy output', status: 'resolved' },
+    ],
+    blockers: ['Approval required before production deploy.'],
+    facts: ['The build already passes locally.'],
+    artifacts: ['/tmp/project/release.log'],
+    constraints: ['Keep the current release shape.'],
+    successCriteria: ['Production deploy completes'],
+    missionStatus: 'active',
+    missionPhase: 'executing',
+    waitState: null,
+    evidenceRefs: [],
+    parentContext: 'Parent is waiting on a concise status update.',
+  })
+
+  assert.ok(text)
+  assert.match(String(text), /Objective: Repair the deployment pipeline/)
+  assert.match(String(text), /Blockers: Approval required before production deploy\./)
+  assert.match(String(text), /Parent context: Parent is waiting on a concise status update\./)
+})

package/src/lib/server/execution-brief.ts

@@ -0,0 +1,295 @@
+import type {
+  EvidenceRef,
+  ExecutionBrief,
+  ExecutionBriefPlanStep,
+  Mission,
+  Session,
+  SessionWorkingState,
+  WorkingPlanStep,
+  WorkingStateItemStatus,
+  WorkingStateStatus,
+} from '@/types'
+import { getSession } from '@/lib/server/sessions/session-repository'
+import { loadSessionWorkingState } from '@/lib/server/working-state/service'
+import { ensureRunContext } from '@/lib/server/run-context'
+import { cleanText, cleanMultiline } from '@/lib/server/text-normalization'
+
+const MAX_PLAN_ITEMS = 8
+const MAX_FACTS = 8
+const MAX_BLOCKERS = 6
+const MAX_ARTIFACTS = 6
+const MAX_EVIDENCE = 6
+const MAX_DELEGATION_PLAN_ITEMS = 4
+const MAX_DELEGATION_FACTS = 4
+const MAX_DELEGATION_BLOCKERS = 4
+const MAX_DELEGATION_ARTIFACTS = 4
+const DELEGATION_BUDGET = 1_200
+
+function uniqueStrings(values: Array<unknown>, maxItems: number, maxChars = 240): string[] {
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const value of values) {
+    const normalized = cleanText(value, maxChars)
+    if (!normalized) continue
+    const key = normalized.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(normalized)
+    if (out.length >= maxItems) break
+  }
+  return out
+}
+
+function summarizeArtifact(value: unknown): string {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return ''
+  const artifact = value as Record<string, unknown>
+  return cleanText(artifact.path || artifact.url || artifact.label, 220)
+}
+
+function summarizeEvidenceRef(ref: EvidenceRef): string {
+  const summary = cleanText(ref.summary, 180)
+  if (!summary) return ''
+  const value = cleanText(ref.value, 140)
+  return value ? `[${ref.type}] ${summary}: ${value}` : `[${ref.type}] ${summary}`
+}
+
+function planStatus(step: WorkingPlanStep): WorkingStateItemStatus {
+  return step.status === 'resolved' || step.status === 'superseded' ? step.status : 'active'
+}
+
+function dedupePlan(steps: ExecutionBriefPlanStep[]): ExecutionBriefPlanStep[] {
+  const out: ExecutionBriefPlanStep[] = []
+  const seen = new Set<string>()
+  for (const step of steps) {
+    const text = cleanText(step.text, 240)
+    if (!text) continue
+    const key = text.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push({
+      text,
+      status: step.status === 'resolved' || step.status === 'superseded' ? step.status : 'active',
+    })
+    if (out.length >= MAX_PLAN_ITEMS) break
+  }
+  return out
+}
+
+function inferStatus(mission: Mission | null | undefined, workingState: SessionWorkingState | null): WorkingStateStatus {
+  if (workingState?.status) return workingState.status
+  if (!mission) return 'idle'
+  if (mission.status === 'completed') return 'completed'
+  if (mission.status === 'waiting') return 'waiting'
+  if (mission.status === 'failed' || mission.phase === 'failed') return 'blocked'
+  if (mission.waitState) return 'waiting'
+  if (mission.phase === 'executing' || mission.phase === 'dispatching' || mission.phase === 'verifying') return 'progress'
+  return 'idle'
+}
+
+function buildPlan(workingState: SessionWorkingState | null, session: Session | null): ExecutionBriefPlanStep[] {
+  if (workingState && Array.isArray(workingState.planSteps) && workingState.planSteps.length > 0) {
+    return dedupePlan(
+      workingState.planSteps
+        .filter((step) => step.status !== 'superseded')
+        .map((step) => ({
+          text: cleanText(step.text, 240),
+          status: planStatus(step),
+        })),
+    )
+  }
+  const runContext = session?.runContext ? ensureRunContext(session.runContext) : null
+  if (!runContext || !Array.isArray(runContext.currentPlan) || runContext.currentPlan.length === 0) return []
+  const completed = new Set((runContext.completedSteps || []).map((value) => cleanText(value, 240).toLowerCase()).filter(Boolean))
+  return dedupePlan(
+    runContext.currentPlan.map((step) => {
+      const text = cleanText(step, 240)
+      return {
+        text,
+        status: completed.has(text.toLowerCase()) ? 'resolved' : 'active',
+      }
+    }),
+  )
+}
+
+function buildFacts(workingState: SessionWorkingState | null, session: Session | null): string[] {
+  const activeFacts = workingState
+    ? workingState.confirmedFacts
+      .filter((fact) => fact.status === 'active')
+      .map((fact) => fact.statement)
+    : []
+  const runContextFacts = session?.runContext ? ensureRunContext(session.runContext).keyFacts : []
+  return uniqueStrings([...activeFacts, ...runContextFacts], MAX_FACTS, 240)
+}
+
+function buildBlockers(workingState: SessionWorkingState | null, mission: Mission | null | undefined, session: Session | null): string[] {
+  const activeBlockers = workingState
+    ? workingState.blockers
+      .filter((blocker) => blocker.status === 'active')
+      .map((blocker) => blocker.nextAction ? `${blocker.summary} | next: ${blocker.nextAction}` : blocker.summary)
+    : []
+  const missionBlockers = mission?.waitState?.reason ? [cleanText(mission.waitState.reason, 280)] : []
+  const runContextBlockers = session?.runContext ? ensureRunContext(session.runContext).blockers : []
+  return uniqueStrings([...activeBlockers, ...missionBlockers, ...runContextBlockers], MAX_BLOCKERS, 280)
+}
+
+function buildArtifacts(workingState: SessionWorkingState | null): string[] {
+  const artifacts = workingState
+    ? workingState.artifacts
+      .filter((artifact) => artifact.status === 'active')
+      .map((artifact) => summarizeArtifact(artifact))
+    : []
+  return uniqueStrings(artifacts, MAX_ARTIFACTS, 220)
+}
+
+function buildConstraints(workingState: SessionWorkingState | null, session: Session | null): string[] {
+  const workingConstraints = workingState?.constraints || []
+  const runContext = session?.runContext ? ensureRunContext(session.runContext) : null
+  return uniqueStrings([...(workingConstraints || []), ...(runContext?.constraints || [])], 10, 220)
+}
+
+function buildSuccessCriteria(workingState: SessionWorkingState | null, mission: Mission | null | undefined): string[] {
+  return uniqueStrings([...(workingState?.successCriteria || []), ...(mission?.successCriteria || [])], 10, 220)
+}
+
+function buildEvidenceRefs(workingState: SessionWorkingState | null): EvidenceRef[] {
+  if (!workingState || !Array.isArray(workingState.evidenceRefs) || workingState.evidenceRefs.length === 0) return []
+  return [...workingState.evidenceRefs]
+    .filter((ref) => Boolean(cleanText(ref.summary, 180)))
+    .slice(-MAX_EVIDENCE)
+}
+
+export function buildExecutionBrief(params: {
+  sessionId?: string | null
+  session?: Session | null
+  mission?: Mission | null
+  workingState?: SessionWorkingState | null
+}): ExecutionBrief {
+  const session = params.session
+    || (params.sessionId ? getSession(params.sessionId) || null : null)
+  const mission = params.mission || null
+  const workingState = params.workingState
+    || (session?.id ? loadSessionWorkingState(session.id, { mission }) : null)
+  const runContext = session?.runContext ? ensureRunContext(session.runContext) : null
+  const plan = buildPlan(workingState, session)
+  const nextAction = cleanText(
+    workingState?.nextAction
+      || mission?.currentStep
+      || plan.find((step) => step.status === 'active')?.text,
+    240,
+  ) || null
+
+  return {
+    sessionId: session?.id || params.sessionId || null,
+    missionId: mission?.id || workingState?.missionId || null,
+    objective: cleanMultiline(
+      workingState?.objective
+        || mission?.objective
+        || runContext?.objective,
+      900,
+    ) || null,
+    summary: cleanMultiline(
+      workingState?.summary
+        || mission?.verifierSummary
+        || mission?.plannerSummary,
+      700,
+    ) || null,
+    status: inferStatus(mission, workingState),
+    nextAction,
+    plan,
+    blockers: buildBlockers(workingState, mission, session),
+    facts: buildFacts(workingState, session),
+    artifacts: buildArtifacts(workingState),
+    constraints: buildConstraints(workingState, session),
+    successCriteria: buildSuccessCriteria(workingState, mission),
+    missionStatus: mission?.status || null,
+    missionPhase: mission?.phase || null,
+    waitState: mission?.waitState || null,
+    evidenceRefs: buildEvidenceRefs(workingState),
+    parentContext: cleanMultiline(runContext?.parentContext, 900) || null,
+  }
+}
+
+function buildListSection(title: string, values: string[]): string | null {
+  if (!values.length) return null
+  return [title, ...values.map((value) => `- ${value}`)].join('\n')
+}
+
+function formatPlan(plan: ExecutionBriefPlanStep[]): string | null {
+  if (!plan.length) return null
+  return [
+    'Plan',
+    ...plan.map((step) => `- [${step.status === 'resolved' ? 'x' : ' '}] ${step.text}`),
+  ].join('\n')
+}
+
+export function buildExecutionBriefContextBlock(
+  brief: ExecutionBrief | null | undefined,
+  options?: { title?: string },
+): string {
+  if (!brief) return ''
+  const hasContent = Boolean(
+    brief.parentContext
+    || brief.objective
+    || brief.summary
+    || brief.nextAction
+    || brief.plan.length > 0
+    || brief.blockers.length > 0
+    || brief.facts.length > 0
+    || brief.artifacts.length > 0
+    || brief.constraints.length > 0
+    || brief.successCriteria.length > 0
+    || brief.evidenceRefs.length > 0
+    || brief.missionStatus
+    || brief.missionPhase
+    || brief.waitState?.reason,
+  )
+  if (!hasContent && brief.status === 'idle') return ''
+  const sections = [
+    options?.title || '## Execution Brief',
+    brief.parentContext ? `Parent context:\n${brief.parentContext}` : '',
+    brief.objective ? `Objective: ${brief.objective}` : '',
+    brief.summary ? `Summary: ${brief.summary}` : '',
+    `Status: ${brief.status}`,
+    brief.missionStatus ? `Mission status: ${brief.missionStatus}` : '',
+    brief.missionPhase ? `Mission phase: ${brief.missionPhase}` : '',
+    brief.waitState?.reason ? `Waiting reason: ${cleanText(brief.waitState.reason, 280)}` : '',
+    brief.nextAction ? `Next action: ${brief.nextAction}` : '',
+    brief.successCriteria.length > 0 ? `Success criteria: ${brief.successCriteria.join(' | ')}` : '',
+    brief.constraints.length > 0 ? `Constraints: ${brief.constraints.join(' | ')}` : '',
+    formatPlan(brief.plan),
+    buildListSection('Blockers', brief.blockers),
+    buildListSection('Facts', brief.facts),
+    buildListSection('Artifacts', brief.artifacts),
+    buildListSection('Evidence', brief.evidenceRefs.map((ref) => summarizeEvidenceRef(ref)).filter(Boolean)),
+    'Trust this execution brief before reconstructing state from the raw transcript or older assistant text.',
+  ].filter(Boolean)
+  return sections.join('\n')
+}
+
+export function serializeExecutionBriefForDelegation(
+  brief: ExecutionBrief | null | undefined,
+): string | null {
+  if (!brief) return null
+  const parts: string[] = []
+  let budget = DELEGATION_BUDGET
+
+  const append = (line: string): void => {
+    if (!line) return
+    if (budget - line.length - 1 < 0) return
+    parts.push(line)
+    budget -= line.length + 1
+  }
+
+  append(brief.objective ? `Objective: ${brief.objective}` : '')
+  append(brief.summary ? `Summary: ${cleanText(brief.summary, 280)}` : '')
+  append(`Status: ${brief.status}`)
+  append(brief.nextAction ? `Next action: ${brief.nextAction}` : '')
+  append(brief.successCriteria.length > 0 ? `Success criteria: ${brief.successCriteria.slice(0, 4).join('; ')}` : '')
+  append(brief.constraints.length > 0 ? `Constraints: ${brief.constraints.slice(0, 4).join('; ')}` : '')
+  append(brief.plan.length > 0 ? `Plan: ${brief.plan.slice(0, MAX_DELEGATION_PLAN_ITEMS).map((step) => step.text).join('; ')}` : '')
+  append(brief.blockers.length > 0 ? `Blockers: ${brief.blockers.slice(0, MAX_DELEGATION_BLOCKERS).join('; ')}` : '')
+  append(brief.facts.length > 0 ? `Facts: ${brief.facts.slice(0, MAX_DELEGATION_FACTS).join('; ')}` : '')
+  append(brief.artifacts.length > 0 ? `Artifacts: ${brief.artifacts.slice(0, MAX_DELEGATION_ARTIFACTS).join('; ')}` : '')
+  append(brief.parentContext ? `Parent context: ${cleanText(brief.parentContext, 280)}` : '')
+  return parts.length > 0 ? parts.join('\n') : null
+}

package/src/lib/server/execution-engine/chat-turn.ts

@@ -0,0 +1,9 @@
+import { executeSessionChatTurn } from '@/lib/server/chat-execution/chat-execution'
+import type {
+  ExecuteChatTurnInput,
+  ExecuteChatTurnResult,
+} from '@/lib/server/chat-execution/chat-execution-types'
+
+export function executeExecutionChatTurn(input: ExecuteChatTurnInput): Promise<ExecuteChatTurnResult> {
+  return executeSessionChatTurn(input)
+}

package/src/lib/server/execution-engine/import-boundary.test.ts

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import path from 'node:path'
+import { describe, it } from 'node:test'
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../../..')
+const srcRoot = path.join(repoRoot, 'src')
+
+const ALLOWED_IMPORTERS = new Set([
+  path.join(srcRoot, 'lib/server/chat-execution/chat-execution.ts'),
+  path.join(srcRoot, 'lib/server/execution-engine/chat-turn.ts'),
+])
+
+function walk(dir: string): string[] {
+  const results: string[] = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      results.push(...walk(fullPath))
+      continue
+    }
+    if (!/\.(?:ts|tsx|js|mjs)$/.test(entry.name)) continue
+    if (entry.name.includes('.test.')) continue
+    results.push(fullPath)
+  }
+  return results
+}
+
+describe('executeSessionChatTurn import boundary', () => {
+  it('is only imported through the execution-engine chat-turn wrapper', () => {
+    const offenders: string[] = []
+    const importPattern = /import\s*\{[^}]*\bexecuteSessionChatTurn\b[^}]*\}\s*from\s*['"][^'"]+['"]/m
+
+    for (const filePath of walk(srcRoot)) {
+      if (ALLOWED_IMPORTERS.has(filePath)) continue
+      const contents = fs.readFileSync(filePath, 'utf8')
+      if (importPattern.test(contents)) {
+        offenders.push(path.relative(repoRoot, filePath))
+      }
+    }
+
+    assert.deepEqual(offenders, [])
+  })
+})

package/src/lib/server/execution-engine/index.ts

@@ -0,0 +1,35 @@
+import { enqueueSessionRun } from '@/lib/server/runtime/session-run-manager'
+import type { ExecuteChatTurnResult } from '@/lib/server/chat-execution/chat-execution-types'
+import type {
+  EnqueueExecutionRequest,
+  ExecutionHandle,
+} from '@/lib/server/execution-engine/types'
+import { enqueueTaskAttemptExecution } from '@/lib/server/execution-engine/task-attempt'
+
+export function enqueueExecution(
+  input: EnqueueExecutionRequest,
+): ExecutionHandle<ExecuteChatTurnResult> {
+  if (input.kind === 'session_turn') {
+    const result = enqueueSessionRun(input.input)
+    return {
+      executionId: result.runId,
+      promise: result.promise,
+      abort: result.abort,
+      position: result.position,
+      deduped: result.deduped,
+      coalesced: result.coalesced,
+      unsubscribe: result.unsubscribe,
+    }
+  }
+
+  return enqueueTaskAttemptExecution(input)
+}
+
+export { executeExecutionChatTurn } from '@/lib/server/execution-engine/chat-turn'
+export type {
+  EnqueueExecutionRequest,
+  EnqueueTaskAttemptExecutionRequest,
+  EnqueueSessionTurnExecutionRequest,
+  ExecutionHandle,
+  ExecutionResult,
+} from '@/lib/server/execution-engine/types'