@lota-sdk/core 0.1.15 → 0.1.16

package/src/services/workstream-plan-registry.service.ts

@@ -0,0 +1,22 @@
+import type { PlanRunRecord, SerializableExecutionPlan } from '@lota-sdk/shared'
+
+import type { RecordIdInput } from '../db/record-id'
+import { planRunService } from './plan-run.service'
+
+class WorkstreamPlanRegistryService {
+  async listActiveRuns(workstreamId: RecordIdInput): Promise<PlanRunRecord[]> {
+    return planRunService.getActiveRunRecords(workstreamId)
+  }
+
+  async countActiveRuns(workstreamId: RecordIdInput): Promise<number> {
+    const runs = await this.listActiveRuns(workstreamId)
+    return runs.length
+  }
+
+  async listActivePlans(workstreamId: RecordIdInput): Promise<SerializableExecutionPlan[]> {
+    const runs = await this.listActiveRuns(workstreamId)
+    return Promise.all(runs.map((run) => planRunService.toSerializablePlan(run)))
+  }
+}
+
+export const workstreamPlanRegistryService = new WorkstreamPlanRegistryService()

package/src/services/workstream-title.service.ts

@@ -10,6 +10,8 @@ import {
 } from '../system-agents/title-generator.agent'
 import { workstreamService } from './workstream.service'
 
+const WORKSTREAM_TITLE_TIMEOUT_MS = 5_000
+
 class WorkstreamTitleService {
   helperRuntime = createHelperModelRuntime()
 
@@ -21,7 +23,7 @@ class WorkstreamTitleService {
           tag: 'workstream-title',
           createAgent: createWorkstreamTitleGeneratorAgent,
           defaultSystemPrompt: WORKSTREAM_TITLE_GENERATOR_PROMPT,
-          timeoutMs: 30_000,
+          timeoutMs: WORKSTREAM_TITLE_TIMEOUT_MS,
           messages: [{ role: 'user', content: sourceText }],
         }),
       )

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

