@lota-sdk/core 0.1.14 → 0.1.16

package/src/services/workstream-turn.ts

@@ -4,8 +4,8 @@ import { createUIMessageStream } from 'ai'
 import { lotaDebugLogger } from '../config/debug-logger'
 import { hasApprovalRespondedParts, isApprovalContinuationRequest } from '../runtime/approval-continuation'
 import { wrapResponseWithKeepalive } from '../utils/sse-keepalive'
-import { prepareWorkstreamRunCore } from './workstream-turn-preparation'
-import type { WorkstreamTurnParams, WorkstreamApprovalContinuationParams } from './workstream-turn-preparation'
+import { prepareWorkstreamRunCore } from './workstream-turn-preparation.service'
+import type { WorkstreamTurnParams, WorkstreamApprovalContinuationParams } from './workstream-turn-preparation.service'
 
 export { hasApprovalRespondedParts, isApprovalContinuationRequest }
 export { wrapResponseWithKeepalive }

package/src/services/workstream.service.ts

@@ -1,7 +1,8 @@
-import { WORKSTREAM } from '@lota-sdk/shared'
+import { WORKSTREAM, sdkWorkstreamStatusSchema } from '@lota-sdk/shared'
 import { BoundQuery, RecordId, StringRecordId, surql } from 'surrealdb'
 
 import { agentDisplayNames, getCoreWorkstreamProfile, isAgentName } from '../config/agent-defaults'
+import { serverLogger } from '../config/logger'
 import { getWorkstreamBootstrapConfig } from '../config/workstream-defaults'
 import { BaseService } from '../db/base.service'
 import { ensureRecordId, recordIdToString } from '../db/record-id'
@@ -24,7 +25,7 @@ import { toIsoDateTimeString } from '../utils/date-time'
 import { chatRunRegistry } from './chat-run-registry.service'
 import { contextCompactionService } from './context-compaction.service'
 import { workstreamMessageService } from './workstream-message.service'
-import { WorkstreamSchema, WorkstreamStatusSchema } from './workstream.types'
+import { WorkstreamSchema } from './workstream.types'
 import type { NormalizedWorkstream, WorkstreamRecord } from './workstream.types'
 
 // Uses SurrealQL directly to keep pagination/order logic close to queries.
@@ -98,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')
   }
@@ -173,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))
@@ -219,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)
@@ -272,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)
@@ -293,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>()
@@ -302,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)
     }
