@lota-sdk/shared 0.1.22 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/shared",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/constants/execution-plan.ts

@@ -0,0 +1,15 @@
+export const SILENT_EXECUTION_VISIBILITY = 'silent' as const
+
+export const PROJECT_PLAN_ROUTING_PROMPT = `<project-plan-routing>
+- Use createExecutionPlan for small inline work inside the current workstream.
+- Use createProjectWithPlan when the work needs a dedicated project workstream, should stay visible in the sidebar or board, or needs 3 or more meaningful execution nodes.
+- If createExecutionPlan rejects a larger draft, immediately retry with createProjectWithPlan instead of forcing the plan inline.
+</project-plan-routing>`
+
+export const EXECUTION_PLAN_SELF_START_PROMPT = `<execution-plan-self-start>
+- When you create an execution plan with createExecutionPlan or createProjectWithPlan and the first node is assigned to you, begin executing that node immediately in the same turn. Do not wait for the user to ask.
+- After completing a node, submit the result and check whether the next ready node is also yours. If so, continue working.
+- When the user's message relates to an active plan where you own ready nodes, inspect the plan state and proactively work on your ready nodes.
+- When you own a blocked or failed node, tell the user what is blocked and what resolution is needed.
+- Briefly acknowledge what you are doing before you start work on a plan node.
+</execution-plan-self-start>`

package/src/index.ts

@@ -1,8 +1,10 @@
 export * from './constants/attachments'
+export * from './constants/execution-plan'
 export * from './constants/workstream'
 export * from './runtime/agent-types'
 export * from './runtime/chat-message-metadata'
 export * from './runtime/execution-plan-result'
+export * from './schemas/agent-plan-draft'
 export * from './schemas/chat-api'
 export * from './schemas/chat-message'
 export * from './schemas/common'
@@ -14,6 +16,7 @@ export * from './schemas/execution-plan'
 export * from './schemas/graph-designer'
 export * from './schemas/organization'
 export * from './schemas/organization-api'
+export * from './schemas/plan-board'
 export * from './schemas/playbook'
 export * from './schemas/plugin-coordination'
 export * from './schemas/queue-job'

package/src/schemas/agent-plan-draft.ts

