@lota-sdk/core 0.1.24 → 0.1.26

package/src/runtime/workstream-plan-turn.ts

@@ -0,0 +1,195 @@
+import { SUBMIT_PLAN_TURN_RESULT_TOOL_NAME, withMessageCreatedAt } from '@lota-sdk/shared'
+import type {
+  ChatMessage,
+  PlanArtifactSubmission,
+  PlanNodeHandoffContext,
+  PlanNodeRunRecord,
+  PlanNodeSpecRecord,
+} from '@lota-sdk/shared'
+
+import { buildCompletionCheckStructuredOutputHints } from './agent-runtime-policy'
+import { mergeInstructionSections } from './instruction-sections'
+
+export interface PlanTurnUpstreamHandoff {
+  nodeId: string
+  label: string
+  ownerRef: string
+  ownerType: PlanNodeSpecRecord['owner']['executorType']
+  handoffContext: PlanNodeHandoffContext
+}
+
+export interface WorkstreamPlanTurnContext {
+  runId: string
+  nodeId: string
+  planTitle: string
+  nodeSpec: PlanNodeSpecRecord
+  nodeRun: PlanNodeRunRecord
+  resolvedInput: Record<string, unknown>
+  inputArtifacts: PlanArtifactSubmission[]
+  upstreamHandoffs: PlanTurnUpstreamHandoff[]
+}
+
+function describePlanTurnDeliverable(deliverable: PlanNodeSpecRecord['deliverables'][number]): string {
+  return [
+    `- ${deliverable.name}`,
+    `kind=${deliverable.kind}`,
+    deliverable.required ? 'required' : 'optional',
+    deliverable.schemaRef ? `schemaRef=${deliverable.schemaRef}` : undefined,
+    deliverable.description ? `description=${deliverable.description}` : undefined,
+  ]
+    .filter(Boolean)
+    .join(' | ')
+}
+
+function describePlanTurnCompletionCheck(check: PlanNodeSpecRecord['completionChecks'][number]): string {
+  return [
+    `- ${check.description}`,
+    `type=${check.type}`,
+    check.blocking ? 'blocking' : 'warning',
+    Object.keys(check.config).length > 0 ? `config=${JSON.stringify(check.config)}` : undefined,
+  ]
+    .filter(Boolean)
+    .join(' | ')
+}
+
+function buildPlanTurnExecutionSection(planTurn: WorkstreamPlanTurnContext): string {
+  const payload = {
+    runId: planTurn.runId,
+    planTitle: planTurn.planTitle,
+    node: {
+      id: planTurn.nodeSpec.nodeId,
+      label: planTurn.nodeSpec.label,
+      owner: planTurn.nodeSpec.owner,
+      objective: planTurn.nodeSpec.objective,
+      instructions: planTurn.nodeSpec.instructions,
+      outputSchemaRef: planTurn.nodeSpec.outputSchemaRef ?? null,
+      deliverables: planTurn.nodeSpec.deliverables,
+      successCriteria: planTurn.nodeSpec.successCriteria,
+      completionChecks: planTurn.nodeSpec.completionChecks,
+      toolPolicy: planTurn.nodeSpec.toolPolicy,
+      contextPolicy: planTurn.nodeSpec.contextPolicy,
+    },
+    resolvedInput: planTurn.resolvedInput,
+    inputArtifacts: planTurn.inputArtifacts,
+  }
+
+  return [
+    '<plan-turn-execution>',
+    'The runtime has activated a visible execution-plan node inside this workstream.',
+    `Complete node "${planTurn.nodeSpec.label}" for plan "${planTurn.planTitle}".`,
+    'Use only the node contract, resolved input, input artifacts, and upstream handoff context provided here.',
+    'Do not ask the user for more input and do not rely on unstated external context.',
+    'Do not submit placeholders, partial work, or speculative outputs.',
+    'Before submitting, satisfy every required deliverable, success criterion, and completion check for this node.',
+    'Deliverables must use the exact artifact names and kinds declared in the node contract.',
+    'If a deliverable declares schemaRef, include the same schemaRef and a payload that satisfies that schema.',
+    'If outputSchemaRef is declared, structuredOutput must satisfy that schema before you submit.',
+    `When finished, call ${SUBMIT_PLAN_TURN_RESULT_TOOL_NAME} exactly once.`,
+    'Always include durable handoffContext for downstream nodes when you submit the final result.',
+    'Do not ask the user for confirmation and do not create or replace execution plans in this turn.',
+    JSON.stringify(payload, null, 2),
+    '</plan-turn-execution>',
+  ].join('\n')
+}
+
+function buildPlanTurnResultContractSection(planTurn: WorkstreamPlanTurnContext): string {
+  const requiredDeliverables = planTurn.nodeSpec.deliverables.filter((deliverable) => deliverable.required)
+  const completionCheckOutputHints = buildCompletionCheckStructuredOutputHints(planTurn.nodeSpec)
+  const deliverableLines =
+    planTurn.nodeSpec.deliverables.length > 0
+      ? planTurn.nodeSpec.deliverables.map(describePlanTurnDeliverable)
+      : ['- none']
+  const completionCheckLines =
+    planTurn.nodeSpec.completionChecks.length > 0
+      ? planTurn.nodeSpec.completionChecks.map(describePlanTurnCompletionCheck)
+      : ['- none']
+
+  return [
+    '<plan-turn-result-contract>',
+    `Call ${SUBMIT_PLAN_TURN_RESULT_TOOL_NAME} exactly once with a result object that passes node validation.`,
+    'Validation is strict. Missing required artifacts, schema mismatches, or failed completion checks will fail the node run.',
+    `Required artifacts: ${requiredDeliverables.length > 0 ? requiredDeliverables.map((deliverable) => deliverable.name).join(', ') : 'none'}`,
+    `Structured output: ${
+      planTurn.nodeSpec.outputSchemaRef
+        ? `required and must match schema "${planTurn.nodeSpec.outputSchemaRef}"`
+        : 'optional unless needed by a completion check'
+    }`,
+    'Deliverables:',
+    ...deliverableLines,
+    'Completion checks:',
+    ...completionCheckLines,
+    ...(completionCheckOutputHints.length > 0
+      ? ['Structured output fields required by completion checks:', ...completionCheckOutputHints]
+      : []),
+    'Include notes with a concise completion summary grounded in the submitted artifacts and structuredOutput.',
+    'Always include handoffContext for downstream execution with a durable summary, key decisions, open questions, risks, recommendations, and references when relevant.',
+    '</plan-turn-result-contract>',
+  ].join('\n')
+}
+
+function buildUpstreamHandoffSection(upstreamHandoffs: PlanTurnUpstreamHandoff[]): string | undefined {
+  if (upstreamHandoffs.length === 0) {
+    return undefined
+  }
+
+  return [
+    '<upstream-handoff>',
+    JSON.stringify(
+      upstreamHandoffs.map((handoff) => ({
+        nodeId: handoff.nodeId,
+        label: handoff.label,
+        ownerRef: handoff.ownerRef,
+        ownerType: handoff.ownerType,
+        handoffContext: handoff.handoffContext,
+      })),
+      null,
+      2,
+    ),
+    '</upstream-handoff>',
+  ].join('\n')
+}
+
+export function buildPlanTurnInstructionSections(planTurn: WorkstreamPlanTurnContext): string[] {
+  const upstreamHandoffSection = buildUpstreamHandoffSection(planTurn.upstreamHandoffs)
+  return (
+    mergeInstructionSections(
+      [buildPlanTurnExecutionSection(planTurn), buildPlanTurnResultContractSection(planTurn)],
+      upstreamHandoffSection ? [upstreamHandoffSection] : undefined,
+    ) ?? []
+  )
+}
+
+export function buildPlanTurnSubmitToolDescription(planTurn: WorkstreamPlanTurnContext): string {
+  const requiredArtifacts =
+    planTurn.nodeSpec.deliverables
+      .filter((deliverable) => deliverable.required)
+      .map((deliverable) => `${deliverable.name} (${deliverable.kind})`)
+      .join(', ') || 'none'
+
+  return [
+    'Submit the final result for the active plan-triggered node turn.',
+    'Call this exactly once when the node output is complete.',
+    `Required artifacts: ${requiredArtifacts}.`,
+    `Structured output: ${
+      planTurn.nodeSpec.outputSchemaRef ? `must satisfy ${planTurn.nodeSpec.outputSchemaRef}` : 'optional'
+    }.`,
+    'Do not submit partial results. Include durable handoffContext for downstream nodes.',
+  ].join(' ')
+}
+
+export function buildPlanTurnPromptMessage(planTurn: WorkstreamPlanTurnContext): ChatMessage {
+  return withMessageCreatedAt(
+    {
+      id: Bun.randomUUIDv7(),
+      role: 'user',
+      parts: [
+        {
+          type: 'text',
+          text: `Execute the active plan node "${planTurn.nodeSpec.label}" now and submit the result with ${SUBMIT_PLAN_TURN_RESULT_TOOL_NAME}.`,
+        },
+      ],
+      metadata: { trigger: 'plan-turn', planRunId: planTurn.runId, planNodeId: planTurn.nodeId },
+    },
+    Date.now(),
+  )
+}

