@lota-sdk/shared 0.4.2 → 0.4.4

package/package.json

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

package/src/constants/execution-plan.ts

@@ -7,11 +7,13 @@ export const STRUCTURAL_NODE_TYPES = ['switch', 'join', 'deliberation-fork'] as
 export const PROJECT_PLAN_ROUTING_PROMPT = `<project-plan-routing>
 - Use executionPlan with action "create" for small inline work inside the current thread.
 - Use executionPlan with action "create-project" when the work needs a dedicated project thread, should stay visible in the sidebar or board, or needs 3 or more meaningful execution nodes.
+- Plans created with action "create-project" usually require human approval before execution starts. Treat them as proposals until approved.
 - Never invent other plan tool names.
 </project-plan-routing>`
 
 export const EXECUTION_PLAN_SELF_START_PROMPT = `<execution-plan-self-start>
-- When you create an execution plan with executionPlan 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.
+- When you create an execution plan with executionPlan and the plan starts running immediately, begin executing your first assigned node in the same turn. Do not wait for the user to ask.
+- When a newly created plan is pending approval, do not start any work. Tell the user the plan is ready for review and wait for approval.
 - 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.

package/src/schemas/execution-plan.ts

@@ -112,7 +112,7 @@ export const PlanSpecStatusSchema = z.enum(['compiled', 'superseded']).meta({ id
 export type PlanSpecStatus = z.infer<typeof PlanSpecStatusSchema>
 
 export const PlanRunStatusSchema = z
-  .enum(['running', 'awaiting-human', 'blocked', 'completed', 'failed', 'aborted'])
+  .enum(['pending-approval', 'running', 'awaiting-human', 'blocked', 'completed', 'failed', 'aborted'])
   .meta({ id: 'PlanRunStatusSchema' })
 export type PlanRunStatus = z.infer<typeof PlanRunStatusSchema>
 
@@ -149,6 +149,10 @@ export type PlanApprovalStatus = z.infer<typeof PlanApprovalStatusSchema>
 export const PlanEventTypeSchema = z
   .enum([
     'plan-created',
+    'plan-pending-approval',
+    'plan-approved',
+    'plan-rejected',
+    'plan-changes-requested',
     'plan-replaced',
     'run-status-changed',
     'ownership-transition',
@@ -635,7 +639,9 @@ export const PlanRunSchema = z.object({
   planSpecId: recordIdSchema,
   organizationId: recordIdSchema,
   threadId: recordIdSchema,
+  sourceThreadId: recordIdSchema.optional(),
   leadAgentId: z.string(),
+  createdByAgentId: z.string().optional(),
   status: PlanRunStatusSchema,
   currentNodeId: z.string().optional(),
   waitingNodeId: z.string().optional(),
@@ -897,12 +903,14 @@ export const SerializableExecutionPlanSchema = z.object({
   specId: z.string(),
   runId: z.string(),
   threadId: z.string(),
+  sourceThreadId: z.string().nullish(),
   organizationId: z.string(),
   title: z.string(),
   objective: z.string(),
   version: z.number().int().positive(),
   status: PlanRunStatusSchema,
   leadAgentId: z.string(),
+  createdByAgentId: z.string().nullish(),
   defaultExecutionVisibility: PlanExecutionVisibilitySchema,
   executionMode: ExecutionModeSchema,
   schemaRegistry: PlanSchemaRegistrySchema,

package/src/schemas/recent-activity.ts

@@ -35,7 +35,7 @@ export const RecentActivityMetadataSchema = z
     userMessageText: z.string().optional(),
     assistantSummary: z.string().optional(),
     messageId: z.string().optional(),
-    planStatus: z.enum(['awaiting-human', 'blocked', 'completed', 'failed']).optional(),
+    planStatus: z.enum(['pending-approval', 'awaiting-human', 'blocked', 'completed', 'failed']).optional(),
     planTitle: z.string().optional(),
   })
   .partial()

package/src/schemas/tools.ts

@@ -4,6 +4,7 @@ import { AgentPlanDraftSchema, AgentPlanEdgeDraftSchema } from './agent-plan-dra
 import { baseChatMessageSchema } from './chat-api'
 import type { AnyChatMessage } from './chat-message'
 import {
+  PlanEdgeSpecSchema,
   PlanNodeResultSubmissionSchema,
   PlanNodeRunStatusSchema,
   PlanNodeTypeSchema,
@@ -15,6 +16,7 @@ export const CONSULT_SPECIALIST_TOOL_NAME = 'consultSpecialist' as const
 export const CONSULT_TEAM_TOOL_NAME = 'consultTeam' as const
 export const EXECUTION_PLAN_TOOL_NAME = 'executionPlan' as const
 export const EXECUTION_PLAN_QUERY_TOOL_NAME = 'executionPlanQuery' as const
+export const PLAN_APPROVAL_TOOL_NAME = 'planApproval' as const
 export const SUBMIT_PLAN_TURN_RESULT_TOOL_NAME = 'submitPlanTurnResult' as const
 export const SUBMIT_EXECUTION_NODE_RESULT_TOOL_NAME = 'submitExecutionNodeResult' as const
 
@@ -86,22 +88,29 @@ const targetThreadIdSchema = z
 
 const runIdSchema = z.string().trim().min(1)
 const replaceReasonSchema = z.string().trim().min(1).max(1000)
+const requireApprovalSchema = z
+  .boolean()
+  .optional()
+  .describe('When true, the created plan stays pending approval until a human explicitly starts it.')
 
 export const ExecutionPlanCreateArgsSchema = AgentPlanDraftSchema.extend({
   action: z.literal('create'),
   targetThreadId: targetThreadIdSchema.optional(),
+  requireApproval: requireApprovalSchema,
 }).strict()
 
 export const ExecutionPlanCreateProjectArgsSchema = AgentPlanDraftSchema.extend({
   action: z.literal('create-project'),
   projectTitle: projectTitleSchema.optional(),
   targetThreadId: targetThreadIdSchema.optional(),
+  requireApproval: requireApprovalSchema,
 }).strict()
 
 export const ExecutionPlanReplaceArgsSchema = AgentPlanDraftSchema.extend({
   action: z.literal('replace'),
   runId: runIdSchema.describe('Required for replace and resume.'),
   reason: replaceReasonSchema.describe('Required for replace.'),
+  requireApproval: requireApprovalSchema,
 }).strict()
 
 export const ExecutionPlanResumeArgsSchema = z
@@ -117,6 +126,7 @@ const ExecutionPlanBaseArgsSchema = z
     edges: z.array(AgentPlanEdgeDraftSchema).optional(),
     projectTitle: projectTitleSchema.optional(),
     targetThreadId: targetThreadIdSchema.optional(),
+    requireApproval: requireApprovalSchema,
     runId: runIdSchema.describe('Required for replace and resume.').optional(),
     reason: replaceReasonSchema.describe('Required for replace.').optional(),
   })
@@ -172,6 +182,13 @@ export const ExecutionPlanArgsSchema = ExecutionPlanBaseArgsSchema.superRefine((
         )
       }
     }
+    if (value.requireApproval !== undefined) {
+      addUnexpectedExecutionPlanFieldIssue(
+        ctx,
+        'requireApproval',
+        'requireApproval is not allowed when action is "resume". Use only action and runId.',
+      )
+    }
   }
 
   if (value.action === 'create') {
@@ -188,6 +205,13 @@ export const ExecutionPlanArgsSchema = ExecutionPlanBaseArgsSchema.superRefine((
         addUnexpectedExecutionPlanFieldIssue(ctx, path, `${path} is not allowed when action is "create-project".`)
       }
     }
+    if (value.projectTitle === undefined && value.targetThreadId === undefined) {
+      addMissingExecutionPlanFieldIssue(
+        ctx,
+        'projectTitle',
+        'Either projectTitle or targetThreadId is required for create-project.',
+      )
+    }
   }
 
   if (value.action === 'replace') {
@@ -244,35 +268,86 @@ export const ExecutionPlanNodeSummarySchema = z.object({
   type: PlanNodeTypeSchema,
   status: PlanNodeRunStatusSchema,
   ownerRef: z.string(),
+  objective: z.string().optional(),
+  ownerType: z.string().optional(),
+  artifactCount: z.number().int().nonnegative().optional(),
+  approvalId: z.string().nullish(),
+  approvalStatus: z.string().nullish(),
+  blockedReason: z.string().nullish(),
+  latestNotes: z.string().nullish(),
+  startedAt: z.iso.datetime().nullish(),
+  completedAt: z.iso.datetime().nullish(),
+  readyAt: z.iso.datetime().nullish(),
+  deliverableNames: z.array(z.string()).optional(),
+  upstreamNodeIds: z.array(z.string()).optional(),
+  downstreamNodeIds: z.array(z.string()).optional(),
 })
 
+export const ExecutionPlanToolPlanSummarySchema = z
+  .object({
+    runId: z.string(),
+    threadId: z.string().optional(),
+    sourceThreadId: z.string().optional(),
+    title: z.string(),
+    objective: z.string(),
+    status: PlanRunStatusSchema,
+    leadAgentId: z.string().optional(),
+    createdByAgentId: z.string().optional(),
+    progress: ExecutionPlanProgressSchema,
+    nodes: z.array(ExecutionPlanNodeSummarySchema),
+    edges: z.array(PlanEdgeSpecSchema).optional(),
+    activeNodeIds: z.array(z.string()),
+    readyNodeIds: z.array(z.string()),
+  })
+  .strict()
+
 export const ExecutionPlanToolResultDataSchema = z
   .object({
     action: ExecutionPlanToolActionSchema,
     message: z.string().optional(),
     hasPlan: z.boolean(),
     status: PlanRunStatusSchema.nullish(),
-    plan: z
-      .object({
-        runId: z.string(),
-        title: z.string(),
-        objective: z.string(),
-        status: PlanRunStatusSchema,
-        progress: ExecutionPlanProgressSchema,
-        nodes: z.array(ExecutionPlanNodeSummarySchema),
-        activeNodeIds: z.array(z.string()),
-        readyNodeIds: z.array(z.string()),
-      })
-      .nullish(),
+    plan: ExecutionPlanToolPlanSummarySchema.nullish(),
   })
   .strict()
 
 export const CreateProjectWithPlanResultDataSchema = ExecutionPlanToolResultDataSchema.extend({
+  runId: z.string().trim().min(1),
   threadId: z.string().trim().min(1),
   threadTitle: z.string().trim().min(1),
   createdThread: z.boolean(),
 }).strict()
 
+export const PlanApprovalToolActionSchema = z.enum(['approved', 'rejected', 'changes-requested'])
+export const PlanApprovalActionSchema = z.enum(['approve', 'reject', 'modify'])
+
+export const PlanApprovalArgsSchema = z
+  .object({
+    action: PlanApprovalActionSchema,
+    runId: z.string().trim().min(1),
+    reason: z.string().trim().min(1).max(2000).optional(),
+  })
+  .superRefine((value, ctx) => {
+    if (value.action !== 'approve' && !value.reason) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['reason'],
+        message: 'reason is required when action is reject or modify.',
+      })
+    }
+  })
+  .strict()
+
+export const PlanApprovalToolResultDataSchema = z
+  .object({
+    action: PlanApprovalToolActionSchema,
+    message: z.string(),
+    hasPlan: z.boolean(),
+    status: PlanRunStatusSchema.nullish(),
+    plan: ExecutionPlanToolPlanSummarySchema.nullish(),
+  })
+  .strict()
+
 export const ConsultTeamResultDataSchema = z.object({ responses: z.array(ConsultTeamResponseSchema) }).strict()
 
 export type UserQuestionItem = z.infer<typeof UserQuestionItemSchema>
@@ -290,8 +365,13 @@ export type ListExecutionPlansSummary = z.infer<typeof ListExecutionPlansSummary
 export type ListExecutionPlansToolResultData = z.infer<typeof ListExecutionPlansToolResultDataSchema>
 export type ExecutionPlanProgress = z.infer<typeof ExecutionPlanProgressSchema>
 export type ExecutionPlanNodeSummary = z.infer<typeof ExecutionPlanNodeSummarySchema>
+export type ExecutionPlanToolPlanSummary = z.infer<typeof ExecutionPlanToolPlanSummarySchema>
 export type ExecutionPlanToolResultData = z.infer<typeof ExecutionPlanToolResultDataSchema>
 export type CreateProjectWithPlanResultData = z.infer<typeof CreateProjectWithPlanResultDataSchema>
+export type PlanApprovalAction = z.infer<typeof PlanApprovalActionSchema>
+export type PlanApprovalArgs = z.infer<typeof PlanApprovalArgsSchema>
+export type PlanApprovalToolAction = z.infer<typeof PlanApprovalToolActionSchema>
+export type PlanApprovalToolResultData = z.infer<typeof PlanApprovalToolResultDataSchema>
 export type CoreChatTools = {
   userQuestions: { input: UserQuestionsArgs; output: unknown }
   consultSpecialist: { input: ConsultSpecialistArgs; output: ConsultSpecialistResultData }
@@ -301,5 +381,6 @@ export type CoreChatTools = {
     input: ExecutionPlanQueryArgs
     output: ExecutionPlanToolResultData | ListExecutionPlansToolResultData
   }
+  planApproval: { input: PlanApprovalArgs; output: PlanApprovalToolResultData }
   submitPlanTurnResult: { input: SubmitPlanTurnResultArgs; output: ExecutionPlanToolResultData }
 }