@lota-sdk/core 0.1.5

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

@@ -0,0 +1,80 @@
+import { ToolLoopAgent } from 'ai'
+import { z } from 'zod'
+
+import { bifrostOpenRouterResponseHealingModel } from '../bifrost/bifrost'
+import {
+  OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
+  OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+} from '../config/model-constants'
+import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
+import { resolveHelperAgentOptions } from './helper-agent-options'
+
+const SKILL_MANAGER_MAX_TOKENS = 4_096
+
+export const skillManagerPrompt = `<agent-instructions>
+You are the skill manager.
+
+<goal>
+Given a candidate skill and optionally the most similar existing skill, decide whether to add, merge, or discard.
+</goal>
+
+<decision-axes>
+Compare on four axes:
+1. Job-to-be-done overlap — do both skills serve the same user intent?
+2. Deliverable type similarity — do both produce the same kind of output?
+3. Hard constraints/success criteria match — do they share quality gates or validation rules?
+4. Required workflow overlap — do they follow similar procedural steps?
+</decision-axes>
+
+<decisions>
+- add: the candidate is a genuinely new capability not covered by the existing skill
+- merge: the candidate refines or extends the existing skill — produce merged instructions that combine both
+- discard: the candidate is too noisy, already fully covered, or non-portable
+</decisions>
+
+<merge-rules>
+When merging:
+- Combine instructions from both, keeping the best parts of each
+- Increment version number
+- Update description to reflect the merged capability
+- Keep triggers and examples from both, deduplicated
+- Use the higher confidence of the two
+</merge-rules>
+
+<output-contract>
+Return a JSON object with:
+- decision: 'add' | 'merge' | 'discard'
+- reason: 1-2 sentence explanation
+- mergedSkill: (only when decision is 'merge') object with merged name, description, instructions, triggers, tags, examples, confidence
+</output-contract>
+</agent-instructions>`
+
+export const MergedSkillSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  instructions: z.string(),
+  triggers: z.array(z.string()),
+  tags: z.array(z.string()),
+  examples: z.array(z.string()),
+  confidence: z.number().min(0).max(1),
+})
+
+export const SkillManagerOutputSchema = z.object({
+  decision: z.enum(['add', 'merge', 'discard']),
+  reason: z.string(),
+  mergedSkill: MergedSkillSchema.optional(),
+})
+
+export type SkillManagerOutput = z.infer<typeof SkillManagerOutputSchema>
+
+export function createSkillManagerAgent(options: CreateHelperToolLoopAgentOptions) {
+  return new ToolLoopAgent({
+    id: 'skill-manager',
+    model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+    providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+    ...resolveHelperAgentOptions(options, {
+      instructions: skillManagerPrompt,
+      maxOutputTokens: SKILL_MANAGER_MAX_TOKENS,
+    }),
+  })
+}

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

@@ -0,0 +1,42 @@
+import { ToolLoopAgent } from 'ai'
+
+import { bifrostModel } from '../bifrost/bifrost'
+import {
+  OPENROUTER_FAST_REASONING_MODEL_ID,
+  OPENROUTER_MINIMAL_REASONING_PROVIDER_OPTIONS,
+} from '../config/model-constants'
+import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
+import { resolveHelperAgentOptions } from './helper-agent-options'
+
+const TITLE_MAX_TOKENS = 500
+
+const WORKSTREAM_TITLE_GENERATOR_PROMPT = `<agent-instructions>
+You are a **Title Generator** that creates concise chat titles.
+
+<task>
+Generate a chat title based only on the user's message.
+</task>
+
+<constraints>
+- Maximum 4-5 words
+- Capture the core workstream or intent
+- Use natural, readable language
+- No punctuation at the end
+</constraints>
+
+<output-format>
+Return only the title text. No quotes, no labels, no explanation.
+</output-format>
+</agent-instructions>`
+
+export function createTitleGeneratorAgent(options: CreateHelperToolLoopAgentOptions) {
+  return new ToolLoopAgent({
+    id: 'title-generator',
+    model: bifrostModel(OPENROUTER_FAST_REASONING_MODEL_ID),
+    providerOptions: OPENROUTER_MINIMAL_REASONING_PROVIDER_OPTIONS,
+    ...resolveHelperAgentOptions(options, {
+      instructions: WORKSTREAM_TITLE_GENERATOR_PROMPT,
+      maxOutputTokens: TITLE_MAX_TOKENS,
+    }),
+  })
+}