package/src/runtime/workstream-state.ts

@@ -116,10 +116,10 @@ export const WorkstreamStateDeltaSchema = z.object({
   conflicts: z
     .array(z.object({ newFact: z.string(), conflictsWith: z.string(), recommendation: z.string() }))
     .optional(),
-  approvedBy: z.string().optional(),
-  approvedAt: z.number().int().optional(),
-  approvalMessageId: z.string().optional(),
-  approvalNote: z.string().optional(),
+  approvedBy: z.string().nullable().optional(),
+  approvedAt: z.number().int().nullable().optional(),
+  approvalMessageId: z.string().nullable().optional(),
+  approvalNote: z.string().nullable().optional(),
 })
 
 export type WorkstreamStateDelta = z.infer<typeof WorkstreamStateDeltaSchema>
@@ -194,6 +194,7 @@ export function createEmptyStructuredWorkstreamStateDelta(): StructuredWorkstrea
 }
 
 export function parseStructuredWorkstreamStateDelta(value: unknown): WorkstreamStateDelta {
+  const inputRecord = typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : null
   const parsed = StructuredWorkstreamStateDeltaSchema.parse(value)
 
   return {
@@ -221,10 +222,12 @@ export function parseStructuredWorkstreamStateDelta(value: unknown): WorkstreamS
     ...(parsed.artifacts.length > 0 ? { artifacts: parsed.artifacts } : {}),
     ...(parsed.agentNote ? { agentNote: parsed.agentNote } : {}),
     ...(parsed.conflicts.length > 0 ? { conflicts: parsed.conflicts } : {}),
-    ...(parsed.approvedBy !== null ? { approvedBy: parsed.approvedBy } : {}),
-    ...(parsed.approvedAt !== null ? { approvedAt: parsed.approvedAt } : {}),
-    ...(parsed.approvalMessageId !== null ? { approvalMessageId: parsed.approvalMessageId } : {}),
-    ...(parsed.approvalNote !== null ? { approvalNote: parsed.approvalNote } : {}),
+    ...(inputRecord && Object.hasOwn(inputRecord, 'approvedBy') ? { approvedBy: parsed.approvedBy } : {}),
+    ...(inputRecord && Object.hasOwn(inputRecord, 'approvedAt') ? { approvedAt: parsed.approvedAt } : {}),
+    ...(inputRecord && Object.hasOwn(inputRecord, 'approvalMessageId')
+      ? { approvalMessageId: parsed.approvalMessageId }
+      : {}),
+    ...(inputRecord && Object.hasOwn(inputRecord, 'approvalNote') ? { approvalNote: parsed.approvalNote } : {}),
   }
 }
 

