@lota-sdk/core 0.1.23 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/core",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -32,7 +32,7 @@
     "@chat-adapter/slack": "^4.23.0",
     "@chat-adapter/state-ioredis": "^4.23.0",
     "@logtape/logtape": "^2.0.5",
-    "@lota-sdk/shared": "0.1.23",
+    "@lota-sdk/shared": "0.1.24",
     "@mendable/firecrawl-js": "^4.18.0",
     "@surrealdb/node": "^3.0.3",
     "ai": "^6.0.141",

package/src/create-runtime.ts

@@ -27,6 +27,8 @@ import type { LotaRuntimeWorkers } from './runtime/runtime-worker-registry'
 import { buildRuntimeWorkerRegistry } from './runtime/runtime-worker-registry'
 import type { LotaRuntimeSocialChat } from './runtime/social-chat'
 import { createSocialChatRuntime } from './runtime/social-chat'
+import type { agentActivityService } from './services/agent-activity.service'
+import { agentActivityService as agentActivityServiceSingleton } from './services/agent-activity.service'
 import type { attachmentService } from './services/attachment.service'
 import { attachmentService as attachmentServiceSingleton } from './services/attachment.service'
 import type { autonomousJobService } from './services/autonomous-job.service'
@@ -117,6 +119,7 @@ export interface LotaRuntime {
     database: SurrealDBService
     redis: RedisConnectionManager
     closeRedisConnection: () => Promise<void>
+    agentActivityService: typeof agentActivityService
     attachmentService: typeof attachmentService
     autonomousJobService: typeof autonomousJobService
     documentChunkService: typeof documentChunkService
@@ -390,6 +393,7 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
         database: db,
         redis: redisManager,
         closeRedisConnection: async () => await redisManager.closeConnection(),
+        agentActivityService: agentActivityServiceSingleton,
         attachmentService: attachmentServiceSingleton,
         autonomousJobService: autonomousJobServiceSingleton,
         documentChunkService: documentChunkServiceSingleton,

package/src/runtime/execution-plan.ts

@@ -1,3 +1,4 @@
+import { PROJECT_PLAN_ROUTING_PROMPT } from '@lota-sdk/shared'
 import type { SerializableExecutionPlan } from '@lota-sdk/shared'
 
 const EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT = `<execution-plan-protocol>
@@ -35,7 +36,7 @@ export function buildExecutionPlanInstructionSections(
   plans: SerializableExecutionPlan[] | null | undefined,
 ): string[] | undefined {
   const normalized = plans ?? []
-  const sections = [EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT]
+  const sections = [EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT, PROJECT_PLAN_ROUTING_PROMPT]
   const stateSection = formatExecutionPlansForPrompt(normalized)
   if (stateSection) {
     sections.push(stateSection)

package/src/services/agent-activity.service.ts

@@ -0,0 +1,350 @@
+import type {
+  AgentActivityCounts,
+  AgentActivityEntry,
+  AgentActivityResponse,
+  AgentProjectEntry,
+  MyTasksResponse,
+  PlanBoardColumn,
+  PlanBoardResponse,
+  PlanNodeCard,
+  PlanViewNode,
+  PlanViewResponse,
+  SerializableExecutionPlan,
+  SerializablePlanNode,
+} from '@lota-sdk/shared'
+
+import { agentRoster } from '../config/agent-defaults'
+import { serverLogger } from '../config/logger'
+import { executionPlanService } from './execution-plan.service'
+import { workstreamService } from './workstream.service'
+import type { NormalizedWorkstream } from './workstream.types'
+
+const BOARD_COLUMN_ORDER = ['ready', 'running', 'awaiting-human', 'completed', 'blocked', 'failed'] as const
+type BoardColumnStatus = (typeof BOARD_COLUMN_ORDER)[number]
+
+const COLUMN_LABELS: Record<BoardColumnStatus, string> = {
+  ready: 'Ready',
+  running: 'Running',
+  'awaiting-human': 'Awaiting Human',
+  completed: 'Completed',
+  blocked: 'Blocked',
+  failed: 'Failed',
+}
+
+type ActivePlanEntry = {
+  plan: SerializableExecutionPlan
+  workstream: Pick<NormalizedWorkstream, 'id' | 'title' | 'isRunning' | 'updatedAt'>
+}
+
+type AgentActivityDeps = {
+  executionPlanService: Pick<typeof executionPlanService, 'getActivePlansForWorkstream'>
+  workstreamService: Pick<typeof workstreamService, 'listWorkstreams'>
+}
+
+function normalizeCardStatus(status: string): BoardColumnStatus {
+  if (status === 'pending' || status === 'scheduled') return 'ready'
+  if (status === 'partial') return 'completed'
+  if (status === 'running' || status === 'awaiting-human' || status === 'completed' || status === 'blocked') {
+    return status
+  }
+  if (status === 'failed') return 'failed'
+  return 'blocked'
+}
+
+function isCompletedStatus(status: string): boolean {
+  return status === 'completed' || status === 'partial' || status === 'skipped'
+}
+
+function createEmptyCounts(): AgentActivityCounts {
+  return { running: 0, ready: 0, pending: 0, awaitingHuman: 0, blocked: 0, completed: 0, failed: 0 }
+}
+
+function maxIsoDate(current: string | null, candidate: string): string {
+  if (!current) return candidate
+  return new Date(candidate).getTime() > new Date(current).getTime() ? candidate : current
+}
+
+function incrementCounts(counts: AgentActivityCounts, rawStatus: string): void {
+  if (rawStatus === 'running') {
+    counts.running += 1
+    return
+  }
+  if (rawStatus === 'ready') {
+    counts.ready += 1
+    return
+  }
+  if (rawStatus === 'pending' || rawStatus === 'scheduled') {
+    counts.pending += 1
+    return
+  }
+  if (rawStatus === 'awaiting-human') {
+    counts.awaitingHuman += 1
+    return
+  }
+  if (rawStatus === 'blocked') {
+    counts.blocked += 1
+    return
+  }
+  if (rawStatus === 'failed') {
+    counts.failed += 1
+    return
+  }
+  if (rawStatus === 'completed' || rawStatus === 'partial') {
+    counts.completed += 1
+  }
+}
+
+export function planNodeToCard(
+  node: SerializablePlanNode,
+  plan: SerializableExecutionPlan,
+  workstreamId: string,
+  workstreamTitle: string,
+): PlanNodeCard {
+  const approval = plan.approvals.find((candidate) => candidate.nodeId === node.id && candidate.status === 'pending')
+
+  return {
+    nodeId: node.id,
+    label: node.label,
+    objective: node.objective,
+    status: normalizeCardStatus(node.status),
+    ownerType: node.owner.executorType,
+    ownerRef: node.owner.ref,
+    planRunId: plan.runId,
+    planTitle: plan.title,
+    workstreamId,
+    workstreamTitle,
+    nodeType: node.type,
+    artifactCount: plan.artifacts.filter((artifact) => artifact.nodeId === node.id).length,
+    hasApproval: Boolean(approval),
+    approvalId: approval?.id ?? null,
+    approvalStatus: approval?.status ?? null,
+    blockedReason: node.blockedReason ?? null,
+    latestNotes: node.latestNotes ?? null,
+    startedAt: node.startedAt ?? null,
+    completedAt: node.completedAt ?? null,
+    readyAt: node.readyAt ?? null,
+  }
+}
+
+function buildPlanViewNode(
+  node: SerializablePlanNode,
+  plan: SerializableExecutionPlan,
+  workstreamId: string,
+  workstreamTitle: string,
+): PlanViewNode {
+  return {
+    ...planNodeToCard(node, plan, workstreamId, workstreamTitle),
+    deliverableNames: node.deliverables.map((deliverable) => deliverable.name),
+    upstreamNodeIds: node.upstreamNodeIds,
+    downstreamNodeIds: node.downstreamNodeIds,
+  }
+}
+
+export class AgentActivityService {
+  constructor(private readonly deps: AgentActivityDeps = { executionPlanService, workstreamService }) {}
+
+  async getBoard(userRef: string, orgRef: string): Promise<PlanBoardResponse> {
+    const activePlans = await this.getAllActivePlans(userRef, orgRef)
+    const cards = activePlans.flatMap(({ plan, workstream }) =>
+      plan.nodes.map((node) => planNodeToCard(node, plan, workstream.id, workstream.title)),
+    )
+
+    const columns: PlanBoardColumn[] = BOARD_COLUMN_ORDER.map((status) => ({
+      status,
+      label: COLUMN_LABELS[status],
+      nodes: cards.filter((card) => card.status === status),
+    }))
+
+    return {
+      columns,
+      summary: {
+        totalNodes: cards.length,
+        completedNodes: cards.filter((card) => card.status === 'completed').length,
+        activePlanCount: activePlans.length,
+        pendingApprovalCount: cards.filter((card) => card.hasApproval).length,
+      },
+    }
+  }
+
+  async getPlanView(orgRef: string, planRunId: string, userRef: string): Promise<PlanViewResponse | null> {
+    const activePlans = await this.getAllActivePlans(userRef, orgRef)
+    const match = activePlans.find(({ plan }) => plan.runId === planRunId)
+    if (!match) return null
+
+    const { plan, workstream } = match
+    return {
+      planRunId: plan.runId,
+      title: plan.title,
+      objective: plan.objective,
+      status: plan.status,
+      leadAgentId: plan.leadAgentId,
+      progress: { completed: plan.progress.completed + plan.progress.partial, total: plan.progress.total },
+      nodes: plan.nodes.map((node) => buildPlanViewNode(node, plan, workstream.id, workstream.title)),
+      edges: plan.edges.map((edge) => ({ from: edge.source, to: edge.target })),
+    }
+  }
+
+  async getMyTasks(userRef: string, orgRef: string): Promise<MyTasksResponse> {
+    const activePlans = await this.getAllActivePlans(userRef, orgRef)
+    const tasks: PlanNodeCard[] = []
+
+    for (const { plan, workstream } of activePlans) {
+      for (const node of plan.nodes) {
+        const humanOwned = node.owner.executorType === 'user'
+        const awaitingHuman = node.status === 'awaiting-human'
+        if (!humanOwned && !awaitingHuman) continue
+
+        tasks.push(planNodeToCard(node, plan, workstream.id, workstream.title))
+      }
+    }
+
+    return { tasks, pendingApprovalCount: tasks.filter((task) => task.hasApproval).length }
+  }
+
+  async getAgentActivity(userRef: string, orgRef: string): Promise<AgentActivityResponse> {
+    const activePlans = await this.getAllActivePlans(userRef, orgRef)
+    const activityByAgent = new Map<string, AgentActivityEntry>()
+
+    for (const agentId of agentRoster) {
+      activityByAgent.set(agentId, this.createEmptyEntry(agentId))
+    }
+
+    for (const { plan, workstream } of activePlans) {
+      const involvedAgents = new Set<string>()
+
+      for (const node of plan.nodes) {
+        if (node.owner.executorType !== 'agent') continue
+
+        const agentId = node.owner.ref
+        const entry = this.ensureEntry(activityByAgent, agentId)
+        involvedAgents.add(agentId)
+        incrementCounts(entry.counts, node.status)
+
+        if (!isCompletedStatus(node.status)) {
+          entry.tasks.push(planNodeToCard(node, plan, workstream.id, workstream.title))
+        }
+      }
+
+      if (plan.leadAgentId.trim()) {
+        const leadEntry = this.ensureEntry(activityByAgent, plan.leadAgentId)
+        leadEntry.isLeadingActivePlan = true
+        involvedAgents.add(plan.leadAgentId)
+      }
+
+      for (const agentId of involvedAgents) {
+        const entry = this.ensureEntry(activityByAgent, agentId)
+        this.ensureProjectEntry(entry.projects, {
+          workstreamId: workstream.id,
+          workstreamTitle: workstream.title,
+          planRunId: plan.runId,
+          planTitle: plan.title,
+          status: plan.status,
+        })
+
+        entry.isRunning = entry.isRunning || workstream.isRunning
+        entry.lastActiveAt = maxIsoDate(entry.lastActiveAt, workstream.updatedAt)
+      }
+    }
+
+    const userTasks = await this.getMyTasks(userRef, orgRef)
+    const agents = [...activityByAgent.values()].sort((left, right) => {
+      const leftIndex = agentRoster.indexOf(left.agentId)
+      const rightIndex = agentRoster.indexOf(right.agentId)
+      if (leftIndex !== -1 || rightIndex !== -1) {
+        if (leftIndex === -1) return 1
+        if (rightIndex === -1) return -1
+        return leftIndex - rightIndex
+      }
+      return left.agentId.localeCompare(right.agentId)
+    })
+
+    return {
+      agents,
+      userActivity: {
+        taskCount: userTasks.tasks.length,
+        pendingApprovalCount: userTasks.pendingApprovalCount,
+        awaitingHumanCount: userTasks.tasks.filter((task) => task.status === 'awaiting-human').length,
+        lastActiveAt: activePlans.reduce<string | null>(
+          (latest, entry) => maxIsoDate(latest, entry.workstream.updatedAt),
+          null,
+        ),
+      },
+      totalActivePlans: activePlans.length,
+    }
+  }
+
+  async getAllActivePlans(userRef: string, orgRef: string): Promise<ActivePlanEntry[]> {
+    const workstreams = await this.listRelevantWorkstreams(userRef, orgRef)
+    const planResults = await Promise.all(
+      workstreams.map(async (workstream) => {
+        try {
+          const plans = await this.deps.executionPlanService.getActivePlansForWorkstream(workstream.id)
+          return plans.map((plan) => ({ plan, workstream }))
+        } catch (error) {
+          serverLogger.error`Failed to load active plans for workstream ${workstream.id}: ${error}`
+          return []
+        }
+      }),
+    )
+
+    return planResults.flat()
+  }
+
+  private async listRelevantWorkstreams(userRef: string, orgRef: string): Promise<NormalizedWorkstream[]> {
+    const [direct, core, group] = await Promise.all([
+      this.deps.workstreamService.listWorkstreams(userRef, orgRef, { mode: 'direct', includeArchived: false }),
+      this.deps.workstreamService.listWorkstreams(userRef, orgRef, {
+        mode: 'group',
+        core: true,
+        includeArchived: false,
+      }),
+      this.deps.workstreamService.listWorkstreams(userRef, orgRef, {
+        mode: 'group',
+        core: false,
+        includeArchived: false,
+        take: 500,
+        page: 1,
+      }),
+    ])
+
+    const deduped = new Map<string, NormalizedWorkstream>()
+    for (const workstream of [...direct.workstreams, ...core.workstreams, ...group.workstreams]) {
+      deduped.set(workstream.id, workstream)
+    }
+
+    return [...deduped.values()]
+  }
+
+  private createEmptyEntry(agentId: string): AgentActivityEntry {
+    return {
+      agentId,
+      counts: createEmptyCounts(),
+      tasks: [],
+      projects: [],
+      isLeadingActivePlan: false,
+      isRunning: false,
+      lastActiveAt: null,
+    }
+  }
+
+  private ensureEntry(entries: Map<string, AgentActivityEntry>, agentId: string): AgentActivityEntry {
+    const existing = entries.get(agentId)
+    if (existing) {
+      return existing
+    }
+
+    const created = this.createEmptyEntry(agentId)
+    entries.set(agentId, created)
+    return created
+  }
+
+  private ensureProjectEntry(projects: AgentProjectEntry[], next: AgentProjectEntry): void {
+    if (projects.some((project) => project.planRunId === next.planRunId)) {
+      return
+    }
+
+    projects.push(next)
+  }
+}
+
+export const agentActivityService = new AgentActivityService()

package/src/services/index.ts

@@ -1,5 +1,6 @@
 export * from './adaptive-playbook.service'
 export * from './agent-executor.service'
+export * from './agent-activity.service'
 export * from './artifact-provenance.service'
 export * from './attachment.service'
 export * from './autonomous-job.service'

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

@@ -7,6 +7,7 @@ import {
   SubmitExecutionNodeResultArgsSchema,
   getLatestExecutionPlanResult,
 } from '@lota-sdk/shared'
+import type { PlanDraft } from '@lota-sdk/shared'
 import { tool } from 'ai'
 
 import type { RecordIdRef } from '../db/record-id'
@@ -17,17 +18,20 @@ export function createCreateExecutionPlanTool(params: {
   workstreamId: RecordIdRef
   agentId: string
   onPlanChanged?: () => void
+  validateInlinePlan?: (draft: PlanDraft) => 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, ...draft } = input
+      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

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'

package/src/tools/project-with-plan.tool.ts

@@ -0,0 +1,87 @@
+import type { CreateProjectWithPlanResultData } from '@lota-sdk/shared'
+import { CreateProjectWithPlanArgsSchema, expandAgentPlanDraft } from '@lota-sdk/shared'
+import { tool } from 'ai'
+
+import type { RecordIdRef } from '../db/record-id'
+import { recordIdToString } from '../db/record-id'
+import { TABLES } from '../db/tables'
+import { executionPlanService } from '../services/execution-plan.service'
+import { workstreamService } from '../services/workstream.service'
+
+type ProjectWithPlanWorkstreamService = Pick<
+  typeof workstreamService,
+  'createWorkstream' | 'deleteWorkstream' | 'getWorkstream'
+>
+
+type ProjectWithPlanExecutionPlanService = Pick<
+  typeof executionPlanService,
+  'createPlan' | 'getActivePlansForWorkstream'
+>
+
+export function createCreateProjectWithPlanTool(params: {
+  orgId: RecordIdRef
+  userId: RecordIdRef
+  agentId: string
+  workstreamService?: ProjectWithPlanWorkstreamService
+  executionPlanService?: ProjectWithPlanExecutionPlanService
+  onPlanChanged?: () => void
+}) {
+  const resolvedWorkstreamService = params.workstreamService ?? workstreamService
+  const resolvedExecutionPlanService = params.executionPlanService ?? executionPlanService
+
+  return tool({
+    description:
+      'Create a dedicated project workstream with an execution plan, or add a simplified agent-authored plan to an existing target workstream.',
+    inputSchema: CreateProjectWithPlanArgsSchema,
+    execute: async (input): Promise<CreateProjectWithPlanResultData> => {
+      const { projectTitle, targetWorkstreamId, ...draftInput } = input
+      const expandedDraft = expandAgentPlanDraft(draftInput)
+
+      const targetWorkstream = targetWorkstreamId
+        ? await resolvedWorkstreamService.getWorkstream(targetWorkstreamId)
+        : await resolvedWorkstreamService.createWorkstream(params.userId, params.orgId, {
+            title: projectTitle,
+            mode: 'group',
+          })
+
+      if (targetWorkstream.organizationId !== recordIdToString(params.orgId, TABLES.ORGANIZATION)) {
+        throw new Error('Target workstream belongs to a different organization.')
+      }
+      if (targetWorkstream.userId !== recordIdToString(params.userId, TABLES.USER)) {
+        throw new Error('Target workstream belongs to a different user.')
+      }
+
+      const existingPlans = await resolvedExecutionPlanService.getActivePlansForWorkstream(targetWorkstream.id)
+      if (!targetWorkstream.core && existingPlans.length > 0) {
+        throw new Error(
+          'This workstream already has an active execution plan. Use replaceExecutionPlan or target a core workstream.',
+        )
+      }
+
+      const createdWorkstream = !targetWorkstreamId
+
+      try {
+        const result = await resolvedExecutionPlanService.createPlan({
+          organizationId: params.orgId,
+          workstreamId: targetWorkstream.id,
+          leadAgentId: params.agentId,
+          input: expandedDraft,
+        })
+
+        params.onPlanChanged?.()
+
+        return {
+          ...result,
+          workstreamId: targetWorkstream.id,
+          workstreamTitle: targetWorkstream.title,
+          createdWorkstream,
+        }
+      } catch (error) {
+        if (createdWorkstream) {
+          await resolvedWorkstreamService.deleteWorkstream(targetWorkstream.id).catch(() => {})
+        }
+        throw error
+      }
+    },
+  })
+}