package/src/system-agents/workstream-tracker.agent.ts

@@ -0,0 +1,58 @@
+import { ToolLoopAgent } from 'ai'
+
+import { bifrostOpenRouterResponseHealingModel } from '../bifrost/bifrost'
+import {
+  OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
+  OPENROUTER_STRUCTURED_REASONING_MODEL_ID,
+} from '../config/model-constants'
+import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
+import { resolveHelperAgentOptions } from './helper-agent-options'
+
+const WORKSTREAM_TRACKER_PROMPT = `<agent-instructions>
+You are the **Workstream Tracker**.
+
+<task>
+Convert one completed workstream turn into:
+- a concise change-tracker summary for the right sidebar
+- a structured workstream state delta containing only the updates implied by this turn
+</task>
+
+<rules>
+- Use only the provided turn evidence and prior state.
+- Keep the summary short, concrete, and focused on what changed or what is blocked now.
+- Prefer durable tracker items over prose: tasks, decisions, questions, risks, artifacts, and agent notes.
+- Do not duplicate existing state unless this turn meaningfully changed it.
+- Never invent analytics, repository facts, customer signals, or business decisions that were not stated.
+</rules>
+
+<state-guidance>
+- Use taskUpdates for concrete next steps, ongoing work, completed work, or blocked work.
+- When the turn includes concrete tool work or operational execution, capture that work as taskUpdates even if it was
+  completed in the same turn.
+- For website inspection or plugin refresh flows, prefer task titles that describe the executed step clearly, such as
+  refreshing website intelligence, overwriting artifacts, or reviewing evidence gaps.
+- If an owner is not explicit, default the task owner to the visible lead agent for the workstream.
+- Use newDecisions only when a clear decision or tradeoff was made.
+- Use newQuestions only for unresolved questions that matter for progress.
+- Use newRisks only for concrete execution or business risks surfaced in this turn.
+- Use agentNote for the main contribution from the lead agent when it is worth retaining.
+- Keep the delta compact. A noisy tracker is worse than a sparse tracker.
+</state-guidance>
+
+<output>
+The caller enforces a structured schema.
+- Return every stateDelta field.
+- Use empty arrays for unchanged list fields.
+- Use null for unchanged nullable fields.
+- For currentPlan, use \`{"action":"unchanged","text":null}\` when nothing changed, \`{"action":"clear","text":null}\` to clear it, and \`{"action":"set","text":"..."}\` to replace it.
+</output>
+</agent-instructions>`
+
+export function createWorkstreamTrackerAgent(options: CreateHelperToolLoopAgentOptions) {
+  return new ToolLoopAgent({
+    id: 'workstream-tracker',
+    model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_REASONING_MODEL_ID),
+    providerOptions: OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
+    ...resolveHelperAgentOptions(options, { instructions: WORKSTREAM_TRACKER_PROMPT }),
+  })
+}

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