package/src/runtime/workstream-turn-context.ts

@@ -0,0 +1,183 @@
+import type { RecordIdRef } from '../db/record-id'
+import { buildAgentPromptContext } from './agent-prompt-context'
+import { buildIndexedRepositoriesContext, getPluginService } from './plugin-resolution'
+import type {
+  LotaRuntimeIndexedRepositoriesContext,
+  LotaRuntimeTurnHooks,
+  LotaRuntimeWorkspaceLifecycleState,
+  LotaRuntimeWorkspaceProjectionState,
+  LotaRuntimeWorkspaceProvider,
+} from './runtime-extensions'
+import { asRecord, readInstructionSections, readOptionalString } from './workstream-chat-helpers'
+
+function readOptionalBoolean(value: unknown): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined
+}
+
+interface AssembledWorkstreamTurnContext {
+  workspace: Record<string, unknown>
+  workspaceLifecycleState: LotaRuntimeWorkspaceLifecycleState | undefined
+  workspaceProfileState: LotaRuntimeWorkspaceProjectionState | undefined
+  onboardingActive: boolean
+  linearInstalled: boolean
+  githubInstalled: boolean
+  indexedRepoContext: LotaRuntimeIndexedRepositoriesContext
+  promptContext: { systemWorkspaceDetails?: string }
+  retrievedKnowledgeSection: string | undefined
+  buildContextResult: Record<string, unknown> | null
+  hookInstructionSections: string[]
+}
+
+export async function assembleWorkstreamTurnContext(params: {
+  workstream: unknown
+  workstreamRef: RecordIdRef
+  orgRef: RecordIdRef
+  userRef: RecordIdRef
+  userName?: string | null
+  orgIdString: string
+  userIdString: string
+  messageText: string
+  workspacePromise: Promise<Record<string, unknown>>
+  workspaceProvider?: LotaRuntimeWorkspaceProvider
+  turnHooks: LotaRuntimeTurnHooks
+  onStep?: (name: string) => void
+}): Promise<AssembledWorkstreamTurnContext> {
+  const workspace = await params.workspacePromise
+  params.onStep?.('fetch-workspace')
+
+  const [workspaceLifecycleState, workspaceProfileState] = await Promise.all([
+    params.workspaceProvider ? params.workspaceProvider.getLifecycleState?.(workspace) : Promise.resolve(undefined),
+    params.workspaceProvider
+      ? params.workspaceProvider.readProfileProjectionState?.(workspace)
+      : Promise.resolve(undefined),
+  ])
+  params.onStep?.('workspace-state')
+
+  const onboardingActive = workspaceLifecycleState?.bootstrapActive ?? false
+  const getLinearInstallationByOrgId = getPluginService([
+    'linear',
+    'services',
+    'linearService',
+    'getInstallationByOrgId',
+  ])
+  const getGithubInstallationForOrganization = getPluginService([
+    'github',
+    'services',
+    'githubService',
+    'getInstallationForOrganization',
+  ])
+  const [linearInstallation, githubInstallation, indexedRepoContext, recentDomainEvents, promptSummary] =
+    await Promise.all([
+      getLinearInstallationByOrgId
+        ? (getLinearInstallationByOrgId(params.orgRef) as Promise<unknown>)
+        : Promise.resolve(null),
+      getGithubInstallationForOrganization
+        ? (getGithubInstallationForOrganization(params.orgIdString) as Promise<unknown>)
+        : Promise.resolve(null),
+      buildIndexedRepositoriesContext(params.orgIdString),
+      params.workspaceProvider?.listRecentDomainEvents?.(params.orgRef, 5) ??
+        Promise.resolve([] as Array<Record<string, unknown>>),
+      params.workspaceProvider?.buildPromptSummary
+        ? params.workspaceProvider.buildPromptSummary(params.orgRef).catch(() => undefined)
+        : Promise.resolve(undefined),
+    ])
+  params.onStep?.('parallel-context-fetch(plugins+repos+events+summary)')
+
+  let linearInstalled = Boolean(linearInstallation)
+  let githubInstalled = Boolean(githubInstallation)
+  let promptContext = buildAgentPromptContext({
+    workspaceName:
+      workspaceProfileState?.workspaceName ?? readOptionalString((workspace as { name?: unknown }).name) ?? undefined,
+    summaryBlock: workspaceProfileState?.summaryBlock,
+    promptSummary,
+    userName: params.userName ?? undefined,
+    recentDomainEvents,
+  })
+  let retrievedKnowledgeSection: string | undefined =
+    onboardingActive || !params.messageText
+      ? undefined
+      : await params.workspaceProvider?.buildRetrievedKnowledgeSection?.({
+          workspaceId: params.orgIdString,
+          userId: params.userIdString,
+          query: params.messageText,
+        })
+  params.onStep?.('rag-knowledge-retrieval')
+
+  const buildContextResult = asRecord(
+    await params.turnHooks.buildContext?.({
+      workstream: params.workstream,
+      workstreamRef: params.workstreamRef,
+      orgRef: params.orgRef,
+      userRef: params.userRef,
+      userName: params.userName,
+      workspace,
+      onboardingActive,
+      messageText: params.messageText,
+      linearInstalled,
+      githubInstalled,
+      indexedRepoContext,
+      promptContext,
+      workspaceLifecycleState,
+      workspaceProfileState,
+      promptSummary,
+      recentDomainEvents,
+      retrievedKnowledgeSection,
+    }),
+  )
+  params.onStep?.('hook:buildContext')
+
+  const buildContextPromptDetails = readOptionalString(buildContextResult?.systemWorkspaceDetails)
+  if (buildContextPromptDetails) {
+    promptContext = { systemWorkspaceDetails: buildContextPromptDetails }
+  }
+  const buildContextRetrievedKnowledge = readOptionalString(buildContextResult?.retrievedKnowledgeSection)
+  if (buildContextRetrievedKnowledge !== undefined) {
+    retrievedKnowledgeSection = buildContextRetrievedKnowledge
+  }
+  const buildContextLinearInstalled = readOptionalBoolean(buildContextResult?.linearInstalled)
+  if (buildContextLinearInstalled !== undefined) {
+    linearInstalled = buildContextLinearInstalled
+  }
+  const buildContextGithubInstalled = readOptionalBoolean(buildContextResult?.githubInstalled)
+  if (buildContextGithubInstalled !== undefined) {
+    githubInstalled = buildContextGithubInstalled
+  }
+
+  const hookInstructionSections = readInstructionSections(
+    await params.turnHooks.buildExtraInstructionSections?.({
+      workstream: params.workstream,
+      workstreamRef: params.workstreamRef,
+      orgRef: params.orgRef,
+      userRef: params.userRef,
+      userName: params.userName,
+      workspace,
+      onboardingActive,
+      messageText: params.messageText,
+      linearInstalled,
+      githubInstalled,
+      indexedRepoContext,
+      promptContext,
+      workspaceLifecycleState,
+      workspaceProfileState,
+      promptSummary,
+      recentDomainEvents,
+      retrievedKnowledgeSection,
+      context: buildContextResult,
+    }),
+  )
+  params.onStep?.('hook:buildExtraInstructionSections')
+
+  return {
+    workspace,
+    workspaceLifecycleState,
+    workspaceProfileState,
+    onboardingActive,
+    linearInstalled,
+    githubInstalled,
+    indexedRepoContext,
+    promptContext,
+    retrievedKnowledgeSection,
+    buildContextResult,
+    hookInstructionSections,
+  }
+}