@@ -1,4 +1,5 @@
 import {
+  WORKSTREAM,
   baseChatMessageSchema,
   CONSULT_SPECIALIST_TOOL_NAME,
   CONSULT_TEAM_TOOL_NAME,
@@ -10,7 +11,7 @@ import {
 } from '@lota-sdk/shared'
 import type { ChatMessage, MessageMetadata } from '@lota-sdk/shared'
 import { convertToModelMessages, readUIMessageStream, stepCountIs, tool as createTool, validateUIMessages } from 'ai'
-import type { PrepareStepFunction, StopCondition, ToolSet, UIMessageStreamWriter } from 'ai'
+import type { PrepareStepFunction, StopCondition, ToolLoopAgent, ToolSet, UIMessageStreamWriter } from 'ai'
 import type { z } from 'zod'
 
 import type { CoreWorkstreamProfile } from '../config/agent-defaults'
@@ -21,7 +22,6 @@ import {
   getLeadAgentId,
   getCoreWorkstreamProfile,
   getAgentRuntimeConfig,
-  pluginRuntime,
 } from '../config/agent-defaults'
 import { lotaDebugLogger } from '../config/debug-logger'
 import { aiLogger } from '../config/logger'
@@ -55,6 +55,7 @@ import {
   shouldEnqueueOnboardingPostChatMemory,
   shouldEnqueueRegularDigestForWorkstream,
 } from '../runtime/memory-digest-policy'
+import { buildIndexedRepositoriesContext, getPluginService } from '../runtime/plugin-resolution'
 import { getRuntimeAdapters, getToolProviders, getTurnHooks } from '../runtime/runtime-extensions'
 import { shouldEnqueueSkillExtraction } from '../runtime/skill-extraction-policy'
 import { finalizeTurnRun } from '../runtime/turn-lifecycle'
@@ -86,12 +87,11 @@ import { contextCompactionRuntime } from './context-compaction-runtime.singleton
 import { executionPlanService } from './execution-plan.service'
 import { learnedSkillService } from './learned-skill.service'
 import { memoryService } from './memory.service'
+import { planRunService } from './plan-run.service'
 import { recentActivityService } from './recent-activity.service'
 import { workstreamMessageService } from './workstream-message.service'
 import { workstreamService } from './workstream.service'
 
-type AgentRuntimeConfig = Record<string, unknown>
-type AgentFactory = Record<string, (...args: unknown[]) => Record<string, (...args: unknown[]) => unknown>>
 type ChatStreamChunk = Parameters<UIMessageStreamWriter<ChatMessage>['write']>[0]
 
 interface UIMessageStreamResult {
@@ -106,45 +106,8 @@ function hasUIMessageStream(value: unknown): value is UIMessageStreamResult {
   )
 }
 
-function getPluginService(path: string[]): ((...args: unknown[]) => unknown) | undefined {
-  let current: unknown = pluginRuntime
-  let owner: unknown = undefined
-  for (const key of path) {
-    if (current === null || current === undefined || typeof current !== 'object') return undefined
-    owner = current
-    current = (current as Record<string, unknown>)[key]
-  }
-  if (typeof current !== 'function') {
-    return undefined
-  }
-
-  return owner && typeof owner === 'object'
-    ? (current as (...args: unknown[]) => unknown).bind(owner)
-    : (current as (...args: unknown[]) => unknown)
-}
-
-async function buildIndexedRepositoriesContext(
-  workspaceId: string,
-): Promise<{ provideRepoTool: boolean; defaultSectionsByAgent: Record<string, unknown>; context: string }> {
-  const buildContext = getRuntimeAdapters().workstream?.buildIndexedRepositoriesContext
-  if (!buildContext) {
-    return { provideRepoTool: false, defaultSectionsByAgent: {}, context: '' }
-  }
-
-  const context = await buildContext(workspaceId)
-  return {
-    provideRepoTool: context.provideRepoTool,
-    defaultSectionsByAgent: context.defaultSectionsByAgent,
-    context: context.context ?? '',
-  }
-}
-
 const PRESEEDED_MEMORY_LOOKUP_LIMIT = 3
 
-function parsePersistedWorkstreamState(value: unknown): WorkstreamState | null {
-  return parseWorkstreamState(value)
-}
-
 function stripExecutionPlanFieldsFromWorkstreamState(
   state: WorkstreamState | null | undefined,
   hasExecutionPlan: boolean,
@@ -155,7 +118,7 @@ function stripExecutionPlanFieldsFromWorkstreamState(
 }
 
 async function waitForWorkstreamCompactionIfNeeded(workstreamId: RecordIdRef): Promise<WorkstreamRecord> {
-  return await waitForCompactionIfNeeded({
+  return waitForCompactionIfNeeded({
     entityId: recordIdToString(workstreamId, TABLES.WORKSTREAM),
     entityLabel: 'Workstream',
     loadEntity: () => workstreamService.getById(workstreamId),
@@ -397,18 +360,18 @@ async function streamAgentResponse(
       optionalInstructionSection(agentResolution?.extraInstructions),
     ),
     context: ctx.buildContextResult,
-  }) as AgentRuntimeConfig
+  }) as Record<string, unknown>
   agentTimer.step('build-agent-config')
   const modelMessages = await convertToModelMessages(streamParams.messages, { ignoreIncompleteToolCalls: true })
   agentTimer.step('convert-model-messages')
-  const agent = (createAgent as unknown as AgentFactory)[config.id as string]({
+  const agent = createAgent[config.id as string]({
     mode: streamParams.mode,
     tools: streamParams.tools,
     extraInstructions: config.extraInstructions,
     stopWhen: (agentResolution?.stopWhen as StopCondition<ToolSet> | Array<StopCondition<ToolSet>> | undefined) ??
       streamParams.stopWhen ?? [stepCountIs(config.maxSteps as number)],
     prepareStep: (agentResolution?.prepareStep as PrepareStepFunction<ToolSet> | undefined) ?? streamParams.prepareStep,
-  })
+  }) as ToolLoopAgent<never, ToolSet>
   const agentAbortSignal = streamParams.abortSignal ?? ctx.runAbortSignal
   agentTimer.step('agent-construction')
 
@@ -443,7 +406,7 @@ async function streamAgentResponse(
     sendSources: true,
     messageMetadata: createAgentMessageMetadata({ agentId: resolvedAgentId, agentName: config.displayName as string }),
     onFinish: ({ responseMessage: finishedResponseMessage }: { responseMessage: ChatMessage }) => {
-      responseMessage = withMessageCreatedAt(finishedResponseMessage)
+      responseMessage = withMessageCreatedAt(finishedResponseMessage, Date.now())
       resolveFinishedStream()
     },
   }) as ReadableStream<ChatStreamChunk>
@@ -474,7 +437,7 @@ async function streamAgentResponse(
   }
 
   for (const toolError of collectToolOutputErrors({ responseMessage: responseMessage })) {
-    aiLogger.warn`Tool execution failed (agent=${resolvedAgentId}, tool=${toolError.toolName}, toolCallId=${toolError.toolCallId}): ${toolError.errorText}`
+    aiLogger.error`Tool execution failed (agent=${resolvedAgentId}, tool=${toolError.toolName}, toolCallId=${toolError.toolCallId}): ${toolError.errorText}`
   }
 
   return responseMessage
@@ -657,7 +620,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
   const shouldProcessPostRunSideEffects =
     params.kind === 'approvalContinuation' || params.kind === 'nativeToolApprovalTurn' || shouldPersistInputMessage
   if (params.kind === 'userTurn') {
-    inputMessage = hydrateMessageFileUrls(withMessageCreatedAt(params.inputMessage))
+    inputMessage = hydrateMessageFileUrls(withMessageCreatedAt(params.inputMessage, Date.now()))
     if (inputMessage.role !== 'user') {
       throw new WorkstreamTurnError('Only user messages can be submitted to the workstream runtime.', 400)
     }
@@ -691,7 +654,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
     timer.step('persist-approval-message')
   }
 
-  const initialWorkstreamState = parsePersistedWorkstreamState(workstreamRecord.state)
+  const initialWorkstreamState = parseWorkstreamState(workstreamRecord.state)
   const persistedCompactionCursor = toOptionalTrimmedString(workstreamRecord.lastCompactedMessageId) ?? undefined
   const persistedLiveHistoryPromise = workstreamMessageService.listMessagesAfterCursor(
     workstreamRef,
@@ -703,10 +666,10 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
   if (inputMessage) {
     userMessage = {
       ...inputMessage,
-      id: inputMessage.id || Bun.randomUUIDv7(),
+      id: inputMessage.id,
       role: 'user',
       parts: inputMessage.parts,
-      metadata: { ...inputMessage.metadata, createdAt: toTimestamp(inputMessage.metadata?.createdAt) ?? Date.now() },
+      metadata: { ...inputMessage.metadata, createdAt: toTimestamp(inputMessage.metadata?.createdAt) },
     }
   }
 
@@ -758,6 +721,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
     workstream.mode === 'group' &&
     !workstream.core &&
     workstreamRecord.nameGenerated !== true &&
+    workstreamRecord.title === WORKSTREAM.DEFAULT_TITLE &&
     messageText.length > 0
   ) {
     void safeEnqueue(
@@ -896,18 +860,21 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
   let workstreamState = initialWorkstreamState
   const executionPlanInstructionSectionCache = createExecutionPlanInstructionSectionCache({
     disabled: onboardingActive,
-    loadPlan: async () => await executionPlanService.getActivePlanForWorkstream(workstreamRef),
+    loadPlans: async () => {
+      const runs = await planRunService.getActiveRunRecords(workstreamRef)
+      return Promise.all(runs.map((run) => planRunService.toSerializablePlan(run)))
+    },
   })
-  const getExecutionPlan = async () => await executionPlanInstructionSectionCache.getPlan()
+  const getExecutionPlans = async () => await executionPlanInstructionSectionCache.getPlans()
   const getExecutionPlanInstructionSections = async (): Promise<string[] | undefined> =>
     await executionPlanInstructionSectionCache.getSections()
   const invalidateExecutionPlanInstructionSections = () => {
     executionPlanInstructionSectionCache.invalidate()
   }
   const getWorkstreamStateSection = async (): Promise<string | undefined> => {
-    const executionPlan = await getExecutionPlan()
+    const executionPlans = await getExecutionPlans()
     return contextCompactionRuntime.formatWorkstreamStateForPrompt(
-      stripExecutionPlanFieldsFromWorkstreamState(workstreamState, Boolean(executionPlan)),
+      stripExecutionPlanFieldsFromWorkstreamState(workstreamState, executionPlans.length > 0),
     )
   }
   const respondedBy = recordIdToString(userRef, TABLES.USER)
@@ -1018,10 +985,10 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
           })
 
           const commitAssistantResponse = async (response: ChatMessage, agentId: string, agentName: string) => {
-            const committed = withMessageCreatedAt({
-              ...response,
-              metadata: { ...response.metadata, ...buildAgentMetadataPatch(agentId, agentName) },
-            })
+            const committed = withMessageCreatedAt(
+              { ...response, metadata: { ...response.metadata, ...buildAgentMetadataPatch(agentId, agentName) } },
+              Date.now(),
+            )
 
             await workstreamMessageService.upsertMessages({ workstreamId: workstreamRef, messages: [committed] })
             currentMessages = upsertChatHistoryMessage(currentMessages, committed)
@@ -1063,6 +1030,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
           }): Promise<ChatMessage> => {
             const visibleTimer = lotaDebugLogger.timer(`visible:${runParams.agentId}`)
             let runMemoryBlock = memoryBlock
+            const includeExecutionPlanTools = runParams.mode !== 'fixedWorkstreamMode' && !onboardingActive
             const tools: ToolSet = {
               ...((await buildAgentTools({
                 agentId: runParams.agentId,
@@ -1084,7 +1052,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                   runMemoryBlock = value
                 },
                 availableUploads: listReadableUploads(runParams.extraMessages),
-                includeExecutionPlanTools: runParams.mode !== 'fixedWorkstreamMode',
+                includeExecutionPlanTools,
                 onExecutionPlanChanged: invalidateExecutionPlanInstructionSections,
                 context: buildContextResult,
               })) as ToolSet),
@@ -1107,7 +1075,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
             visibleTimer.step('stream-agent-response')
             memoryBlock = runMemoryBlock
 
-            return await commitAssistantResponse(
+            return commitAssistantResponse(
               responseMessage,
               runParams.agentId,
               agentDisplayNames[runParams.agentId] ?? runParams.agentId,
@@ -1182,14 +1150,14 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                   hookInstructionSections,
                 ),
                 context: buildContextResult,
-              }) as AgentRuntimeConfig
+              }) as Record<string, unknown>
               const observer = createObserver(agentId)
