@lota-sdk/core 0.1.15 → 0.1.17

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'
 }

package/src/storage/generated-document-storage.service.ts

@@ -1,8 +1,9 @@
 import { S3Client } from 'bun'
 
 import { getRuntimeConfig } from '../runtime/runtime-config'
+import { toSafeSegment } from './attachment-utils'
 
-function toSafeSegment(value: string): string {
+function toSafePathSegment(value: string): string {
   return value
     .trim()
     .replace(/\\/g, '/')
@@ -18,7 +19,7 @@ function buildGeneratedDocumentStorageKey(params: {
 }): string {
   const safeOrganizationId = toSafeSegment(params.organizationId)
   const safeNamespace = toSafeSegment(params.namespace)
-  const safeRelativePath = toSafeSegment(params.relativePath)
+  const safeRelativePath = toSafePathSegment(params.relativePath)
   return `${safeOrganizationId}/generated/${safeNamespace}/${safeRelativePath}`
 }
 

package/src/system-agents/context-compaction.agent.ts

@@ -1,6 +1,7 @@
 import { ToolLoopAgent } from 'ai'
 
 import { bifrostOpenRouterResponseHealingModel } from '../bifrost/bifrost'
+import { buildBifrostCacheHeaders } from '../bifrost/cache-headers'
 import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
   OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
@@ -40,6 +41,7 @@ export function createContextCompactionAgent(options: CreateHelperToolLoopAgentO
   return new ToolLoopAgent({
     id: 'context-compaction',
     model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+    headers: buildBifrostCacheHeaders('context-compaction'),
     providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
     ...resolveHelperAgentOptions(options, { instructions: CONTEXT_COMPACTION_PROMPT }),
   })

package/src/system-agents/delegated-agent-factory.ts

@@ -3,6 +3,7 @@ import type { ModelMessage, LanguageModel, ToolLoopAgentSettings, ToolSet } from
 import { z } from 'zod'
 
 import type { ToolDefinition } from '../ai/definitions'
+import { aiLogger } from '../config/logger'
 import { isRecord } from '../utils/string'
 import { assertSubstantiveAgentResult } from './agent-result'
 
@@ -16,6 +17,7 @@ interface DelegatedAgentDefinition {
   providerOptions?: AgentProviderOptions
   instructions: string
   tools?: ToolSet
+  headers?: Record<string, string>
   maxSteps?: number
   maxOutputTokens?: number
   temperature?: number
@@ -136,6 +138,7 @@ async function generateSubstantiveDelegatedAgentResult(params: {
     try {
       return assertSubstantiveAgentResult(result.text, params.label)
     } catch (error) {
+      aiLogger.error`Delegated agent returned non-substantive result (label=${params.label}, attempt=${attempt + 1}, textLength=${result.text.length}, textPreview=${result.text.slice(0, 200)})`
       lastError = error
       if (params.abortSignal?.aborted) {
         throw error
@@ -163,6 +166,7 @@ export function createDelegatedAgentTool(definition: DelegatedAgentDefinition):
               id: definition.id,
               model: resolveAgentModel(definition.model),
               ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
+              ...(definition.headers ? { headers: definition.headers } : {}),
               instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
               tools: agentTools,
               maxOutputTokens: definition.maxOutputTokens ?? DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS,
@@ -204,6 +208,7 @@ export function createDelegatedAgentToolWithContext<TContext>(
               id: definition.id,
               model: resolveAgentModel(definition.model),
               ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
+              ...(definition.headers ? { headers: definition.headers } : {}),
               instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
               tools: agentTools,
               maxOutputTokens: definition.maxOutputTokens ?? DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS,

package/src/system-agents/memory-reranker.agent.ts

@@ -1,9 +1,10 @@
 import { ToolLoopAgent } from 'ai'
 
 import { bifrostOpenRouterResponseHealingModel } from '../bifrost/bifrost'
+import { buildBifrostCacheHeaders } from '../bifrost/cache-headers'
 import {
   OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
-  OPENROUTER_STRUCTURED_REASONING_MODEL_ID,
+  OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
 } from '../config/model-constants'
 import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
@@ -31,7 +32,8 @@ Set every item.relevance as a string; use empty string when no reason is needed.
 export function createMemoryRerankerAgent(options: CreateHelperToolLoopAgentOptions) {
   return new ToolLoopAgent({
     id: 'memory-reranker',
-    model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_REASONING_MODEL_ID),
+    model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+    headers: buildBifrostCacheHeaders('memory-reranker'),
     providerOptions: OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
     ...resolveHelperAgentOptions(options),
   })

package/src/system-agents/memory.agent.ts

@@ -1,6 +1,7 @@
 import { ToolLoopAgent } from 'ai'
 
 import { bifrostOpenRouterResponseHealingModel } from '../bifrost/bifrost'
+import { buildBifrostCacheHeaders } from '../bifrost/cache-headers'
 import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
   OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
@@ -52,6 +53,7 @@ export function createOrgMemoryAgent(options: CreateHelperToolLoopAgentOptions)
   return new ToolLoopAgent({
     id: 'org-memory',
     model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+    headers: buildBifrostCacheHeaders('org-memory'),
     providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
     ...resolveHelperAgentOptions(options),
   })

package/src/system-agents/recent-activity-title-refiner.agent.ts

@@ -1,6 +1,7 @@
 import { ToolLoopAgent } from 'ai'
 
 import { bifrostModel } from '../bifrost/bifrost'
+import { buildBifrostCacheHeaders } from '../bifrost/cache-headers'
 import { getLeadAgentDisplayName } from '../config/agent-defaults'
 import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
@@ -79,6 +80,7 @@ export function createRecentActivityTitleRefinerAgent(options: CreateHelperToolL
   return new ToolLoopAgent({
     id: 'recent-activity-title-refiner',
     model: bifrostModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+    headers: buildBifrostCacheHeaders('recent-activity-title-refiner'),
     providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
     ...resolveHelperAgentOptions(options, {
       instructions: buildRecentActivityTitleRefinerPrompt(),

package/src/system-agents/regular-chat-memory-digest.agent.ts

@@ -1,6 +1,7 @@
 import { ToolLoopAgent } from 'ai'
 
 import { bifrostOpenRouterResponseHealingModel } from '../bifrost/bifrost'
+import { buildBifrostCacheHeaders } from '../bifrost/cache-headers'
 import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
   OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
@@ -66,6 +67,7 @@ export function createRegularChatMemoryDigestAgent(options: CreateHelperToolLoop
   return new ToolLoopAgent({
     id: 'regular-chat-memory-digest',
     model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+    headers: buildBifrostCacheHeaders('regular-chat-memory-digest'),
     providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
     ...resolveHelperAgentOptions(options, {
       instructions: regularChatMemoryDigestPrompt,

package/src/system-agents/skill-extractor.agent.ts

@@ -2,6 +2,7 @@ import { ToolLoopAgent } from 'ai'
 import { z } from 'zod'
 
 import { bifrostOpenRouterResponseHealingModel } from '../bifrost/bifrost'
+import { buildBifrostCacheHeaders } from '../bifrost/cache-headers'
 import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
   OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
@@ -79,6 +80,7 @@ export function createSkillExtractorAgent(options: CreateHelperToolLoopAgentOpti
   return new ToolLoopAgent({
     id: 'skill-extractor',
     model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+    headers: buildBifrostCacheHeaders('skill-extractor'),
     providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
     ...resolveHelperAgentOptions(options, {
       instructions: skillExtractorPrompt,

package/src/system-agents/skill-manager.agent.ts

@@ -2,6 +2,7 @@ import { ToolLoopAgent } from 'ai'
 import { z } from 'zod'
 
 import { bifrostOpenRouterResponseHealingModel } from '../bifrost/bifrost'
+import { buildBifrostCacheHeaders } from '../bifrost/cache-headers'
 import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
   OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
@@ -69,6 +70,7 @@ export function createSkillManagerAgent(options: CreateHelperToolLoopAgentOption
   return new ToolLoopAgent({
     id: 'skill-manager',
     model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+    headers: buildBifrostCacheHeaders('skill-manager'),
     providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
     ...resolveHelperAgentOptions(options, {
       instructions: skillManagerPrompt,

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

@@ -1,6 +1,7 @@
 import { ToolLoopAgent } from 'ai'
 
 import { bifrostModel } from '../bifrost/bifrost'
+import { buildBifrostCacheHeaders } from '../bifrost/cache-headers'
 import {
   OPENROUTER_FAST_REASONING_MODEL_ID,
   OPENROUTER_MINIMAL_REASONING_PROVIDER_OPTIONS,
@@ -33,6 +34,7 @@ export function createWorkstreamTitleGeneratorAgent(options: CreateHelperToolLoo
   return new ToolLoopAgent({
     id: 'workstream-title-generator',
     model: bifrostModel(OPENROUTER_FAST_REASONING_MODEL_ID),
+    headers: buildBifrostCacheHeaders('workstream-title-generator'),
     providerOptions: OPENROUTER_MINIMAL_REASONING_PROVIDER_OPTIONS,
     ...resolveHelperAgentOptions(options, {
       instructions: WORKSTREAM_TITLE_GENERATOR_PROMPT,

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

@@ -1,35 +1,17 @@
 import {
   CreateExecutionPlanArgsSchema,
   GetActiveExecutionPlanArgsSchema,
+  ListExecutionPlansArgsSchema,
   ResumeExecutionPlanRunArgsSchema,
   ReplaceExecutionPlanArgsSchema,
   SubmitExecutionNodeResultArgsSchema,
+  getLatestExecutionPlanResult,
 } from '@lota-sdk/shared'
-import type { ExecutionPlanToolResultData } from '@lota-sdk/shared'
 import { tool } from 'ai'
 
 import type { RecordIdRef } from '../db/record-id'
 import { executionPlanService } from '../services/execution-plan.service'
 
-function isExecutionPlanResult(value: unknown): value is ExecutionPlanToolResultData {
-  return value !== null && value !== undefined && typeof value === 'object' && 'hasPlan' in value
-}
-
-function getLatestExecutionPlanToolResult(output: unknown): ExecutionPlanToolResultData | undefined {
-  if (isExecutionPlanResult(output)) {
-    return output
-  }
-
-  if (Array.isArray(output)) {
-    for (let index = output.length - 1; index >= 0; index -= 1) {
-      const candidate = getLatestExecutionPlanToolResult(output[index])
-      if (candidate) return candidate
-    }
-  }
-
-  return undefined
-}
-
 export function createCreateExecutionPlanTool(params: {
   orgId: RecordIdRef
   workstreamId: RecordIdRef
@@ -45,6 +27,7 @@ export function createCreateExecutionPlanTool(params: {
         organizationId: params.orgId,
         workstreamId: params.workstreamId,
         leadAgentId: params.agentId,
+        dispatchMode: 'deferred',
         input,
       })
       params.onPlanChanged?.()
@@ -68,6 +51,7 @@ export function createReplaceExecutionPlanTool(params: {
         organizationId: params.orgId,
         workstreamId: params.workstreamId,
         leadAgentId: params.agentId,
+        dispatchMode: 'deferred',
         input,
       })
       params.onPlanChanged?.()
@@ -95,21 +79,31 @@ export function createSubmitExecutionNodeResultTool(params: {
       return result
     },
     toModelOutput: ({ output }) => {
-      const result = getLatestExecutionPlanToolResult(output)
+      const result = getLatestExecutionPlanResult(output)
       const summary = result?.message?.trim()
       return { type: 'text', value: summary && summary.length > 0 ? summary : 'Execution node result submitted.' }
     },
   })
 }
 
-export function createGetActiveExecutionPlanTool(params: { workstreamId: RecordIdRef }) {
+export function createListExecutionPlansTool(params: { workstreamId: RecordIdRef }) {
+  return tool({
+    description:
+      'List all active execution plans for this workstream with summary info (title, status, objective, node counts). Use getExecutionPlanDetails to inspect a specific plan.',
+    inputSchema: ListExecutionPlansArgsSchema,
+    execute: async () => await executionPlanService.listActivePlanSummaries(params.workstreamId),
+  })
+}
+
+export function createGetExecutionPlanDetailsTool(params: { workstreamId: RecordIdRef }) {
   return tool({
     description:
-      'Load the active execution run for this workstream, including graph state, node contracts, recent events, approvals, artifacts, and checkpoints when requested.',
+      'Load a specific execution run by runId, or the most recent active run if runId is omitted. Returns full graph state, node contracts, events, approvals, artifacts, and checkpoints.',
     inputSchema: GetActiveExecutionPlanArgsSchema,
     execute: async (input) =>
       await executionPlanService.getActivePlanToolResult({
         workstreamId: params.workstreamId,
+        runId: input.runId,
         includeEvents: input.includeEvents,
         includeArtifacts: input.includeArtifacts,
         includeApprovals: input.includeApprovals,

package/src/tools/index.ts

@@ -1,6 +1,5 @@
 export * from './execution-plan.tool'
 export * from './fetch-webpage.tool'
-export * from './log-hello-world.tool'
 export * from './memory-block.tool'
 export * from './read-file-parts.tool'
 export * from './remember-memory.tool'

package/src/tools/research-topic.tool.ts

@@ -1,4 +1,5 @@
 import { bifrostChatModel } from '../bifrost/bifrost'
+import { buildBifrostCacheHeaders } from '../bifrost/cache-headers'
 import {
   OPENROUTER_MEDIUM_REASONING_PROVIDER_OPTIONS,
   OPENROUTER_WEB_RESEARCH_MODEL_ID,
@@ -14,6 +15,7 @@ export const researchTopicTool = createDelegatedAgentTool({
     'Delegate a research task to a dedicated research agent that searches the web, fetches pages, and returns a synthesized markdown report. Call multiple instances in parallel for broad research across different topics.',
   model: () => bifrostChatModel(OPENROUTER_WEB_RESEARCH_MODEL_ID),
   providerOptions: OPENROUTER_MEDIUM_REASONING_PROVIDER_OPTIONS,
+  headers: buildBifrostCacheHeaders('researchTopic'),
   instructions: RESEARCHER_PROMPT,
   tools: { searchWeb: searchWebTool.create(), fetchWebpage: fetchWebpageTool.create() },
 })