@@ -0,0 +1,232 @@
+import { z } from 'zod'
+
+import { SILENT_EXECUTION_VISIBILITY } from '../constants/execution-plan'
+import type { PlanArtifactSpec, PlanCompletionCheck, PlanDraft, PlanNodeOwner, PlanNodeType } from './execution-plan'
+import {
+  ExecutionModeSchema,
+  PlanArtifactSpecSchema,
+  PlanCompletionCheckSchema,
+  PlanCompletionCheckTypeSchema,
+  PlanContextPolicySchema,
+  PlanEdgeSpecSchema,
+  PlanExecutionVisibilitySchema,
+  PlanNodeOwnerSchema,
+  PlanNodeTypeSchema,
+  PlanRetryPolicySchema,
+  PlanToolPolicySchema,
+} from './execution-plan'
+
+const STRUCTURAL_NODE_TYPES = new Set<PlanNodeType>(['switch', 'join', 'deliberation-fork'])
+
+const agentPlanOwnerStringSchema = z.string().trim().min(1).max(200)
+
+const AgentPlanDeliverableDraftSchema = z.union([z.string().trim().min(1).max(1000), PlanArtifactSpecSchema])
+
+const SimplifiedCompletionCheckSchema = z.object({
+  type: PlanCompletionCheckTypeSchema,
+  description: z.string().trim().min(1).max(1000),
+  blocking: z.boolean().optional(),
+  config: z.record(z.string(), z.unknown()).optional(),
+})
+
+const AgentPlanCompletionCheckDraftSchema = z.union([PlanCompletionCheckSchema, SimplifiedCompletionCheckSchema])
+
+export const AgentPlanNodeDraftSchema = z.object({
+  id: z.string().trim().min(1).max(200),
+  type: PlanNodeTypeSchema,
+  label: z.string().trim().min(1).max(300),
+  owner: z.union([PlanNodeOwnerSchema, agentPlanOwnerStringSchema]),
+  objective: z.string().trim().min(1).max(2000),
+  instructions: z.string().trim().min(1).max(4000),
+  successCriteria: z.array(z.string().trim().min(1).max(1000)).min(1),
+  deliverables: z.array(AgentPlanDeliverableDraftSchema).min(1).optional(),
+  completionChecks: z.array(AgentPlanCompletionCheckDraftSchema).min(1).optional(),
+})
+export type AgentPlanNodeDraft = z.infer<typeof AgentPlanNodeDraftSchema>
+
+export const AgentPlanEdgeDraftSchema = z.object({
+  id: z.string().trim().min(1).max(200),
+  source: z.string().trim().min(1).max(200),
+  target: z.string().trim().min(1).max(200),
+  when: z.string().trim().min(1).max(500).optional(),
+})
+export type AgentPlanEdgeDraft = z.infer<typeof AgentPlanEdgeDraftSchema>
+
+export const AgentPlanDraftSchema = z.object({
+  title: z.string().trim().min(1).max(200),
+  objective: z.string().trim().min(1).max(2000),
+  nodes: z.array(AgentPlanNodeDraftSchema).min(1).max(32),
+  edges: z.array(AgentPlanEdgeDraftSchema).default([]),
+  entryNodeIds: z.array(z.string().trim().min(1).max(200)).min(1).optional(),
+  executionMode: ExecutionModeSchema.optional(),
+})
+export type AgentPlanDraft = z.infer<typeof AgentPlanDraftSchema>
+
+export function normalizeOwner(owner: string | PlanNodeOwner): PlanNodeOwner {
+  if (typeof owner !== 'string') {
+    return owner
+  }
+
+  const normalized = owner.trim()
+  if (normalized.toLowerCase() === 'user') {
+    return { executorType: 'user', ref: 'user' }
+  }
+
+  return { executorType: 'agent', ref: normalized }
+}
+
+function toDeliverableName(value: string, fallback: string): string {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+  return normalized.length > 0 ? normalized.slice(0, 200) : fallback
+}
+
+function isStructuralNodeType(type: PlanNodeType): boolean {
+  return STRUCTURAL_NODE_TYPES.has(type)
+}
+
+function buildDefaultDeliverables(node: AgentPlanNodeDraft): PlanArtifactSpec[] {
+  if (isStructuralNodeType(node.type)) {
+    return []
+  }
+
+  if (node.type === 'human-approval') {
+    return [
+      { name: `${node.id}-approval`, kind: 'json', required: false, description: `Approval record from ${node.label}` },
+    ]
+  }
+
+  if (node.type === 'human-input' || node.type === 'human-review-edit' || node.type === 'human-decision') {
+    return [{ name: `${node.id}-response`, kind: 'json', required: false, description: `Response from ${node.label}` }]
+  }
+
+  return [{ name: `${node.id}-output`, kind: 'markdown', required: false, description: `Output from ${node.label}` }]
+}
+
+function expandDeliverables(node: AgentPlanNodeDraft): PlanArtifactSpec[] {
+  const deliverables = node.deliverables
+  if (!deliverables || deliverables.length === 0) {
+    return buildDefaultDeliverables(node)
+  }
+
+  return deliverables.map((deliverable, index) => {
+    if (typeof deliverable !== 'string') {
+      return deliverable
+    }
+
+    const description = deliverable.trim()
+    const fallbackName = `${node.id}-output-${index + 1}`
+    return { name: toDeliverableName(description, fallbackName), kind: 'markdown', required: false, description }
+  })
+}
+
+function buildDefaultCompletionChecks(
+  node: AgentPlanNodeDraft,
+  deliverables: PlanArtifactSpec[],
+): PlanCompletionCheck[] {
+  if (isStructuralNodeType(node.type)) {
+    return []
+  }
+
+  if (node.type === 'human-approval') {
+    return [
+      {
+        type: 'human-approval',
+        config: { approvedField: 'approved' },
+        blocking: true,
+        description: 'Approval recorded',
+      },
+    ]
+  }
+
+  if (node.type === 'human-input' || node.type === 'human-review-edit') {
+    return [
+      {
+        type: 'assertion',
+        config: { truthyPaths: ['responseText'] },
+        blocking: true,
+        description: 'Response captured',
+      },
+    ]
+  }
+
+  if (node.type === 'human-decision') {
+    return [
+      { type: 'assertion', config: { truthyPaths: ['approved'] }, blocking: true, description: 'Decision captured' },
+    ]
+  }
+
+  const primaryDeliverable = deliverables.at(0)
+  return [
+    {
+      type: 'tool-check',
+      config: primaryDeliverable ? { artifact: primaryDeliverable.name, mode: 'artifact-present' } : {},
+      blocking: true,
+      description: primaryDeliverable ? `Artifact "${primaryDeliverable.name}" exists` : 'Required output is present',
+    },
+  ]
+}
+
+function expandCompletionChecks(node: AgentPlanNodeDraft, deliverables: PlanArtifactSpec[]): PlanCompletionCheck[] {
+  const completionChecks = node.completionChecks
+  if (!completionChecks || completionChecks.length === 0) {
+    return buildDefaultCompletionChecks(node, deliverables)
+  }
+
+  const primaryDeliverable = deliverables.at(0)
+  return completionChecks.map((check) => {
+    const blocking = check.blocking ?? true
+    const config =
+      check.config ??
+      (check.type === 'human-approval'
+        ? { approvedField: 'approved' }
+        : check.type === 'tool-check' && primaryDeliverable
+          ? { artifact: primaryDeliverable.name, mode: 'artifact-present' }
+          : {})
+
+    return { type: check.type, description: check.description, blocking, config }
+  })
+}
+
+export function expandAgentPlanDraft(draft: AgentPlanDraft): PlanDraft {
+  const expandedNodes = draft.nodes.map((node) => {
+    const deliverables = expandDeliverables(node)
+    const completionChecks = expandCompletionChecks(node, deliverables)
+
+    return {
+      id: node.id,
+      type: node.type,
+      label: node.label,
+      owner: normalizeOwner(node.owner),
+      objective: node.objective,
+      instructions: node.instructions,
+      deliverables,
+      successCriteria: [...node.successCriteria],
+      completionChecks,
+      retryPolicy: PlanRetryPolicySchema.parse({ maxAttempts: 0, retryOn: [] }),
+      failurePolicy: [],
+      toolPolicy: PlanToolPolicySchema.parse({ allow: [], deny: [] }),
+      contextPolicy: PlanContextPolicySchema.parse({
+        retrievalScopes: [],
+        attachmentPolicy: 'referenced-only',
+        webPolicy: 'allowed',
+      }),
+      executionVisibility: PlanExecutionVisibilitySchema.parse('auto'),
+    }
+  })
+
+  return {
+    title: draft.title,
+    objective: draft.objective,
+    schemas: {},
+    defaultExecutionVisibility: SILENT_EXECUTION_VISIBILITY,
+    nodes: expandedNodes,
+    edges: draft.edges.map((edge) => PlanEdgeSpecSchema.parse({ ...edge, map: {} })),
+    entryNodeIds: draft.entryNodeIds ? [...draft.entryNodeIds] : undefined,
+    executionMode: draft.executionMode,
+  }
+}

