@lota-sdk/core 0.1.8 → 0.1.11

package/src/services/workstream.service.ts

@@ -20,23 +20,12 @@ import {
   parseMemoryBlock,
   serializeMemoryBlock,
 } from '../runtime/memory-block'
-import { toOptionalTrimmedString } from '../runtime/workstream-chat-helpers'
-import { WorkstreamStateSchema } from '../runtime/workstream-state'
-import type { WorkstreamState } from '../runtime/workstream-state'
 import { toIsoDateTimeString } from '../utils/date-time'
 import { chatRunRegistry } from './chat-run-registry.service'
 import { contextCompactionService } from './context-compaction.service'
 import { workstreamMessageService } from './workstream-message.service'
 import { WorkstreamSchema, WorkstreamStatusSchema } from './workstream.types'
-import type {
-  NormalizedWorkstream,
-  PublicWorkstreamApprovalState,
-  PublicWorkstreamDetail,
-  PublicWorkstreamStateFocus,
-  PublicWorkstreamStatePayload,
-  PublicWorkstreamStateProgress,
-  WorkstreamRecord,
-} from './workstream.types'
+import type { NormalizedWorkstream, WorkstreamRecord } from './workstream.types'
 
 // Uses SurrealQL directly to keep pagination/order logic close to queries.
 
