@lota-sdk/core 0.4.4 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/core",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -32,7 +32,7 @@
     "@chat-adapter/slack": "^4.23.0",
     "@chat-adapter/state-ioredis": "^4.23.0",
     "@logtape/logtape": "^2.0.5",
-    "@lota-sdk/shared": "0.4.4",
+    "@lota-sdk/shared": "0.4.6",
     "@mendable/firecrawl-js": "^4.18.1",
     "@surrealdb/node": "^3.0.3",
     "ai": "^6.0.145",

package/src/ai-gateway/ai-gateway.ts

@@ -305,17 +305,6 @@ export function injectAiGatewayExtraParamsRequestBody(
   return JSON.stringify({ ...parsed, extra_params: mergedExtraParams })
 }
 
-export function injectAiGatewayOpenAIPromptCacheRetentionRequestBody(
-  body: BodyInit | null | undefined,
-): BodyInit | null | undefined {
-  const parsed = parseAiGatewayJsonRequestBody(body)
-  if (!parsed) return body
-  if (!readString(parsed.model)?.startsWith('openai/')) return body
-  if (readString(parsed.prompt_cache_retention) !== null) return body
-
-  return JSON.stringify({ ...parsed, prompt_cache_retention: OPENAI_PROMPT_CACHE_RETENTION })
-}
-
 function createAiGatewayFetch(extraParams?: AiGatewayExtraParams): typeof fetch {
   const fetchWithMutations = (input: RequestInfo | URL, init?: RequestInit | BunFetchRequestInit) => {
     const parsedBody = parseAiGatewayJsonRequestBody(init?.body)

package/src/config/background-processing.ts

@@ -14,15 +14,6 @@ const DEFAULT_CONFIG: BackgroundProcessingConfig = {
 
 let resolvedConfig: BackgroundProcessingConfig = { ...DEFAULT_CONFIG }
 
-export function configureBackgroundProcessing(config?: Partial<BackgroundProcessingConfig>): void {
-  resolvedConfig = {
-    memoryExtractionFrequency: config?.memoryExtractionFrequency ?? DEFAULT_CONFIG.memoryExtractionFrequency,
-    skillExtractionFrequency: config?.skillExtractionFrequency ?? DEFAULT_CONFIG.skillExtractionFrequency,
-    memoryDigestFrequency: config?.memoryDigestFrequency ?? DEFAULT_CONFIG.memoryDigestFrequency,
-    memoryConsolidationFrequency: config?.memoryConsolidationFrequency ?? DEFAULT_CONFIG.memoryConsolidationFrequency,
-  }
-}
-
 export function getBackgroundProcessingConfig(): BackgroundProcessingConfig {
   return resolvedConfig
 }

package/src/config/model-constants.ts

@@ -8,7 +8,6 @@ export {
   OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
   OPENROUTER_MEDIUM_REASONING_PROVIDER_OPTIONS,
   OPENROUTER_MINIMAL_REASONING_PROVIDER_OPTIONS,
-  OPENROUTER_STRUCTURED_REASONING_MODEL_ID,
   OPENROUTER_TEAM_AGENT_MODEL_ID,
   OPENROUTER_WEB_RESEARCH_MODEL_ID,
   OPENROUTER_XHIGH_REASONING_PROVIDER_OPTIONS,

package/src/create-runtime.ts

@@ -2,7 +2,6 @@ import type { ChatMessage } from '@lota-sdk/shared'
 
 import { configureEmbeddingCache } from './ai/embedding-cache'
 import { configureAgentFactory, configureAgents } from './config/agent-defaults'
-import { configureBackgroundProcessing } from './config/background-processing'
 import { configureLotaLogger } from './config/logger'
 import { configureThreads } from './config/thread-defaults'
 import { ensureRecordId } from './db/record-id'
@@ -251,7 +250,6 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
     const redisManager = createRedisConnectionManager({ url: runtimeConfig.redis.url })
     setRedisConnectionManager(redisManager)
     configureEmbeddingCache(redisManager.getConnection(), runtimeConfig.memory.embeddingCacheTtlSeconds)
-    configureBackgroundProcessing()
     configureSocialChatHistory({ keyPrefix: runtimeConfig.socialChat?.historyRedisKeyPrefix })
 
     const socialChatAgentId = runtimeConfig.socialChat?.agentId?.trim() || 'socialChat'

package/src/db/service.ts

@@ -44,8 +44,6 @@ export interface SurrealDatabaseLogger {
   error?: (message: string) => void
 }
 
-export type BoundQueryLike = { query: string; bindings?: Record<string, unknown> }
-
 interface FindManyOptions {
   limit?: number
   offset?: number
@@ -91,18 +89,6 @@ function configureMutation(
   return builder.merge(data)
 }
 
-function isBoundQueryLike(value: unknown): value is BoundQueryLike {
-  if (!isRecord(value)) {
-    return false
-  }
-
-  if (typeof value.query !== 'string') {
-    return false
-  }
-
-  return value.bindings === undefined || isRecord(value.bindings)
-}
-
 const CONNECT_MAX_ATTEMPTS = 5
 const CONNECT_RETRY_BASE_DELAY_MS = 100
 const CONNECT_RETRY_JITTER_MS = 50
@@ -396,11 +382,7 @@ export class SurrealDBService {
     return { clause: clauses.join(' AND '), bindings }
   }
 
-  private normalizeBoundQuery(query: BoundQuery | BoundQueryLike): BoundQuery {
-    if (!(query instanceof BoundQuery) && !isBoundQueryLike(query)) {
-      throw new SurrealDBError('Invalid query object: expected a BoundQuery-like value')
-    }
-
+  private normalizeBoundQuery(query: BoundQuery): BoundQuery {
     return new BoundQuery(query.query, this.normalizeBindings(query.bindings))
   }
 
@@ -533,7 +515,7 @@ export class SurrealDBService {
   private wrapTransaction(tx: SurrealTransaction): DatabaseTransaction {
     return {
       query: async (query: unknown) => {
-        const boundQuery = this.normalizeBoundQuery(query as BoundQuery | BoundQueryLike)
+        const boundQuery = this.normalizeBoundQuery(query as BoundQuery)
         const queryText = this.resolveQueryText(boundQuery)
 
         try {
@@ -578,16 +560,16 @@ export class SurrealDBService {
     }
   }
 
-  private resolveQueryText(query: BoundQuery | BoundQueryLike): string {
+  private resolveQueryText(query: BoundQuery): string {
     return query.query
   }
 
-  async query<T>(query: BoundQuery | BoundQueryLike): Promise<T[]> {
+  async query<T>(query: BoundQuery): Promise<T[]> {
     const statements = await this.queryAll<T>(query)
     return statements.at(0) ?? []
   }
 
-  async queryAll<T>(query: BoundQuery | BoundQueryLike, schema?: z.ZodTypeAny): Promise<T[][]> {
+  async queryAll<T>(query: BoundQuery, schema?: z.ZodTypeAny): Promise<T[][]> {
     const client = await this.ensureConnected()
     const boundQuery = this.normalizeBoundQuery(query)
     const queryText = this.resolveQueryText(boundQuery)
@@ -607,13 +589,13 @@ export class SurrealDBService {
     }
   }
 
-  async queryOne<T extends z.ZodTypeAny>(query: BoundQuery | BoundQueryLike, schema: T): Promise<z.infer<T> | null> {
+  async queryOne<T extends z.ZodTypeAny>(query: BoundQuery, schema: T): Promise<z.infer<T> | null> {
     const results = await this.query<unknown>(query)
     const first = results.at(0)
     return first ? this.parseSchema(schema, first) : null
   }
 
-  async queryMany<T extends z.ZodTypeAny>(query: BoundQuery | BoundQueryLike, schema: T): Promise<z.infer<T>[]> {
+  async queryMany<T extends z.ZodTypeAny>(query: BoundQuery, schema: T): Promise<z.infer<T>[]> {
     const results = await this.query<unknown>(query)
     return results.map((row) => this.parseSchema(schema, row))
   }

package/src/queues/autonomous-job.queue.ts

@@ -129,10 +129,6 @@ export function startAutonomousJobWorker(options: AutonomousJobWorkerOptions = {
   return handle
 }
 
-export function getAutonomousJobQueueHandle(): WorkerHandle {
-  return startAutonomousJobWorker()
-}
-
 if (import.meta.main) {
   startAutonomousJobWorker()
 }

package/src/runtime/agent-runtime-policy.ts

@@ -183,7 +183,7 @@ export function buildThreadAgentToolPolicy<TAgent extends string, TSkill extends
     includeMemoryRemember: !params.onboardingActive,
     includeOrgActionSearch: !params.onboardingActive,
     includeMemoryBlockAppend: true,
-    includeReadFileParts: !params.onboardingActive,
+    includeReadFileParts: true,
     includeExecutionPlanTools: !params.onboardingActive,
     includeInspectWebsite: params.onboardingActive && params.agentId === onboardingOwnerAgentId,
     includeProceedInOnboarding: params.onboardingActive && params.agentId === onboardingOwnerAgentId,

package/src/services/artifact.service.ts

@@ -7,6 +7,7 @@ import type {
   GetArtifactResult,
   PublishArtifactArgs,
 } from '@lota-sdk/shared'
+import { BoundQuery } from 'surrealdb'
 
 import type { RecordIdInput } from '../db/record-id'
 import { ensureRecordId, recordIdToString } from '../db/record-id'
@@ -361,13 +362,10 @@ class ArtifactService {
   async listBacklinks(artifact: Pick<ArtifactRecord, 'id' | 'organizationId'>): Promise<ArtifactRecord[]> {
     const artifactId = recordIdToString(artifact.id, TABLES.ARTIFACT)
     const records = await databaseService.queryMany(
-      {
-        query: `SELECT * FROM ${TABLES.ARTIFACT} WHERE organizationId = $organizationId AND references[*].targetId CONTAINS $targetId`,
-        bindings: {
-          organizationId: ensureRecordId(artifact.organizationId, TABLES.ORGANIZATION),
-          targetId: artifactId,
-        },
-      },
+      new BoundQuery(
+        `SELECT * FROM ${TABLES.ARTIFACT} WHERE organizationId = $organizationId AND references[*].targetId CONTAINS $targetId`,
+        { organizationId: ensureRecordId(artifact.organizationId, TABLES.ORGANIZATION), targetId: artifactId },
+      ),
       ArtifactRecordSchema,
     )
     return records

package/src/services/autonomous-job.service.ts

@@ -22,7 +22,7 @@ import type {
 } from '@lota-sdk/shared'
 import type { Job } from 'bullmq'
 import { CronExpressionParser } from 'cron-parser'
-import { RecordId } from 'surrealdb'
+import { BoundQuery, RecordId } from 'surrealdb'
 import { z } from 'zod'
 
 import { ensureRecordId, recordIdToString } from '../db/record-id'
@@ -262,17 +262,14 @@ class AutonomousJobService {
 
   private async findRecoverableRunRow(autonomousJobId: RecordIdInput): Promise<AutonomousJobRunRow | null> {
     const rows = await databaseService.queryMany(
-      {
-        query: `SELECT * FROM ${TABLES.AUTONOMOUS_JOB_RUN}
+      new BoundQuery(
+        `SELECT * FROM ${TABLES.AUTONOMOUS_JOB_RUN}
           WHERE autonomousJobId = $autonomousJobId
             AND status IN $statuses
           ORDER BY createdAt DESC
           LIMIT 1`,
-        bindings: {
-          autonomousJobId: ensureRecordId(autonomousJobId, TABLES.AUTONOMOUS_JOB),
-          statuses: ['queued', 'running'],
-        },
-      },
+        { autonomousJobId: ensureRecordId(autonomousJobId, TABLES.AUTONOMOUS_JOB), statuses: ['queued', 'running'] },
+      ),
       AutonomousJobRunRowSchema,
     )
 
@@ -371,10 +368,9 @@ class AutonomousJobService {
   async recoverActiveJobs(now = new Date()): Promise<void> {
     await databaseService.connect()
     const activeRows = await databaseService.queryMany(
-      {
-        query: `SELECT * FROM ${TABLES.AUTONOMOUS_JOB} WHERE status = $status ORDER BY createdAt ASC`,
-        bindings: { status: 'active' },
-      },
+      new BoundQuery(`SELECT * FROM ${TABLES.AUTONOMOUS_JOB} WHERE status = $status ORDER BY createdAt ASC`, {
+        status: 'active',
+      }),
       AutonomousJobRowSchema,
     )
 

package/src/services/plan-agent-query.service.ts

@@ -1,5 +1,6 @@
 import type { PlanExecutionVisibility, PlanNodeSpecRecord, PlanRunRecord, PlanSpecRecord } from '@lota-sdk/shared'
 import { PlanRunSchema } from '@lota-sdk/shared'
+import { BoundQuery } from 'surrealdb'
 
 import type { RecordIdInput } from '../db/record-id'
 import { ensureRecordId, recordIdToString } from '../db/record-id'
@@ -254,10 +255,10 @@ class PlanAgentQueryService {
 
     const whereOrganization = organizationId ? ' AND organizationId = $organizationId' : ''
     return databaseService.queryMany(
-      {
-        query: `SELECT * FROM ${TABLES.PLAN_RUN} WHERE status INSIDE $statuses${whereOrganization} ORDER BY updatedAt DESC`,
+      new BoundQuery(
+        `SELECT * FROM ${TABLES.PLAN_RUN} WHERE status INSIDE $statuses${whereOrganization} ORDER BY updatedAt DESC`,
         bindings,
-      },
+      ),
       PlanRunSchema,
     )
   }

package/src/services/plan-builder.service.ts

@@ -18,10 +18,6 @@ function buildImplicitLinearEdges(draft: PlanDraft) {
 }
 
 class PlanBuilderService {
-  roleAssignment(draft: PlanDraft): PlanDraft {
-    return draft
-  }
-
   structureDesign(draft: PlanDraft): PlanDraft {
     return {
       ...draft,
@@ -63,8 +59,7 @@ class PlanBuilderService {
   }
 
   prepareDraft(draft: PlanDraft): PlanDraft {
-    const withRoles = this.roleAssignment(draft)
-    const withStructure = this.structureDesign(withRoles)
+    const withStructure = this.structureDesign(draft)
     return this.semanticCompletion(withStructure)
   }
 }

package/src/services/plan-deadline.service.ts

@@ -8,7 +8,7 @@ import type {
   PlanRunRecord,
 } from '@lota-sdk/shared'
 import { PlanEventSchema, PlanNodeRunSchema, PlanNodeSpecRecordSchema, PlanRunSchema } from '@lota-sdk/shared'
-import { RecordId } from 'surrealdb'
+import { BoundQuery, RecordId } from 'surrealdb'
 
 import type { RecordIdInput } from '../db/record-id'
 import { ensureRecordId, recordIdToString } from '../db/record-id'
@@ -185,10 +185,9 @@ class PlanDeadlineService {
     entries: Array<{ nodeRun: PlanNodeRunRecord; nodeSpec: PlanNodeSpecRecord; evaluation: DeadlineEvaluationResult }>
   }> {
     const activeNodeRuns = await databaseService.queryMany(
-      {
-        query: `SELECT * FROM ${TABLES.PLAN_NODE_RUN} WHERE status IN $statuses`,
-        bindings: { statuses: ['running', 'awaiting-human'] },
-      },
+      new BoundQuery(`SELECT * FROM ${TABLES.PLAN_NODE_RUN} WHERE status IN $statuses`, {
+        statuses: ['running', 'awaiting-human'],
+      }),
       PlanNodeRunSchema,
     )
 
@@ -380,20 +379,20 @@ class PlanDeadlineService {
 
     if (dedupeKey) {
       const existing = await databaseService.queryMany(
-        {
-          query: `SELECT * FROM ${TABLES.PLAN_EVENT}
+        new BoundQuery(
+          `SELECT * FROM ${TABLES.PLAN_EVENT}
             WHERE runId = $runId
               AND nodeId = $nodeId
               AND eventType = $eventType
               AND detail.dedupeKey = $dedupeKey
             LIMIT 1`,
-          bindings: {
+          {
             runId: ensureRecordId(params.run.id, TABLES.PLAN_RUN),
             nodeId: params.nodeRun.nodeId,
             eventType: params.eventType,
             dedupeKey,
           },
-        },
+        ),
         PlanEventSchema,
       )
       if (existing.length > 0) {

package/src/services/plan-scheduler.service.ts

@@ -1,6 +1,7 @@
 import { PlanCycleRecordSchema, PlanScheduleRecordSchema } from '@lota-sdk/shared'
 import type { PlanScheduleRecord, PlanScheduleSpec } from '@lota-sdk/shared'
 import { CronExpressionParser } from 'cron-parser'
+import { BoundQuery } from 'surrealdb'
 
 import type { RecordIdInput } from '../db/record-id'
 import { ensureRecordId, recordIdToString } from '../db/record-id'
@@ -156,10 +157,9 @@ class PlanSchedulerService {
   /** Re-enqueue BullMQ jobs for all active schedules. Called once at worker startup. */
   async recoverActiveSchedules(): Promise<void> {
     const activeSchedules = await databaseService.queryMany(
-      {
-        query: `SELECT * FROM ${TABLES.PLAN_SCHEDULE} WHERE status = $status ORDER BY nextFireAt ASC`,
-        bindings: { status: 'active' },
-      },
+      new BoundQuery(`SELECT * FROM ${TABLES.PLAN_SCHEDULE} WHERE status = $status ORDER BY nextFireAt ASC`, {
+        status: 'active',
+      }),
       PlanScheduleRecordSchema,
     )
 

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

@@ -25,3 +25,12 @@ export function assertSubstantiveAgentResult(value: string, label = 'Agent resul
 
   return normalized
 }
+
+/**
+ * Returns the normalized text if substantive, otherwise returns the fallback.
+ * Useful for delegated agent results where the agent may end on a tool call without prose output.
+ */
+export function resolveSubstantiveAgentResult(value: string, fallback: string): string {
+  const normalized = normalizeAgentResultText(value)
+  return isSubstantiveAgentResult(normalized) ? normalized : fallback
+}

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

@@ -5,6 +5,7 @@ import {
   ExecutionPlanQueryArgsSchema,
   ExecutionPlanReplaceArgsSchema,
   ExecutionPlanResumeArgsSchema,
+  ExecutionPlanUpdateNodeArgsSchema,
   SubmitExecutionNodeResultArgsSchema,
   AgentPlanDraftSchema,
   expandAgentPlanDraft,
@@ -26,6 +27,7 @@ type ExecutionPlanExecutionPlanService = Pick<
   | 'createPlan'
   | 'replacePlan'
   | 'resumeRun'
+  | 'submitNodeResult'
   | 'listActivePlanSummaries'
   | 'getActivePlanToolResult'
   | 'getActivePlansForThread'
@@ -46,7 +48,7 @@ export function createExecutionPlanTool(params: {
 
   return tool({
     description:
-      'Manage execution plans. Actions: create (inline, 1-2 nodes), create-project (dedicated project thread, 3+ nodes), replace (swap active plan), resume (resume interrupted plan).',
+      'Manage execution plans. Actions: create (inline, 1-2 nodes), create-project (dedicated project thread, 3+ nodes), replace (swap active plan), resume (resume interrupted plan), update-node (submit result for a specific node).',
     inputSchema: ExecutionPlanArgsSchema,
     execute: async (input) => {
       const parsed = parseExecutionPlanArgs(input)
@@ -148,6 +150,19 @@ export function createExecutionPlanTool(params: {
             input: { runId: parsed.runId },
           })
           break
+
+        case 'update-node':
+          result = await resolvedEpService.submitNodeResult({
+            threadId: params.threadId,
+            emittedBy: params.agentId,
+            input: {
+              runId: parsed.runId,
+              nodeId: parsed.node.id,
+              notes: parsed.node.latestNotes,
+              artifacts: parsed.node.deliverables ?? [],
+            },
+          })
+          break
       }
 
       params.onPlanChanged?.()
@@ -168,6 +183,8 @@ function parseExecutionPlanArgs(input: unknown): ExecutionPlanArgs {
       return ExecutionPlanReplaceArgsSchema.parse(parsed)
     case 'resume':
       return ExecutionPlanResumeArgsSchema.parse(parsed)
+    case 'update-node':
+      return ExecutionPlanUpdateNodeArgsSchema.parse(parsed)
   }
 }
 

package/src/workers/worker-utils.ts

@@ -5,17 +5,11 @@ import type { Job, Worker } from 'bullmq'
 
 import { chatLogger } from '../config/logger'
 import { queueJobService } from '../services/queue-job.service'
-import { truncateText } from '../utils/string'
-
 export const DEFAULT_JOB_RETENTION = { removeOnComplete: true, removeOnFail: { age: 24 * 60 * 60, count: 200 } }
 export const LOW_JOB_RETENTION = { removeOnComplete: true, removeOnFail: { age: 6 * 60 * 60, count: 50 } }
 export const LONG_JOB_LOCK_DURATION_MS = 600_000
 
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000
-const MAX_TRACE_STRING_CHARS = 2_000
-const MAX_TRACE_ARRAY_ITEMS = 12
-const MAX_TRACE_OBJECT_KEYS = 24
-const MAX_TRACE_DEPTH = 4
 
 export function getWorkerPath(workerName: string): string {
   return fileURLToPath(new URL(path.join('.', workerName), import.meta.url))
@@ -35,68 +29,6 @@ interface TracedWorkerJobLike {
   timestamp?: number
 }
 
-function truncateTraceString(value: string, maxChars = MAX_TRACE_STRING_CHARS): string {
-  return truncateText(value, maxChars)
-}
-
-function normalizeTraceValue(value: unknown, depth = 0): unknown {
-  if (value === null || value === undefined) return value
-  if (typeof value === 'string') return truncateTraceString(value)
-  if (typeof value === 'number' || typeof value === 'boolean') return value
-  if (typeof value === 'bigint') return value.toString()
-  if (typeof value === 'symbol') return value.description ? `Symbol(${value.description})` : 'Symbol()'
-  if (typeof value === 'function') return value.name ? `[function ${value.name}]` : '[function anonymous]'
-  if (value instanceof Date) return value.toISOString()
-
-  if (depth >= MAX_TRACE_DEPTH) {
-    if (Array.isArray(value)) return `[array(${value.length})]`
-    return '[object]'
-  }
-
-  if (Array.isArray(value)) {
-    return value.slice(0, MAX_TRACE_ARRAY_ITEMS).map((item) => normalizeTraceValue(item, depth + 1))
-  }
-
-  if (!(value instanceof Date) && typeof value === 'object') {
-    const record = value as Record<string, unknown>
-    return Object.fromEntries(
-      Object.entries(record)
-        .slice(0, MAX_TRACE_OBJECT_KEYS)
-        .map(([key, entryValue]) => [key, normalizeTraceValue(entryValue, depth + 1)]),
-    )
-  }
-
-  return '[unknown]'
-}
-
-function serializeTraceValue(value: unknown): string {
-  const serialized = JSON.stringify(normalizeTraceValue(value))
-  return truncateTraceString(serialized || 'null')
-}
-
-function traceTextValue(value: unknown): string {
-  if (typeof value === 'string') return truncateTraceString(value)
-  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
-    return truncateTraceString(String(value))
-  }
-  if (value instanceof Date) return value.toISOString()
-  return serializeTraceValue(value)
-}
-
-export function buildWorkerObservationMetadata(
-  queueName: string,
-  job: { id?: unknown; name: string; attemptsMade: number | null | undefined },
-): Record<string, string> {
-  return {
-    queue: traceTextValue(queueName),
-    job_name: traceTextValue(job.name),
-    ...(job.id !== undefined ? { job_id: traceTextValue(job.id) } : {}),
-    ...(job.attemptsMade !== null && job.attemptsMade !== undefined
-      ? { attempts_made: traceTextValue(job.attemptsMade) }
-      : {}),
-  }
-}
-
 export const attachWorkerEvents = (worker: Worker, name: string, logger: typeof chatLogger = chatLogger) => {
   worker.on('ready', () => {
     logger.info`${name} worker ready`