-              const agent = (createAgent as unknown as AgentFactory)[specialistConfig.id as string]({
+              const agent = createAgent[specialistConfig.id as string]({
                 mode: 'fixedWorkstreamMode',
                 tools: { ...(specialistTools as ToolSet), ...toolProviders },
                 extraInstructions: specialistConfig.extraInstructions,
                 stopWhen: [stepCountIs(specialistConfig.maxSteps as number)],
-              })
+              }) as ToolLoopAgent<never, ToolSet>
               const modelMessages = await convertToModelMessages(buildRunInputMessages([specialistTaskMessage]), {
                 ignoreIncompleteToolCalls: true,
               })
@@ -1225,7 +1193,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                   }),
                 }) as ReadableStream<never>,
               })) {
-                finalMessage = withMessageCreatedAt(message)
+                finalMessage = withMessageCreatedAt(message, Date.now())
                 yield finalMessage
               }
 
@@ -1301,7 +1269,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
         } finally {
           try {
             const latestWorkstreamRecord = await workstreamService.getById(workstreamRef)
-            const latestPersistedState = parsePersistedWorkstreamState(latestWorkstreamRecord.state)
+            const latestPersistedState = parseWorkstreamState(latestWorkstreamRecord.state)
 
             await finalizeTurnRun({
               serverRunId,

package/src/services/workstream.service.ts

@@ -99,7 +99,7 @@ function requireDirectAgentId(agentId: string | undefined): string {
   return agentId
 }
 
-function requirestring(coreType: string | undefined): string {
+function requireString(coreType: string | undefined): string {
   if (!coreType) {
     throw new Error('Core workstreams require a coreType')
   }
@@ -174,7 +174,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
         return options.title
       }
       if (core) {
-        return getCoreWorkstreamProfile(requirestring(coreType)).config.title
+        return getCoreWorkstreamProfile(requireString(coreType)).config.title
       }
       if (mode === 'direct') {
         return getAgentDisplayName(requireDirectAgentId(directAgentId))
@@ -220,7 +220,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     }
 
     if (core) {
-      const resolvedCoreType = requirestring(coreType)
+      const resolvedCoreType = requireString(coreType)
       const coreProfile = getCoreWorkstreamProfile(resolvedCoreType)
       const coreWorkstreamId = buildCoreWorkstreamId({ userId, orgId, coreType: resolvedCoreType })
       const existing = await this.findById(coreWorkstreamId)
@@ -273,6 +273,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
       core: false,
       title,
       status: 'regular',
+      nameGenerated: options?.title !== undefined && options.title !== WORKSTREAM.DEFAULT_TITLE,
     })
 
     return this.normalizeWorkstream(groupWorkstream)
@@ -294,7 +295,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     )
 
     const hasStandardGroupWorkstream = existingWorkstreams.some(
-      (workstream) => workstream.mode === 'group' && workstream.core !== true,
+      (workstream) => workstream.mode === 'group' && !workstream.core,
     )
     const directWorkstreamsByAgent = new Map<string, WorkstreamRecord>()
     const coreWorkstreamsByType = new Map<string, WorkstreamRecord>()
@@ -303,7 +304,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
       directWorkstreamsByAgent.set(workstream.agentId, workstream)
     }
     for (const workstream of existingWorkstreams) {
-      if (workstream.mode !== 'group' || workstream.core !== true) continue
+      if (workstream.mode !== 'group' || !workstream.core) continue
       if (typeof workstream.coreType !== 'string') continue
       coreWorkstreamsByType.set(workstream.coreType, workstream)
     }
@@ -457,14 +458,10 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     return this.normalizeWorkstream(workstream)
   }
 
-  async getWorkstreamRecord(workstreamId: RecordIdRef): Promise<WorkstreamRecord> {
-    return await this.getById(workstreamId)
-  }
-
   async updateTitle(workstreamId: RecordIdRef, title: string): Promise<NormalizedWorkstream> {
     const existing = await this.getById(workstreamId)
     this.assertMutableWorkstream(existing, 'rename')
-    const workstream = await this.update(workstreamId, { title })
+    const workstream = await this.update(workstreamId, { title, nameGenerated: true })
     return this.normalizeWorkstream(workstream)
   }
 
@@ -501,9 +498,8 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
   }
 
   async clearActiveRunIdIfMatches(workstreamId: RecordIdRef, runId: string): Promise<void> {
-    const activeRunId = await this.getActiveRunId(workstreamId)
-    if (activeRunId !== runId) return
-    await this.setActiveRunId(workstreamId, null)
+    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+    await databaseService.query(surql`UPDATE ONLY ${workstreamRef} SET activeRunId = NONE WHERE activeRunId = ${runId}`)
   }
 
   async setActiveStreamId(workstreamId: RecordIdRef, streamId: string): Promise<void> {
@@ -523,13 +519,10 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
   }
 
   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
