@lota-sdk/core 0.4.3 → 0.4.5

package/src/services/plan-run-data.ts

@@ -1,4 +1,9 @@
-import type { ExecutionPlanToolResultData, PlanRunRecord, SerializableExecutionPlan } from '@lota-sdk/shared'
+import type {
+  ExecutionPlanToolPlanSummary,
+  ExecutionPlanToolResultData,
+  PlanRunRecord,
+  SerializableExecutionPlan,
+} from '@lota-sdk/shared'
 
 import type { RecordIdInput } from '../db/record-id'
 import { ensureRecordId } from '../db/record-id'
@@ -7,12 +12,25 @@ import { toDatabaseDateTime } from '../utils/date-time'
 
 export type PlanRunUpdate = Omit<
   Partial<PlanRunRecord>,
-  'currentNodeId' | 'waitingNodeId' | 'replacedRunId' | 'lastCheckpointId' | 'startedAt' | 'completedAt'
+  | 'sourceThreadId'
+  | 'createdByAgentId'
+  | 'currentNodeId'
+  | 'waitingNodeId'
+  | 'replacedRunId'
+  | 'lastCheckpointId'
+  | 'scheduledAt'
+  | 'scheduleId'
+  | 'startedAt'
+  | 'completedAt'
 > & {
+  sourceThreadId?: RecordIdInput | null
+  createdByAgentId?: string | null
   currentNodeId?: string | null
   waitingNodeId?: string | null
   replacedRunId?: RecordIdInput | null
   lastCheckpointId?: RecordIdInput | null
+  scheduledAt?: string | Date | null
+  scheduleId?: RecordIdInput | null
   startedAt?: string | Date | null
   completedAt?: string | Date | null
 }
