@lota-sdk/core 0.1.14 → 0.1.15

package/src/queues/context-compaction.queue.ts

@@ -12,6 +12,7 @@ import {
   attachWorkerEvents,
   createTracedWorkerProcessor,
   createWorkerShutdown,
+  DEFAULT_JOB_RETENTION,
   registerShutdownSignals,
 } from '../workers/worker-utils'
 import type { WorkerHandle } from '../workers/worker-utils'
@@ -29,12 +30,7 @@ function getContextCompactionQueue(): Queue<ContextCompactionJob> {
   if (!_contextCompactionQueue) {
     _contextCompactionQueue = new Queue<ContextCompactionJob>(CONTEXT_COMPACTION_QUEUE, {
       connection: getRedisConnectionForBullMQ(),
-      defaultJobOptions: {
-        removeOnComplete: 200,
-        removeOnFail: 200,
-        attempts: 2,
-        backoff: { type: 'exponential', delay: 3_000 },
-      },
+      defaultJobOptions: { ...DEFAULT_JOB_RETENTION, attempts: 2, backoff: { type: 'exponential', delay: 3_000 } },
     })
   }
   return _contextCompactionQueue
@@ -51,11 +47,11 @@ async function processContextCompactionJob(job: Job<ContextCompactionJob>): Prom
 
   const { entityId, contextSize } = job.data
   const workstreamRef = ensureRecordId(entityId, TABLES.WORKSTREAM)
-  await workstreamService.setCompacting(workstreamRef, true)
+  await workstreamService.markCompacting(workstreamRef)
   try {
     await contextCompactionService.compactWorkstreamHistory({ workstreamId: workstreamRef, contextSize })
   } finally {
-    await workstreamService.setCompacting(workstreamRef, false)
+    await workstreamService.clearCompacting(workstreamRef)
   }
 }
 

package/src/queues/document-processor.queue.ts

@@ -4,7 +4,12 @@ import { Queue, Worker } from 'bullmq'
 import type IORedis from 'ioredis'
 
 import type { chatLogger } from '../config/logger'
-import { attachWorkerEvents, createWorkerShutdown, registerShutdownSignals } from '../workers/worker-utils'
+import {
+  attachWorkerEvents,
+  createWorkerShutdown,
+  DEFAULT_JOB_RETENTION,
+  registerShutdownSignals,
+} from '../workers/worker-utils'
 import type { WorkerHandle } from '../workers/worker-utils'
 
 export type DocumentSourceChannel = string
@@ -82,12 +87,7 @@ export function createDocumentProcessorQueueRuntime<TJob extends DocumentProcess
 
     queue = new Queue<TJob, unknown, string>(queueName, {
       connection: params.getConnectionForBullMQ(),
-      defaultJobOptions: {
-        removeOnComplete: 200,
-        removeOnFail: 200,
-        attempts: 3,
-        backoff: { type: 'exponential', delay: 1000 },
-      },
+      defaultJobOptions: { ...DEFAULT_JOB_RETENTION, attempts: 3, backoff: { type: 'exponential', delay: 1000 } },
     })
 
     return queue

package/src/queues/memory-consolidation.queue.ts

@@ -5,6 +5,8 @@ import { getRedisConnectionForBullMQ } from '../redis'
 import {
   attachWorkerEvents,
   getWorkerPath,
+  LONG_JOB_LOCK_DURATION_MS,
+  LOW_JOB_RETENTION,
   createWorkerShutdown,
   registerShutdownSignals,
 } from '../workers/worker-utils'
@@ -15,18 +17,15 @@ export interface MemoryConsolidationJob {
 }
 
 const MEMORY_CONSOLIDATION_QUEUE = 'memory-consolidation'