package/src/schemas/execution-plan.ts

@@ -549,7 +549,7 @@ export const PlanNodeSpecSchema = z
     outputSchemaRef: z.string().trim().min(1).max(200).optional(),
     deliverables: z.array(PlanArtifactSpecSchema).default([]),
     successCriteria: z.array(z.string().trim().min(1).max(1000)).default([]),
-    completionChecks: z.array(PlanCompletionCheckSchema).default([]),
+    completionChecks: z.array(PlanCompletionCheckSchema).min(1),
     retryPolicy: PlanRetryPolicySchema.default({ maxAttempts: 0, retryOn: [] }),
     failurePolicy: z.array(PlanFailureRuleSchema).default([]),
     timeoutMs: z.number().int().positive().optional(),

package/src/schemas/plan-board.ts

@@ -0,0 +1,129 @@
+import { z } from 'zod'
+
+export const PlanNodeCardSchema = z
+  .object({
+    nodeId: z.string().trim().min(1),
+    label: z.string().trim().min(1),
+    objective: z.string(),
+    status: z.string().trim().min(1),
+    ownerType: z.string().trim().min(1),
+    ownerRef: z.string().trim().min(1),
+    planRunId: z.string().trim().min(1),
+    planTitle: z.string().trim().min(1),
+    workstreamId: z.string().trim().min(1),
+    workstreamTitle: z.string().trim().min(1),
+    nodeType: z.string().trim().min(1),
+    artifactCount: z.number().int().nonnegative(),
+    hasApproval: z.boolean(),
+    approvalId: z.string().trim().min(1).nullable(),
+    approvalStatus: z.string().trim().min(1).nullable(),
+    blockedReason: z.string().nullable(),
+    latestNotes: z.string().nullable(),
+    startedAt: z.iso.datetime().nullable(),
+    completedAt: z.iso.datetime().nullable(),
+    readyAt: z.iso.datetime().nullable(),
+  })
+  .strict()
+export type PlanNodeCard = z.infer<typeof PlanNodeCardSchema>
+
+export const PlanBoardColumnSchema = z
+  .object({ status: z.string().trim().min(1), label: z.string().trim().min(1), nodes: z.array(PlanNodeCardSchema) })
+  .strict()
+export type PlanBoardColumn = z.infer<typeof PlanBoardColumnSchema>
+
+export const PlanBoardResponseSchema = z
+  .object({
+    columns: z.array(PlanBoardColumnSchema),
+    summary: z
+      .object({
+        totalNodes: z.number().int().nonnegative(),
+        completedNodes: z.number().int().nonnegative(),
+        activePlanCount: z.number().int().nonnegative(),
+        pendingApprovalCount: z.number().int().nonnegative(),
+      })
+      .strict(),
+  })
+  .strict()
+export type PlanBoardResponse = z.infer<typeof PlanBoardResponseSchema>
+
+export const PlanViewNodeSchema = PlanNodeCardSchema.extend({
+  deliverableNames: z.array(z.string()),
+  upstreamNodeIds: z.array(z.string()),
+  downstreamNodeIds: z.array(z.string()),
+}).strict()
+export type PlanViewNode = z.infer<typeof PlanViewNodeSchema>
+
+export const PlanViewResponseSchema = z
+  .object({
+    planRunId: z.string().trim().min(1),
+    title: z.string().trim().min(1),
+    objective: z.string().trim().min(1),
+    status: z.string().trim().min(1),
+    leadAgentId: z.string().trim().min(1),
+    progress: z.object({ completed: z.number().int().nonnegative(), total: z.number().int().nonnegative() }).strict(),
+    nodes: z.array(PlanViewNodeSchema),
+    edges: z.array(z.object({ from: z.string().trim().min(1), to: z.string().trim().min(1) }).strict()),
+  })
+  .strict()
+export type PlanViewResponse = z.infer<typeof PlanViewResponseSchema>
+
+export const MyTasksResponseSchema = z
+  .object({ tasks: z.array(PlanNodeCardSchema), pendingApprovalCount: z.number().int().nonnegative() })
+  .strict()
+export type MyTasksResponse = z.infer<typeof MyTasksResponseSchema>
+
+export const AgentProjectEntrySchema = z
+  .object({
+    workstreamId: z.string().trim().min(1),
+    workstreamTitle: z.string().trim().min(1),
+    planRunId: z.string().trim().min(1),
+    planTitle: z.string().trim().min(1),
+    status: z.string().trim().min(1),
+  })
+  .strict()
+export type AgentProjectEntry = z.infer<typeof AgentProjectEntrySchema>
+
+export const AgentActivityCountsSchema = z
+  .object({
+    running: z.number().int().nonnegative(),
+    ready: z.number().int().nonnegative(),
+    pending: z.number().int().nonnegative(),
+    awaitingHuman: z.number().int().nonnegative(),
+    blocked: z.number().int().nonnegative(),
+    completed: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+  })
+  .strict()
+export type AgentActivityCounts = z.infer<typeof AgentActivityCountsSchema>
+
+export const UserActivitySummarySchema = z
+  .object({
+    taskCount: z.number().int().nonnegative(),
+    pendingApprovalCount: z.number().int().nonnegative(),
+    awaitingHumanCount: z.number().int().nonnegative(),
+    lastActiveAt: z.iso.datetime().nullable(),
+  })
+  .strict()
+export type UserActivitySummary = z.infer<typeof UserActivitySummarySchema>
+
+export const AgentActivityEntrySchema = z
+  .object({
+    agentId: z.string().trim().min(1),
+    counts: AgentActivityCountsSchema,
+    tasks: z.array(PlanNodeCardSchema),
+    projects: z.array(AgentProjectEntrySchema),
+    isLeadingActivePlan: z.boolean(),
+    isRunning: z.boolean(),
+    lastActiveAt: z.iso.datetime().nullable(),
+  })
+  .strict()
+export type AgentActivityEntry = z.infer<typeof AgentActivityEntrySchema>
+
+export const AgentActivityResponseSchema = z
+  .object({
+    agents: z.array(AgentActivityEntrySchema),
+    userActivity: UserActivitySummarySchema,
+    totalActivePlans: z.number().int().nonnegative(),
+  })
+  .strict()
+export type AgentActivityResponse = z.infer<typeof AgentActivityResponseSchema>

