@lota-sdk/core 0.1.9 → 0.1.11

package/src/services/workstream-turn-preparation.ts

@@ -140,6 +140,15 @@ export function parsePersistedWorkstreamState(value: unknown): WorkstreamState |
   return parseWorkstreamState(value)
 }
 
+export function stripExecutionPlanFieldsFromWorkstreamState(
+  state: WorkstreamState | null | undefined,
+  hasExecutionPlan: boolean,
+): WorkstreamState | null | undefined {
+  if (!state || !hasExecutionPlan) return state
+
+  return { ...state, currentPlan: null, tasks: [], artifacts: [] }
+}
+
 export async function waitForWorkstreamCompactionIfNeeded(workstreamId: RecordIdRef): Promise<WorkstreamRecord> {
   return await waitForCompactionIfNeeded({
     entityId: recordIdToString(workstreamId, TABLES.WORKSTREAM),
@@ -220,6 +229,7 @@ export interface WorkstreamTurnParams {
   inputMessage: ChatMessage
   persistInputMessage?: boolean
   abortSignal?: AbortSignal
+  streamId?: string
 }
 
 export interface WorkstreamApprovalContinuationParams {
@@ -230,6 +240,7 @@ export interface WorkstreamApprovalContinuationParams {
   userName?: string | null
   approvalMessages: ChatMessage[]
   abortSignal?: AbortSignal
+  streamId?: string
 }
 
 export type WorkstreamRunCoreParams = {
@@ -239,9 +250,11 @@ export type WorkstreamRunCoreParams = {
   userRef: RecordIdRef
   userName?: string | null
   abortSignal?: AbortSignal
+  streamId?: string
 } & (
   | { kind: 'userTurn'; inputMessage: ChatMessage; persistInputMessage?: boolean }
   | { kind: 'approvalContinuation'; approvalMessages: ChatMessage[] }
+  | { kind: 'nativeToolApprovalTurn'; approvalMessages: ChatMessage[] }
 )
 
 export interface PreparedWorkstreamTurn {
@@ -307,7 +320,8 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
 
   let inputMessage: ChatMessage | undefined
   const shouldPersistInputMessage = params.kind === 'userTurn' ? params.persistInputMessage !== false : false
-  const shouldProcessPostRunSideEffects = params.kind === 'approvalContinuation' || shouldPersistInputMessage
+  const shouldProcessPostRunSideEffects =
+    params.kind === 'approvalContinuation' || params.kind === 'nativeToolApprovalTurn' || shouldPersistInputMessage
   if (params.kind === 'userTurn') {
     inputMessage = hydrateMessageFileUrls(withMessageCreatedAt(params.inputMessage))
     if (inputMessage.role !== 'user') {
@@ -326,7 +340,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
     throw new WorkstreamTurnError('A chat run is already active.', 409)
   }
 
-  if (params.kind === 'approvalContinuation') {
+  if (params.kind === 'approvalContinuation' || params.kind === 'nativeToolApprovalTurn') {
     const approvedAssistantMessage = [...params.approvalMessages]
       .reverse()
       .find((m) => m.role === 'assistant' && hasApprovalRespondedParts(m))
@@ -539,11 +553,38 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
     disabled: onboardingActive,
     loadPlan: async () => await executionPlanService.getActivePlanForWorkstream(workstreamRef),
   })
+  const getExecutionPlan = async () => await executionPlanInstructionSectionCache.getPlan()
   const getExecutionPlanInstructionSections = async (): Promise<string[] | undefined> =>
     await executionPlanInstructionSectionCache.getSections()
   const invalidateExecutionPlanInstructionSections = () => {
     executionPlanInstructionSectionCache.invalidate()
   }
+  const getWorkstreamStateSection = async (): Promise<string | undefined> => {
+    const executionPlan = await getExecutionPlan()
+    return contextCompactionRuntime.formatWorkstreamStateForPrompt(
+      stripExecutionPlanFieldsFromWorkstreamState(workstreamState, Boolean(executionPlan)),
+    )
+  }
+  const respondedBy = recordIdToString(userRef, TABLES.USER)
+  if (params.kind === 'approvalContinuation') {
+    const appliedApproval = await executionPlanService.applyApprovalResponseFromMessages({
+      workstreamId: workstreamRef,
+      approvalMessages: params.approvalMessages,
+      respondedBy,
+    })
+    if (appliedApproval) {
+      invalidateExecutionPlanInstructionSections()
+    }
+  } else if (userMessage) {
+    const appliedHumanInput = await executionPlanService.applyHumanInputFromUserMessage({
+      workstreamId: workstreamRef,
+      message: userMessage,
+      respondedBy,
+    })
+    if (appliedHumanInput) {
+      invalidateExecutionPlanInstructionSections()
+    }
+  }
   const preSeededMemoriesByAgent = new Map<string, string | undefined>()
   const getPreSeededMemoriesSection = async (agentId: string): Promise<string | undefined> => {
     if (preSeededMemoriesByAgent.has(agentId)) {
@@ -601,6 +642,9 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
         const serverRunId = Bun.randomUUIDv7()
         const runAbort = createServerRunAbortController(params.abortSignal)
         await workstreamService.setActiveRunId(workstreamRef, serverRunId)
+        if (params.streamId) {
+          await workstreamService.setActiveStreamId(workstreamRef, params.streamId)
+        }
         chatRunRegistry.register(serverRunId, runAbort.controller)
 
         try {
@@ -692,7 +736,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
               preSeededMemoriesSection: await getPreSeededMemoriesSection(resolvedAgentId),
               retrievedKnowledgeSection,
               workstreamMemoryBlock: memoryBlock,
-              workstreamStateSection: contextCompactionRuntime.formatWorkstreamStateForPrompt(workstreamState),
+              workstreamStateSection: await getWorkstreamStateSection(),
               learnedSkillsSection: await getLearnedSkillsSection(resolvedAgentId),
               additionalInstructionSections: mergeInstructionSections(
                 executionPlanInstructionSections,
@@ -839,6 +883,12 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
             )
           }
 
+          // Execution-plan approval continuations mutate plan state and persist the approval message,
+          // but they do not begin a new visible agent turn.
+          if (params.kind === 'approvalContinuation') {
+            return
+          }
+
           const consultSpecialistTool = createTool({
             description: 'Consult one specialist teammate for domain-specific guidance before replying to the user.',
             inputSchema: ConsultSpecialistArgsSchema,
@@ -883,7 +933,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                 preSeededMemoriesSection: await getPreSeededMemoriesSection(agentId),
                 retrievedKnowledgeSection,
                 workstreamMemoryBlock: specialistMemoryBlock,
-                workstreamStateSection: contextCompactionRuntime.formatWorkstreamStateForPrompt(workstreamState),
+                workstreamStateSection: await getWorkstreamStateSection(),
                 learnedSkillsSection: await getLearnedSkillsSection(agentId),
                 additionalInstructionSections: mergeInstructionSections(
                   specialistExecutionPlanInstructionSections,
@@ -995,17 +1045,6 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
               throw new WorkstreamTurnError('Direct workstreams require an assigned agent.', 400)
             }
             await runVisibleAgent({ agentId: workstream.agentId, mode: 'direct' })
-          } else if (params.kind === 'userTurn') {
-            await runVisibleAgent({
-              agentId: visibleWorkstreamAgentId ?? 'chief',
-              mode: 'workstreamMode',
-              skills: coreWorkstreamProfile?.skills ? [...coreWorkstreamProfile.skills] : undefined,
-              additionalInstructionSections: mergeInstructionSections(coreInstructionSections, hookInstructionSections),
-              extraTools: {
-                [CONSULT_SPECIALIST_TOOL_NAME]: consultSpecialistTool,
-                ...(teamThinkTool ? { [CONSULT_TEAM_TOOL_NAME]: teamThinkTool } : {}),
-              },
-            })
           } else {
             await runVisibleAgent({
               agentId: visibleWorkstreamAgentId ?? 'chief',
@@ -1043,6 +1082,9 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
               unregisterRun: (runId) => chatRunRegistry.unregister(runId),
               clearActiveRunId: (runId) => workstreamService.clearActiveRunIdIfMatches(workstreamRef, runId),
               disposeAbort: () => runAbort.dispose(),
+              activeStreamId: params.streamId,
+              clearActiveStreamId: (streamId) =>
+                workstreamService.clearActiveStreamIdIfMatches(workstreamRef, streamId),
             })
 
             if (allAssistantMessages.length > 0 && shouldProcessPostRunSideEffects) {

package/src/services/workstream-turn.ts

@@ -21,6 +21,18 @@ export async function createWorkstreamApprovalContinuationStream(params: Workstr
   })
 }
 
+export async function createWorkstreamNativeToolApprovalStream(params: WorkstreamApprovalContinuationParams) {
+  const prepared = await prepareWorkstreamRunCore({ ...params, kind: 'nativeToolApprovalTurn' })
+
+  return createUIMessageStream<ChatMessage>({
+    originalMessages: prepared.originalMessages,
+    onError: (error) => (error instanceof Error ? error.message : 'Native tool approval stream failed.'),
+    execute: async ({ writer }) => {
+      await prepared.run(writer)
+    },
+  })
+}
+
 export async function createWorkstreamTurnStream(params: WorkstreamTurnParams) {
   const prepared = await prepareWorkstreamRunCore({ ...params, kind: 'userTurn' })
 

package/src/services/workstream.service.ts

@@ -504,6 +504,32 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     await this.setActiveRunId(workstreamId, null)
   }
 
+  async setActiveStreamId(workstreamId: RecordIdRef, streamId: string): Promise<void> {
+    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+    await databaseService.query<unknown>(surql`
+      UPDATE ONLY ${workstreamRef}
+      SET activeStreamId = ${streamId}
+    `)
+  }
+
+  async getActiveStreamId(workstreamId: RecordIdRef): Promise<string | null> {
+    const workstream = await this.getById(workstreamId)
+    const activeStreamId = workstream.activeStreamId
+    if (typeof activeStreamId !== 'string') return null
+    const normalized = activeStreamId.trim()
+    return normalized.length > 0 ? normalized : null
+  }
+
+  async clearActiveStreamIdIfMatches(workstreamId: RecordIdRef, streamId: string): Promise<void> {
+    const activeStreamId = await this.getActiveStreamId(workstreamId)
+    if (activeStreamId !== streamId) return
+    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+    await databaseService.query<unknown>(surql`
+      UPDATE ONLY ${workstreamRef}
+      SET activeStreamId = NONE
+    `)
+  }
+
   async stopActiveRun(workstreamId: RecordIdRef): Promise<boolean> {
     const activeRunId = await this.getActiveRunId(workstreamId)
     if (!activeRunId) return false

package/src/services/workstream.types.ts

@@ -42,6 +42,7 @@ export const WorkstreamSchema = z.object({
   memoryBlock: z.string().nullish(),
   memoryBlockSummary: z.string().nullish(),
   activeRunId: z.string().nullish(),
+  activeStreamId: z.string().nullish(),
   compactionSummary: z.string().nullish(),
   lastCompactedMessageId: z.string().nullish(),
   nameGenerated: z.boolean().optional().default(false),

package/src/system-agents/title-generator.agent.ts

@@ -8,7 +8,7 @@ import {
 import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
-const WORKSTREAM_TITLE_MAX_TOKENS = 64
+const WORKSTREAM_TITLE_MAX_TOKENS = 512
 
 export const WORKSTREAM_TITLE_GENERATOR_PROMPT = `<agent-instructions>
 You are a **Title Generator** that creates concise chat titles.
@@ -18,7 +18,7 @@ Generate a chat title based only on the user's message.
 </task>
 
 <constraints>
-- Maximum 4-5 words
+- Maximum 3-4 words
 - Capture the core workstream or intent
 - Use natural, readable language
 - No punctuation at the end

package/src/tools/execution-plan.tool.ts

@@ -1,9 +1,9 @@
 import {
   CreateExecutionPlanArgsSchema,
   GetActiveExecutionPlanArgsSchema,
-  RestartExecutionTaskArgsSchema,
+  ResumeExecutionPlanRunArgsSchema,
   ReplaceExecutionPlanArgsSchema,
-  SetExecutionTaskStatusArgsSchema,
+  SubmitExecutionNodeResultArgsSchema,
 } from '@lota-sdk/shared/schemas/tools'
 import type { ExecutionPlanToolResultData } from '@lota-sdk/shared/schemas/tools'
 import { tool } from 'ai'
@@ -34,7 +34,7 @@ export function createCreateExecutionPlanTool(params: {
 }) {
   return tool({
     description:
-      'Create a structured execution plan for multi-step work in this workstream. Use this before starting multi-step execution.',
+      'Create a contract-driven execution plan for this workstream. Nodes must define deliverables, success criteria, completion checks, and executor policy.',
     inputSchema: CreateExecutionPlanArgsSchema,
     execute: async (input) => {
       const result = await executionPlanService.createPlan({
@@ -56,7 +56,8 @@ export function createReplaceExecutionPlanTool(params: {
   onPlanChanged?: () => void
 }) {
   return tool({
-    description: 'Replace the active execution plan when the ordered steps or approach have materially changed.',
+    description:
+      'Replace the active execution run with a new contract-driven plan when the graph, contracts, or approach materially change.',
     inputSchema: ReplaceExecutionPlanArgsSchema,
     execute: async (input) => {
       const result = await executionPlanService.replacePlan({
@@ -71,48 +72,17 @@ export function createReplaceExecutionPlanTool(params: {
   })
 }
 
-export function createSetExecutionTaskStatusTool(params: {
+export function createSubmitExecutionNodeResultTool(params: {
   workstreamId: RecordIdRef
   agentId: string
   onPlanChanged?: () => void
 }) {
   return tool({
     description:
-      'Update the active execution-plan task state, including in-progress, completed, blocked, failed, or skipped outcomes.',
-    inputSchema: SetExecutionTaskStatusArgsSchema,
-    execute: async function* (input) {
-      const activePlan = await executionPlanService.getActivePlanToolResult({
-        workstreamId: params.workstreamId,
-        includeEvents: true,
-      })
-
-      if (activePlan.plan && activePlan.plan.planId === input.planId) {
-        const optimisticPlan = structuredClone(activePlan.plan)
-        const targetTask = optimisticPlan.tasks.find((task) => task.id === input.taskId)
-
-        if (targetTask) {
-          targetTask.status = input.status
-          if (input.resultStatus !== undefined) targetTask.resultStatus = input.resultStatus
-          if (input.outputSummary !== undefined) targetTask.outputSummary = input.outputSummary || undefined
-          if (input.blockedReason !== undefined) targetTask.blockedReason = input.blockedReason || undefined
-          if (input.externalRef !== undefined) targetTask.externalRef = input.externalRef || undefined
-          if (input.status === 'in-progress') {
-            optimisticPlan.status = 'executing'
-            optimisticPlan.currentTaskId = targetTask.id
-          }
-
-          yield {
-            action: 'task-status-updated',
-            message: `Updating task "${targetTask.title}".`,
-            changedTaskId: targetTask.id,
-            plan: optimisticPlan,
-            hasPlan: true,
-            status: optimisticPlan.status,
-          } satisfies ExecutionPlanToolResultData
-        }
-      }
-
-      const result = await executionPlanService.setTaskStatus({
+      'Submit the result for the currently running execution node. The executor validates outputs, artifacts, and completion checks before advancing the run.',
+    inputSchema: SubmitExecutionNodeResultArgsSchema,
+    execute: async (input) => {
+      const result = await executionPlanService.submitNodeResult({
         workstreamId: params.workstreamId,
         emittedBy: params.agentId,
         input,
@@ -123,7 +93,7 @@ export function createSetExecutionTaskStatusTool(params: {
     toModelOutput: ({ output }) => {
       const result = getLatestExecutionPlanToolResult(output)
       const summary = result?.message?.trim()
-      return { type: 'text', value: summary && summary.length > 0 ? summary : 'Execution task status updated.' }
+      return { type: 'text', value: summary && summary.length > 0 ? summary : 'Execution node result submitted.' }
     },
   })
 }
@@ -131,27 +101,31 @@ export function createSetExecutionTaskStatusTool(params: {
 export function createGetActiveExecutionPlanTool(params: { workstreamId: RecordIdRef }) {
   return tool({
     description:
-      'Load the active execution plan for this workstream, including task state and recent events when needed.',
+      'Load the active execution run for this workstream, including graph state, node contracts, recent events, approvals, artifacts, and checkpoints when requested.',
     inputSchema: GetActiveExecutionPlanArgsSchema,
     execute: async (input) =>
       await executionPlanService.getActivePlanToolResult({
         workstreamId: params.workstreamId,
         includeEvents: input.includeEvents,
+        includeArtifacts: input.includeArtifacts,
+        includeApprovals: input.includeApprovals,
+        includeCheckpoints: input.includeCheckpoints,
+        includeValidationIssues: input.includeValidationIssues,
       }),
   })
 }
 
-export function createRestartExecutionTaskTool(params: {
+export function createResumeExecutionPlanRunTool(params: {
   workstreamId: RecordIdRef
   agentId: string
   onPlanChanged?: () => void
 }) {
   return tool({
     description:
-      'Restart a failed or blocked execution-plan task and optionally reset downstream tasks back to pending.',
-    inputSchema: RestartExecutionTaskArgsSchema,
+      'Resume the active execution run from its latest checkpoint after interruption. The executor reconciles state before re-activating nodes.',
+    inputSchema: ResumeExecutionPlanRunArgsSchema,
     execute: async (input) => {
-      const result = await executionPlanService.restartTask({
+      const result = await executionPlanService.resumeRun({
         workstreamId: params.workstreamId,
         emittedBy: params.agentId,
         input,

package/src/tools/log-hello-world.tool.ts

@@ -0,0 +1,17 @@
+import { tool } from 'ai'
+import { z } from 'zod'
+
+export function createLogHelloWorldTool() {
+  return tool({
+    description: 'Logs "Hello World" to the server console. Requires user approval before running.',
+    inputSchema: z.object({
+      message: z.string().optional().describe('Optional custom message to log alongside Hello World'),
+    }),
+    needsApproval: true,
+    execute: async ({ message }: { message?: string }) => {
+      const output = message ? `Hello World: ${message}` : 'Hello World'
+      console.log('[logHelloWorld]', output)
+      return { logged: output, timestamp: new Date().toISOString() }
+    },
+  })
+}

package/src/workers/skill-extraction.runner.ts

@@ -7,7 +7,7 @@ import { ensureRecordId, recordIdToString } from '../db/record-id'
 import type { RecordIdRef } from '../db/record-id'
 import { databaseService } from '../db/service'
 import { TABLES } from '../db/tables'
-import { createDefaultEmbeddings } from '../embeddings/provider'
+import { getDefaultEmbeddings } from '../embeddings/provider'
 import type { SkillExtractionJob } from '../queues/skill-extraction.queue'
 import { createHelperModelRuntime } from '../runtime/helper-model'
 import { getRuntimeAdapters, withConfiguredWorkspaceMemoryLock } from '../runtime/runtime-extensions'
@@ -54,7 +54,7 @@ interface SkillExtractionRunResult {
   extractedSkills: number
 }
 
-const embeddings = createDefaultEmbeddings()
+const embeddings = getDefaultEmbeddings()
 
 const helperModelRuntime = createHelperModelRuntime()