@@ -22,7 +40,21 @@ export function toRunData(run: PlanRunRecord, patch: PlanRunUpdate) {
     planSpecId: ensureRecordId(run.planSpecId, TABLES.PLAN_SPEC),
     organizationId: ensureRecordId(run.organizationId, TABLES.ORGANIZATION),
     threadId: ensureRecordId(run.threadId, TABLES.THREAD),
+    ...(patch.sourceThreadId === null
+      ? {}
+      : patch.sourceThreadId !== undefined
+        ? { sourceThreadId: ensureRecordId(patch.sourceThreadId, TABLES.THREAD) }
+        : run.sourceThreadId
+          ? { sourceThreadId: ensureRecordId(run.sourceThreadId, TABLES.THREAD) }
+          : {}),
     leadAgentId: patch.leadAgentId ?? run.leadAgentId,
+    ...(patch.createdByAgentId === null
+      ? {}
+      : patch.createdByAgentId !== undefined
+        ? { createdByAgentId: patch.createdByAgentId }
+        : run.createdByAgentId
+          ? { createdByAgentId: run.createdByAgentId }
+          : {}),
     status: patch.status ?? run.status,
     ...(patch.currentNodeId === null
       ? {}
@@ -54,6 +86,20 @@ export function toRunData(run: PlanRunRecord, patch: PlanRunUpdate) {
         : run.lastCheckpointId
           ? { lastCheckpointId: ensureRecordId(run.lastCheckpointId, TABLES.PLAN_CHECKPOINT) }
           : {}),
+    ...(patch.scheduledAt === null
+      ? {}
+      : patch.scheduledAt !== undefined
+        ? { scheduledAt: toDatabaseDateTime(patch.scheduledAt) }
+        : run.scheduledAt
+          ? { scheduledAt: toDatabaseDateTime(run.scheduledAt) }
+          : {}),
+    ...(patch.scheduleId === null
+      ? {}
+      : patch.scheduleId
+        ? { scheduleId: ensureRecordId(patch.scheduleId, TABLES.PLAN_SCHEDULE) }
+        : run.scheduleId
+          ? { scheduleId: ensureRecordId(run.scheduleId, TABLES.PLAN_SCHEDULE) }
+          : {}),
     ...(patch.startedAt === null
       ? {}
       : patch.startedAt !== undefined
@@ -71,13 +117,17 @@ export function toRunData(run: PlanRunRecord, patch: PlanRunUpdate) {
   }
 }
 
-function toSlimPlanSummary(plan: SerializableExecutionPlan): NonNullable<ExecutionPlanToolResultData['plan']> {
+export function toToolPlanSummary(plan: SerializableExecutionPlan): ExecutionPlanToolPlanSummary {
   const completed = plan.progress.completed + plan.progress.partial
   return {
     runId: plan.runId,
+    threadId: plan.threadId,
     title: plan.title,
     objective: plan.objective,
     status: plan.status,
+    leadAgentId: plan.leadAgentId,
+    ...(plan.sourceThreadId ? { sourceThreadId: plan.sourceThreadId } : {}),
+    ...(plan.createdByAgentId ? { createdByAgentId: plan.createdByAgentId } : {}),
     progress: { completed, total: plan.progress.total },
     nodes: plan.nodes.map((node) => ({
       id: node.id,
@@ -85,7 +135,23 @@ function toSlimPlanSummary(plan: SerializableExecutionPlan): NonNullable<Executi
       type: node.type,
       status: node.status,
       ownerRef: node.owner.ref,
+      objective: node.objective,
+      ownerType: node.owner.executorType,
+      artifactCount: plan.artifacts.filter((artifact) => artifact.nodeId === node.id).length,
+      approvalId:
+        plan.approvals.find((approval) => approval.nodeId === node.id && approval.status === 'pending')?.id ?? null,
+      approvalStatus:
+        plan.approvals.find((approval) => approval.nodeId === node.id && approval.status === 'pending')?.status ?? null,
+      blockedReason: node.blockedReason ?? null,
+      latestNotes: node.latestNotes ?? null,
+      startedAt: node.startedAt ?? null,
+      completedAt: node.completedAt ?? null,
+      readyAt: node.readyAt ?? null,
+      deliverableNames: node.deliverables.map((deliverable) => deliverable.name),
+      upstreamNodeIds: [...node.upstreamNodeIds],
+      downstreamNodeIds: [...node.downstreamNodeIds],
     })),
+    edges: [...plan.edges],
     activeNodeIds: plan.activeNodeIds,
     readyNodeIds: plan.readyNodeIds,
   }
@@ -96,7 +162,7 @@ export function buildExecutionPlanToolResult(params: {
   plan: SerializableExecutionPlan | null
   message: string
 }): ExecutionPlanToolResultData {
-  const slim = params.plan ? toSlimPlanSummary(params.plan) : null
+  const slim = params.plan ? toToolPlanSummary(params.plan) : null
   return {
     action: params.action,
     message: params.message,

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

@@ -37,7 +37,7 @@ import { databaseService } from '../db/service'
 import { TABLES } from '../db/tables'
 import { toIsoDateTimeString, toOptionalIsoDateTimeString } from '../utils/date-time'
 
-const ACTIVE_RUN_STATUSES = new Set(['running', 'awaiting-human', 'blocked'])
+const ACTIVE_RUN_STATUSES = new Set(['pending-approval', 'running', 'awaiting-human', 'blocked'])
 
 function buildProgress(nodeRuns: PlanNodeRunRecord[]) {
   const counts = nodeRuns.reduce(
@@ -239,6 +239,31 @@ class PlanRunService {
     return runs.filter((run) => ACTIVE_RUN_STATUSES.has(run.status))
   }
 
+  async getRunsCreatedInContext(params: {
+    organizationId: RecordIdInput
+    sourceThreadId?: RecordIdInput
+    createdByAgentId?: string
+    statuses?: ReadonlyArray<PlanRunRecord['status']>
+  }): Promise<PlanRunRecord[]> {
+    const filter: Record<string, unknown> = {
+      organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+    }
+    if (params.sourceThreadId) {
+      filter.sourceThreadId = ensureRecordId(params.sourceThreadId, TABLES.THREAD)
+    }
+    if (params.createdByAgentId) {
+      filter.createdByAgentId = params.createdByAgentId
+    }
+
+    const runs = await databaseService.findMany(TABLES.PLAN_RUN, filter, PlanRunSchema, {
+      orderBy: 'updatedAt',
+      orderDir: 'DESC',
+    })
+
+    const statuses = params.statuses ? new Set(params.statuses) : ACTIVE_RUN_STATUSES
+    return runs.filter((run) => statuses.has(run.status))
+  }
+
   async listNodeRuns(runId: RecordIdInput): Promise<PlanNodeRunRecord[]> {
     return databaseService.findMany(
       TABLES.PLAN_NODE_RUN,
@@ -435,12 +460,14 @@ class PlanRunService {
       specId: recordIdToString(spec.id, TABLES.PLAN_SPEC),
       runId: recordIdToString(run.id, TABLES.PLAN_RUN),
       threadId: recordIdToString(run.threadId, TABLES.THREAD),
+      sourceThreadId: run.sourceThreadId ? recordIdToString(run.sourceThreadId, TABLES.THREAD) : undefined,
       organizationId: recordIdToString(run.organizationId, TABLES.ORGANIZATION),
       title: spec.title,
       objective: spec.objective,
       version: spec.version,
       status: run.status,
       leadAgentId: run.leadAgentId,
+      createdByAgentId: run.createdByAgentId,
       defaultExecutionVisibility: spec.defaultExecutionVisibility,
       executionMode: spec.executionMode,
       schemaRegistry: slim ? {} : structuredClone(spec.schemaRegistry),

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/services/plan-template.service.ts

@@ -143,7 +143,10 @@ class PlanTemplateService {
     templateId: RecordIdInput
     organizationId: RecordIdInput
     threadId: RecordIdInput
+    sourceThreadId?: RecordIdInput
     leadAgentId: string
+    createdByAgentId?: string
+    requireApproval?: boolean
     overrides?: Partial<PlanDraft>
     carryForwardArtifacts?: PlanArtifactRecord[]
   }): Promise<ExecutionPlanToolResultData> {
@@ -162,7 +165,10 @@ class PlanTemplateService {
     return executionPlanService.createPlan({
       organizationId: params.organizationId,
       threadId: params.threadId,
+      sourceThreadId: params.sourceThreadId,
       leadAgentId: params.leadAgentId,
+      createdByAgentId: params.createdByAgentId,
+      requireApproval: params.requireApproval,
       input: draft,
     })
   }

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

@@ -56,10 +56,16 @@ export function createExecutionPlanTool(params: {
         case 'create': {
           const draft = extractAgentPlanDraft(parsed)
           params.validateInlinePlan?.(draft)
+          const targetThreadId = parsed.targetThreadId ?? params.threadId
+          const isCrossThreadTarget =
+            recordIdToString(targetThreadId, TABLES.THREAD) !== recordIdToString(params.threadId, TABLES.THREAD)
           result = await resolvedEpService.createPlan({
             organizationId: params.orgId,
-            threadId: parsed.targetThreadId ?? params.threadId,
+            threadId: targetThreadId,
+            ...(isCrossThreadTarget ? { sourceThreadId: params.threadId } : {}),
             leadAgentId: params.agentId,
+            createdByAgentId: params.agentId,
+            requireApproval: parsed.requireApproval ?? isCrossThreadTarget,
             input: draft,
           })
           break
@@ -101,11 +107,15 @@ export function createExecutionPlanTool(params: {
             const created = await resolvedEpService.createPlan({
               organizationId: params.orgId,
               threadId: targetThread.id,
+              sourceThreadId: params.threadId,
               leadAgentId: params.agentId,
+              createdByAgentId: params.agentId,
+              requireApproval: parsed.requireApproval ?? true,
               input: draft,
             })
             result = {
               ...created,
+              runId: created.plan?.runId ?? '',
               threadId: targetThread.id,
               threadTitle: targetThread.title,
               createdThread,
@@ -125,7 +135,8 @@ export function createExecutionPlanTool(params: {
             organizationId: params.orgId,
             threadId: params.threadId,
             leadAgentId: params.agentId,
-            input: { runId: parsed.runId, reason: parsed.reason, ...draft },
+            createdByAgentId: params.agentId,
+            input: { runId: parsed.runId, reason: parsed.reason, requireApproval: parsed.requireApproval, ...draft },
           })
           break
         }

package/src/tools/index.ts

@@ -1,6 +1,7 @@
 export * from './execution-plan.tool'
 export * from './fetch-webpage.tool'
 export * from './memory-block.tool'
+export * from './plan-approval.tool'
 export * from './read-file-parts.tool'
 export * from './remember-memory.tool'
 export * from './research-topic.tool'

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

@@ -0,0 +1,66 @@
+import { PlanApprovalArgsSchema, PlanApprovalToolResultDataSchema } from '@lota-sdk/shared'
+import { tool } from 'ai'
+
+import type { RecordIdRef } from '../db/record-id'
+import { executionPlanService } from '../services/execution-plan.service'
+import { toToolPlanSummary } from '../services/plan-run-data'
+
+type PlanApprovalExecutionPlanService = Pick<typeof executionPlanService, 'approvePlan' | 'rejectPlan'>
+
+export function createPlanApprovalTool(params: {
+  orgId: RecordIdRef
+  threadId: RecordIdRef
+  actorId: string
+  executionPlanService?: PlanApprovalExecutionPlanService
+}) {
+  const resolvedExecutionPlanService = params.executionPlanService ?? executionPlanService
+
+  return tool({
+    description:
+      'Approve, reject, or request changes to a plan that is pending approval. Use approve to start execution, reject to abort it, or modify to request a revised plan.',
+    inputSchema: PlanApprovalArgsSchema,
+    outputSchema: PlanApprovalToolResultDataSchema,
+    execute: async (input) => {
+      switch (input.action) {
+        case 'approve': {
+          const plan = await resolvedExecutionPlanService.approvePlan({
+            organizationId: params.orgId,
+            threadId: params.threadId,
+            runId: input.runId,
+            emittedBy: params.actorId,
+          })
+          const toolPlan = toToolPlanSummary(plan)
+          return {
+            action: 'approved',
+            message: `Approved execution plan "${plan.title}" and started it.`,
+            hasPlan: true,
+            status: toolPlan.status,
+            plan: toolPlan,
+          }
+        }
+        case 'reject':
+        case 'modify': {
+          const plan = await resolvedExecutionPlanService.rejectPlan({
+            organizationId: params.orgId,
+            threadId: params.threadId,
+            runId: input.runId,
+            emittedBy: params.actorId,
+            reason: input.reason,
+            resolution: input.action === 'modify' ? 'changes-requested' : 'rejected',
+          })
+          const toolPlan = toToolPlanSummary(plan)
+          return {
+            action: input.action === 'modify' ? 'changes-requested' : 'rejected',
+            message:
+              input.action === 'modify'
+                ? `Requested changes for execution plan "${plan.title}".`
+                : `Rejected execution plan "${plan.title}".`,
+            hasPlan: true,
+            status: toolPlan.status,
+            plan: toolPlan,
+          }
+        }
+      }
+    },
+  })
+}

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`