package/src/schemas/tools.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 
+import { AgentPlanDraftSchema } from './agent-plan-draft'
 import { baseChatMessageSchema } from './chat-api'
 import type { AnyChatMessage } from './chat-message'
 import {
@@ -13,6 +14,7 @@ export const USER_QUESTIONS_TOOL_NAME = 'userQuestions' as const
 export const CONSULT_SPECIALIST_TOOL_NAME = 'consultSpecialist' as const
 export const CONSULT_TEAM_TOOL_NAME = 'consultTeam' as const
 export const CREATE_EXECUTION_PLAN_TOOL_NAME = 'createExecutionPlan' as const
+export const CREATE_PROJECT_WITH_PLAN_TOOL_NAME = 'createProjectWithPlan' as const
 export const REPLACE_EXECUTION_PLAN_TOOL_NAME = 'replaceExecutionPlan' as const
 export const SUBMIT_EXECUTION_NODE_RESULT_TOOL_NAME = 'submitExecutionNodeResult' as const
 export const SUBMIT_PLAN_TURN_RESULT_TOOL_NAME = 'submitPlanTurnResult' as const
@@ -60,7 +62,17 @@ const ExecutionPlanToolActionSchema = z.enum([
   'none',
 ])
 
-export const CreateExecutionPlanArgsSchema = PlanDraftSchema
+export const CreateExecutionPlanArgsSchema = PlanDraftSchema.extend({
+  targetWorkstreamId: z.string().trim().min(1).optional(),
+}).strict()
+
+export const CreateProjectWithPlanArgsSchema = AgentPlanDraftSchema.extend({
+  projectTitle: z.string().trim().min(1).max(200).optional(),
+  targetWorkstreamId: z.string().trim().min(1).optional(),
+}).refine((value) => Boolean(value.projectTitle) !== Boolean(value.targetWorkstreamId), {
+  message: 'Provide exactly one of projectTitle or targetWorkstreamId.',
+  path: ['projectTitle'],
+})
 
 export const ReplaceExecutionPlanArgsSchema = PlanDraftSchema.extend({
   runId: z.string().trim().min(1),
@@ -121,6 +133,12 @@ export const ExecutionPlanToolResultDataSchema = z
   })
   .strict()
 
+export const CreateProjectWithPlanResultDataSchema = ExecutionPlanToolResultDataSchema.extend({
+  workstreamId: z.string().trim().min(1),
+  workstreamTitle: z.string().trim().min(1),
+  createdWorkstream: z.boolean(),
+}).strict()
+
 export const ConsultTeamResultDataSchema = z.object({ responses: z.array(ConsultTeamResponseSchema) }).strict()
 
 export type UserQuestionItem = z.infer<typeof UserQuestionItemSchema>
@@ -133,6 +151,7 @@ export type ConsultTeamResponseData = Omit<z.infer<typeof ConsultTeamResponseSch
 }
 export type ConsultTeamResultData = { responses: ConsultTeamResponseData[] }
 export type CreateExecutionPlanArgs = z.infer<typeof CreateExecutionPlanArgsSchema>