-    `)
+    await databaseService.query(
+      surql`UPDATE ONLY ${workstreamRef} SET activeStreamId = NONE WHERE activeStreamId = ${streamId}`,
+    )
   }
 
   async stopActiveRun(workstreamId: RecordIdRef): Promise<boolean> {
@@ -659,7 +652,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
       throw new Error(`Invalid record id for table ${table}`)
     }
 
-    return recordIdToString(id, String(table))
+    return recordIdToString(id, table)
   }
 
   formatMemoryBlockForPrompt(workstream: Pick<WorkstreamRecord, 'memoryBlock' | 'memoryBlockSummary'>): string {
@@ -670,7 +663,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
   }
 
   private getDefaultTitle(workstream: Pick<WorkstreamRecord, 'core' | 'coreType'>): string {
-    if (workstream.core === true && typeof workstream.coreType === 'string') {
+    if (workstream.core && typeof workstream.coreType === 'string') {
       return getCoreWorkstreamProfile(workstream.coreType).config.title
     }
 
@@ -683,10 +676,10 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
         ? workstream.activeRunId
         : null
     const isCompacting = workstream.isCompacting === true
-    const mode = typeof workstream.mode === 'string' ? workstream.mode : 'group'
-    const core = workstream.core === true
+    const mode = workstream.mode
+    const core = workstream.core
     const coreType = core && typeof workstream.coreType === 'string' ? workstream.coreType : undefined
-    const status = typeof workstream.status === 'string' ? workstream.status : 'regular'
+    const status = workstream.status
     return {
       id: this.normalizeWorkstreamId(workstream.id),
       userId: this.normalizeRecordIdString(workstream.userId, TABLES.USER),
@@ -694,7 +687,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
       mode,
       core,
       ...(coreType ? { coreType } : {}),
-      nameGenerated: workstream.nameGenerated === true,
+      nameGenerated: workstream.nameGenerated,
       isRunning: activeRunId !== null,
       isCompacting,
       ...(isAgentName(workstream.agentId) ? { agentId: workstream.agentId } : {}),
@@ -706,35 +699,20 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     }
   }
 
-  toPublicWorkstream(workstream: NormalizedWorkstream | WorkstreamRecord) {
-    const id = typeof workstream.id === 'string' ? workstream.id : this.normalizeWorkstreamId(workstream.id)
-    const createdAt = toIsoDateTimeString(workstream.createdAt)
-    const updatedAt = toIsoDateTimeString(workstream.updatedAt)
-    const activeRunId =
-      'activeRunId' in workstream &&
-      typeof workstream.activeRunId === 'string' &&
-      workstream.activeRunId.trim().length > 0
-        ? workstream.activeRunId
-        : null
-    const isRunning = 'isRunning' in workstream ? workstream.isRunning : activeRunId !== null
-    const isCompacting = workstream.isCompacting === true
-    const mode = typeof workstream.mode === 'string' ? workstream.mode : 'group'
-    const core = workstream.core === true
-    const coreType = core && typeof workstream.coreType === 'string' ? workstream.coreType : undefined
-    const nameGenerated = 'nameGenerated' in workstream ? workstream.nameGenerated === true : false
+  toPublicWorkstream(workstream: NormalizedWorkstream) {
     return {
-      id,
-      mode,
-      core,
-      ...(coreType ? { coreType } : {}),
-      ...(isAgentName(workstream.agentId) ? { agentId: workstream.agentId } : {}),
-      title: workstream.title ?? this.getDefaultTitle(workstream),
-      status: workstream.status ?? 'regular',
-      nameGenerated,
-      isRunning,
-      isCompacting,
-      createdAt,
-      updatedAt,
+      id: workstream.id,
+      mode: workstream.mode,
+      core: workstream.core,
+      ...(workstream.coreType ? { coreType: workstream.coreType } : {}),
+      ...(workstream.agentId ? { agentId: workstream.agentId } : {}),
+      title: workstream.title,
+      status: workstream.status,
+      nameGenerated: workstream.nameGenerated,
+      isRunning: workstream.isRunning,
+      isCompacting: workstream.isCompacting,
+      createdAt: workstream.createdAt,
+      updatedAt: workstream.updatedAt,
     }
   }
 
@@ -745,7 +723,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
       SET turnCount += 1
       RETURN turnCount
     `)
