@lota-sdk/core 0.1.14 → 0.1.16

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

@@ -1,31 +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 getLatestExecutionPlanToolResult(output: unknown): ExecutionPlanToolResultData | undefined {
-  if (output && typeof output === 'object' && 'hasPlan' in output) {
-    return output as ExecutionPlanToolResultData
-  }
-
-  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
@@ -41,6 +27,7 @@ export function createCreateExecutionPlanTool(params: {
         organizationId: params.orgId,
         workstreamId: params.workstreamId,
         leadAgentId: params.agentId,
+        dispatchMode: 'deferred',
         input,
       })
       params.onPlanChanged?.()
@@ -64,6 +51,7 @@ export function createReplaceExecutionPlanTool(params: {
         organizationId: params.orgId,
         workstreamId: params.workstreamId,
         leadAgentId: params.agentId,
+        dispatchMode: 'deferred',
         input,
       })
       params.onPlanChanged?.()
@@ -91,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/fetch-webpage.tool.ts

@@ -2,10 +2,10 @@ import { tool } from 'ai'
 import { z } from 'zod'
 
 import type { ToolDefinition } from '../ai/definitions'
-import type { Citation } from '../services/workstream.types'
 import { withTimeout } from '../utils/async'
 import { readStringField, truncateOptionalText } from '../utils/string'
 import { getFirecrawlClient } from './firecrawl-client'
+import type { WebCitation } from './tool-contracts'
 
 const TOOL_TIMEOUT_MS = 30_000
 const FormatSchema = z.enum(['markdown', 'html', 'rawHtml', 'links', 'images', 'screenshot', 'summary'])
@@ -14,6 +14,11 @@ const MAX_SUMMARY_CHARS = 1_200
 const MAX_LINKS = 25
 const MAX_IMAGES = 10
 
+function toRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  return value as Record<string, unknown>
+}
+
 function readStringList(record: Record<string, unknown>, key: string, maxItems: number): string[] {
   const value = record[key]
   if (!Array.isArray(value)) return []
@@ -24,15 +29,12 @@ function readStringList(record: Record<string, unknown>, key: string, maxItems:
 }
 
 function summarizeDocument(url: string, document: unknown): Record<string, unknown> {
-  if (!document || typeof document !== 'object' || Array.isArray(document)) {
+  const record = toRecord(document)
+  if (!record) {
     return { url }
   }
 
-  const record = document as Record<string, unknown>
-  const metadata =
-    record.metadata && typeof record.metadata === 'object' && !Array.isArray(record.metadata)
-      ? (record.metadata as Record<string, unknown>)
-      : {}
+  const metadata = toRecord(record.metadata) ?? {}
 
   const canonicalUrl = truncateOptionalText(
     readStringField(metadata, 'url') ?? readStringField(metadata, 'sourceURL') ?? readStringField(record, 'url') ?? url,
@@ -51,8 +53,8 @@ function summarizeDocument(url: string, document: unknown): Record<string, unkno
             return truncateOptionalText(image, 500)
           }
 
-          if (image && typeof image === 'object' && !Array.isArray(image)) {
-            const imageRecord = image as Record<string, unknown>
+          const imageRecord = toRecord(image)
+          if (imageRecord) {
             return truncateOptionalText(readStringField(imageRecord, 'src') ?? readStringField(imageRecord, 'url'), 500)
           }
 
@@ -73,18 +75,18 @@ function summarizeDocument(url: string, document: unknown): Record<string, unkno
   }
 }
 
-function buildFetchCitations(url: string, document: unknown): Citation[] {
+function buildFetchCitations(url: string, document: unknown): WebCitation[] {
   const fallbackUrl = url.trim()
   let sourceId = fallbackUrl
 
-  if (document && typeof document === 'object') {
-    const metadata = (document as Record<string, unknown>).metadata
-    if (metadata && typeof metadata === 'object') {
-      const record = metadata as Record<string, unknown>
-      if (typeof record.url === 'string' && record.url.trim().length > 0) {
-        sourceId = record.url.trim()
-      } else if (typeof record.sourceURL === 'string' && record.sourceURL.trim().length > 0) {
-        sourceId = record.sourceURL.trim()
+  const docRecord = toRecord(document)
+  if (docRecord) {
+    const metadataRecord = toRecord(docRecord.metadata)
+    if (metadataRecord) {
+      if (typeof metadataRecord.url === 'string' && metadataRecord.url.trim().length > 0) {
+        sourceId = metadataRecord.url.trim()
+      } else if (typeof metadataRecord.sourceURL === 'string' && metadataRecord.sourceURL.trim().length > 0) {
+        sourceId = metadataRecord.sourceURL.trim()
       }
     }
   }

package/src/tools/index.ts

@@ -1,12 +1,11 @@
 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'
 export * from './research-topic.tool'
-export * from './search-tools'
+export * from './search.tool'
 export * from './search-web.tool'
 export * from './team-think.tool'
-export * from './tool-contract'
+export * from './tool-contracts'
 export * from './user-questions.tool'

package/src/tools/read-file-parts.tool.ts

@@ -3,7 +3,7 @@ import { z } from 'zod'
 
 import type { ToolDefinition } from '../ai/definitions'
 import { attachmentStorageService } from '../storage/attachment-storage.service'
-import type { ReadableUploadMetadata } from '../storage/attachments.types'
+import type { ReadableUploadMetadata } from '../storage/attachment-types'
 
 const PAGES_PER_PART = 25
 

package/src/tools/search-web.tool.ts

@@ -2,22 +2,26 @@ import { tool } from 'ai'
 import { z } from 'zod'
 
 import type { ToolDefinition } from '../ai/definitions'
-import type { Citation } from '../services/workstream.types'
 import { withTimeout } from '../utils/async'
 import { readStringField, truncateOptionalText } from '../utils/string'
 import { getFirecrawlClient } from './firecrawl-client'
+import type { WebCitation } from './tool-contracts'
 
 const TOOL_TIMEOUT_MS = 30_000
 const SourceSchema = z.enum(['web', 'news', 'images'])
 const MAX_RESULTS_PER_SOURCE = 4
 const MAX_SNIPPET_CHARS = 320
 
+function toRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  return value as Record<string, unknown>
+}
+
 function readMetadata(item: unknown): Record<string, unknown> {
-  if (!item || typeof item !== 'object') return {}
-  const metadata = (item as Record<string, unknown>).metadata
-  return metadata && typeof metadata === 'object' && !Array.isArray(metadata)
-    ? (metadata as Record<string, unknown>)
-    : {}
+  const record = toRecord(item)
+  if (!record) return {}
+  const metadata = toRecord(record.metadata)
+  return metadata ?? {}
 }
 
 function readSearchItemSnippet(record: Record<string, unknown>, metadata: Record<string, unknown>): string | undefined {
@@ -36,9 +40,9 @@ function readSearchItemSnippet(record: Record<string, unknown>, metadata: Record
 }
 
 function summarizeSearchItem(item: unknown): Record<string, string> | null {
-  if (!item || typeof item !== 'object' || Array.isArray(item)) return null
+  const record = toRecord(item)
+  if (!record) return null
 
-  const record = item as Record<string, unknown>
   const metadata = readMetadata(item)
   const url = extractUrlFromSearchItem(item)
 
@@ -79,9 +83,9 @@ function summarizeSearchItems(items: unknown[] | undefined): Record<string, unkn
 }
 
 function extractUrlFromSearchItem(item: unknown): string | undefined {
-  if (!item || typeof item !== 'object') return undefined
+  const record = toRecord(item)
+  if (!record) return undefined
 
-  const record = item as Record<string, unknown>
   if (typeof record.url === 'string' && record.url.trim().length > 0) {
     return record.url.trim()
   }
@@ -89,9 +93,8 @@ function extractUrlFromSearchItem(item: unknown): string | undefined {
     return record.imageUrl.trim()
   }
 
-  const metadata = record.metadata
-  if (metadata && typeof metadata === 'object') {
-    const metadataRecord = metadata as Record<string, unknown>
+  const metadataRecord = toRecord(record.metadata)
+  if (metadataRecord) {
     if (typeof metadataRecord.url === 'string' && metadataRecord.url.trim().length > 0) {
       return metadataRecord.url.trim()
     }
@@ -106,9 +109,9 @@ function extractUrlFromSearchItem(item: unknown): string | undefined {
   return undefined
 }
 
-function buildWebCitations(results: { web?: unknown[]; news?: unknown[]; images?: unknown[] }): Citation[] {
+function buildWebCitations(results: { web?: unknown[]; news?: unknown[]; images?: unknown[] }): WebCitation[] {
   const seen = new Set<string>()
-  const citations: Citation[] = []
+  const citations: WebCitation[] = []
   const retrievedAt = new Date().toISOString()
 
   const append = (items: unknown[] | undefined) => {

package/src/tools/{search-tools.ts → search.tool.ts}

@@ -22,7 +22,7 @@ export function createMemorySearchTool(
       const normalizedQuery = query.trim()
       const retrieval = await memoryService.searchAllMemoriesBatched({
         orgId: orgIdString,
-        agentName: isAgentName(agentName) ? (agentName as string) : undefined,
+        agentName: isAgentName(agentName) ? agentName : undefined,
         query: normalizedQuery,
         ...(typeof options?.fastMode === 'boolean' ? { fastMode: options.fastMode } : {}),
         ...(typeof options?.allowMultiScopeRerank === 'boolean'

package/src/tools/team-think.tool.ts

@@ -9,22 +9,26 @@ import { recordIdToString } from '../db/record-id'
 import { TABLES } from '../db/tables'
 import { mergeInstructionSections } from '../runtime/instruction-sections'
 import { getRuntimeAdapters } from '../runtime/runtime-extensions'
+import type { LotaRuntimeTeamThinkToolsParams } from '../runtime/runtime-extensions'
 import { createConsultTeamTool as createConsultTeamToolSdk } from '../runtime/team-consultation-orchestrator'
 import type { DefaultRepoSections, TeamConsultationParticipantRunner } from '../runtime/team-consultation-orchestrator'
 import { buildTeamConsultationResponseGuard } from '../runtime/team-consultation-prompts'
 import type { ReadableUploadMetadata } from '../services/attachment.service'
 
-async function buildTeamThinkAgentTools(params: Record<string, unknown>): Promise<{ tools: Record<string, unknown> }> {
+async function buildTeamThinkAgentTools(
+  params: LotaRuntimeTeamThinkToolsParams,
+): Promise<{ tools: Record<string, unknown> }> {
   const builder = getRuntimeAdapters().workstream?.buildTeamThinkAgentTools
   if (!builder) {
     return { tools: {} }
   }
 
-  const result = await builder(params as never)
+  const result = await builder(params)
   return { tools: result.tools as Record<string, unknown> }
 }
 
-const TEAM_THINK_AGENT_MAX_RETRIES = 4
+const TEAM_THINK_AGENT_MAX_RETRIES = 1
+const TEAM_THINK_AGENT_MAX_STEPS = 3
 
 export function createTeamThinkTool(params: {
   historyMessages: ChatMessage[]
@@ -55,7 +59,7 @@ export function createTeamThinkTool(params: {
         mode: 'fixedWorkstreamMode',
         onboardingActive: false,
         linearInstalled: false,
-        reasoningProfile: runParams.reasoningProfile,
+        reasoningProfile: 'fast',
         systemWorkspaceDetails: runParams.systemWorkspaceDetails,
         preSeededMemoriesSection: runParams.preSeededMemoriesSection,
         retrievedKnowledgeSection: runParams.retrievedKnowledgeSection,
@@ -72,20 +76,22 @@ export function createTeamThinkTool(params: {
         workspaceIdString: recordIdToString(params.orgId, TABLES.ORGANIZATION),
         workstreamId: params.workstreamId,
         githubInstalled: params.githubInstalled,
-        provideRepoTool: params.provideRepoTool,
+        provideRepoTool: agentId !== 'mentor' && params.provideRepoTool,
         availableUploads: params.availableUploads,
         defaultRepoSections: params.defaultRepoSectionsByAgent[agentId],
         context: params.context,
         toolProviders: params.toolProviders,
       })
       const agentConfig = config as Record<string, unknown>
-      const agentFactory = createAgent as unknown as Record<string, (...args: unknown[]) => unknown>
-      const agent = agentFactory[agentConfig.id as string]({
+      const agentId_ = typeof agentConfig.id === 'string' ? agentConfig.id : agentId
+      const configuredMaxSteps = typeof agentConfig.maxSteps === 'number' ? agentConfig.maxSteps : 10
+      const maxSteps = Math.min(configuredMaxSteps, TEAM_THINK_AGENT_MAX_STEPS)
+      const agent = createAgent[agentId_]({
         mode: 'fixedWorkstreamMode',
         tools,
         extraInstructions: agentConfig.extraInstructions,
         maxRetries: TEAM_THINK_AGENT_MAX_RETRIES,
-        stopWhen: [stepCountIs(agentConfig.maxSteps as number)],
+        stopWhen: [stepCountIs(maxSteps)],
       })
       const observer = {
         run: async <T>(fn: () => T | Promise<T>): Promise<T> => fn(),

package/src/tools/{tool-contract.ts → tool-contracts.ts}

@@ -7,7 +7,6 @@ export const MutatingApprovalSchema = {
   approvalMessageId: z.string().trim().min(1).max(200).optional(),
 } as const
 
-/** @lintignore */
 export const CitationSchema = z
   .object({
     source: z.string().trim().min(1),
@@ -17,5 +16,13 @@ export const CitationSchema = z
   })
   .strict()
 
-/** @lintignore */
 export type Citation = z.infer<typeof CitationSchema>
+
+export interface WebCitation {
+  title?: string
+  url?: string
+  snippet?: string
+  source?: string
+  sourceId?: string
+  retrievedAt?: string
+}

package/src/utils/async.ts

@@ -1,4 +1,5 @@
-import { getErrorMessage } from './error'
+import { serverLogger } from '../config/logger'
+import { getErrorMessage } from './errors'
 
 class TimeoutError extends Error {
   constructor(operation: string, ms: number) {
@@ -41,7 +42,7 @@ export function createSafeEnqueue(logger: { warn: (message: string) => void }) {
   }
 }
 
-const _defaultSafeEnqueue = createSafeEnqueue({ warn: console.warn })
+const _defaultSafeEnqueue = createSafeEnqueue({ warn: (message: string) => serverLogger.warn`${message}` })
 export function safeEnqueue<T>(
   operation: () => T | Promise<T>,
   options: { operationName: string; onError?: (error: unknown) => void; logPrefix?: string },

package/src/utils/date-time.ts

@@ -1,34 +1,6 @@
-export function toIsoDateTimeString(value: unknown): string {
-  if (value instanceof Date) {
-    return value.toISOString()
-  }
+export { toIsoDateTimeString, toOptionalIsoDateTimeString } from '@lota-sdk/shared'
 
-  // Assume API boundaries already use ISO strings.
-  if (typeof value === 'string') {
-    return value
-  }
-
-  // Support unix timestamps (seconds or milliseconds).
-  if (typeof value === 'number') {
-    const millis = value < 1_000_000_000_000 ? value * 1000 : value
-    return new Date(millis).toISOString()
-  }
-
-  // Support objects that expose toISOString (e.g., SurrealDB temporal types).
-  if (value && typeof value === 'object') {
-    const maybeToIso = (value as { toISOString?: unknown }).toISOString
-    if (typeof maybeToIso === 'function') {
-      return (value as { toISOString: () => string }).toISOString()
-    }
-  }
-
-  return String(value)
-}
-
-export function toOptionalIsoDateTimeString(value: unknown): string | undefined {
-  if (value === null || value === undefined || value === '') {
-    return undefined
-  }
-
-  return toIsoDateTimeString(value)
+export function toDatabaseDateTime(value: string | Date | null | undefined): Date | undefined {
+  if (value === null || value === undefined) return undefined
+  return value instanceof Date ? value : new Date(value)
 }

package/src/utils/env.ts

@@ -0,0 +1,8 @@
+/**
+ * Reads a required environment variable. Throws if the variable is missing or empty.
+ */
+export function getRequiredEnv(key: string): string {
+  const value = process.env[key]
+  if (!value) throw new Error(`Missing required env var: ${key}`)
+  return value
+}

package/src/utils/errors.ts

@@ -1,3 +1,9 @@
+export { getErrorMessage } from '@lota-sdk/shared'
+
+export function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value))
+}
+
 export class AppError extends Error {
   public readonly code: string
   public readonly statusCode: number
@@ -26,3 +32,44 @@ export class BadRequestError extends AppError {
     super(message, 'BAD_REQUEST', 400)
   }
 }
+
+type ErrorCode =
+  | 'UNAUTHORIZED'
+  | 'FORBIDDEN'
+  | 'NOT_FOUND'
+  | 'CONFLICT'
+  | 'BAD_REQUEST'
+  | 'VALIDATION_ERROR'
+  | 'INTERNAL_SERVER_ERROR'
+  | 'HTTP_ERROR'
+  | 'TOO_MANY_REQUESTS'
+
+interface ValidationIssue {
+  path: string
+  message: string
+}
+
+export interface ErrorBody {
+  error: { code: ErrorCode; message: string; issues?: ValidationIssue[] }
+}
+
+function createErrorResponse(code: ErrorCode, message: string): ErrorBody {
+  return { error: { code, message } }
+}
+
+function createValidationErrorResponse(message: string, issues: ValidationIssue[]): ErrorBody {
+  return { error: { code: 'VALIDATION_ERROR', message, issues } }
+}
+
+export const errorResponses = {
+  unauthorized: (message = 'Invalid credentials') => createErrorResponse('UNAUTHORIZED', message),
+  forbidden: (message = 'Access denied') => createErrorResponse('FORBIDDEN', message),
+  notFound: (message: string) => createErrorResponse('NOT_FOUND', message),
+  conflict: (message: string) => createErrorResponse('CONFLICT', message),
+  badRequest: (message: string) => createErrorResponse('BAD_REQUEST', message),
+  tooManyRequests: (message = 'Too many requests') => createErrorResponse('TOO_MANY_REQUESTS', message),
+  serverError: (message = 'Internal server error') => createErrorResponse('INTERNAL_SERVER_ERROR', message),
+  validationError: (issues: ValidationIssue[], message = 'Validation failed') =>
+    createValidationErrorResponse(message, issues),
+  httpError: (message: string) => createErrorResponse('HTTP_ERROR', message),
+} as const

package/src/utils/hono-error-handler.ts

@@ -2,8 +2,7 @@ import type { ErrorHandler } from 'hono'
 import { HTTPException } from 'hono/http-exception'
 import { ZodError } from 'zod'
 
-import { getErrorMessage } from './error'
-import { AppError } from './errors'
+import { AppError, getErrorMessage } from './errors'
 
 type AppErrorLike = Pick<AppError, 'code' | 'message' | 'statusCode' | 'toResponse'> & { name?: string }
 

package/src/utils/index.ts

@@ -1,6 +1,23 @@
 export * from './async'
 export * from './date-time'
-export * from './error'
+export * from './env'
 export * from './errors'
 export * from './hono-error-handler'
-export * from './string'
+export * from './sse-keepalive'
+export {
+  CHARS_PER_TOKEN_ESTIMATE,
+  clampImportance,
+  compactRecord,
+  compactWhitespace,
+  isRecord,
+  parseLineList,
+  readRecordArray,
+  readString,
+  readStringArray,
+  readStringField,
+  slugify,
+  stringifyLineList,
+  stringifyUnknown,
+  truncateOptionalText,
+  truncateText,
+} from './string'

package/src/utils/string.ts

@@ -29,7 +29,7 @@ export function readStringField(record: Record<string, unknown>, key: string): s
  * Returns the original string when it fits within maxChars.
  */
 export function truncateText(value: string, maxChars: number): string {
-  return value.length <= maxChars ? value : `${value.slice(0, maxChars).trimEnd()}...`
+  return value.length <= maxChars ? value : `${value.slice(0, maxChars - 3).trimEnd()}...`
 }
 
 /**
@@ -49,3 +49,130 @@ export function truncateOptionalText(value: string | undefined, maxChars: number
 export function compactWhitespace(value: string): string {
   return value.trim().replace(/\s+/g, ' ')
 }
+
+/**
+ * Returns the value as a plain record if it is a non-null, non-array object,
+ * or null otherwise.
+ */
+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>
+}
+
+/**
+ * Strips null and undefined values from a record, returning a new object with only defined entries.
+ */
+export function compactRecord(value: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== null && entry !== undefined))
+}
+
+/**
+ * Converts a string into a URL-safe slug: lowercase, non-alphanumeric runs
+ * replaced with hyphens, leading/trailing hyphens stripped, capped at 80 chars.
+ */
+export function slugify(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '')
+    .slice(0, 80)
+}
+
+/**
+ * Rough character-to-token estimate used for context budget calculations.
+ */
+export const CHARS_PER_TOKEN_ESTIMATE = 3
+
+/**
+ * Converts an unknown value to a trimmed, non-empty string representation.
+ * Returns null for null, undefined, empty, or whitespace-only results.
+ *
+ * When maxChars is provided, the result is compacted and truncated.
+ * Without maxChars, strings are trimmed and objects are JSON-serialized.
+ */
+export function stringifyUnknown(value: unknown, maxChars?: number): string | null {
+  if (value === null || value === undefined) return null
+
+  const raw = (() => {
+    if (typeof value === 'string') return value
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+      return String(value)
+    }
+    if (typeof value === 'symbol') return value.description ? `Symbol(${value.description})` : 'Symbol()'
+    if (typeof value === 'function') return value.name ? `[function ${value.name}]` : '[function anonymous]'
+    if (Array.isArray(value)) {
+      try {
+        return JSON.stringify(value)
+      } catch {
+        return `[array(${value.length})]`
+      }
+    }
+
+    try {
+      return JSON.stringify(value)
+    } catch {
+      const maybeName =
+        isRecord(value) && typeof (value as { constructor?: { name?: unknown } }).constructor?.name === 'string'
+          ? (value as { constructor?: { name?: string } }).constructor?.name
+          : 'Object'
+      return `[object ${maybeName}]`
+    }
+  })()
+
+  if (maxChars !== undefined) {
+    const normalized = compactWhitespace(raw)
+    if (!normalized) return null
+    return truncateText(normalized, maxChars)
+  }
+
+  const trimmed = raw.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+/**
+ * Clamps a numeric importance/confidence value to [0, 1].
+ * Returns 0 for non-finite values.
+ */
+export function clampImportance(value: number): number {
+  if (!Number.isFinite(value)) return 0
+  return Math.max(0, Math.min(1, value))
+}
+
+/**
+ * Splits a string on newlines, trims each line, and filters empties.
+ */
+export function parseLineList(value: string): string[] {
+  return value
+    .split('\n')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+}
+
+/**
+ * Joins an array of values into a newline-separated string.
+ * Returns an empty string for non-array inputs.
+ */
+export function stringifyLineList(value: unknown): string {
+  return Array.isArray(value) ? value.map(String).join('\n') : ''
+}
+
+/**
+ * Reads an array of strings from an unknown value.
+ * Returns an empty array when the input is not an array.
+ */
+export function readStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((entry): entry is string => typeof entry === 'string')
+}
+
+/**
+ * Reads an array of plain records from an unknown value.
+ * Returns an empty array when the input is not an array.
+ */
+export function readRecordArray(value: unknown): Array<Record<string, unknown>> {
+  if (!Array.isArray(value)) return []
+  return value.filter(
+    (entry): entry is Record<string, unknown> => typeof entry === 'object' && entry !== null && !Array.isArray(entry),
+  )
+}