package/src/services/autonomous-job.service.ts

@@ -31,6 +31,7 @@ import { databaseService } from '../db/service'
 import { TABLES } from '../db/tables'
 import type { AutonomousJobQueuePayload } from '../queues/autonomous-job.queue'
 import { extractMessageText } from '../runtime/workstream-chat-helpers'
+import { buildAutonomousAtJobId, encodeBullmqId } from '../utils/autonomous-job-ids'
 import { toIsoDateTimeString, toOptionalIsoDateTimeString } from '../utils/date-time'
 import { compactRecord, compactWhitespace, stringifyUnknown, truncateText } from '../utils/string'
 import { executionPlanService } from './execution-plan.service'
@@ -41,14 +42,6 @@ import { workstreamService } from './workstream.service'
 
 const AUTONOMOUS_JOB_QUEUE_NAME = 'autonomous-job'
 
-function encodeBullmqId(raw: string): string {
-  return Buffer.from(raw).toString('base64url')
-}
-
-function buildAutonomousAtJobId(autonomousJobId: string): string {
-  return `autonomous-at-${encodeBullmqId(autonomousJobId)}`
-}
-
 function buildAutonomousManualJobId(autonomousJobId: string): string {
   return `autonomous-manual-${encodeBullmqId(autonomousJobId)}-${Date.now()}`
 }