-    return result[0]?.turnCount ?? 0
+    return result[0].turnCount
   }
 
   async persistGeneratedTitle(workstreamId: RecordIdRef, title: string): Promise<void> {
@@ -759,7 +737,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     if (workstream.mode === 'direct') {
       throw new Error(`Direct workstreams cannot be ${action}d`)
     }
-    if (workstream.core === true) {
+    if (workstream.core) {
       throw new Error(`Core workstreams cannot be ${action}d`)
     }
   }

package/src/services/workstream.types.ts

@@ -1,4 +1,4 @@
-import { sdkWorkstreamStatusSchema } from '@lota-sdk/shared'
+import { recordIdSchema, sdkWorkstreamStatusSchema } from '@lota-sdk/shared'
 import { z } from 'zod'
 
 const WorkstreamModeSchema = z.enum(['direct', 'group'])
@@ -23,27 +23,27 @@ export interface NormalizedWorkstream {
 }
 
 export const WorkstreamSchema = z.object({
-  id: z.unknown(), // SurrealDB RecordId — validated structurally at DB boundary
-  mode: WorkstreamModeSchema.optional().default('group'),
-  core: z.boolean().optional().default(false),
+  id: recordIdSchema,
+  mode: WorkstreamModeSchema,
+  core: z.boolean(),
   coreType: CoreWorkstreamTypeSchema.nullish(),
   agentId: z.string().nullish(),
   title: z.string().nullish(),
-  status: sdkWorkstreamStatusSchema.nullish(),
+  status: sdkWorkstreamStatusSchema,
   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), // Ideally `isNameGenerated`, but maps directly to SurrealDB column `nameGenerated`
+  nameGenerated: z.boolean(), // Ideally `isNameGenerated`, but maps directly to SurrealDB column `nameGenerated`
   isCompacting: z.boolean().optional(),
   state: z.unknown().optional(),
-  turnCount: z.number().int().optional().default(0),
+  turnCount: z.number().int(),
   createdAt: z.coerce.date(),
   updatedAt: z.coerce.date(),
-  userId: z.unknown(), // SurrealDB RecordId — validated structurally at DB boundary
-  organizationId: z.unknown(), // SurrealDB RecordId — validated structurally at DB boundary
+  userId: recordIdSchema,
+  organizationId: recordIdSchema,
 })
 
 export type WorkstreamRecord = z.infer<typeof WorkstreamSchema>