@@ -368,15 +370,16 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
   async listWorkstreams(
     userId: RecordIdRef,
     orgId: RecordIdRef,
-    options: { mode: string; core?: boolean; take?: number; page?: number; includeArchived: boolean },
+    options: { mode: string; core?: boolean; take?: number; page?: number; includeArchived?: boolean },
   ): Promise<{ workstreams: NormalizedWorkstream[]; hasMore: boolean }> {
     const core = options.core === true
+    const includeArchived = options.includeArchived ?? false
     if (options.mode === 'direct' && core) {
       throw new Error('Direct workstreams cannot be queried as core workstreams')
     }
 
     if (options.mode === 'direct' || core) {
-      const query = options.includeArchived
+      const query = includeArchived
         ? LIST_ALL_WORKSTREAMS_BY_MODE_QUERY
         : LIST_ALL_WORKSTREAMS_BY_MODE_EXCLUDE_ARCHIVED_QUERY
       const workstreams = await databaseService.queryMany<typeof WorkstreamSchema>(
@@ -389,7 +392,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
 
     const take = options.take ?? WORKSTREAM.DEFAULT_PAGE_LIMIT
     const page = options.page ?? 1
-    const query = options.includeArchived ? LIST_WORKSTREAMS_QUERY : LIST_WORKSTREAMS_EXCLUDE_ARCHIVED_QUERY
+    const query = includeArchived ? LIST_WORKSTREAMS_QUERY : LIST_WORKSTREAMS_EXCLUDE_ARCHIVED_QUERY
     const workstreams = await databaseService.queryMany<typeof WorkstreamSchema>(
       new BoundQuery(query, {
         userId,
@@ -455,19 +458,15 @@ 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)
   }
 
   async updateStatus(workstreamId: RecordIdRef, status: string): Promise<NormalizedWorkstream> {
-    const validStatus = WorkstreamStatusSchema.parse(status)
+    const validStatus = sdkWorkstreamStatusSchema.parse(status)
     const existing = await this.getById(workstreamId)
     this.assertMutableWorkstream(existing, validStatus === 'archived' ? 'archive' : 'unarchive')
     const workstream = await this.update(workstreamId, { status: validStatus })
@@ -499,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> {
@@ -521,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> {
@@ -543,11 +538,19 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     return false
   }
 
-  async setCompacting(workstreamId: RecordIdRef, value: boolean): Promise<void> {
+  async markCompacting(workstreamId: RecordIdRef): Promise<void> {
+    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+    await databaseService.query<unknown>(surql`
+      UPDATE ONLY ${workstreamRef}
+      SET isCompacting = ${true}
+    `)
+  }
+
+  async clearCompacting(workstreamId: RecordIdRef): Promise<void> {
     const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
     await databaseService.query<unknown>(surql`
       UPDATE ONLY ${workstreamRef}
-      SET isCompacting = ${value}
+      SET isCompacting = ${false}
     `)
   }
 
@@ -566,7 +569,9 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     await this.update(workstreamRef, { memoryBlock: serialized })
 
     if (updatedEntries.length >= MEMORY_BLOCK_COMPACTION_TRIGGER_ENTRIES) {
-      void this.compactMemoryBlock(workstreamRef).catch(() => {})
+      void this.compactMemoryBlock(workstreamRef).catch((err: unknown) => {
+        serverLogger.warn`Memory block compaction failed for ${workstreamRef}: ${err}`
+      })
     }
 
     return this.formatMemoryBlockForPrompt({
@@ -612,7 +617,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     orgId: RecordIdRef
     excludeWorkstreamId?: RecordIdRef
     limit: number
-  }) {
+  }): Promise<NormalizedWorkstream[]> {
     let excludeCondition = ''
     const vars: Record<string, unknown> = { userId, orgId, limit }
 
@@ -647,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 {
@@ -658,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
     }
 
@@ -671,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),
@@ -682,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 } : {}),
@@ -694,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,
     }
   }
 
@@ -733,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> {
@@ -747,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,16 +1,7 @@
+import { recordIdSchema, sdkWorkstreamStatusSchema } from '@lota-sdk/shared'
 import { z } from 'zod'
 
-export interface Citation {
-  title?: string
-  url?: string
-  snippet?: string
-  source?: string
-  sourceId?: string
-  retrievedAt?: string
-}
-
 const WorkstreamModeSchema = z.enum(['direct', 'group'])
-export const WorkstreamStatusSchema = z.enum(['regular', 'archived'])
 const CoreWorkstreamTypeSchema = z.string()
 
 export interface NormalizedWorkstream {
@@ -20,7 +11,7 @@ export interface NormalizedWorkstream {
   mode: 'direct' | 'group'
   core: boolean
   coreType?: string
-  nameGenerated: boolean
+  nameGenerated: boolean // Ideally `isNameGenerated`, but maps directly to SurrealDB column `nameGenerated`
   isRunning: boolean
   isCompacting: boolean
   agentId?: string | null
@@ -32,27 +23,27 @@ export interface NormalizedWorkstream {
 }
 
 export const WorkstreamSchema = z.object({
-  id: z.any(), // RecordId
-  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: WorkstreamStatusSchema.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),
+  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.any(), // RecordId
-  organizationId: z.any(), // RecordId
+  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-storage.service.ts

@@ -15,14 +15,14 @@ import type {
   ReadableUploadMetadata,
   ReadableUploadPageMode,
   ReadableUploadPagePart,
-} from './attachments.types'
+} from './attachment-types'
 import {
   buildOrganizationDocumentStorageKey,
   buildUploadStorageKey,
   buildUploadStoragePrefix,
   readNonNegativeInteger,
   readRecord,
-} from './attachments.utils'
+} from './attachment-utils'
 
 const READ_FILE_PARTS_PAGES_PER_PART = 25
 
@@ -386,7 +386,7 @@ export function getAttachmentStorageService(): AttachmentStorageService {
 }
 
 export const attachmentStorageService = new Proxy({} as AttachmentStorageService, {
-  get(_target, prop: string) {
-    return (getAttachmentStorageService() as unknown as Record<string, unknown>)[prop]
+  get(_target, prop: string): unknown {
+    return Reflect.get(getAttachmentStorageService(), prop)
   },
 })

package/src/storage/{attachments.utils.ts → 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'
 }
@@ -48,10 +48,7 @@ export function buildOrganizationDocumentStorageKey(params: {
   return `${buildOrganizationDocumentStoragePrefix({ orgId: params.orgId, namespace: params.namespace })}${relativePath || 'document.txt'}`
 }
 
-export function readRecord(value: unknown): Record<string, unknown> | null {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
-  return value as Record<string, unknown>
-}
+export { readRecord } from '../utils/string'
 
 export function readNonNegativeInteger(value: unknown): number | null {
   return Number.isInteger(value) && typeof value === 'number' && value >= 0 ? value : null

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/storage/index.ts

@@ -1,10 +1,10 @@
 export * from './attachment-parser'
 export * from './attachment-storage.service'
 export * from './generated-document-storage.service'
-export type { MessagePartLike, ReadableUploadPageMode, ReadableUploadPagePart } from './attachments.types'
+export type { MessagePartLike, ReadableUploadPageMode, ReadableUploadPagePart } from './attachment-types'
 export {
   buildOrganizationDocumentStorageKey,
   buildUploadStorageKey,
   buildUploadStoragePrefix,
   readNonNegativeInteger,
-} from './attachments.utils'
+} from './attachment-utils'

package/src/system-agents/{context-compacter.agent.ts → context-compaction.agent.ts}

@@ -8,7 +8,7 @@ import {
 import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
-const contextCompacterPrompt = `<agent-instructions>
+const CONTEXT_COMPACTION_PROMPT = `<agent-instructions>
 You are a **Context Compacter** that produces both:
 1) a dense but shorter summary of prior context
 2) a structured state delta for durable execution continuity
@@ -36,11 +36,11 @@ Return valid data for:
 </output-format>
 </agent-instructions>`
 
-export function createContextCompacterAgent(options: CreateHelperToolLoopAgentOptions) {
+export function createContextCompactionAgent(options: CreateHelperToolLoopAgentOptions) {
   return new ToolLoopAgent({
-    id: 'context-compacter',
+    id: 'context-compaction',
     model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
     providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
-    ...resolveHelperAgentOptions(options, { instructions: contextCompacterPrompt }),
+    ...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'
 
@@ -79,6 +80,7 @@ const TERMINATION_SUFFIX = `
 When your analysis is complete, return your final answer directly as markdown text. Do not leave the task unfinished or end on a tool result without a final response.
 </termination>`
 
+const DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS = 4096
 const MAX_RETAINED_AGENT_MESSAGES = 10
 const MAX_NON_SUBSTANTIVE_AGENT_RESULT_ATTEMPTS = 2
 const NON_SUBSTANTIVE_AGENT_RESULT_RETRY_PROMPT =
@@ -135,6 +137,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
@@ -164,7 +167,7 @@ export function createDelegatedAgentTool(definition: DelegatedAgentDefinition):
               ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
               instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
               tools: agentTools,
-              maxOutputTokens: definition.maxOutputTokens ?? 4096,
+              maxOutputTokens: definition.maxOutputTokens ?? DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS,
               ...(typeof temperature === 'number' ? { temperature } : {}),
               stopWhen: [stepCountIs(maxSteps)],
               prepareStep: async ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),
@@ -205,7 +208,7 @@ export function createDelegatedAgentToolWithContext<TContext>(
               ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
               instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
               tools: agentTools,
-              maxOutputTokens: definition.maxOutputTokens ?? 4096,
+              maxOutputTokens: definition.maxOutputTokens ?? DEFAULT_DELEGATED_AGENT_MAX_OUTPUT_TOKENS,
               ...(typeof temperature === 'number' ? { temperature } : {}),
               stopWhen: [stepCountIs(maxSteps)],
               prepareStep: async ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),

package/src/system-agents/index.ts

@@ -1,4 +1,12 @@
 export * from './agent-result'
+export * from './context-compaction.agent'
 export * from './delegated-agent-factory'
 export * from './helper-agent-options'
+export * from './memory-reranker.agent'
+export * from './memory.agent'
 export * from './recent-activity-title-refiner.agent'
+export * from './regular-chat-memory-digest.agent'
+export * from './researcher.agent'
+export * from './skill-extractor.agent'
+export * from './skill-manager.agent'
+export * from './title-generator.agent'

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

@@ -8,7 +8,7 @@ import {
 import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
-export const memoryRerankerPrompt = `<agent-instructions>
+export const MEMORY_RERANKER_PROMPT = `<agent-instructions>
 You are a **Memory Reranker** that selects and organizes the most relevant memories for a user query.
 
 <task>

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

@@ -8,7 +8,7 @@ import {
 import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
-export const orgMemoryPrompt = `<agent-instructions>
+export const ORG_MEMORY_PROMPT = `<agent-instructions>
 You are an **Organization Fact Extractor** that captures only durable, explicitly stated organization facts.
 
 <task>

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

@@ -45,7 +45,7 @@ Return only the title text. No quotes, labels, JSON, markdown, or explanation.
 </agent-instructions>`
 }
 
-export const recentActivityTitleRefinerPrompt = `<agent-instructions>
+export const RECENT_ACTIVITY_TITLE_REFINER_PROMPT = `<agent-instructions>
 You are the lead agent writing the visible title for a recent activity item.
 
 <goal>