@@ -0,0 +1,163 @@
+import {
+  CreateExecutionPlanArgsSchema,
+  GetActiveExecutionPlanArgsSchema,
+  RestartExecutionTaskArgsSchema,
+  ReplaceExecutionPlanArgsSchema,
+  SetExecutionTaskStatusArgsSchema,
+} from '@lota-sdk/shared/schemas/tools'
+import type { ExecutionPlanToolResultData } from '@lota-sdk/shared/schemas/tools'
+import { tool } from 'ai'
+
+import type { RecordIdRef } from '../db/record-id'
+import { executionPlanService } from '../services/execution-plan.service'
+
+function getLatestExecutionPlanToolResult(output: unknown): ExecutionPlanToolResultData | undefined {
+  if (output && typeof output === 'object' && 'hasPlan' in output) {
+    return output as ExecutionPlanToolResultData
+  }
+
+  if (Array.isArray(output)) {
+    for (let index = output.length - 1; index >= 0; index -= 1) {
+      const candidate = getLatestExecutionPlanToolResult(output[index])
+      if (candidate) return candidate
+    }
+  }
+
+  return undefined
+}
+
+export function createCreateExecutionPlanTool(params: {
+  orgId: RecordIdRef
+  workstreamId: RecordIdRef
+  agentId: string
+  onPlanChanged?: () => void
+}) {
+  return tool({
+    description:
+      'Create a structured execution plan for multi-step work in this workstream. Use this before starting multi-step execution.',
+    inputSchema: CreateExecutionPlanArgsSchema,
+    execute: async (input) => {
+      const result = await executionPlanService.createPlan({
+        organizationId: params.orgId,
+        workstreamId: params.workstreamId,
+        leadAgentId: params.agentId,
+        input,
+      })
+      params.onPlanChanged?.()
+      return result
+    },
+  })
+}
+
+export function createReplaceExecutionPlanTool(params: {
+  orgId: RecordIdRef
+  workstreamId: RecordIdRef
+  agentId: string
+  onPlanChanged?: () => void
+}) {
+  return tool({
+    description: 'Replace the active execution plan when the ordered steps or approach have materially changed.',
+    inputSchema: ReplaceExecutionPlanArgsSchema,
+    execute: async (input) => {
+      const result = await executionPlanService.replacePlan({
+        organizationId: params.orgId,
+        workstreamId: params.workstreamId,
+        leadAgentId: params.agentId,
+        input,
+      })
+      params.onPlanChanged?.()
+      return result
+    },
+  })
+}
+
+export function createSetExecutionTaskStatusTool(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({
+        workstreamId: params.workstreamId,
+        emittedBy: params.agentId,
+        input,
+      })
+      params.onPlanChanged?.()
+      return result
+    },
+    toModelOutput: ({ output }) => {
+      const result = getLatestExecutionPlanToolResult(output)
+      const summary = result?.message?.trim()
+      return { type: 'text', value: summary && summary.length > 0 ? summary : 'Execution task status updated.' }
+    },
+  })
+}
+
+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.',
+    inputSchema: GetActiveExecutionPlanArgsSchema,
+    execute: async (input) =>
+      await executionPlanService.getActivePlanToolResult({
+        workstreamId: params.workstreamId,
+        includeEvents: input.includeEvents,
+      }),
+  })
+}
+
+export function createRestartExecutionTaskTool(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,
+    execute: async (input) => {
+      const result = await executionPlanService.restartTask({
+        workstreamId: params.workstreamId,
+        emittedBy: params.agentId,
+        input,
+      })
+      params.onPlanChanged?.()
+      return result
+    },
+  })
+}

package/src/tools/fetch-webpage.tool.ts

