@lota-sdk/core 0.1.23 → 0.1.25

package/src/services/workstream.service.ts

@@ -11,10 +11,6 @@ import { databaseService } from '../db/service'
 import type { DatabaseTable } from '../db/tables'
 import { TABLES } from '../db/tables'
 import { getRedisConnection, withRedisLeaseLock } from '../redis'
-import {
-  MEMORY_BLOCK_COMPACTION_CHUNK_ENTRIES,
-  MEMORY_BLOCK_COMPACTION_TRIGGER_ENTRIES,
-} from '../runtime/context-compaction-constants'
 import {
   appendToMemoryBlock,
   compactMemoryBlockEntries,
@@ -25,44 +21,13 @@ import {
 import { toIsoDateTimeString } from '../utils/date-time'
 import { chatRunRegistry } from './chat-run-registry.service'
 import { contextCompactionService } from './context-compaction.service'
+import { MEMORY_BLOCK_COMPACTION_CHUNK_ENTRIES, MEMORY_BLOCK_COMPACTION_TRIGGER_ENTRIES } from './workstream-constants'
 import { workstreamMessageService } from './workstream-message.service'
-import { WorkstreamSchema } from './workstream.types'
-import type { NormalizedWorkstream, WorkstreamRecord } from './workstream.types'
+import { NormalizedWorkstreamSchema, PublicWorkstreamSchema, WorkstreamSchema } from './workstream.types'
+import type { NormalizedWorkstream, PublicWorkstream, WorkstreamRecord } from './workstream.types'
 
 // Uses SurrealQL directly to keep pagination/order logic close to queries.
 
-const LIST_WORKSTREAMS_QUERY = `SELECT * FROM ${TABLES.WORKSTREAM}
-WHERE userId = $userId
-  AND organizationId = $orgId
-  AND mode = $mode
-  AND core = $core
-ORDER BY updatedAt DESC
-LIMIT $limit START $offset`
-
-const LIST_WORKSTREAMS_EXCLUDE_ARCHIVED_QUERY = `SELECT * FROM ${TABLES.WORKSTREAM}
-WHERE userId = $userId
-  AND organizationId = $orgId
-  AND mode = $mode
-  AND core = $core
-  AND status = "regular"
-ORDER BY updatedAt DESC
-LIMIT $limit START $offset`
-
-const LIST_ALL_WORKSTREAMS_BY_MODE_QUERY = `SELECT * FROM ${TABLES.WORKSTREAM}
-WHERE userId = $userId
-  AND organizationId = $orgId
-  AND mode = $mode
-  AND core = $core
-ORDER BY updatedAt DESC`
-
-const LIST_ALL_WORKSTREAMS_BY_MODE_EXCLUDE_ARCHIVED_QUERY = `SELECT * FROM ${TABLES.WORKSTREAM}
-WHERE userId = $userId
-  AND organizationId = $orgId
-  AND mode = $mode
-  AND core = $core
-  AND status = "regular"
-ORDER BY updatedAt DESC`
-
 const WORKSTREAM_ACTIVE_RUN_LOCK_TTL_MS = 90_000
 const WORKSTREAM_ACTIVE_RUN_LOCK_MAX_WAIT_MS = 750
 const WORKSTREAM_ACTIVE_RUN_LOCK_RETRY_DELAY_MS = 75
@@ -116,6 +81,33 @@ function buildActiveRunLockKey(workstreamId: RecordIdRef): string {
   return `workstream-active-run:${recordIdToString(ensureRecordId(workstreamId, TABLES.WORKSTREAM), TABLES.WORKSTREAM)}`
 }
 
+function buildListWorkstreamsQuery(options: { includeArchived: boolean; paginate: boolean }): string {
+  const clauses = [
+    `SELECT * FROM ${TABLES.WORKSTREAM}`,
+    'WHERE userId = $userId',
+    '  AND organizationId = $orgId',
+    '  AND mode = $mode',
+    '  AND core = $core',
+  ]
+  if (!options.includeArchived) {
+    clauses.push('  AND status = "regular"')
+  }
+  clauses.push('ORDER BY updatedAt DESC')
+  if (options.paginate) {
+    clauses.push('LIMIT $limit START $offset')
+  }
+  return clauses.join('\n')
+}
+
+function normalizeActiveTurnValue(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null
+  }
+
+  const normalized = value.trim()
+  return normalized.length > 0 ? normalized : null
+}
+
 export class ActiveWorkstreamRunConflictError extends Error {
   constructor() {
     super('A chat run is already active.')
@@ -201,37 +193,16 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     if (mode === 'direct') {
       const agentId = requireDirectAgentId(directAgentId)
       const directWorkstreamId = buildDirectWorkstreamId({ userId, orgId, agentId })
-
-      const existing = await this.findById(directWorkstreamId)
-      if (existing) {
-        return await this.toNormalizedWorkstream(existing)
-      }
-
-      let createError: unknown = null
-
-      let workstream = await databaseService
-        .createWithId(
-          TABLES.WORKSTREAM,
-          directWorkstreamId,
-          { userId, organizationId: orgId, mode, core: false, agentId, title, status: 'regular', nameGenerated: true },
-          WorkstreamSchema,
-        )
-        .catch((error) => {
-          createError = error
-          return null
-        })
-
-      if (!workstream) {
-        workstream = await this.findById(directWorkstreamId)
-      }
-
-      if (!workstream) {
-        if (createError instanceof Error) {
-          throw createError
-        }
-        throw new Error('Failed to create or load direct workstream')
-      }
-
+      const workstream = await this.upsertDeterministicWorkstream(directWorkstreamId, {
+        userId,
+        organizationId: orgId,
+        mode,
+        core: false,
+        agentId,
+        title,
+        status: 'regular',
+        nameGenerated: true,
+      })
       return await this.toNormalizedWorkstream(workstream)
     }
 
@@ -239,46 +210,17 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
       const resolvedCoreType = requireString(coreType)
       const coreProfile = getCoreWorkstreamProfile(resolvedCoreType)
       const coreWorkstreamId = buildCoreWorkstreamId({ userId, orgId, coreType: resolvedCoreType })
-      const existing = await this.findById(coreWorkstreamId)
-      if (existing) {
-        return await this.toNormalizedWorkstream(existing)
-      }
-
-      let createError: unknown = null
-
-      let workstream = await databaseService
-        .createWithId(
-          TABLES.WORKSTREAM,
-          coreWorkstreamId,
-          {
-            userId,
-            organizationId: orgId,
-            mode,
-            core: true,
-            coreType: resolvedCoreType,
-            agentId: coreProfile.config.agentId,
-            title,
-            status: 'regular',
-            nameGenerated: true,
-          },
-          WorkstreamSchema,
-        )
-        .catch((error) => {
-          createError = error
-          return null
-        })
-
-      if (!workstream) {
-        workstream = await this.findById(coreWorkstreamId)
-      }
-
-      if (!workstream) {
-        if (createError instanceof Error) {
-          throw createError
-        }
-        throw new Error('Failed to create or load core workstream')
-      }
-
+      const workstream = await this.upsertDeterministicWorkstream(coreWorkstreamId, {
+        userId,
+        organizationId: orgId,
+        mode,
+        core: true,
+        coreType: resolvedCoreType,
+        agentId: coreProfile.config.agentId,
+        title,
+        status: 'regular',
+        nameGenerated: true,
+      })
       return await this.toNormalizedWorkstream(workstream)
     }
 
@@ -395,22 +337,23 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     }
 
     if (options.mode === 'direct' || core) {
-      const query = includeArchived
-        ? LIST_ALL_WORKSTREAMS_BY_MODE_QUERY
-        : LIST_ALL_WORKSTREAMS_BY_MODE_EXCLUDE_ARCHIVED_QUERY
       const workstreams = await databaseService.queryMany<typeof WorkstreamSchema>(
-        new BoundQuery(query, { userId, orgId, mode: options.mode, core }),
+        new BoundQuery(buildListWorkstreamsQuery({ includeArchived, paginate: false }), {
+          userId,
+          orgId,
+          mode: options.mode,
+          core,
+        }),
         WorkstreamSchema,
       )
 
-      return { workstreams: await this.toNormalizedWorkstreams(workstreams), hasMore: false }
+      return { workstreams: await this.toNormalizedWorkstreams(workstreams, { checkLease: false }), hasMore: false }
     }
 
     const take = options.take ?? WORKSTREAM.DEFAULT_PAGE_LIMIT
     const page = options.page ?? 1
-    const query = includeArchived ? LIST_WORKSTREAMS_QUERY : LIST_WORKSTREAMS_EXCLUDE_ARCHIVED_QUERY
     const workstreams = await databaseService.queryMany<typeof WorkstreamSchema>(
-      new BoundQuery(query, {
+      new BoundQuery(buildListWorkstreamsQuery({ includeArchived, paginate: true }), {
         userId,
         orgId,
         mode: options.mode,
@@ -424,7 +367,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     const hasMore = workstreams.length > take
     const sliced = hasMore ? workstreams.slice(0, take) : workstreams
 
-    return { workstreams: await this.toNormalizedWorkstreams(sliced), hasMore }
+    return { workstreams: await this.toNormalizedWorkstreams(sliced, { checkLease: false }), hasMore }
   }
 
   async listOrganizationWorkstreams(params: {
@@ -466,7 +409,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
       WorkstreamSchema,
     )
 
-    return await this.toNormalizedWorkstreams(workstreams)
+    return await this.toNormalizedWorkstreams(workstreams, { checkLease: false })
   }
 
   async getWorkstream(workstreamId: RecordIdRef): Promise<NormalizedWorkstream> {
@@ -489,28 +432,35 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     return await this.toNormalizedWorkstream(workstream)
   }
 
-  async setActiveRunId(workstreamId: RecordIdRef, runId: string | null): Promise<void> {
+  async setActiveTurn(workstreamId: RecordIdRef, runId: string, streamId?: string | null): Promise<void> {
     const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
-    if (runId === null) {
+    if (streamId === null || streamId === undefined) {
       await databaseService.query<unknown>(surql`
         UPDATE ONLY ${workstreamRef}
-        SET activeRunId = NONE
+        SET activeRunId = ${runId},
+            activeStreamId = NONE
       `)
       return
     }
 
     await databaseService.query<unknown>(surql`
       UPDATE ONLY ${workstreamRef}
-      SET activeRunId = ${runId}
+      SET activeRunId = ${runId},
+          activeStreamId = ${streamId}
     `)
   }
 
-  async getActiveRunId(workstreamId: RecordIdRef): Promise<string | null> {
+  async getActiveTurn(workstreamId: RecordIdRef): Promise<{ runId: string | null; streamId: string | null }> {
     const workstream = await this.getById(workstreamId)
-    const activeRunId = workstream.activeRunId
-    if (typeof activeRunId !== 'string') return null
-    const normalized = activeRunId.trim()
-    return normalized.length > 0 ? normalized : null
+    return {
+      runId: normalizeActiveTurnValue(workstream.activeRunId),
+      streamId: normalizeActiveTurnValue(workstream.activeStreamId),
+    }
+  }
+
+  async getActiveRunId(workstreamId: RecordIdRef): Promise<string | null> {
+    const { runId } = await this.getActiveTurn(workstreamId)
+    return runId
   }
 
   async hasActiveRunLease(workstreamId: RecordIdRef): Promise<boolean> {
@@ -540,52 +490,43 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     }
   }
 
-  async clearActiveRunIdIfMatches(workstreamId: RecordIdRef, runId: string): Promise<void> {
-    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
-    await databaseService.query(surql`UPDATE ONLY ${workstreamRef} SET activeRunId = NONE WHERE activeRunId = ${runId}`)
+  async getActiveStreamId(workstreamId: RecordIdRef): Promise<string | null> {
+    const { streamId } = await this.getActiveTurn(workstreamId)
+    return streamId
   }
 
-  async setActiveStreamId(workstreamId: RecordIdRef, streamId: string): Promise<void> {
+  async clearActiveTurn(workstreamId: RecordIdRef, params: { runId: string; streamId?: string | null }): Promise<void> {
     const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
-    await databaseService.query<unknown>(surql`
+    const currentStreamId = params.streamId ?? null
+    if (currentStreamId === null) {
+      await databaseService.query(
+        surql`UPDATE ONLY ${workstreamRef} SET activeRunId = NONE, activeStreamId = NONE WHERE activeRunId = ${params.runId}`,
+      )
+      return
+    }
+
+    await databaseService.query(surql`
       UPDATE ONLY ${workstreamRef}
-      SET activeStreamId = ${streamId}
+      SET activeRunId = NONE,
+          activeStreamId = NONE
+      WHERE activeRunId = ${params.runId} AND activeStreamId = ${currentStreamId}
     `)
   }
 
-  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 workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
-    await databaseService.query(
-      surql`UPDATE ONLY ${workstreamRef} SET activeStreamId = NONE WHERE activeStreamId = ${streamId}`,
-    )
-  }
-
   async clearStaleActiveRunIfMissingFromRegistry(workstreamId: RecordIdRef): Promise<boolean> {
-    const activeRunId = await this.getActiveRunId(workstreamId)
+    const { runId: activeRunId, streamId: activeStreamId } = await this.getActiveTurn(workstreamId)
     if (!activeRunId || (await this.hasActiveRunLease(workstreamId))) {
       return false
     }
 
-    const activeStreamId = await this.getActiveStreamId(workstreamId)
-    await Promise.all([
-      this.clearActiveRunIdIfMatches(workstreamId, activeRunId),
-      activeStreamId ? this.clearActiveStreamIdIfMatches(workstreamId, activeStreamId) : Promise.resolve(),
-    ])
+    await this.clearActiveTurn(workstreamId, { runId: activeRunId, streamId: activeStreamId })
 
     serverLogger.warn`Cleared stale workstream run after lease expired: workstream=${recordIdToString(ensureRecordId(workstreamId, TABLES.WORKSTREAM), TABLES.WORKSTREAM)} run=${activeRunId}`
     return true
   }
 
   async stopActiveRun(workstreamId: RecordIdRef): Promise<boolean> {
-    const activeRunId = await this.getActiveRunId(workstreamId)
+    const { runId: activeRunId } = await this.getActiveTurn(workstreamId)
     if (!activeRunId) return false
 
     const stopped = chatRunRegistry.stop(activeRunId, new DOMException('Run stopped by user.', 'AbortError'))
@@ -597,19 +538,11 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     return false
   }
 
-  async markCompacting(workstreamId: RecordIdRef): Promise<void> {
+  async setCompacting(workstreamId: RecordIdRef, value: boolean): Promise<void> {
     const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
     await databaseService.query<unknown>(surql`
       UPDATE ONLY ${workstreamRef}
-      SET isCompacting = ${true}
-    `)
-  }
-
-  async clearCompacting(workstreamId: RecordIdRef): Promise<void> {
-    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
-    await databaseService.query<unknown>(surql`
-      UPDATE ONLY ${workstreamRef}
-      SET isCompacting = ${false}
+      SET isCompacting = ${value}
     `)
   }
 
@@ -699,7 +632,7 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
       WorkstreamSchema,
     )
 
-    return await this.toNormalizedWorkstreams(workstreams)
+    return await this.toNormalizedWorkstreams(workstreams, { checkLease: false })
   }
 
   private normalizeWorkstreamId(id: unknown): string {
@@ -729,7 +662,10 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     return WORKSTREAM.DEFAULT_TITLE
   }
 
-  private async computeIsRunning(workstream: Pick<WorkstreamRecord, 'id' | 'activeRunId'>): Promise<boolean> {
+  private async computeIsRunning(
+    workstream: Pick<WorkstreamRecord, 'id' | 'activeRunId'>,
+    options: { checkLease: boolean },
+  ): Promise<boolean> {
     const activeRunId =
       typeof workstream.activeRunId === 'string' && workstream.activeRunId.trim().length > 0
         ? workstream.activeRunId
@@ -743,17 +679,24 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
       return true
     }
 
+    if (!options.checkLease) {
+      return true
+    }
+
     return await this.hasActiveRunLease(ensureRecordId(workstream.id, TABLES.WORKSTREAM))
   }
 
-  private async toNormalizedWorkstream(workstream: WorkstreamRecord): Promise<NormalizedWorkstream> {
-    const isRunning = await this.computeIsRunning(workstream)
+  private async toNormalizedWorkstream(
+    workstream: WorkstreamRecord,
+    options: { checkLease?: boolean } = {},
+  ): Promise<NormalizedWorkstream> {
+    const isRunning = await this.computeIsRunning(workstream, { checkLease: options.checkLease ?? true })
     const isCompacting = workstream.isCompacting === true
     const mode = workstream.mode
     const core = workstream.core
     const coreType = core && typeof workstream.coreType === 'string' ? workstream.coreType : undefined
     const status = workstream.status
-    return {
+    return NormalizedWorkstreamSchema.parse({
       id: this.normalizeWorkstreamId(workstream.id),
       userId: this.normalizeRecordIdString(workstream.userId, TABLES.USER),
       organizationId: this.normalizeRecordIdString(workstream.organizationId, TABLES.ORGANIZATION),
@@ -769,28 +712,26 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
       memoryBlock: this.formatMemoryBlockForPrompt(workstream),
       createdAt: toIsoDateTimeString(workstream.createdAt),
       updatedAt: toIsoDateTimeString(workstream.updatedAt),
-    }
+    })
   }
 
-  private async toNormalizedWorkstreams(workstreams: WorkstreamRecord[]): Promise<NormalizedWorkstream[]> {
-    return await Promise.all(workstreams.map(async (workstream) => await this.toNormalizedWorkstream(workstream)))
+  private async toNormalizedWorkstreams(
+    workstreams: WorkstreamRecord[],
+    options: { checkLease?: boolean } = {},
+  ): Promise<NormalizedWorkstream[]> {
+    return await Promise.all(
+      workstreams.map(async (workstream) => await this.toNormalizedWorkstream(workstream, options)),
+    )
   }
 
-  toPublicWorkstream(workstream: NormalizedWorkstream) {
-    return {
-      id: workstream.id,
-      mode: workstream.mode,
-      core: workstream.core,
-      ...(workstream.coreType ? { coreType: workstream.coreType } : {}),
-      ...(workstream.agentId ? { agentId: workstream.agentId } : {}),
-      title: workstream.title,
-      status: workstream.status,
-      nameGenerated: workstream.nameGenerated,
-      isRunning: workstream.isRunning,
-      isCompacting: workstream.isCompacting,
-      createdAt: workstream.createdAt,
-      updatedAt: workstream.updatedAt,
-    }
+  toPublicWorkstream(workstream: NormalizedWorkstream): PublicWorkstream {
+    const {
+      organizationId: _organizationId,
+      userId: _userId,
+      memoryBlock: _memoryBlock,
+      ...publicWorkstream
+    } = workstream
+    return PublicWorkstreamSchema.parse(publicWorkstream)
   }
 
   async incrementTurnCount(workstreamId: RecordIdRef): Promise<number> {
@@ -803,10 +744,6 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     return result[0].turnCount
   }
 
-  async persistGeneratedTitle(workstreamId: RecordIdRef, title: string): Promise<void> {
-    await this.update(workstreamId, { title, nameGenerated: true })
-  }
-
   private assertMutableWorkstream(
     workstream: WorkstreamRecord,
     action: 'rename' | 'archive' | 'unarchive' | 'delete',
@@ -818,6 +755,39 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
       throw new Error(`Core workstreams cannot be ${action}d`)
     }
   }
+
+  private async upsertDeterministicWorkstream(
+    workstreamId: RecordIdRef,
+    data: Record<string, unknown>,
+  ): Promise<WorkstreamRecord> {
+    const workstreamRef = ensureRecordId(workstreamId, TABLES.WORKSTREAM)
+    const existing = await this.findById(workstreamRef)
+    if (existing) {
+      return existing
+    }
+
+    let createError: unknown = null
+    let workstream = await databaseService
+      .createWithId(TABLES.WORKSTREAM, workstreamRef, data, WorkstreamSchema)
+      .catch((error) => {
+        createError = error
+        return null
+      })
+
+    if (!workstream) {
+      workstream = await this.findById(workstreamRef)
+    }
+
+    if (workstream) {
+      return workstream
+    }
+
+    if (createError instanceof Error) {
+      throw createError
+    }
+
+    throw new Error('Failed to create or load deterministic workstream')
+  }
 }
 
 export const workstreamService = new WorkstreamService()

package/src/services/workstream.types.ts

@@ -1,49 +1,17 @@
-import { recordIdSchema, sdkWorkstreamStatusSchema } from '@lota-sdk/shared'
+import { sdkPublicWorkstreamSchema, sdkWorkstreamRecordSchema, sdkWorkstreamSchema } from '@lota-sdk/shared'
+import type { SdkPublicWorkstream, SdkWorkstreamRecord } from '@lota-sdk/shared'
 import { z } from 'zod'
 
-const WorkstreamModeSchema = z.enum(['direct', 'group'])
-const CoreWorkstreamTypeSchema = z.string()
+export const WorkstreamSchema = sdkWorkstreamRecordSchema
+export type WorkstreamRecord = SdkWorkstreamRecord
 
-export interface NormalizedWorkstream {
-  id: string
-  title: string
-  status: 'regular' | 'archived'
-  mode: 'direct' | 'group'
-  core: boolean
-  coreType?: string
-  nameGenerated: boolean // Ideally `isNameGenerated`, but maps directly to SurrealDB column `nameGenerated`
-  isRunning: boolean
-  isCompacting: boolean
-  agentId?: string | null
-  memoryBlock: string
-  createdAt: string
-  updatedAt: string
-  userId: string
-  organizationId: string
-}
-
-export const WorkstreamSchema = z.object({
-  id: recordIdSchema,
-  mode: WorkstreamModeSchema,
-  core: z.boolean(),
-  coreType: CoreWorkstreamTypeSchema.nullish(),
-  agentId: z.string().nullish(),
-  title: z.string().nullish(),
-  status: sdkWorkstreamStatusSchema,
-  memoryBlock: z.string().nullish(),
-  memoryBlockSummary: z.string().nullish(),
-  activeRunId: z.string().nullish(),
-  activeStreamId: z.string().nullish(),
-  compactionSummary: z.string().nullish(),
-  lastCompactedMessageId: z.string().nullish(),
-  nameGenerated: z.boolean(), // Ideally `isNameGenerated`, but maps directly to SurrealDB column `nameGenerated`
-  isCompacting: z.boolean().optional(),
-  state: z.unknown().optional(),
-  turnCount: z.number().int(),
-  createdAt: z.coerce.date(),
-  updatedAt: z.coerce.date(),
-  userId: recordIdSchema,
-  organizationId: recordIdSchema,
+export const NormalizedWorkstreamSchema = sdkWorkstreamSchema.extend({
+  agentId: z.string().optional(),
+  coreType: z.string().optional(),
+  memoryBlock: z.string(),
 })
 
-export type WorkstreamRecord = z.infer<typeof WorkstreamSchema>
+export type NormalizedWorkstream = z.infer<typeof NormalizedWorkstreamSchema>
+export type PublicWorkstream = SdkPublicWorkstream
+
+export { sdkPublicWorkstreamSchema as PublicWorkstreamSchema }

package/src/system-agents/regular-chat-memory-digest.agent.ts

@@ -52,6 +52,9 @@ produce one updated workspace profile summary plus durable memory facts.
 - Set type to one of: fact, preference, decision.
 - Set confidence between 0 and 1.
 - Set durability to core, standard, or ephemeral based on expected longevity.
+- Set importance between 0 and 1 for long-term usefulness.
+- Set classification to durable, transient, or uncertain.
+- Set rationale to one short evidence-grounded sentence.
 </facts-format>
 
 <output-contract>

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

@@ -5,6 +5,7 @@ import {
   ResumeExecutionPlanRunArgsSchema,
   ReplaceExecutionPlanArgsSchema,
   SubmitExecutionNodeResultArgsSchema,
+  expandAgentPlanDraft,
   getLatestExecutionPlanResult,
 } from '@lota-sdk/shared'
 import { tool } from 'ai'
@@ -17,17 +18,21 @@ export function createCreateExecutionPlanTool(params: {
   workstreamId: RecordIdRef
   agentId: string
   onPlanChanged?: () => void
+  validateInlinePlan?: (draft: ReturnType<typeof expandAgentPlanDraft>) => void
 }) {
   return tool({
     description:
-      'Create a contract-driven execution plan for this workstream. Nodes must define deliverables, success criteria, completion checks, and executor policy.',
+      'Create a contract-driven execution plan for this workstream. Use createProjectWithPlan instead when the work needs a dedicated project workstream or a larger 3+ node plan.',
     inputSchema: CreateExecutionPlanArgsSchema,
     execute: async (input) => {
+      const { targetWorkstreamId, ...draftInput } = input
+      const draft = expandAgentPlanDraft(draftInput)
+      params.validateInlinePlan?.(draft)
       const result = await executionPlanService.createPlan({
         organizationId: params.orgId,
-        workstreamId: params.workstreamId,
+        workstreamId: targetWorkstreamId ?? params.workstreamId,
         leadAgentId: params.agentId,
-        input,
+        input: draft,
       })
       params.onPlanChanged?.()
       return result
@@ -46,11 +51,12 @@ export function createReplaceExecutionPlanTool(params: {
       '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 { runId, reason, ...draftInput } = input
       const result = await executionPlanService.replacePlan({
         organizationId: params.orgId,
         workstreamId: params.workstreamId,
         leadAgentId: params.agentId,
-        input,
+        input: { runId, reason, ...expandAgentPlanDraft(draftInput) },
       })
       params.onPlanChanged?.()
       return result
@@ -95,8 +101,7 @@ export function createListExecutionPlansTool(params: { workstreamId: RecordIdRef
 
 export function createGetExecutionPlanDetailsTool(params: { workstreamId: RecordIdRef }) {
   return tool({
-    description:
-      '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.',
+    description: 'Load a plan run and its current state.',
     inputSchema: GetActiveExecutionPlanArgsSchema,
     execute: async (input) =>
       await executionPlanService.getActivePlanToolResult({

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 './project-with-plan.tool'
 export * from './read-file-parts.tool'
 export * from './remember-memory.tool'
 export * from './research-topic.tool'