@lota-sdk/core 0.1.15 → 0.1.17

package/src/runtime/team-consultation-orchestrator.ts

@@ -1,6 +1,6 @@
 import { ConsultTeamArgsSchema, withMessageCreatedAt } from '@lota-sdk/shared'
 import type { ChatMessage, ConsultTeamResultData } from '@lota-sdk/shared'
-import { convertToModelMessages, readUIMessageStream, tool as createTool } from 'ai'
+import { convertToModelMessages, tool as createTool } from 'ai'
 
 import { agentDisplayNames, teamConsultParticipants } from '../config/agent-defaults'
 import { createTimedAbortSignal } from './agent-stream-helpers'
@@ -9,7 +9,6 @@ import type { ReadableUploadMetadataLike } from './chat-attachments'
 import type { RepoSectionName } from './indexed-repositories-policy'
 import { buildTeamConsultationFailureMessage } from './team-consultation-prompts'
 import { extractMessageText } from './workstream-chat-helpers'
-import type { ReasoningProfileName } from './workstream-routing-policy'
 
 export type DefaultRepoSections = RepoSectionName[]
 const TEAM_CONSULTATION_TIMEOUT_MS = 90_000
@@ -33,6 +32,28 @@ function getConsultTeamOutput(output: unknown): ConsultTeamResultData | undefine
   return undefined
 }
 