@@ -0,0 +1,132 @@
+import { tool } from 'ai'
+import { z } from 'zod'
+
+import type { ToolDefinition } from '../ai/definitions'
+import type { Citation } from '../services/workstream.types'
+import { withTimeout } from '../utils/async'
+import { readStringField, truncateOptionalText } from '../utils/string'
+import { getFirecrawlClient } from './firecrawl-client'
+
+const TOOL_TIMEOUT_MS = 30_000
+const FormatSchema = z.enum(['markdown', 'html', 'rawHtml', 'links', 'images', 'screenshot', 'summary'])
+const MAX_MARKDOWN_CHARS = 6_000
+const MAX_SUMMARY_CHARS = 1_200
+const MAX_LINKS = 25
+const MAX_IMAGES = 10
+
+function readStringList(record: Record<string, unknown>, key: string, maxItems: number): string[] {
+  const value = record[key]
+  if (!Array.isArray(value)) return []
+
+  return value
+    .filter((entry): entry is string => typeof entry === 'string' && entry.trim().length > 0)
+    .slice(0, maxItems)
+}
+
+function summarizeDocument(url: string, document: unknown): Record<string, unknown> {
+  if (!document || typeof document !== 'object' || Array.isArray(document)) {
+    return { url }
+  }
+
+  const record = document as Record<string, unknown>
+  const metadata =
+    record.metadata && typeof record.metadata === 'object' && !Array.isArray(record.metadata)
+      ? (record.metadata as Record<string, unknown>)
+      : {}
+
+  const canonicalUrl = truncateOptionalText(
+    readStringField(metadata, 'url') ?? readStringField(metadata, 'sourceURL') ?? readStringField(record, 'url') ?? url,
+    500,
+  )
+  const title = truncateOptionalText(readStringField(metadata, 'title') ?? readStringField(record, 'title'), 160)
+  const description = truncateOptionalText(readStringField(metadata, 'description'), 320)
+  const summary = truncateOptionalText(readStringField(record, 'summary'), MAX_SUMMARY_CHARS)
+  const markdownExcerpt = truncateOptionalText(readStringField(record, 'markdown'), MAX_MARKDOWN_CHARS)
+  const links = readStringList(record, 'links', MAX_LINKS)
+
+  const images = Array.isArray(record.images)
+    ? record.images
+        .map((image) => {
+          if (typeof image === 'string') {
+            return truncateOptionalText(image, 500)
+          }
+
+          if (image && typeof image === 'object' && !Array.isArray(image)) {
+            const imageRecord = image as Record<string, unknown>
+            return truncateOptionalText(readStringField(imageRecord, 'src') ?? readStringField(imageRecord, 'url'), 500)
+          }
+
+          return undefined
+        })
+        .filter((image): image is string => typeof image === 'string' && image.length > 0)
+        .slice(0, MAX_IMAGES)
+    : []
+
+  return {
+    url: canonicalUrl ?? url,
+    ...(title ? { title } : {}),
+    ...(description ? { description } : {}),
+    ...(summary ? { summary } : {}),
+    ...(markdownExcerpt ? { markdownExcerpt } : {}),
+    ...(links.length > 0 ? { links } : {}),
+    ...(images.length > 0 ? { images } : {}),
+  }
+}
+
+function buildFetchCitations(url: string, document: unknown): Citation[] {
+  const fallbackUrl = url.trim()
+  let sourceId = fallbackUrl
+
+  if (document && typeof document === 'object') {
+    const metadata = (document as Record<string, unknown>).metadata
+    if (metadata && typeof metadata === 'object') {
+      const record = metadata as Record<string, unknown>
+      if (typeof record.url === 'string' && record.url.trim().length > 0) {
+        sourceId = record.url.trim()
+      } else if (typeof record.sourceURL === 'string' && record.sourceURL.trim().length > 0) {
+        sourceId = record.sourceURL.trim()
+      }
+    }
+  }
+
+  return [{ source: 'web', sourceId, retrievedAt: new Date().toISOString() }]
+}
+
+export const fetchWebpageTool = {
+  name: 'fetchWebpage',
+  create: () =>
+    tool({
+      description: 'Retrieve and parse a single webpage.',
+      inputSchema: z
+        .object({
+          url: z.url('Valid URL is required'),
+          formats: z.array(FormatSchema).optional(),
+          onlyMainContent: z.boolean().optional(),
+          maxAge: z.number().int().min(1).optional(),
+        })
+        .strict(),
+      execute: async ({
+        url,
+        formats,
+        onlyMainContent,
+        maxAge,
+      }: {
+        url: string
+        formats?: z.infer<typeof FormatSchema>[]
+        onlyMainContent?: boolean
+        maxAge?: number
+      }) => {
+        const result = await withTimeout(
+          getFirecrawlClient().scrape(url, {
+            formats: formats?.length ? formats : ['markdown'],
+            onlyMainContent: onlyMainContent ?? true,
+            maxAge,
+          }),
+          TOOL_TIMEOUT_MS,
+          'Webpage fetch',
+        )
+
+        return { url, document: summarizeDocument(url, result), citations: buildFetchCitations(url, result) }
+      },
+    }),
+} as const satisfies ToolDefinition<void>

package/src/tools/firecrawl-client.ts

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

package/src/tools/memory-block.tool.ts