+export type CreateProjectWithPlanArgs = z.infer<typeof CreateProjectWithPlanArgsSchema>
 export type ReplaceExecutionPlanArgs = z.infer<typeof ReplaceExecutionPlanArgsSchema>
 export type SubmitExecutionNodeResultArgs = z.infer<typeof SubmitExecutionNodeResultArgsSchema>
 export type SubmitPlanTurnResultArgs = z.infer<typeof SubmitPlanTurnResultArgsSchema>
@@ -142,11 +161,13 @@ export type ListExecutionPlansToolResultData = z.infer<typeof ListExecutionPlans
 export type GetActiveExecutionPlanArgs = z.infer<typeof GetActiveExecutionPlanArgsSchema>
 export type ResumeExecutionPlanRunArgs = z.infer<typeof ResumeExecutionPlanRunArgsSchema>
 export type ExecutionPlanToolResultData = z.infer<typeof ExecutionPlanToolResultDataSchema>
+export type CreateProjectWithPlanResultData = z.infer<typeof CreateProjectWithPlanResultDataSchema>
 export type CoreChatTools = {
   userQuestions: { input: UserQuestionsArgs; output: unknown }
   consultSpecialist: { input: ConsultSpecialistArgs; output: ConsultSpecialistResultData }
   consultTeam: { input: ConsultTeamArgs; output: ConsultTeamResultData }
   createExecutionPlan: { input: CreateExecutionPlanArgs; output: ExecutionPlanToolResultData }
+  createProjectWithPlan: { input: CreateProjectWithPlanArgs; output: CreateProjectWithPlanResultData }
   replaceExecutionPlan: { input: ReplaceExecutionPlanArgs; output: ExecutionPlanToolResultData }
   submitExecutionNodeResult: { input: SubmitExecutionNodeResultArgs; output: ExecutionPlanToolResultData }
   submitPlanTurnResult: { input: SubmitPlanTurnResultArgs; output: ExecutionPlanToolResultData }