package/src/services/write-intent-validator.service.ts

@@ -0,0 +1,81 @@
+import type { PlanDataSchema, PlanNodeSpec, PlanSchemaRegistry, WriteIntent } from '@lota-sdk/shared'
+
+import { validateSchemaValue } from './plan-validator.service'
+
+export interface WriteValidationIssue {
+  code: string
+  message: string
+  path?: string
+}
+
+export interface WriteValidationResult {
+  status: 'pass' | 'fail'
+  issues: WriteValidationIssue[]
+  suggestion?: string
+  validatedAt: string
+}
+
+class WriteIntentValidatorService {
+  validate(params: {
+    intent: WriteIntent
+    nodeSpec: PlanNodeSpec
+    schemaRegistry: PlanSchemaRegistry
+    existingDeliverables: Map<string, unknown>
+  }): WriteValidationResult {
+    const issues: WriteValidationIssue[] = []
+    const { intent, nodeSpec, schemaRegistry, existingDeliverables } = params
+
+    if (intent.targetPath.startsWith('structuredOutput')) {
+      if (nodeSpec.outputSchemaRef) {
+        const schema = schemaRegistry[nodeSpec.outputSchemaRef] as PlanDataSchema | undefined
+        if (schema) {
+          const schemaIssues = validateSchemaValue({ schema, value: intent.payload, path: intent.targetPath })
+          for (const message of schemaIssues) {
+            issues.push({ code: 'schema_validation_failed', message })
+          }
+        }
+      }
+      return this.buildResult(issues)
+    }
+
+    const deliverable = nodeSpec.deliverables.find((d) => d.name === intent.targetPath)
+    if (!deliverable) {
+      issues.push({
+        code: 'unknown_deliverable',
+        message: `"${intent.targetPath}" does not match any declared deliverable.`,
+      })
+      return this.buildResult(issues)
+    }
+
+    if (deliverable.schemaRef) {
+      const schema = schemaRegistry[deliverable.schemaRef] as PlanDataSchema | undefined
+      if (schema) {
+        const schemaIssues = validateSchemaValue({ schema, value: intent.payload, path: intent.targetPath })
+        for (const message of schemaIssues) {
+          issues.push({ code: 'schema_validation_failed', message })
+        }
+      }
+    }
+
+    if (intent.action === 'update' && !existingDeliverables.has(intent.targetPath)) {
+      issues.push({
+        code: 'update_target_not_found',
+        message: `Cannot update "${intent.targetPath}" — no prior write exists.`,
+      })
+    }
+
+    return this.buildResult(issues)
+  }
+
+  private buildResult(issues: WriteValidationIssue[]): WriteValidationResult {
+    const hasFailed = issues.length > 0
+    return {
+      status: hasFailed ? 'fail' : 'pass',
+      issues,
+      ...(hasFailed ? { suggestion: issues.map((i) => i.message).join('; ') } : {}),
+      validatedAt: new Date().toISOString(),
+    }
+  }
+}
+
+export const writeIntentValidatorService = new WriteIntentValidatorService()

package/src/storage/attachment-parser.ts

@@ -64,7 +64,7 @@ export async function extractAttachmentText(file: File): Promise<string> {
     return normalizeExtractedText((await extractPdfPages(file)).join('\n\n'))
   }
   if (isDocxAttachmentFile(file)) {
-    return await extractDocxText(file)
+    return extractDocxText(file)
   }
   return ''
 }

package/src/storage/attachment-utils.ts

@@ -3,7 +3,7 @@ function sanitizeFilename(name: string): string {
   return ascii.replace(/[\\/:"*?<>|]+/g, '-').trim()
 }
 
-function toSafeSegment(value: string): string {
+export function toSafeSegment(value: string): string {
   const cleaned = value.replace(/[^a-zA-Z0-9._-]/g, '-')
   return cleaned.length > 0 ? cleaned : 'unknown'
 }