+const MEMORY_CONSOLIDATION_INTERVAL_MS = 24 * 60 * 60 * 1000
+const MEMORY_CONSOLIDATION_JOB_ID = 'memory-consolidation-recurring'
 
 let _memoryConsolidationQueue: Queue<MemoryConsolidationJob> | null = null
 function getMemoryConsolidationQueue(): Queue<MemoryConsolidationJob> {
   if (!_memoryConsolidationQueue) {
     _memoryConsolidationQueue = new Queue<MemoryConsolidationJob>(MEMORY_CONSOLIDATION_QUEUE, {
       connection: getRedisConnectionForBullMQ(),
-      defaultJobOptions: {
-        removeOnComplete: 50,
-        removeOnFail: 50,
-        attempts: 2,
-        backoff: { type: 'exponential', delay: 5000 },
-      },
+      defaultJobOptions: { ...LOW_JOB_RETENTION, attempts: 2, backoff: { type: 'exponential', delay: 5000 } },
     })
   }
   return _memoryConsolidationQueue
@@ -42,7 +41,7 @@ export async function scheduleRecurringConsolidation() {
   await getMemoryConsolidationQueue().add(
     'consolidate',
     {},
-    { repeat: { every: 24 * 60 * 60 * 1000 }, jobId: 'memory-consolidation-recurring' },
+    { repeat: { every: MEMORY_CONSOLIDATION_INTERVAL_MS }, jobId: MEMORY_CONSOLIDATION_JOB_ID },
   )
 }
 
@@ -51,7 +50,7 @@ export function startMemoryConsolidationWorker(options: { registerSignals?: bool
   const processorPath = getWorkerPath('memory-consolidation.worker.ts')
   const worker = new Worker(MEMORY_CONSOLIDATION_QUEUE, processorPath, {
     connection: getRedisConnectionForBullMQ(),
-    lockDuration: 600_000,
+    lockDuration: LONG_JOB_LOCK_DURATION_MS,
     concurrency: 1,
   })
 

package/src/queues/post-chat-memory.queue.ts

@@ -10,6 +10,7 @@ import {
   attachWorkerEvents,
   createTracedWorkerProcessor,
   createWorkerShutdown,
+  DEFAULT_JOB_RETENTION,
   registerShutdownSignals,
 } from '../workers/worker-utils'
 import type { WorkerHandle } from '../workers/worker-utils'
@@ -43,12 +44,7 @@ function getPostChatMemoryQueue(): Queue<PostChatMemoryExtractionJob> {
   if (!_postChatMemoryQueue) {
     _postChatMemoryQueue = new Queue<PostChatMemoryExtractionJob>(POST_CHAT_MEMORY_QUEUE, {
       connection: getRedisConnectionForBullMQ(),
-      defaultJobOptions: {
-        removeOnComplete: 200,
-        removeOnFail: 200,
-        attempts: 3,
-        backoff: { type: 'exponential', delay: 2_000 },
-      },
+      defaultJobOptions: { ...DEFAULT_JOB_RETENTION, attempts: 3, backoff: { type: 'exponential', delay: 2_000 } },
     })
   }
   return _postChatMemoryQueue

package/src/queues/recent-activity-title-refinement.queue.ts

@@ -9,6 +9,7 @@ import {
   attachWorkerEvents,
   createTracedWorkerProcessor,
   createWorkerShutdown,
+  DEFAULT_JOB_RETENTION,
   registerShutdownSignals,
 } from '../workers/worker-utils'
 import type { WorkerHandle } from '../workers/worker-utils'
@@ -26,12 +27,7 @@ function getRecentActivityTitleRefinementQueue(): Queue<RecentActivityTitleRefin
       RECENT_ACTIVITY_TITLE_REFINEMENT_QUEUE,
       {
         connection: getRedisConnectionForBullMQ(),
-        defaultJobOptions: {
-          removeOnComplete: 200,
-          removeOnFail: 200,
-          attempts: 3,
-          backoff: { type: 'exponential', delay: 2_000 },
-        },
+        defaultJobOptions: { ...DEFAULT_JOB_RETENTION, attempts: 3, backoff: { type: 'exponential', delay: 2_000 } },
       },
     )
   }

package/src/queues/regular-chat-memory-digest.queue.ts

@@ -4,7 +4,9 @@ import { serverLogger } from '../config/logger'
 import { getRedisConnectionForBullMQ } from '../redis'
 import {
   attachWorkerEvents,
+  DEFAULT_JOB_RETENTION,
   getWorkerPath,
+  LONG_JOB_LOCK_DURATION_MS,
   createWorkerShutdown,
   registerShutdownSignals,
 } from '../workers/worker-utils'
@@ -25,12 +27,7 @@ function getRegularChatMemoryDigestQueue(): Queue<RegularChatMemoryDigestJob> {
   if (!_regularChatMemoryDigestQueue) {
     _regularChatMemoryDigestQueue = new Queue<RegularChatMemoryDigestJob>(REGULAR_CHAT_MEMORY_DIGEST_QUEUE, {
       connection: getRedisConnectionForBullMQ(),
-      defaultJobOptions: {
-        removeOnComplete: 200,
-        removeOnFail: 200,
-        attempts: 2,
-        backoff: { type: 'exponential', delay: 5000 },
-      },
+      defaultJobOptions: { ...DEFAULT_JOB_RETENTION, attempts: 2, backoff: { type: 'exponential', delay: 5000 } },
     })
   }
   return _regularChatMemoryDigestQueue
@@ -54,7 +51,7 @@ export function startRegularChatMemoryDigestWorker(options: { registerSignals?:
   const worker = new Worker(REGULAR_CHAT_MEMORY_DIGEST_QUEUE, processorPath, {
     connection: getRedisConnectionForBullMQ(),
     concurrency: 1,
-    lockDuration: 600_000,
+    lockDuration: LONG_JOB_LOCK_DURATION_MS,
   })
 
   attachWorkerEvents(worker, 'Regular chat memory digest', serverLogger)

package/src/queues/skill-extraction.queue.ts

@@ -4,7 +4,9 @@ import { serverLogger } from '../config/logger'
 import { getRedisConnectionForBullMQ } from '../redis'
 import {
   attachWorkerEvents,
+  DEFAULT_JOB_RETENTION,
   getWorkerPath,
+  LONG_JOB_LOCK_DURATION_MS,
   createWorkerShutdown,
   registerShutdownSignals,
 } from '../workers/worker-utils'
@@ -22,12 +24,7 @@ function getSkillExtractionQueue(): Queue<SkillExtractionJob> {
   if (!_skillExtractionQueue) {
     _skillExtractionQueue = new Queue<SkillExtractionJob>(SKILL_EXTRACTION_QUEUE, {
       connection: getRedisConnectionForBullMQ(),
-      defaultJobOptions: {
-        removeOnComplete: 200,
-        removeOnFail: 200,
-        attempts: 2,
-        backoff: { type: 'exponential', delay: 5000 },
-      },
+      defaultJobOptions: { ...DEFAULT_JOB_RETENTION, attempts: 2, backoff: { type: 'exponential', delay: 5000 } },
     })
   }
   return _skillExtractionQueue
@@ -43,7 +40,7 @@ export function startSkillExtractionWorker(options: { registerSignals?: boolean
   const worker = new Worker(SKILL_EXTRACTION_QUEUE, processorPath, {
     connection: getRedisConnectionForBullMQ(),
     concurrency: 1,
-    lockDuration: 600_000,
+    lockDuration: LONG_JOB_LOCK_DURATION_MS,
   })
 
   attachWorkerEvents(worker, 'Skill extraction', serverLogger)

package/src/queues/workstream-title-generation.queue.ts

@@ -10,6 +10,7 @@ import {
   attachWorkerEvents,
   createTracedWorkerProcessor,
   createWorkerShutdown,
+  DEFAULT_JOB_RETENTION,
   registerShutdownSignals,
 } from '../workers/worker-utils'
 import type { WorkerHandle } from '../workers/worker-utils'
@@ -26,12 +27,7 @@ function getWorkstreamTitleGenerationQueue(): Queue<WorkstreamTitleGenerationJob
   if (!_workstreamTitleGenerationQueue) {
     _workstreamTitleGenerationQueue = new Queue<WorkstreamTitleGenerationJob>(WORKSTREAM_TITLE_GENERATION_QUEUE, {
       connection: getRedisConnectionForBullMQ(),
-      defaultJobOptions: {
-        removeOnComplete: 200,
-        removeOnFail: 200,
-        attempts: 2,
-        backoff: { type: 'exponential', delay: 2_000 },
-      },
+      defaultJobOptions: { ...DEFAULT_JOB_RETENTION, attempts: 2, backoff: { type: 'exponential', delay: 2_000 } },
     })
   }
   return _workstreamTitleGenerationQueue

package/src/redis/connection.ts

@@ -1,7 +1,7 @@
 import IORedis from 'ioredis'
 import type { RedisOptions } from 'ioredis'
 
-import { getErrorMessage } from '../utils/error'
+import { getErrorMessage } from '../utils/errors'
 
 export interface RedisConnectionLogger {
   debug?: (message: string) => void
@@ -25,20 +25,23 @@ export interface RedisConnectionManager {
 }
 
 const DEFAULT_HEALTH_CHECK_INTERVAL_MS = 30_000
+const REDIS_RETRY_STEP_MS = 50
+const REDIS_RETRY_MAX_DELAY_MS = 2000
+const REDIS_CONNECT_TIMEOUT_MS = 10_000
 
 export const DEFAULT_REDIS_OPTIONS: RedisOptions = {
   maxRetriesPerRequest: null,
   enableReadyCheck: true,
   enableOfflineQueue: true,
   retryStrategy: (times: number) => {
-    const delay = Math.min(times * 50, 2000)
+    const delay = Math.min(times * REDIS_RETRY_STEP_MS, REDIS_RETRY_MAX_DELAY_MS)
     return delay
   },
   reconnectOnError: (err: Error) => {
     const targetErrors = ['READONLY', 'ETIMEDOUT', 'ECONNREFUSED', 'EAI_AGAIN']
     return targetErrors.some((candidate) => err.message.includes(candidate))
   },
-  connectTimeout: 10000,
+  connectTimeout: REDIS_CONNECT_TIMEOUT_MS,
   lazyConnect: false,
 }
 

package/src/redis/index.ts

@@ -8,6 +8,7 @@ export {
   type RedisConnectionAccessor,
 } from './connection-accessor'
 export { withOrgMemoryLock } from './org-memory-lock'
+export { LeaseLockLostError, withRedisLeaseLock } from './redis-lease-lock'
 export { createWorkstreamResumableContext } from './stream-context'
 
 export { createRedisConnectionManager }

package/src/redis/org-memory-lock.ts

@@ -9,7 +9,7 @@ const ORG_MEMORY_LOCK_REFRESH_INTERVAL_MS = 30_000
 const ORG_MEMORY_LOCK_WAIT_LOG_INTERVAL_MS = 30_000
 const ORG_MEMORY_LOCK_MAX_WAIT_MS = 15 * 60 * 1000
 
-export async function withOrgMemoryLock<T>(orgId: string, fn: () => Promise<T>): Promise<T> {
+export async function withOrgMemoryLock<T>(orgId: string, fn: (signal: AbortSignal) => Promise<T>): Promise<T> {
   const normalizedOrgId = orgId.trim()
 
   if (!normalizedOrgId) {

package/src/redis/redis-lease-lock.ts

@@ -3,7 +3,7 @@ import { setTimeout as delay } from 'node:timers/promises'
 
 import type IORedis from 'ioredis'
 
-import { getErrorMessage } from '../utils/error'
+import { getErrorMessage } from '../utils/errors'
 
 interface RedisLeaseLockLogger {
   debug?: (message: string) => void
@@ -95,16 +95,30 @@ async function releaseLeaseLock(options: RedisLeaseLockOptions & { lockValue: st
   await options.redis.eval(RELEASE_LOCK_SCRIPT, 1, options.lockKey, options.lockValue)
 }
 
+export class LeaseLockLostError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'LeaseLockLostError'
+  }
+}
+
 function startLeaseLockRefreshLoop(
   options: Required<Pick<RedisLeaseLockOptions, 'refreshIntervalMs'>> &
     RedisLeaseLockOptions & { lockValue: string; label: string },
+  ac: AbortController,
 ): () => void {
   let stopped = false
 
   const timer = setInterval(() => {
     if (stopped) return
     void refreshLeaseLock(options).catch((error: unknown) => {
-      log(options.logger, 'warn', `Failed to refresh ${options.label} (${options.lockKey}): ${getErrorMessage(error)}`)
+      stopped = true
+      clearInterval(timer)
+      const message = `Failed to refresh ${options.label} (${options.lockKey}): ${getErrorMessage(error)}`
+      log(options.logger, 'warn', message)
+      if (!ac.signal.aborted) {
+        ac.abort(new LeaseLockLostError(message))
+      }
     })
   }, options.refreshIntervalMs)
 
@@ -116,7 +130,10 @@ function startLeaseLockRefreshLoop(
   }
 }
 
-export async function withRedisLeaseLock<T>(options: RedisLeaseLockOptions, fn: () => Promise<T>): Promise<T> {
+export async function withRedisLeaseLock<T>(
+  options: RedisLeaseLockOptions,
+  fn: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
   const lockKey = options.lockKey.trim()
   if (!lockKey) {
     throw new Error('Redis lease lock requires a non-empty lock key')
@@ -138,17 +155,33 @@ export async function withRedisLeaseLock<T>(options: RedisLeaseLockOptions, fn:
     log(options.logger, 'info', `Acquired ${label} (${lockKey}) after waiting waitedMs=${waitedMs}`)
   }
 
-  const stopRefreshLoop = startLeaseLockRefreshLoop({ ...options, lockKey, lockValue, label, refreshIntervalMs })
+  const ac = new AbortController()
+  const stopRefreshLoop = startLeaseLockRefreshLoop({ ...options, lockKey, lockValue, label, refreshIntervalMs }, ac)
   const holdStart = Date.now()
 
   try {
-    return await fn()
+    const abortPromise = new Promise<never>((_, reject) => {
+      if (ac.signal.aborted) {
+        reject(ac.signal.reason as Error)
+        return
+      }
+      ac.signal.addEventListener(
+        'abort',
+        () => {
+          reject(ac.signal.reason as Error)
+        },
+        { once: true },
+      )
+    })
+    return await Promise.race([fn(ac.signal), abortPromise])
   } finally {
     stopRefreshLoop()
     const heldMs = Date.now() - holdStart
-    await releaseLeaseLock({ ...options, lockKey, lockValue }).catch((error: unknown) => {
-      log(options.logger, 'warn', `Failed to release ${label} (${lockKey}): ${getErrorMessage(error)}`)
-    })
+    if (!ac.signal.aborted) {
+      await releaseLeaseLock({ ...options, lockKey, lockValue }).catch((error: unknown) => {
+        log(options.logger, 'warn', `Failed to release ${label} (${lockKey}): ${getErrorMessage(error)}`)
+      })
+    }
     if (heldMs >= heldInfoThresholdMs) {
       log(options.logger, 'info', `Released ${label} (${lockKey}) heldMs=${heldMs}`)
     } else {

package/src/runtime/agent-stream-helpers.ts

@@ -2,13 +2,14 @@ import type { ChatMessage } from '@lota-sdk/shared'
 import type { LanguageModelUsage, UIMessageStreamOptions } from 'ai'
 
 import { agentDisplayNames, getLeadAgentDisplayName } from '../config/agent-defaults'
+import { readRecord as _readRecord } from '../utils/string'
 
 export function readFiniteNumber(value: unknown): number | undefined {
   return typeof value === 'number' && Number.isFinite(value) ? value : undefined
 }
 
 export function readRecord(value: unknown): Record<string, unknown> | undefined {
-  return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined
+  return _readRecord(value) ?? undefined
 }
 
 export function readOpenRouterUsageCost(usage: LanguageModelUsage): { cost?: number; upstreamInferenceCost?: number } {

package/src/runtime/context-compaction-constants.ts

@@ -7,5 +7,5 @@ export const CONTEXT_COMPACTION_INCLUDED_TOOL_NAMES = ['userQuestions', 'proceed
 export const CONTEXT_COMPACTION_INCLUDED_TOOL_PREFIXES = ['linear'] as const
 export const MEMORY_BLOCK_COMPACTION_TRIGGER_ENTRIES = 15
 export const MEMORY_BLOCK_COMPACTION_CHUNK_ENTRIES = 10
-export const CONTEXT_SIZE = 200_000
+export const CONTEXT_WINDOW_TOKENS = 200_000
 export const WORKSTREAM_RAW_TAIL_MESSAGES = 6

package/src/runtime/context-compaction-runtime.ts

@@ -1,4 +1,4 @@
-import { createContextCompacterAgent } from '../system-agents/context-compacter.agent'
+import { createContextCompactionAgent } from '../system-agents/context-compaction.agent'
 import {
   buildContextCompactionPrompt,
   buildMemoryBlockCompactionPrompt,
@@ -18,6 +18,8 @@ import {
 import type { GenerateHelperStructuredParams, GenerateHelperTextParams } from './helper-model'
 import { StructuredCompactionOutputSchema } from './workstream-state'
 
+const CONTEXT_COMPACTION_MAX_OUTPUT_TOKENS = 512
+
 interface HelperModelRuntime {
   generateHelperStructured<T>(params: GenerateHelperStructuredParams<T>): Promise<T>
   generateHelperText(params: GenerateHelperTextParams): Promise<string>
@@ -32,7 +34,7 @@ interface CreateContextCompactionRuntimeDeps {
 async function runContextCompacter(helperModelRuntime: HelperModelRuntime, params: ContextCompactionRunnerParams) {
   const output = await helperModelRuntime.generateHelperStructured({
     tag: 'context-compaction',
-    createAgent: createContextCompacterAgent,
+    createAgent: createContextCompactionAgent,
     messages: [
       {
         role: 'user',
@@ -76,9 +78,9 @@ export function createWiredContextCompactionRuntime(deps: CreateContextCompactio
 
     return await helperModelRuntime.generateHelperText({
       tag: 'memory-block-compaction',
-      createAgent: createContextCompacterAgent,
+      createAgent: createContextCompactionAgent,
       messages: [{ role: 'user', content: buildMemoryBlockCompactionPrompt({ previousSummary, newEntriesText }) }],
-      maxOutputTokens: 512,
+      maxOutputTokens: CONTEXT_COMPACTION_MAX_OUTPUT_TOKENS,
     })
   }
 

package/src/runtime/context-compaction.ts

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from 'node:crypto'
 
 import type { ChatMessage } from '@lota-sdk/shared'
 
-import { readString } from '../utils/string'
+import { CHARS_PER_TOKEN_ESTIMATE, compactWhitespace, readRecord, readString } from '../utils/string'
 import {
   COMPACTION_CHUNK_MAX_CHARS,
   CONTEXT_COMPACTION_INCLUDED_TOOL_NAMES,
@@ -15,14 +15,8 @@ import {
 import {
   StructuredCompactionOutputSchema,
   WorkstreamStateDeltaSchema,
-  WORKSTREAM_STATE_MAX_ACTIVE_CONSTRAINTS,
-  WORKSTREAM_STATE_MAX_AGENT_CONTRIBUTIONS,
-  WORKSTREAM_STATE_MAX_ARTIFACTS,
-  WORKSTREAM_STATE_MAX_KEY_DECISIONS,
-  WORKSTREAM_STATE_MAX_OPEN_QUESTIONS,
-  WORKSTREAM_STATE_MAX_RISKS,
-  WORKSTREAM_STATE_MAX_TASKS,
   WorkstreamStateSchema,
+  applyWorkstreamStateCaps,
   createEmptyWorkstreamState,
   parseStructuredWorkstreamStateDelta,
 } from './workstream-state'
@@ -99,15 +93,11 @@ const PROMPT_INJECTION_PATTERN =
   /\b(ignore (all )?(previous|prior|system|developer)? instructions?|system prompt|developer prompt|tool override|jailbreak|role ?override|do not follow|bypass)\b/i
 
 function estimateTokens(text: string): number {
-  return Math.ceil(text.length / 3)
-}
-
-function normalizeWhitespace(value: string): string {
-  return value.replace(/\s+/g, ' ').trim()
+  return Math.ceil(text.length / CHARS_PER_TOKEN_ESTIMATE)
 }
 
 function sanitizeStateText(value: string): string | null {
-  const normalized = normalizeWhitespace(value)
+  const normalized = compactWhitespace(value)
   if (!normalized) return null
   if (PROMPT_INJECTION_PATTERN.test(normalized)) return null
   return normalized
@@ -116,16 +106,12 @@ function sanitizeStateText(value: string): string | null {
 function createStableId(prefix: string, ...parts: Array<string | number | undefined>): string {
   const payload = parts
     .map((part) => (part === undefined ? '' : String(part)))
-    .map((part) => normalizeWhitespace(part))
+    .map((part) => compactWhitespace(part))
     .join('|')
   const hash = createHash('sha1').update(`${prefix}|${payload}`).digest('hex').slice(0, 20)
   return `${prefix}_${hash}`
 }
 
-function readRecord(value: unknown): Record<string, unknown> | null {
-  return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : null
-}
-
 function stringifyUnknown(value: unknown): string | null {
   if (value === undefined) return null
   if (typeof value === 'string') {
@@ -141,11 +127,11 @@ function stringifyUnknown(value: unknown): string | null {
 }
 
 function appendUnique(values: string[], nextValues: string[]): string[] {
-  const seen = new Set(values.map((value) => normalizeWhitespace(value).toLowerCase()))
+  const seen = new Set(values.map((value) => compactWhitespace(value).toLowerCase()))
   const merged = [...values]
 
   for (const value of nextValues) {
-    const normalized = normalizeWhitespace(value)
+    const normalized = compactWhitespace(value)
     if (!normalized) continue
     const key = normalized.toLowerCase()
     if (seen.has(key)) continue
@@ -395,7 +381,7 @@ export function mergeStateDelta(
       const normalizedRationale = sanitizeStateText(decision.rationale)
       if (!normalizedDecision || !normalizedRationale) continue
 
-      const sourceIds = [...new Set(decision.sourceMessageIds.map((id) => normalizeWhitespace(id)).filter(Boolean))]
+      const sourceIds = [...new Set(decision.sourceMessageIds.map((id) => compactWhitespace(id)).filter(Boolean))]
       const decisionId = createStableId('decision', normalizedDecision, normalizedRationale, sourceIds.sort().join('|'))
       const alreadyExists = state.keyDecisions.some((item) => item.id === decisionId)
       if (alreadyExists) continue
@@ -403,7 +389,7 @@ export function mergeStateDelta(
         id: decisionId,
         decision: normalizedDecision,
         rationale: normalizedRationale,
-        agent: normalizeWhitespace(decision.agent),
+        agent: compactWhitespace(decision.agent),
         sourceMessageIds: sourceIds,
         confidence: decision.confidence,
         timestamp,
@@ -417,11 +403,9 @@ export function mergeStateDelta(
       if (!title) continue
 
       const externalId = sanitizeStateText(update.externalId ?? '')
-      const owner = normalizeWhitespace(update.owner)
+      const owner = compactWhitespace(update.owner)
       const taskId = externalId ? createStableId('task-external', externalId) : createStableId('task', title, owner)
-      const sourceMessageIds = [
-        ...new Set(update.sourceMessageIds.map((id) => normalizeWhitespace(id)).filter(Boolean)),
-      ]
+      const sourceMessageIds = [...new Set(update.sourceMessageIds.map((id) => compactWhitespace(id)).filter(Boolean))]
       const existingIndex = state.tasks.findIndex((task) => task.id === taskId)
       const nextTask = {
         id: taskId,
@@ -455,7 +439,7 @@ export function mergeStateDelta(
       const artifactId = createStableId('artifact', name, pointer)
       const exists = state.artifacts.some((item) => item.id === artifactId)
       if (exists) continue
-      state.artifacts.push({ id: artifactId, name, type: normalizeWhitespace(artifact.type), pointer, timestamp })
+      state.artifacts.push({ id: artifactId, name, type: compactWhitespace(artifact.type), pointer, timestamp })
     }
   }
 
@@ -495,13 +479,7 @@ export function mergeStateDelta(
     state.approvalNote = sanitizeStateText(delta.approvalNote) ?? undefined
   }
 
-  state.keyDecisions = state.keyDecisions.slice(-WORKSTREAM_STATE_MAX_KEY_DECISIONS)
-  state.activeConstraints = state.activeConstraints.slice(-WORKSTREAM_STATE_MAX_ACTIVE_CONSTRAINTS)
-  state.tasks = state.tasks.slice(-WORKSTREAM_STATE_MAX_TASKS)
-  state.openQuestions = state.openQuestions.slice(-WORKSTREAM_STATE_MAX_OPEN_QUESTIONS)
-  state.risks = state.risks.slice(-WORKSTREAM_STATE_MAX_RISKS)
-  state.artifacts = state.artifacts.slice(-WORKSTREAM_STATE_MAX_ARTIFACTS)
-  state.agentContributions = state.agentContributions.slice(-WORKSTREAM_STATE_MAX_AGENT_CONTRIBUTIONS)
+  applyWorkstreamStateCaps(state)
 
   return WorkstreamStateSchema.parse(state)
 }
@@ -727,9 +705,12 @@ export function createContextCompactionRuntime(
     return summaryMessage ? [summaryMessage, ...liveMessages] : [...liveMessages]
   }
 
+  const CONTEXT_OUTPUT_RESERVE_MAX_RATIO = 0.35
+  const CONTEXT_SAFETY_MARGIN_MAX_RATIO = 0.1
+
   const estimateThreshold = (contextSize = 256_000): number => {
-    const reservedOutput = Math.min(outputReserveTokens, Math.floor(contextSize * 0.35))
-    const safetyMargin = Math.min(safetyMarginTokens, Math.floor(contextSize * 0.1))
+    const reservedOutput = Math.min(outputReserveTokens, Math.floor(contextSize * CONTEXT_OUTPUT_RESERVE_MAX_RATIO))
+    const safetyMargin = Math.min(safetyMarginTokens, Math.floor(contextSize * CONTEXT_SAFETY_MARGIN_MAX_RATIO))
     const reservedThreshold = contextSize - (reservedOutput + safetyMargin)
     const ratioThreshold = Math.floor(contextSize * thresholdRatio)
     return Math.max(1_000, Math.min(contextSize - 1, Math.min(reservedThreshold, ratioThreshold)))
@@ -834,7 +815,7 @@ export function createContextCompactionRuntime(
       const contextMessages = messagesToCompact.map(toContextMessageFromChatMessage)
       const sourceText = toCompactionTranscript(contextMessages)
 
-      if (!normalizeWhitespace(sourceText)) {
+      if (!compactWhitespace(sourceText)) {
         const summaryPayload = buildSyntheticSummaryPayload(summaryText)
         const outputPayload = JSON.stringify([...(summaryPayload ? [summaryPayload] : []), ...remainingMessages])
         return {

package/src/runtime/execution-plan.ts

@@ -1,6 +1,6 @@
 import type { SerializableExecutionPlan } from '@lota-sdk/shared'
 
-export const EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT = `<execution-plan-protocol>
+const EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT = `<execution-plan-protocol>
 - Before doing multi-step work, create a contract-driven execution plan instead of tracking steps only in prose.
 - Plans are graph-capable workflow contracts. Every execution node must define objective, instructions, deliverables, success criteria, completion checks, retry policy, failure policy, and tool/context policy.
 - The runtime executor owns lifecycle truth. Do not claim that a node is complete until submitExecutionNodeResult succeeds.
@@ -10,7 +10,7 @@ export const EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT = `<execution-plan-protocol>
 - If the graph, contracts, or success criteria materially change, replace the plan instead of silently drifting.
 </execution-plan-protocol>`
 
-export function formatExecutionPlanForPrompt(plan: SerializableExecutionPlan | null | undefined): string | undefined {
+function formatExecutionPlanForPrompt(plan: SerializableExecutionPlan | null | undefined): string | undefined {
   if (!plan) return undefined
 
   const payload = {

package/src/runtime/helper-model.ts

@@ -7,6 +7,8 @@ import type {
 } from 'ai'
 import type { ZodSchema } from 'zod'
 
+import { compactWhitespace } from '../utils/string'
+
 export interface HelperToolLoopAgentOptions {
   instructions?: string
   maxOutputTokens?: number
@@ -102,7 +104,7 @@ function stringifyUnknown(value: unknown, maxChars: number): string | null {
     }
   })()
 
-  const normalized = raw.replace(/\s+/g, ' ').trim()
+  const normalized = compactWhitespace(raw)
   if (!normalized) return null
   return normalized.length > maxChars ? `${normalized.slice(0, maxChars)}...` : normalized
 }

package/src/runtime/index.ts

@@ -23,4 +23,15 @@ export * from './team-consultation-prompts'
 export * from './turn-lifecycle'
 export * from './workstream-chat-helpers'
 export * from './workstream-routing-policy'
-export * from './workstream-state'
+export {
+  WorkstreamStateSchema,
+  type WorkstreamState,
+  type WorkstreamStateDelta,
+  StructuredWorkstreamStateDeltaSchema,
+  type StructuredWorkstreamStateDelta,
+  createEmptyStructuredWorkstreamStateDelta,
+  parseStructuredWorkstreamStateDelta,
+  StructuredCompactionOutputSchema,
+  type CompactionOutput,
+  createEmptyWorkstreamState,
+} from './workstream-state'