@@ -146,155 +135,6 @@ function buildCoreWorkstreamId({
   return new RecordId(TABLES.WORKSTREAM, `core_${typeValue}_user_${userValue}_organization_${orgValue}`)
 }
 
-function toOptionalIsoDateTimeString(value: number | null | undefined): string | null {
-  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return null
-  return toIsoDateTimeString(new Date(value))
-}
-
-function getCompactedSummaryFocus(chatSummary: string | null): string | null {
-  if (!chatSummary) return null
-
-  const lines = chatSummary
-    .split('\n')
-    .map((line) => line.trim())
-    .filter(Boolean)
-
-  for (const line of lines) {
-    if (line.endsWith(':')) continue
-    if (line.startsWith('- ')) {
-      return toOptionalTrimmedString(line.slice(2))
-    }
-    return toOptionalTrimmedString(line)
-  }
-
-  return null
-}
-
-function parsePersistedWorkstreamState(value: unknown): WorkstreamState | null {
-  const parsed = WorkstreamStateSchema.safeParse(value)
-  return parsed.success ? parsed.data : null
-}
-
-function buildEmptyWorkstreamStateProgress(): PublicWorkstreamStateProgress {
-  return {
-    hasState: false,
-    lastUpdated: null,
-    completionRatio: null,
-    tasks: { total: 0, open: 0, inProgress: 0, done: 0, blocked: 0 },
-    constraints: { total: 0, approved: 0, candidate: 0 },
-    keyDecisions: 0,
-    openQuestions: 0,
-    risks: 0,
-    artifacts: 0,
-    agentContributions: 0,
-  }
-}
-
-function buildWorkstreamStateProgress(state: WorkstreamState | null): PublicWorkstreamStateProgress {
-  if (!state) {
-    return buildEmptyWorkstreamStateProgress()
-  }
-
-  const tasks = {
-    total: state.tasks.length,
-    open: state.tasks.filter((task) => task.status === 'open').length,
-    inProgress: state.tasks.filter((task) => task.status === 'in-progress').length,
-    done: state.tasks.filter((task) => task.status === 'done').length,
-    blocked: state.tasks.filter((task) => task.status === 'blocked').length,
-  }
-  const constraintsApproved = state.activeConstraints.filter((constraint) => constraint.approved).length
-
-  return {
-    hasState:
-      state.currentPlan !== null ||
-      state.activeConstraints.length > 0 ||
-      state.keyDecisions.length > 0 ||
-      state.tasks.length > 0 ||
-      state.openQuestions.length > 0 ||
-      state.risks.length > 0 ||
-      state.artifacts.length > 0 ||
-      state.agentContributions.length > 0 ||
-      toOptionalTrimmedString(state.approvedBy) !== null ||
-      typeof state.approvedAt === 'number' ||
-      toOptionalTrimmedString(state.approvalMessageId) !== null ||
-      toOptionalTrimmedString(state.approvalNote) !== null,
-    lastUpdated: toOptionalIsoDateTimeString(state.lastUpdated),
-    completionRatio: tasks.total > 0 ? Number((tasks.done / tasks.total).toFixed(4)) : null,
-    tasks,
-    constraints: {
-      total: state.activeConstraints.length,
-      approved: constraintsApproved,
-      candidate: state.activeConstraints.length - constraintsApproved,
-    },
-    keyDecisions: state.keyDecisions.length,
-    openQuestions: state.openQuestions.length,
-    risks: state.risks.length,
-    artifacts: state.artifacts.length,
-    agentContributions: state.agentContributions.length,
-  }
-}
-
-function buildWorkstreamApprovalState(state: WorkstreamState | null): PublicWorkstreamApprovalState | null {
-  if (!state) return null
-
-  const approvedBy = toOptionalTrimmedString(state.approvedBy)
-  const approvedAt = toOptionalIsoDateTimeString(state.approvedAt)
-  const approvalMessageId = toOptionalTrimmedString(state.approvalMessageId)
-  const approvalNote = toOptionalTrimmedString(state.approvalNote)
-
-  if (!approvedBy && !approvedAt && !approvalMessageId && !approvalNote) {
-    return null
-  }
-
-  return { approvedBy, approvedAt, approvalMessageId, approvalNote }
-}
-
-function buildWorkstreamStateFocus(
-  state: WorkstreamState | null,
-  chatSummary: string | null,
-): PublicWorkstreamStateFocus | null {
-  if (!state) {
-    const compactedSummaryFocus = getCompactedSummaryFocus(chatSummary)
-    return compactedSummaryFocus ? { kind: 'chat-summary', text: compactedSummaryFocus } : null
-  }
-
-  const currentPlan = toOptionalTrimmedString(state.currentPlan?.text)
-  if (currentPlan) {
-    return { kind: 'plan', text: currentPlan }
-  }
-
-  const latestTask =
-    [...state.tasks].reverse().find((task) => task.status === 'blocked') ??
-    [...state.tasks].reverse().find((task) => task.status === 'in-progress') ??
-    [...state.tasks].reverse().find((task) => task.status === 'open')
-  const taskTitle = toOptionalTrimmedString(latestTask?.title)
-  if (taskTitle) {
-    return { kind: 'task', text: taskTitle }
-  }
-
-  const latestQuestion = toOptionalTrimmedString(state.openQuestions.at(-1)?.text)
-  if (latestQuestion) {
-    return { kind: 'question', text: latestQuestion }
-  }
-
-  const latestDecision = toOptionalTrimmedString(state.keyDecisions.at(-1)?.decision)
-  if (latestDecision) {
-    return { kind: 'decision', text: latestDecision }
-  }
-
-  const latestAgentNote = toOptionalTrimmedString(state.agentContributions.at(-1)?.summary)
-  if (latestAgentNote) {
-    return { kind: 'agent-note', text: latestAgentNote }
-  }
-
-  const compactedSummaryFocus = getCompactedSummaryFocus(chatSummary)
-  if (compactedSummaryFocus) {
-    return { kind: 'chat-summary', text: compactedSummaryFocus }
-  }
-
-  return null
-}
-
 class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
   constructor() {
     super(TABLES.WORKSTREAM, WorkstreamSchema)
@@ -664,12 +504,30 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     await this.setActiveRunId(workstreamId, null)
   }
 
-  async persistChangeTracker(
-    workstreamId: RecordIdRef,
-    payload: { chatSummary: string; state: WorkstreamState },
-  ): Promise<void> {
+  async setActiveStreamId(workstreamId: RecordIdRef, streamId: string): Promise<void> {
+    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+    await databaseService.query<unknown>(surql`
+      UPDATE ONLY ${workstreamRef}
+      SET activeStreamId = ${streamId}
+    `)
+  }
+
+  async getActiveStreamId(workstreamId: RecordIdRef): Promise<string | null> {
+    const workstream = await this.getById(workstreamId)
+    const activeStreamId = workstream.activeStreamId
+    if (typeof activeStreamId !== 'string') return null
+    const normalized = activeStreamId.trim()
+    return normalized.length > 0 ? normalized : null
+  }
+
+  async clearActiveStreamIdIfMatches(workstreamId: RecordIdRef, streamId: string): Promise<void> {
+    const activeStreamId = await this.getActiveStreamId(workstreamId)
+    if (activeStreamId !== streamId) return
     const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
-    await this.update(workstreamRef, { chatSummary: payload.chatSummary, state: payload.state })
+    await databaseService.query<unknown>(surql`
+      UPDATE ONLY ${workstreamRef}
+      SET activeStreamId = NONE
+    `)
   }
 
   async stopActiveRun(workstreamId: RecordIdRef): Promise<boolean> {
@@ -868,22 +726,6 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     }
   }
 
-  toPublicWorkstreamDetail(workstream: WorkstreamRecord): PublicWorkstreamDetail {
-    const publicWorkstream = this.toPublicWorkstream(workstream)
-    const snapshot = parsePersistedWorkstreamState(workstream.state)
-    const chatSummary = toOptionalTrimmedString(workstream.chatSummary)
-    const progress = buildWorkstreamStateProgress(snapshot)
-    const workstreamState: PublicWorkstreamStatePayload = {
-      focus: buildWorkstreamStateFocus(snapshot, chatSummary),
-      chatSummary,
-      approval: buildWorkstreamApprovalState(snapshot),
-      progress,
-      snapshot,
-    }
-
-    return { ...publicWorkstream, workstreamState }
-  }
-
   async incrementTurnCount(workstreamId: RecordIdRef): Promise<number> {
     const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
     const result = await databaseService.query<{ turnCount: number }>(surql`

package/src/services/workstream.types.ts

@@ -1,7 +1,5 @@
 import { z } from 'zod'
 
-import type { WorkstreamState } from '../runtime/workstream-state'
-
 export interface Citation {
   title?: string
   url?: string
@@ -33,68 +31,6 @@ export interface NormalizedWorkstream {
   organizationId: string
 }
 
-export interface PublicWorkstreamStateFocus {
-  kind: 'plan' | 'task' | 'question' | 'decision' | 'agent-note' | 'chat-summary'
-  text: string
-}
-
-export interface PublicWorkstreamTaskProgress {
-  total: number
-  open: number
-  inProgress: number
-  done: number
-  blocked: number
-}
-
-export interface PublicWorkstreamConstraintProgress {
-  total: number
-  approved: number
-  candidate: number
-}
-
-export interface PublicWorkstreamStateProgress {
-  hasState: boolean
-  lastUpdated: string | null
-  completionRatio: number | null
-  tasks: PublicWorkstreamTaskProgress
-  constraints: PublicWorkstreamConstraintProgress
-  keyDecisions: number
-  openQuestions: number
-  risks: number
-  artifacts: number
-  agentContributions: number
-}
-
-export interface PublicWorkstreamApprovalState {
-  approvedBy: string | null
-  approvedAt: string | null
-  approvalMessageId: string | null
-  approvalNote: string | null
-}
-
-export interface PublicWorkstreamStatePayload {
-  focus: PublicWorkstreamStateFocus | null
-  chatSummary: string | null
-  approval: PublicWorkstreamApprovalState | null
-  progress: PublicWorkstreamStateProgress
-  snapshot: WorkstreamState | null
-}
-
-export interface PublicWorkstreamDetail {
-  id: string
-  title: string
-  status: 'regular' | 'archived'
-  mode: 'direct' | 'group'
-  core: boolean
-  coreType?: string
-  isRunning: boolean
-  isCompacting: boolean
-  agentId?: string | null
-  createdAt: string
-  updatedAt: string
-  workstreamState: PublicWorkstreamStatePayload
-}
-
 export const WorkstreamSchema = z.object({
   id: z.any(), // RecordId
   mode: WorkstreamModeSchema.optional().default('group'),
@@ -106,7 +42,8 @@ export const WorkstreamSchema = z.object({
   memoryBlock: z.string().nullish(),
   memoryBlockSummary: z.string().nullish(),
   activeRunId: z.string().nullish(),
-  chatSummary: z.string().nullish(),
+  activeStreamId: z.string().nullish(),
+  compactionSummary: z.string().nullish(),
   lastCompactedMessageId: z.string().nullish(),
   nameGenerated: z.boolean().optional().default(false),
   isCompacting: z.boolean().optional(),

package/src/system-agents/title-generator.agent.ts

@@ -8,7 +8,7 @@ import {
 import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
 import { resolveHelperAgentOptions } from './helper-agent-options'
 
-const WORKSTREAM_TITLE_MAX_TOKENS = 64
+const WORKSTREAM_TITLE_MAX_TOKENS = 512
 
 export const WORKSTREAM_TITLE_GENERATOR_PROMPT = `<agent-instructions>
 You are a **Title Generator** that creates concise chat titles.
@@ -18,7 +18,7 @@ Generate a chat title based only on the user's message.
 </task>
 
 <constraints>
-- Maximum 4-5 words
+- Maximum 3-4 words
 - Capture the core workstream or intent
 - Use natural, readable language
 - No punctuation at the end

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

@@ -1,9 +1,9 @@
 import {
   CreateExecutionPlanArgsSchema,
   GetActiveExecutionPlanArgsSchema,
-  RestartExecutionTaskArgsSchema,
+  ResumeExecutionPlanRunArgsSchema,
   ReplaceExecutionPlanArgsSchema,
-  SetExecutionTaskStatusArgsSchema,
+  SubmitExecutionNodeResultArgsSchema,
 } from '@lota-sdk/shared/schemas/tools'
 import type { ExecutionPlanToolResultData } from '@lota-sdk/shared/schemas/tools'
 import { tool } from 'ai'
@@ -34,7 +34,7 @@ export function createCreateExecutionPlanTool(params: {
 }) {
   return tool({
     description:
-      'Create a structured execution plan for multi-step work in this workstream. Use this before starting multi-step execution.',
+      'Create a contract-driven execution plan for this workstream. Nodes must define deliverables, success criteria, completion checks, and executor policy.',
     inputSchema: CreateExecutionPlanArgsSchema,
     execute: async (input) => {
       const result = await executionPlanService.createPlan({
@@ -56,7 +56,8 @@ export function createReplaceExecutionPlanTool(params: {
   onPlanChanged?: () => void
 }) {
   return tool({
-    description: 'Replace the active execution plan when the ordered steps or approach have materially changed.',
+    description:
+      'Replace the active execution run with a new contract-driven plan when the graph, contracts, or approach materially change.',
     inputSchema: ReplaceExecutionPlanArgsSchema,
     execute: async (input) => {
       const result = await executionPlanService.replacePlan({
@@ -71,48 +72,17 @@ export function createReplaceExecutionPlanTool(params: {
   })
 }
 
-export function createSetExecutionTaskStatusTool(params: {
+export function createSubmitExecutionNodeResultTool(params: {
   workstreamId: RecordIdRef
   agentId: string
   onPlanChanged?: () => void
 }) {
   return tool({
     description:
-      'Update the active execution-plan task state, including in-progress, completed, blocked, failed, or skipped outcomes.',
-    inputSchema: SetExecutionTaskStatusArgsSchema,
-    execute: async function* (input) {
-      const activePlan = await executionPlanService.getActivePlanToolResult({
-        workstreamId: params.workstreamId,
-        includeEvents: true,
-      })
-
-      if (activePlan.plan && activePlan.plan.planId === input.planId) {
-        const optimisticPlan = structuredClone(activePlan.plan)
-        const targetTask = optimisticPlan.tasks.find((task) => task.id === input.taskId)
-
-        if (targetTask) {
-          targetTask.status = input.status
-          if (input.resultStatus !== undefined) targetTask.resultStatus = input.resultStatus
-          if (input.outputSummary !== undefined) targetTask.outputSummary = input.outputSummary || undefined
-          if (input.blockedReason !== undefined) targetTask.blockedReason = input.blockedReason || undefined
-          if (input.externalRef !== undefined) targetTask.externalRef = input.externalRef || undefined
-          if (input.status === 'in-progress') {
-            optimisticPlan.status = 'executing'
-            optimisticPlan.currentTaskId = targetTask.id
-          }
-
-          yield {
-            action: 'task-status-updated',
-            message: `Updating task "${targetTask.title}".`,
-            changedTaskId: targetTask.id,
-            plan: optimisticPlan,
-            hasPlan: true,
-            status: optimisticPlan.status,
-          } satisfies ExecutionPlanToolResultData
-        }
-      }
-
-      const result = await executionPlanService.setTaskStatus({
+      'Submit the result for the currently running execution node. The executor validates outputs, artifacts, and completion checks before advancing the run.',
+    inputSchema: SubmitExecutionNodeResultArgsSchema,
+    execute: async (input) => {
+      const result = await executionPlanService.submitNodeResult({
         workstreamId: params.workstreamId,
         emittedBy: params.agentId,
         input,
@@ -123,7 +93,7 @@ export function createSetExecutionTaskStatusTool(params: {
     toModelOutput: ({ output }) => {
       const result = getLatestExecutionPlanToolResult(output)
       const summary = result?.message?.trim()
-      return { type: 'text', value: summary && summary.length > 0 ? summary : 'Execution task status updated.' }
+      return { type: 'text', value: summary && summary.length > 0 ? summary : 'Execution node result submitted.' }
     },
   })
 }
@@ -131,27 +101,31 @@ export function createSetExecutionTaskStatusTool(params: {
 export function createGetActiveExecutionPlanTool(params: { workstreamId: RecordIdRef }) {
   return tool({
     description:
-      'Load the active execution plan for this workstream, including task state and recent events when needed.',
+      'Load the active execution run for this workstream, including graph state, node contracts, recent events, approvals, artifacts, and checkpoints when requested.',
     inputSchema: GetActiveExecutionPlanArgsSchema,
     execute: async (input) =>
       await executionPlanService.getActivePlanToolResult({
         workstreamId: params.workstreamId,
         includeEvents: input.includeEvents,
+        includeArtifacts: input.includeArtifacts,
+        includeApprovals: input.includeApprovals,
+        includeCheckpoints: input.includeCheckpoints,
+        includeValidationIssues: input.includeValidationIssues,
       }),
   })
 }
 
-export function createRestartExecutionTaskTool(params: {
+export function createResumeExecutionPlanRunTool(params: {
   workstreamId: RecordIdRef
   agentId: string
   onPlanChanged?: () => void
 }) {
   return tool({
     description:
-      'Restart a failed or blocked execution-plan task and optionally reset downstream tasks back to pending.',
-    inputSchema: RestartExecutionTaskArgsSchema,
+      'Resume the active execution run from its latest checkpoint after interruption. The executor reconciles state before re-activating nodes.',
+    inputSchema: ResumeExecutionPlanRunArgsSchema,
     execute: async (input) => {
-      const result = await executionPlanService.restartTask({
+      const result = await executionPlanService.resumeRun({
         workstreamId: params.workstreamId,
         emittedBy: params.agentId,
         input,

package/src/tools/log-hello-world.tool.ts

@@ -0,0 +1,17 @@
+import { tool } from 'ai'
+import { z } from 'zod'
+
+export function createLogHelloWorldTool() {
+  return tool({
+    description: 'Logs "Hello World" to the server console. Requires user approval before running.',
+    inputSchema: z.object({
+      message: z.string().optional().describe('Optional custom message to log alongside Hello World'),
+    }),
+    needsApproval: true,
+    execute: async ({ message }: { message?: string }) => {
+      const output = message ? `Hello World: ${message}` : 'Hello World'
+      console.log('[logHelloWorld]', output)
+      return { logged: output, timestamp: new Date().toISOString() }
+    },
+  })
+}

package/src/workers/skill-extraction.runner.ts

@@ -7,7 +7,7 @@ import { ensureRecordId, recordIdToString } from '../db/record-id'
 import type { RecordIdRef } from '../db/record-id'
 import { databaseService } from '../db/service'
 import { TABLES } from '../db/tables'
-import { createDefaultEmbeddings } from '../embeddings/provider'
+import { getDefaultEmbeddings } from '../embeddings/provider'
 import type { SkillExtractionJob } from '../queues/skill-extraction.queue'
 import { createHelperModelRuntime } from '../runtime/helper-model'
 import { getRuntimeAdapters, withConfiguredWorkspaceMemoryLock } from '../runtime/runtime-extensions'
@@ -54,7 +54,7 @@ interface SkillExtractionRunResult {
   extractedSkills: number
 }
 
-const embeddings = createDefaultEmbeddings()
+const embeddings = getDefaultEmbeddings()
 
 const helperModelRuntime = createHelperModelRuntime()