@lota-sdk/core 0.1.9 → 0.1.12

package/src/services/workstream.service.ts

@@ -1,4 +1,4 @@
-import { WORKSTREAM } from '@lota-sdk/shared/constants/workstream'
+import { WORKSTREAM } from '@lota-sdk/shared'
 import { BoundQuery, RecordId, StringRecordId, surql } from 'surrealdb'
 
 import { agentDisplayNames, getCoreWorkstreamProfile, isAgentName } from '../config/agent-defaults'
@@ -345,19 +345,19 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
 
     const onboardingWelcome = bootstrapConfig.onboardingWelcome
     if (!onboardingCompleted && onboardingWelcome) {
-      const createdChiefWorkstream = createdWorkstreams.find(
+      const createdOnboardingOwnerWorkstream = createdWorkstreams.find(
         (workstream) => workstream.mode === 'direct' && workstream.agentId === onboardingWelcome.directAgentId,
       )
-      const existingChiefWorkstream = directWorkstreamsByAgent.get(onboardingWelcome.directAgentId)
+      const existingOnboardingOwnerWorkstream = directWorkstreamsByAgent.get(onboardingWelcome.directAgentId)
 
-      const chiefWorkstreamId =
-        createdChiefWorkstream?.id ??
-        (existingChiefWorkstream ? this.normalizeWorkstreamId(existingChiefWorkstream.id) : null)
+      const onboardingOwnerWorkstreamId =
+        createdOnboardingOwnerWorkstream?.id ??
+        (existingOnboardingOwnerWorkstream ? this.normalizeWorkstreamId(existingOnboardingOwnerWorkstream.id) : null)
 
-      if (chiefWorkstreamId) {
-        const chiefWorkstreamRef = ensureRecordId(chiefWorkstreamId, TABLES.WORKSTREAM)
+      if (onboardingOwnerWorkstreamId) {
+        const onboardingOwnerWorkstreamRef = ensureRecordId(onboardingOwnerWorkstreamId, TABLES.WORKSTREAM)
         await workstreamMessageService.ensureBootstrapWelcomeMessage({
-          workstreamId: chiefWorkstreamRef,
+          workstreamId: onboardingOwnerWorkstreamRef,
           agentId: onboardingWelcome.directAgentId,
           text: onboardingWelcome.buildMessageText({ userName: options?.userName }),
         })
@@ -504,6 +504,32 @@ class WorkstreamService extends BaseService<typeof WorkstreamSchema> {
     await this.setActiveRunId(workstreamId, null)
   }
 
+  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 databaseService.query<unknown>(surql`
+      UPDATE ONLY ${workstreamRef}
+      SET activeStreamId = NONE
+    `)
+  }
+
   async stopActiveRun(workstreamId: RecordIdRef): Promise<boolean> {
     const activeRunId = await this.getActiveRunId(workstreamId)
     if (!activeRunId) return false

package/src/services/workstream.types.ts

@@ -42,6 +42,7 @@ export const WorkstreamSchema = z.object({
   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().optional().default(false),

package/src/storage/attachment-parser.ts

@@ -1,4 +1,4 @@
-import { SUPPORTED_ATTACHMENT_MIME_TYPES, getAttachmentExtension } from '@lota-sdk/shared/constants/attachments'
+import { SUPPORTED_ATTACHMENT_MIME_TYPES, getAttachmentExtension } from '@lota-sdk/shared'
 import mammoth from 'mammoth'
 import { PDFParse } from 'pdf-parse'
 

package/src/storage/attachment-storage.service.ts

@@ -1,8 +1,8 @@
-import { inferContentType } from '@lota-sdk/shared/constants/attachments'
+import { inferContentType } from '@lota-sdk/shared'
 import { S3Client } from 'bun'
 
-import { env } from '../config/env-shapes'
 import { serverLogger } from '../config/logger'
+import { getRuntimeConfig } from '../runtime/runtime-config'
 import { readString } from '../utils/string'
 import {
   extractAttachmentText,
@@ -41,17 +41,18 @@ export class AttachmentStorageService {
   private readonly client: S3Client
 
   constructor() {
+    const config = getRuntimeConfig()
     this.client = new S3Client({
-      accessKeyId: env.S3_ACCESS_KEY_ID,
-      secretAccessKey: env.S3_SECRET_ACCESS_KEY,
-      bucket: env.S3_BUCKET,
-      endpoint: env.S3_ENDPOINT,
-      region: env.S3_REGION,
+      accessKeyId: config.s3.accessKeyId,
+      secretAccessKey: config.s3.secretAccessKey,
+      bucket: config.s3.bucket,
+      endpoint: config.s3.endpoint,
+      region: config.s3.region,
     })
   }
 
   getAttachmentUrl(storageKey: string): string {
-    return this.client.file(storageKey).presign({ expiresIn: env.ATTACHMENT_URL_EXPIRES_IN })
+    return this.client.file(storageKey).presign({ expiresIn: getRuntimeConfig().s3.attachmentUrlExpiresIn })
   }
 
   async writeOrganizationDocument({
@@ -102,7 +103,7 @@ export class AttachmentStorageService {
       sizeBytes: file.size,
       storageKey,
       url: this.getAttachmentUrl(storageKey),
-      expiresInSeconds: env.ATTACHMENT_URL_EXPIRES_IN,
+      expiresInSeconds: getRuntimeConfig().s3.attachmentUrlExpiresIn,
     }
   }
 
@@ -128,7 +129,7 @@ export class AttachmentStorageService {
       sizeBytes,
       storageKey,
       url: this.getAttachmentUrl(storageKey),
-      expiresInSeconds: env.ATTACHMENT_URL_EXPIRES_IN,
+      expiresInSeconds: getRuntimeConfig().s3.attachmentUrlExpiresIn,
     }
   }
 

package/src/storage/generated-document-storage.service.ts

@@ -1,6 +1,6 @@
 import { S3Client } from 'bun'
 
-import { env } from '../config/env-shapes'
+import { getRuntimeConfig } from '../runtime/runtime-config'
 
 function toSafeSegment(value: string): string {
   return value
@@ -27,12 +27,13 @@ class GeneratedDocumentStorageService {
 
   private get client(): InstanceType<typeof S3Client> {
     if (!this._client) {
+      const config = getRuntimeConfig()
       this._client = new S3Client({
-        accessKeyId: env.S3_ACCESS_KEY_ID,
-        secretAccessKey: env.S3_SECRET_ACCESS_KEY,
-        bucket: env.S3_BUCKET,
-        endpoint: env.S3_ENDPOINT,
-        region: env.S3_REGION,
+        accessKeyId: config.s3.accessKeyId,
+        secretAccessKey: config.s3.secretAccessKey,
+        bucket: config.s3.bucket,
+        endpoint: config.s3.endpoint,
+        region: config.s3.region,
       })
     }
     return this._client

package/src/storage/index.ts

@@ -0,0 +1,10 @@
+export * from './attachment-parser'
+export * from './attachment-storage.service'
+export * from './generated-document-storage.service'
+export type { MessagePartLike, ReadableUploadPageMode, ReadableUploadPagePart } from './attachments.types'
+export {
+  buildOrganizationDocumentStorageKey,
+  buildUploadStorageKey,
+  buildUploadStoragePrefix,
+  readNonNegativeInteger,
+} from './attachments.utils'

package/src/system-agents/delegated-agent-factory.ts

@@ -7,11 +7,12 @@ import { isRecord } from '../utils/string'
 import { assertSubstantiveAgentResult } from './agent-result'
 
 type AgentProviderOptions = ToolLoopAgentSettings['providerOptions']
+type AgentModel = LanguageModel | (() => LanguageModel)
 
 interface DelegatedAgentDefinition {
   id: string
   description: string
-  model: LanguageModel
+  model: AgentModel
   providerOptions?: AgentProviderOptions
   instructions: string
   tools?: ToolSet
@@ -24,6 +25,10 @@ interface DelegatedAgentDefinitionWithContext<TContext> extends Omit<DelegatedAg
   createTools: (context: TContext) => ToolSet
 }
 
+function resolveAgentModel(model: AgentModel): LanguageModel {
+  return typeof model === 'function' ? model() : model
+}
+
 function buildCurrentDateContext(now = new Date()): string {
   const isoDate = now.toISOString().slice(0, 10)
   const humanDate = new Intl.DateTimeFormat('en-US', {
@@ -75,6 +80,9 @@ When your analysis is complete, return your final answer directly as markdown te
 </termination>`
 
 const MAX_RETAINED_AGENT_MESSAGES = 10
+const MAX_NON_SUBSTANTIVE_AGENT_RESULT_ATTEMPTS = 2
+const NON_SUBSTANTIVE_AGENT_RESULT_RETRY_PROMPT =
+  'Return a complete substantive markdown answer. Do not reply with an empty result, placeholder, or tool-only outcome.'
 
 export function retainCriticalAgentMessages(messages: ModelMessage[]): ModelMessage[] {
   const systemMessages = messages.filter((message) => message.role === 'system')
@@ -112,6 +120,31 @@ function resolveDelegatedAgentTemperature(definition: {
   return definition.temperature ?? 0.2
 }
 
+async function generateSubstantiveDelegatedAgentResult(params: {
+  label: string
+  task: string
+  abortSignal?: AbortSignal
+  createAgent: () => ToolLoopAgent<never, ToolSet>
+}): Promise<string> {
+  let lastError: unknown
+
+  for (let attempt = 0; attempt < MAX_NON_SUBSTANTIVE_AGENT_RESULT_ATTEMPTS; attempt += 1) {
+    const prompt = attempt === 0 ? params.task : `${params.task}\n\n${NON_SUBSTANTIVE_AGENT_RESULT_RETRY_PROMPT}`
+    const result = await params.createAgent().generate({ prompt, abortSignal: params.abortSignal })
+
+    try {
+      return assertSubstantiveAgentResult(result.text, params.label)
+    } catch (error) {
+      lastError = error
+      if (params.abortSignal?.aborted) {
+        throw error
+      }
+    }
+  }
+
+  throw lastError ?? new Error(`${params.label} must contain substantive text.`)
+}
+
 export function createDelegatedAgentTool(definition: DelegatedAgentDefinition): ToolDefinition<void> {
   const maxSteps = definition.maxSteps ?? 10
   const temperature = resolveDelegatedAgentTemperature(definition)
@@ -124,20 +157,28 @@ export function createDelegatedAgentTool(definition: DelegatedAgentDefinition):
         inputSchema: z.object({ task: z.string().min(1) }),
         execute: async ({ task }: { task: string }, { abortSignal }) => {
           const agentTools = definition.tools
-          const agent = new ToolLoopAgent({
-            id: definition.id,
-            model: definition.model,
-            ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
-            instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
-            tools: agentTools,
-            maxOutputTokens: definition.maxOutputTokens ?? 4096,
-            ...(typeof temperature === 'number' ? { temperature } : {}),
-            stopWhen: [stepCountIs(maxSteps)],
-            prepareStep: async ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),
-          })
-
-          const result = await agent.generate({ prompt: task, abortSignal })
-          return { task, result: assertSubstantiveAgentResult(result.text, `${definition.id} result`) }
+          const createAgent = () =>
+            new ToolLoopAgent({
+              id: definition.id,
+              model: resolveAgentModel(definition.model),
+              ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
+              instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
+              tools: agentTools,
+              maxOutputTokens: definition.maxOutputTokens ?? 4096,
+              ...(typeof temperature === 'number' ? { temperature } : {}),
+              stopWhen: [stepCountIs(maxSteps)],
+              prepareStep: async ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),
+            })
+
+          return {
+            task,
+            result: await generateSubstantiveDelegatedAgentResult({
+              label: `${definition.id} result`,
+              task,
+              abortSignal,
+              createAgent,
+            }),
+          }
         },
       }),
   } as const satisfies ToolDefinition<void>
@@ -157,20 +198,28 @@ export function createDelegatedAgentToolWithContext<TContext>(
         inputSchema: z.object({ task: z.string().min(1) }),
         execute: async ({ task }: { task: string }, { abortSignal }) => {
           const agentTools = definition.createTools(context)
-          const agent = new ToolLoopAgent({
-            id: definition.id,
-            model: definition.model,
-            ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
-            instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
-            tools: agentTools,
-            maxOutputTokens: definition.maxOutputTokens ?? 4096,
-            ...(typeof temperature === 'number' ? { temperature } : {}),
-            stopWhen: [stepCountIs(maxSteps)],
-            prepareStep: async ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),
-          })
-
-          const result = await agent.generate({ prompt: task, abortSignal })
-          return { task, result: assertSubstantiveAgentResult(result.text, `${definition.id} result`) }
+          const createAgent = () =>
+            new ToolLoopAgent({
+              id: definition.id,
+              model: resolveAgentModel(definition.model),
+              ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
+              instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
+              tools: agentTools,
+              maxOutputTokens: definition.maxOutputTokens ?? 4096,
+              ...(typeof temperature === 'number' ? { temperature } : {}),
+              stopWhen: [stepCountIs(maxSteps)],
+              prepareStep: async ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),
+            })
+
+          return {
+            task,
+            result: await generateSubstantiveDelegatedAgentResult({
+              label: `${definition.id} result`,
+              task,
+              abortSignal,
+              createAgent,
+            }),
+          }
         },
       }),
   } as const satisfies ToolDefinition<TContext>

package/src/system-agents/index.ts

@@ -0,0 +1,4 @@
+export * from './agent-result'
+export * from './delegated-agent-factory'
+export * from './helper-agent-options'
+export * from './recent-activity-title-refiner.agent'

package/src/system-agents/recent-activity-title-refiner.agent.ts

@@ -1,6 +1,7 @@
 import { ToolLoopAgent } from 'ai'
 
 import { bifrostModel } from '../bifrost/bifrost'
+import { getLeadAgentDisplayName } from '../config/agent-defaults'
 import {
   OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
   OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
@@ -10,8 +11,42 @@ import { resolveHelperAgentOptions } from './helper-agent-options'
 
 const RECENT_ACTIVITY_TITLE_MAX_TOKENS = 256
 
+export function buildRecentActivityTitleRefinerPrompt(): string {
+  const leadAgentDisplayName = getLeadAgentDisplayName() || 'the lead agent'
+
+  return `<agent-instructions>
+You are ${leadAgentDisplayName} writing the visible title for a recent activity item.
+
+<goal>
+Turn recent activity context into a short label that helps the user quickly recognize and reopen the task.
+</goal>
+
+<rules>
+- Write 4-10 words when possible.
+- Prefer concrete task language over generic labels.
+- Mention the agent only when it adds useful context.
+- Focus on what the user was trying to accomplish.
+- Avoid generic phrases like "Chat", "Conversation", "Recent activity", "Task", or "Workstream update".
+- Avoid punctuation at the end.
+- Do not invent details that are not present in the input.
+- If the input is too weak for improvement, return the current system title.
+</rules>
+
+<examples>
+- "Review pending decisions with ${leadAgentDisplayName}"
+- "Extract website intelligence findings"
+- "Discuss onboarding repository indexing"
+- "Review PRD from GitHub indexing"
+</examples>
+
+<output>
+Return only the title text. No quotes, labels, JSON, markdown, or explanation.
+</output>
+</agent-instructions>`
+}
+
 export const recentActivityTitleRefinerPrompt = `<agent-instructions>
-You are the Chief of Staff writing the visible title for a recent activity item.
+You are the lead agent writing the visible title for a recent activity item.
 
 <goal>
 Turn recent activity context into a short label that helps the user quickly recognize and reopen the task.
@@ -29,7 +64,7 @@ Turn recent activity context into a short label that helps the user quickly reco
 </rules>
 
 <examples>
-- "Review pending decisions with Chief"
+- "Review pending decisions with the lead agent"
 - "Extract website intelligence findings"
 - "Discuss onboarding repository indexing"
 - "Review PRD from GitHub indexing"
@@ -46,7 +81,7 @@ export function createRecentActivityTitleRefinerAgent(options: CreateHelperToolL
     model: bifrostModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
     providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
     ...resolveHelperAgentOptions(options, {
-      instructions: recentActivityTitleRefinerPrompt,
+      instructions: buildRecentActivityTitleRefinerPrompt(),
       maxOutputTokens: RECENT_ACTIVITY_TITLE_MAX_TOKENS,
     }),
   })

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

@@ -10,7 +10,7 @@ import { resolveHelperAgentOptions } from './helper-agent-options'
 
 const REGULAR_CHAT_MEMORY_DIGEST_MAX_TOKENS = 8_192
 
-export const regularChatMemoryDigestPrompt = `<agent-instructions>
+const regularChatMemoryDigestPrompt = `<agent-instructions>
 You are the regular-chat memory digest synthesizer.
 
 <goal>

package/src/system-agents/skill-extractor.agent.ts

@@ -11,7 +11,7 @@ import { resolveHelperAgentOptions } from './helper-agent-options'
 
 const SKILL_EXTRACTOR_MAX_TOKENS = 8_192
 
-export const skillExtractorPrompt = `<agent-instructions>
+const skillExtractorPrompt = `<agent-instructions>
 You are the skill extractor.
 
 <goal>

package/src/system-agents/skill-manager.agent.ts

@@ -11,7 +11,7 @@ import { resolveHelperAgentOptions } from './helper-agent-options'
 
 const SKILL_MANAGER_MAX_TOKENS = 4_096
 
-export const skillManagerPrompt = `<agent-instructions>
+const skillManagerPrompt = `<agent-instructions>
 You are the skill manager.
 
 <goal>
@@ -49,7 +49,7 @@ Return a JSON object with:
 </output-contract>
 </agent-instructions>`
 
-export const MergedSkillSchema = z.object({
+const MergedSkillSchema = z.object({
   name: z.string(),
   description: z.string(),
   instructions: z.string(),
@@ -65,8 +65,6 @@ export const SkillManagerOutputSchema = z.object({
   mergedSkill: MergedSkillSchema.optional(),
 })
 
-export type SkillManagerOutput = z.infer<typeof SkillManagerOutputSchema>
-
 export function createSkillManagerAgent(options: CreateHelperToolLoopAgentOptions) {
   return new ToolLoopAgent({
     id: 'skill-manager',

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,11 +1,11 @@
 import {
   CreateExecutionPlanArgsSchema,
   GetActiveExecutionPlanArgsSchema,
-  RestartExecutionTaskArgsSchema,
+  ResumeExecutionPlanRunArgsSchema,
   ReplaceExecutionPlanArgsSchema,
-  SetExecutionTaskStatusArgsSchema,
-} from '@lota-sdk/shared/schemas/tools'
-import type { ExecutionPlanToolResultData } from '@lota-sdk/shared/schemas/tools'
+  SubmitExecutionNodeResultArgsSchema,
+} from '@lota-sdk/shared'
+import type { ExecutionPlanToolResultData } from '@lota-sdk/shared'
 import { tool } from 'ai'
 
 import type { RecordIdRef } from '../db/record-id'
@@ -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/firecrawl-client.ts

@@ -1,12 +1,12 @@
 import Firecrawl from '@mendable/firecrawl-js'
 
-import { env } from '../config/env-shapes'
+import { getRuntimeConfig } from '../runtime/runtime-config'
 
 let _firecrawlClient: Firecrawl | undefined
 
 export function getFirecrawlClient(): Firecrawl {
   if (!_firecrawlClient) {
-    _firecrawlClient = new Firecrawl({ apiKey: env.FIRECRAWL_API_KEY })
+    _firecrawlClient = new Firecrawl({ apiKey: getRuntimeConfig().firecrawl.apiKey })
   }
   return _firecrawlClient
 }

package/src/tools/index.ts

@@ -0,0 +1,12 @@
+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-web.tool'
+export * from './team-think.tool'
+export * from './tool-contract'
+export * from './user-questions.tool'

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() }
+    },
+  })
+}