+function findLastUserMessage(
+  messages: ChatMessage[],
+  predicate: (message: ChatMessage) => boolean,
+): ChatMessage | null {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index]
+    if (predicate(message)) {
+      return message
+    }
+  }
+
+  return null
+}
+
+function selectTeamConsultationContextMessages(messages: ChatMessage[], latestUserMessageId: string): ChatMessage[] {
+  const latestUserMessage =
+    findLastUserMessage(messages, (message) => message.id === latestUserMessageId && message.role === 'user') ??
+    findLastUserMessage(messages, (message) => message.role === 'user')
+
+  return latestUserMessage ? [latestUserMessage] : []
+}
+
 interface ParticipantObserver {
   run<T>(fn: () => T | Promise<T>): Promise<T>
   recordError?: (error: unknown) => void
@@ -44,13 +65,13 @@ export interface TeamConsultationParticipantRunner {
     agentId: string,
     params: {
       task: string
-      reasoningProfile: ReasoningProfileName
       systemWorkspaceDetails?: string
       preSeededMemoriesSection?: string
       retrievedKnowledgeSection?: string
     },
   ): Promise<{
     agent: {
+      generate(params: Record<string, unknown>): Promise<{ text: string }>
       stream(
         params: Record<string, unknown>,
       ): Promise<{
@@ -67,7 +88,6 @@ export interface CreateConsultTeamToolParams {
   latestUserMessageId: string
   availableUploads: ReadableUploadMetadataLike[]
   defaultRepoSectionsByAgent: Record<string, DefaultRepoSections | undefined>
-  reasoningProfile: 'fast' | 'standard' | 'deep'
   systemWorkspaceDetails?: string
   getPreSeededMemoriesSection: (agentId: string) => Promise<string | undefined>
   retrievedKnowledgeSection?: string
@@ -112,23 +132,28 @@ export function createConsultTeamTool(params: CreateConsultTeamToolParams) {
         try {
           const { agent, observer } = await params.participantRunner.buildParticipantAgent(agentId, {
             task,
-            reasoningProfile: params.reasoningProfile,
             systemWorkspaceDetails: params.systemWorkspaceDetails,
             preSeededMemoriesSection: await params.getPreSeededMemoriesSection(agentId),
             retrievedKnowledgeSection: params.retrievedKnowledgeSection,
           })
           const modelMessages = await convertToModelMessages(
             buildModelInputMessagesWithUploadMetadata({
-              messages: params.historyMessages,
+              messages: selectTeamConsultationContextMessages(params.historyMessages, params.latestUserMessageId),
               latestUserMessageId: params.latestUserMessageId,
               uploadMetadataText,
             }),
             { ignoreIncompleteToolCalls: true },
           )
 
-          let result: Awaited<ReturnType<typeof agent.stream>>
+          let result: Awaited<ReturnType<typeof agent.generate>>
           try {
-            result = await observer.run(() => agent.stream({ messages: modelMessages, abortSignal: timedAbort.signal }))
+            result = await observer.run(() =>
+              agent.generate({
+                messages: modelMessages,
+                abortSignal: timedAbort.signal,
+                timeout: TEAM_CONSULTATION_TIMEOUT_MS,
+              }),
+            )
           } catch (error) {
             if (params.abortSignal.aborted || timedAbort.signal.aborted) {
               observer.recordAbort?.(error)
@@ -138,33 +163,21 @@ export function createConsultTeamTool(params: CreateConsultTeamToolParams) {
             throw error
           }
 
-          for await (const message of readUIMessageStream<ChatMessage>({
-            stream: result.toUIMessageStream({
-              generateMessageId: () => Bun.randomUUIDv7(),
-              sendReasoning: true,
-              sendSources: true,
-              sendStart: false,
-              sendFinish: false,
-            }) as ReadableStream<never>,
-            onError: (error) => {
-              params.onReadError?.(agentId, error)
-            },
-          })) {
-            latestMessage = withMessageCreatedAt(message)
-            responses[index] = {
-              agentId,
-              agentName,
-              status: 'running',
-              summary: extractMessageText(latestMessage).trim() || undefined,
-              message: latestMessage,
-            }
-            pushSnapshot()
-          }
-
-          if (!latestMessage) {
+          const responseText = result.text.trim()
+          if (!responseText) {
             throw new Error(`Team participant ${agentId} did not produce a response.`)
           }
 
+          latestMessage = withMessageCreatedAt(
+            {
+              id: Bun.randomUUIDv7(),
+              role: 'assistant',
+              parts: [{ type: 'text', text: responseText }],
+              metadata: { agentId, agentName },
+            } satisfies ChatMessage,
+            Date.now(),
+          )
+
           responses[index] = {
             agentId,
             agentName,

package/src/runtime/team-consultation-prompts.ts

@@ -3,12 +3,21 @@ import { agentDisplayNames, getLeadAgentDisplayName } from '../config/agent-defa
 export function buildTeamConsultationResponseGuard(params: { agentId: string; task: string }) {
   const agentName = agentDisplayNames[params.agentId] ?? params.agentId
   const leadAgentDisplayName = getLeadAgentDisplayName()
+  const mentorConstraint =
+    params.agentId === 'mentor'
+      ? ['- As Mentor, answer as an experienced operator reviewing launch discipline, not as a coach or therapist.']
+      : []
   return [
     '<team-consultation-agent-protocol>',
     `- You are participating in a structured internal team consultation led by ${leadAgentDisplayName}.`,
     `- Your role for this response is ${agentName}.`,
-    '- Use markdown when it helps clarity.',
-    '- Make the recommendation, explain key tradeoffs, and note the next decision.',
+    '- Chief is already coordinating this panel. Do not refer the task back to Chief or tell the user to consult another agent.',
+    '- Answer only from your role-specific perspective for the task below.',
+    '- Do not coach the user, ask follow-up questions, or challenge assumptions in this panel response. Give the recommendation directly.',
+    ...mentorConstraint,
+    '- Return exactly 3 short markdown bullets in this order: recommendation, key risk/tradeoff, next decision.',
+    '- Keep the whole response under 120 words.',
+    '- Do not use headings, code fences, XML, evidence blocks, gap lists, or preamble text.',
     '',
     '<team-consultation-task>',
     params.task.trim(),

package/src/runtime/title-helpers.ts

@@ -1,4 +1,4 @@
-import { compactWhitespace } from '../utils/string'
+import { compactWhitespace, truncateText } from '../utils/string'
 
 const TITLE_WORD_LIMIT = 5
 
@@ -8,9 +8,7 @@ export function limitTitleWords(text: string): string {
 }
 
 export function deriveTitle(text: string): string {
-  const trimmed = compactWhitespace(text)
-  if (trimmed.length <= 60) return trimmed
-  return `${trimmed.slice(0, 57)}...`
+  return truncateText(compactWhitespace(text), 60)
 }
 
 export function normalizeTitle(value: string): string {

package/src/runtime/workstream-chat-helpers.ts

@@ -77,7 +77,7 @@ export function appendPersistedWorkstreamContextToHistoryMessages(
     nextHistoryMessages.push({ role: 'agent', content: `Compacted chat summary:\n${compactionSummary}` })
   }
 
-  if (params.persistedState !== undefined && params.persistedState !== null) {
+  if (params.persistedState !== null && params.persistedState !== undefined) {
     nextHistoryMessages.push({
       role: 'agent',
       content: `Structured workstream state:\n${JSON.stringify(params.persistedState)}`,

package/src/services/adaptive-playbook.service.ts

@@ -0,0 +1,152 @@
+import type { PlaybookVersion, Recommendation } from '@lota-sdk/shared'
+import { PlaybookSchema, PlaybookVersionSchema } from '@lota-sdk/shared'
+
+import { ensureRecordId, recordIdToString } from '../db/record-id'
+import { databaseService } from '../db/service'
+import { TABLES } from '../db/tables'
+
+class AdaptivePlaybookService {
+  async refineFromCycle(params: {
+    playbookId: string
+    runId: string
+    recommendations: Recommendation[]
+    organizationId: string
+  }): Promise<PlaybookVersion> {
+    const playbook = await databaseService.findOne(
+      TABLES.PLAYBOOK,
+      { id: ensureRecordId(params.playbookId, TABLES.PLAYBOOK) },
+      PlaybookSchema,
+    )
+    if (!playbook) {
+      throw new Error(`Playbook not found: ${params.playbookId}`)
+    }
+
+    const currentVersion = await databaseService.findOne(
+      TABLES.PLAYBOOK_VERSION,
+      {
+        id: ensureRecordId(
+          recordIdToString(playbook.currentVersionId, TABLES.PLAYBOOK_VERSION),
+          TABLES.PLAYBOOK_VERSION,
+        ),
+      },
+      PlaybookVersionSchema,
+    )
+
+    const nextVersionNumber = currentVersion ? currentVersion.version + 1 : 1
+    const now = new Date()
+
+    const newVersion = await databaseService.create(
+      TABLES.PLAYBOOK_VERSION,
+      {
+        playbookId: ensureRecordId(params.playbookId, TABLES.PLAYBOOK),
+        version: nextVersionNumber,
+        parentVersionId: playbook.currentVersionId,
+        appliedRecommendations: params.recommendations.map((r) => r.description),
+        status: 'testing',
+        createdAt: now,
+      },
+      PlaybookVersionSchema,
+    )
+
+    await databaseService.update(
+      TABLES.PLAYBOOK,
+      ensureRecordId(params.playbookId, TABLES.PLAYBOOK),
+      {
+        currentVersionId: newVersion.id,
+        previousVersionId: playbook.currentVersionId,
+        cycleCount: playbook.cycleCount + 1,
+      },
+      PlaybookSchema,
+    )
+
+    return newVersion
+  }
+
+  evaluateRegression(params: { currentScore: number; previousScore: number; threshold?: number }): {
+    shouldRollback: boolean
+  } {
+    const threshold = params.threshold ?? 0.9
+    if (params.previousScore === 0) return { shouldRollback: false }
+    return { shouldRollback: params.currentScore < params.previousScore * threshold }
+  }
+
+  async rollback(params: {
+    playbookId: string
+    organizationId: string
+    maxLevels?: number
+  }): Promise<PlaybookVersion | null> {
+    const maxLevels = params.maxLevels ?? 3
+    return this.rollbackRecursive(params.playbookId, params.organizationId, maxLevels)
+  }
+
+  private async rollbackRecursive(
+    playbookId: string,
+    organizationId: string,
+    remainingLevels: number,
+  ): Promise<PlaybookVersion | null> {
+    if (remainingLevels <= 0) return null
+
+    const playbook = await databaseService.findOne(
+      TABLES.PLAYBOOK,
+      { id: ensureRecordId(playbookId, TABLES.PLAYBOOK) },
+      PlaybookSchema,
+    )
+    if (!playbook) return null
+
+    const currentVersion = await databaseService.findOne(
+      TABLES.PLAYBOOK_VERSION,
+      {
+        id: ensureRecordId(
+          recordIdToString(playbook.currentVersionId, TABLES.PLAYBOOK_VERSION),
+          TABLES.PLAYBOOK_VERSION,
+        ),
+      },
+      PlaybookVersionSchema,
+    )
+    if (!currentVersion?.parentVersionId) return null
+
+    // Mark current version as rolled-back
+    await databaseService.update(
+      TABLES.PLAYBOOK_VERSION,
+      ensureRecordId(recordIdToString(currentVersion.id, TABLES.PLAYBOOK_VERSION), TABLES.PLAYBOOK_VERSION),
+      { status: 'rolled-back' },
+      PlaybookVersionSchema,
+    )
+
+    // Restore parent version as active
+    const parentVersion = await databaseService.findOne(
+      TABLES.PLAYBOOK_VERSION,
+      {
+        id: ensureRecordId(
+          recordIdToString(currentVersion.parentVersionId, TABLES.PLAYBOOK_VERSION),
+          TABLES.PLAYBOOK_VERSION,
+        ),
+      },
+      PlaybookVersionSchema,
+    )
+    if (!parentVersion) return null
+
+    await databaseService.update(
+      TABLES.PLAYBOOK_VERSION,
+      ensureRecordId(recordIdToString(parentVersion.id, TABLES.PLAYBOOK_VERSION), TABLES.PLAYBOOK_VERSION),
+      { status: 'active' },
+      PlaybookVersionSchema,
+    )
+
+    await databaseService.update(
+      TABLES.PLAYBOOK,
+      ensureRecordId(playbookId, TABLES.PLAYBOOK),
+      { currentVersionId: parentVersion.id, previousVersionId: parentVersion.parentVersionId },
+      PlaybookSchema,
+    )
+
+    // Check if parent version is also regressed (caller can evaluate and re-invoke)
+    if (parentVersion.qualityScore !== undefined && parentVersion.qualityScore < 0.5) {
+      return this.rollbackRecursive(playbookId, organizationId, remainingLevels - 1)
+    }
+
+    return parentVersion
+  }
+}
+
+export const adaptivePlaybookService = new AdaptivePlaybookService()

package/src/services/agent-executor.service.ts

@@ -0,0 +1,292 @@
+import type {
+  ExecutionMode,
+  OwnershipDispatchContext,
+  PlanArtifactSubmission,
+  PlanNodeResult,
+  PlanNodeSpec,
+  PlanSchemaRegistry,
+  WriteIntent,
+} from '@lota-sdk/shared'
+import { PlanNodeResultSubmissionSchema, WriteIntentSchema } from '@lota-sdk/shared'
+import { stepCountIs, tool } from 'ai'
+import type { ToolLoopAgent, ToolSet } from 'ai'
+
+import { agentRoster, buildAgentTools, createAgent, getAgentRuntimeConfig } from '../config/agent-defaults'
+import { ensureRecordId } from '../db/record-id'
+import { databaseService } from '../db/service'
+import { TABLES } from '../db/tables'
+import {
+  OWNERSHIP_DISPATCH_BLOCKED_TOOL_NAMES,
+  buildOwnershipDispatchContextSection,
+  buildOwnershipDispatchResponseGuard,
+} from '../runtime/agent-runtime-policy'
+import { buildIndexedRepositoriesContext, getPluginService } from '../runtime/plugin-resolution'
+import { nodeWorkspaceService } from './node-workspace.service'
+import type { PlanValidationIssueInput } from './plan-validator.service'
+import { WorkstreamSchema } from './workstream.types'
+import { writeIntentValidatorService } from './write-intent-validator.service'
+
+function applyToolPolicy(tools: ToolSet, nodeSpec: PlanNodeSpec): ToolSet {
+  const blockedToolNames = new Set([...OWNERSHIP_DISPATCH_BLOCKED_TOOL_NAMES, ...nodeSpec.toolPolicy.deny])
+  const allowList = nodeSpec.toolPolicy.allow.length > 0 ? new Set(nodeSpec.toolPolicy.allow) : null
+
+  return Object.fromEntries(
+    Object.entries(tools).filter(
+      ([toolName]) => !blockedToolNames.has(toolName) && (allowList === null || allowList.has(toolName)),
+    ),
+  )
+}
+
+function buildDispatchPrompt(nodeSpec: PlanNodeSpec): string {
+  return [
+    `Execute the execution-plan node "${nodeSpec.label}".`,
+    `Objective: ${nodeSpec.objective}`,
+    `Instructions: ${nodeSpec.instructions}`,
+    'Return the final node result JSON only.',
+  ].join('\n\n')
+}
+
+export function buildWriteIntentDispatchPrompt(nodeSpec: PlanNodeSpec): string {
+  const deliverables = nodeSpec.deliverables
+    .map((d) => `- ${d.name} (${d.kind}${d.required ? ', required' : ''})`)
+    .join('\n')
+  return [
+    `Execute the execution-plan node "${nodeSpec.label}".`,
+    `Objective: ${nodeSpec.objective}`,
+    `Instructions: ${nodeSpec.instructions}`,
+    '',
+    'Produce each deliverable by calling the writeIntent tool:',
+    deliverables,
+    '',
+    'For each, call writeIntent with targetPath matching the deliverable name.',
+    'If writeIntent returns validation_failed, correct the payload and try again.',
+    'When all deliverables are written, end with a brief completion summary.',
+  ].join('\n')
+}
+
+const MAX_SELF_CORRECTION_RETRIES = 3
+
+class AgentExecutorService {
+  validateOwner(agentId: string, nodeId: string): PlanValidationIssueInput[] {
+    if (!agentRoster.includes(agentId)) {
+      return [
+        {
+          severity: 'blocking',
+          code: 'agent_executor_missing',
+          message: `Node "${nodeId}" references unknown agent executor "${agentId}".`,
+          nodeId,
+          detail: { agentId },
+        },
+      ]
+    }
+
+    return []
+  }
+
+  async executeNode(params: {
+    nodeSpec: PlanNodeSpec
+    resolvedInput: Record<string, unknown>
+    inputArtifacts: PlanArtifactSubmission[]
+    context: OwnershipDispatchContext
+    executionMode?: ExecutionMode
+    schemaRegistry?: PlanSchemaRegistry
+  }): Promise<PlanNodeResult> {
+    if (params.nodeSpec.owner.executorType !== 'agent') {
+      throw new Error(`AgentExecutor cannot execute owner type "${params.nodeSpec.owner.executorType}".`)
+    }
+
+    const agentId = params.nodeSpec.owner.ref
+    if (!agentRoster.includes(agentId)) {
+      throw new Error(`Agent executor "${agentId}" is not registered.`)
+    }
+
+    const workstream = await databaseService.findOne(
+      TABLES.WORKSTREAM,
+      { id: ensureRecordId(params.context.workstreamId, TABLES.WORKSTREAM) },
+      WorkstreamSchema,
+    )
+    if (!workstream) {
+      throw new Error(`Workstream ${params.context.workstreamId} not found for dispatched execution.`)
+    }
+
+    const organizationRef = ensureRecordId(params.context.organizationId, TABLES.ORGANIZATION)
+    const workstreamRef = ensureRecordId(params.context.workstreamId, TABLES.WORKSTREAM)
+    const userRefSource = params.context.userId ?? workstream.userId
+    if (!userRefSource) {
+      throw new Error(`Workstream ${params.context.workstreamId} is missing a user context for dispatched execution.`)
+    }
+    const userRef = ensureRecordId(userRefSource, TABLES.USER)
+    const userName = params.context.userName ?? 'User'
+    const getLinearInstallationByOrgId = getPluginService([
+      'linear',
+      'services',
+      'linearService',
+      'getInstallationByOrgId',
+    ])
+    const getGithubInstallationForOrganization = getPluginService([
+      'github',
+      'services',
+      'githubService',
+      'getInstallationForOrganization',
+    ])
+    const [linearInstallation, githubInstallation, indexedRepoContext] = await Promise.all([
+      getLinearInstallationByOrgId ? getLinearInstallationByOrgId(organizationRef) : Promise.resolve(null),
+      getGithubInstallationForOrganization
+        ? getGithubInstallationForOrganization(params.context.organizationId)
+        : Promise.resolve(null),
+      buildIndexedRepositoriesContext(params.context.organizationId),
+    ])
+
+    const mode = params.executionMode ?? 'linear'
+
+    const dispatchMode = workstream.mode === 'group' ? 'fixedWorkstreamMode' : 'direct'
+    const runtimeConfig = getAgentRuntimeConfig({
+      agentId,
+      workstreamMode: workstream.mode,
+      mode: dispatchMode,
+      onboardingActive: false,
+      linearInstalled: Boolean(linearInstallation),
+      additionalInstructionSections: [
+        buildOwnershipDispatchContextSection({
+          node: params.nodeSpec,
+          resolvedInput: params.resolvedInput,
+          inputArtifacts: params.inputArtifacts,
+        }),
+      ],
+      responseGuardSection: buildOwnershipDispatchResponseGuard({ node: params.nodeSpec, executionMode: mode }),
+    }) as Record<string, unknown>
+
+    const rawTools = (await buildAgentTools({
+      agentId,
+      orgId: organizationRef,
+      userId: userRef,
+      userName,
+      workstreamId: workstreamRef,
+      orgIdString: params.context.organizationId,
+      workstreamMode: workstream.mode,
+      mode: dispatchMode,
+      linearInstalled: Boolean(linearInstallation),
+      onboardingActive: false,
+      githubInstalled: Boolean(githubInstallation),
+      provideRepoTool: indexedRepoContext.provideRepoTool,
+      defaultRepoSections: indexedRepoContext.defaultSectionsByAgent[agentId],
+      memoryBlock: '',
+      onAppendMemoryBlock: () => undefined,
+      availableUploads: [],
+      includeExecutionPlanTools: false,
+    })) as ToolSet
+    const tools = applyToolPolicy(rawTools, params.nodeSpec)
+
+    const agentFactory = createAgent[agentId] as ((...args: unknown[]) => unknown) | undefined
+    if (!agentFactory) {
+      throw new Error(`Agent factory "${agentId}" is not registered.`)
+    }
+
+    const maxSteps = typeof runtimeConfig.maxSteps === 'number' ? runtimeConfig.maxSteps : 8
+
+    if (mode === 'linear') {
+      const agent = agentFactory({
+        mode: dispatchMode,
+        tools,
+        extraInstructions:
+          typeof runtimeConfig.extraInstructions === 'string' ? runtimeConfig.extraInstructions : undefined,
+        maxRetries: 1,
+        stopWhen: [stepCountIs(maxSteps)],
+      }) as ToolLoopAgent<never, ToolSet>
+
+      const result = await agent.generate({ prompt: buildDispatchPrompt(params.nodeSpec) })
+      const outputCandidate = PlanNodeResultSubmissionSchema.safeParse(result.output)
+      if (outputCandidate.success) {
+        return outputCandidate.data
+      }
+
+      throw new Error(`Agent executor "${agentId}" returned an invalid node result.`)
+    }
+
+    // --- Graph-lite / Graph-full path ---
+
+    const workspace = nodeWorkspaceService.initialize({
+      nodeSpec: params.nodeSpec,
+      resolvedInput: params.resolvedInput,
+      inputArtifacts: params.inputArtifacts,
+      schemaRegistry: params.schemaRegistry ?? {},
+    })
+
+    const writeIntentTool = tool({
+      description:
+        'Write a validated artifact or structured output field. Call this for each deliverable. If validation fails, correct your payload and try again.',
+      inputSchema: WriteIntentSchema,
+      execute: async (intent: WriteIntent) => {
+        const correctionCount = workspace.sys.correctionCounts.get(intent.targetPath) ?? 0
+
+        const validation = writeIntentValidatorService.validate({
+          intent,
+          nodeSpec: params.nodeSpec,
+          schemaRegistry: workspace.ctx.schemaRegistry,
+          existingDeliverables: workspace.deliverables,
+        })
+
+        if (validation.issues.length > 0) {
+          if (correctionCount >= MAX_SELF_CORRECTION_RETRIES) {
+            throw new Error(
+              `Write validation failed for "${intent.targetPath}" after ${MAX_SELF_CORRECTION_RETRIES} retries: ${validation.issues.map((i) => i.message).join(', ')}`,
+            )
+          }
+          workspace.sys.correctionCounts.set(intent.targetPath, correctionCount + 1)
+          workspace.sys.writeLog.push({
+            targetPath: intent.targetPath,
+            action: intent.action,
+            timestamp: new Date(),
+            result: 'rejected',
+          })
+          return {
+            status: 'validation_failed',
+            error: { targetPath: intent.targetPath, action: intent.action, issues: validation.issues },
+            hint: `Correct and re-emit. Attempt ${correctionCount + 1}/${MAX_SELF_CORRECTION_RETRIES}.`,
+          }
+        }
+
+        nodeWorkspaceService.stageWrite(workspace, intent, 'validated')
+        return { status: 'accepted', message: `Write to "${intent.targetPath}" validated and staged.` }
+      },
+    })
+
+    const graphTools = { ...tools, writeIntent: writeIntentTool }
+
+    const agent = agentFactory({
+      mode: dispatchMode,
+      tools: graphTools,
+      extraInstructions:
+        typeof runtimeConfig.extraInstructions === 'string' ? runtimeConfig.extraInstructions : undefined,
+      maxRetries: 1,
+      stopWhen: [stepCountIs(maxSteps)],
+    }) as ToolLoopAgent<never, ToolSet>
+
+    await agent.generate({ prompt: buildWriteIntentDispatchPrompt(params.nodeSpec) })
+
+    const finalResult = nodeWorkspaceService.finalize(workspace)
+
+    if (!finalResult.isComplete) {
+      const result: PlanNodeResult = {
+        structuredOutput: finalResult.structuredOutput,
+        artifacts: finalResult.artifacts,
+        notes: 'Execution incomplete: missing required deliverables or validation failures.',
+        quality: 'partial',
+      }
+      nodeWorkspaceService.cleanup(workspace)
+      return result
+    }
+
+    const result: PlanNodeResult = {
+      structuredOutput: finalResult.structuredOutput,
+      artifacts: finalResult.artifacts,
+      notes: finalResult.notes,
+      quality: finalResult.quality,
+    }
+
+    nodeWorkspaceService.cleanup(workspace)
+    return result
+  }
+}
+
+export const agentExecutorService = new AgentExecutorService()