@@ -0,0 +1,55 @@
+import { tool } from 'ai'
+import { z } from 'zod'
+
+import type { RecordIdRef } from '../db/record-id'
+import {
+  hasMemoryBlockEntry,
+  normalizeMemoryBlockEntry,
+  prepareMemoryBlockAppend,
+  validateMemoryBlockEntry,
+} from '../runtime/memory-block'
+import { workstreamService } from '../services/workstream.service'
+import { safeEnqueue } from '../utils/async'
+
+export function createMemoryBlockTool({
+  workstreamId,
+  agentLabel,
+  getCurrentBlock,
+  onAppend,
+}: {
+  workstreamId: RecordIdRef
+  agentLabel: string
+  getCurrentBlock?: () => string
+  onAppend?: (value: string) => void
+}) {
+  return tool({
+    description:
+      'Append a critical 2-3 sentence note to the conversation memory block. Include only essential information.',
+    inputSchema: z.object({ entry: z.string().min(1) }).strict(),
+    execute: ({ entry }: { entry: string }) => {
+      const prepared = prepareMemoryBlockAppend({
+        entry,
+        agentLabel,
+        currentBlock: getCurrentBlock?.() ?? '',
+        normalizeEntry: normalizeMemoryBlockEntry,
+        validateEntry: validateMemoryBlockEntry,
+        hasEntry: hasMemoryBlockEntry,
+      })
+      if (prepared.skipped) {
+        return { skipped: true, reason: prepared.reason }
+      }
+
+      onAppend?.(prepared.optimisticBlock)
+
+      void safeEnqueue(
+        async () => {
+          const updated = await workstreamService.appendMemoryBlock(workstreamId, prepared.formatted)
+          onAppend?.(updated)
+        },
+        { operationName: 'append memory block entry', logPrefix: 'Background memoryBlockAppend task failed' },
+      )
+
+      return { success: true, status: 'scheduled', appendedBy: prepared.appendedBy }
+    },
+  })
+}

package/src/tools/read-file-parts.tool.ts

@@ -0,0 +1,80 @@
+import { tool } from 'ai'
+import { z } from 'zod'
+
+import type { ToolDefinition } from '../ai/definitions'
+import { attachmentStorageService } from '../storage/attachment-storage.service'
+import type { ReadableUploadMetadata } from '../storage/attachments.types'
+
+const PAGES_PER_PART = 25
+
+export interface ReadFilePartsToolContext {
+  orgId: string
+  userId: string
+  uploads: ReadableUploadMetadata[]
+}
+
+function toUploadSummary(upload: ReadableUploadMetadata) {
+  return {
+    storageKey: upload.storageKey,
+    filename: upload.filename,
+    mediaType: upload.mediaType,
+    sizeBytes: upload.sizeBytes,
+  }
+}
+
+function resolveUploadTarget(params: {
+  uploads: ReadableUploadMetadata[]
+  storageKey?: string
+}): ReadableUploadMetadata | null {
+  const normalizedStorageKey = params.storageKey?.trim()
+  const byStorageKey = normalizedStorageKey
+    ? params.uploads.find((upload) => upload.storageKey === normalizedStorageKey)
+    : null
+  if (normalizedStorageKey !== undefined && !byStorageKey) {
+    throw new Error(`No upload found for storageKey "${normalizedStorageKey}".`)
+  }
+
+  return byStorageKey ?? null
+}
+
+export const readFilePartsTool = {
+  name: 'readFileParts',
+  create: ({ orgId, userId, uploads }: ReadFilePartsToolContext) =>
+    tool({
+      description:
+        'Read uploaded file content by part. Call with no args to list uploads metadata, then call with storageKey and part (25 pages per part).',
+      inputSchema: z
+        .object({ storageKey: z.string().trim().min(1).optional(), part: z.number().int().positive().default(1) })
+        .strict(),
+      execute: async ({ storageKey, part }: { storageKey?: string; part?: number }) => {
+        const availableUploads = uploads.map(toUploadSummary)
+        const selected = resolveUploadTarget({ uploads, storageKey })
+
+        if (!selected) {
+          return {
+            pagesPerPart: PAGES_PER_PART,
+            currentPart: 1,
+            hasNextPart: false,
+            totalParts: 0,
+            data: [],
+            availableUploads,
+            selectedUpload: null,
+            message:
+              uploads.length === 0
+                ? 'No uploaded files are available in this conversation.'
+                : 'Select an upload via storageKey, then provide part (25 pages per part).',
+          }
+        }
+
+        const parts = await attachmentStorageService.readFilePartsFromUpload({
+          upload: selected,
+          orgId,
+          userId,
+          part,
+          pagesPerPart: PAGES_PER_PART,
+        })
+
+        return { availableUploads, selectedUpload: toUploadSummary(selected), ...parts }
+      },
+    }),
+} as const satisfies ToolDefinition<ReadFilePartsToolContext>