@lota-sdk/shared 0.1.23 → 0.1.25

package/package.json

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

package/src/constants/execution-plan.ts

@@ -0,0 +1,19 @@
+export const SILENT_EXECUTION_VISIBILITY = 'silent' as const
+
+export const HUMAN_NODE_TYPES = ['human-input', 'human-approval', 'human-review-edit', 'human-decision'] as const
+
+export const STRUCTURAL_NODE_TYPES = ['switch', 'join', 'deliberation-fork'] 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/constants/model.ts

@@ -1,34 +1,22 @@
 export const OPENAI_REASONING_MODEL_ID = 'openai/gpt-5.4' as const
 
+export const OPENROUTER_GEMINI_FLASH_MODEL_ID = 'openrouter/google/gemini-3-flash-preview' as const
 export const OPENROUTER_TEAM_AGENT_MODEL_ID = 'openrouter/google/gemini-3.1-pro-preview' as const
-export const OPENROUTER_STRUCTURED_HELPER_MODEL_ID = 'openrouter/google/gemini-3-flash-preview' as const
-export const OPENROUTER_DELEGATED_REASONING_MODEL_ID = 'openrouter/google/gemini-3-flash-preview' as const
 export const OPENROUTER_WEB_RESEARCH_MODEL_ID = 'openrouter/stepfun/step-3.5-flash' as const
 export const OPENROUTER_FAST_REASONING_MODEL_ID = 'openrouter/qwen/qwen3.5-flash-02-23' as const
 export const OPENROUTER_STRUCTURED_REASONING_MODEL_ID = 'openrouter/google/gemini-3.1-pro-preview' as const
 
 export const AI_GATEWAY_REASONING_SUMMARY_LEVEL = 'detailed' as const
 
-export const OPENAI_HIGH_REASONING_PROVIDER_OPTIONS = {
-  openai: { forceReasoning: true, reasoningEffort: 'high', reasoningSummary: AI_GATEWAY_REASONING_SUMMARY_LEVEL },
-} as const
-
-export const OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS = {
-  openai: { forceReasoning: true, reasoningEffort: 'high', reasoningSummary: AI_GATEWAY_REASONING_SUMMARY_LEVEL },
-} as const
-
-export const OPENROUTER_XHIGH_REASONING_PROVIDER_OPTIONS = {
-  openai: { forceReasoning: true, reasoningEffort: 'xhigh', reasoningSummary: AI_GATEWAY_REASONING_SUMMARY_LEVEL },
-} as const
-
-export const OPENROUTER_MEDIUM_REASONING_PROVIDER_OPTIONS = {
-  openai: { forceReasoning: true, reasoningEffort: 'medium', reasoningSummary: AI_GATEWAY_REASONING_SUMMARY_LEVEL },
-} as const
-
-export const OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS = {
-  openai: { forceReasoning: true, reasoningEffort: 'low', reasoningSummary: AI_GATEWAY_REASONING_SUMMARY_LEVEL },
-} as const
-
-export const OPENROUTER_MINIMAL_REASONING_PROVIDER_OPTIONS = {
-  openai: { forceReasoning: true, reasoningEffort: 'minimal', reasoningSummary: AI_GATEWAY_REASONING_SUMMARY_LEVEL },
-} as const
+export function makeOpenRouterReasoningOptions(effort: string) {
+  return {
+    openai: { forceReasoning: true, reasoningEffort: effort, reasoningSummary: AI_GATEWAY_REASONING_SUMMARY_LEVEL },
+  } as const
+}
+
+export const OPENAI_HIGH_REASONING_PROVIDER_OPTIONS = makeOpenRouterReasoningOptions('high')
+export const OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS = makeOpenRouterReasoningOptions('high')
+export const OPENROUTER_XHIGH_REASONING_PROVIDER_OPTIONS = makeOpenRouterReasoningOptions('xhigh')
+export const OPENROUTER_MEDIUM_REASONING_PROVIDER_OPTIONS = makeOpenRouterReasoningOptions('medium')
+export const OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS = makeOpenRouterReasoningOptions('low')
+export const OPENROUTER_MINIMAL_REASONING_PROVIDER_OPTIONS = makeOpenRouterReasoningOptions('minimal')

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, STRUCTURAL_NODE_TYPES } 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_TYPE_SET = new Set<PlanNodeType>(STRUCTURAL_NODE_TYPES)
+
+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_TYPE_SET.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

@@ -54,7 +54,6 @@ export const PlanNodeTypeSchema = z
     'human-decision',
     'switch',
     'join',
-    'subgraph',
     'monitoring',
     'deliberation-fork',
   ])
@@ -112,7 +111,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', 'scheduled'])
+  .enum(['running', 'awaiting-human', 'blocked', 'completed', 'failed', 'aborted'])
   .meta({ id: 'PlanRunStatusSchema' })
 export type PlanRunStatus = z.infer<typeof PlanRunStatusSchema>
 
@@ -133,9 +132,7 @@ export const PlanNodeRunStatusSchema = z
   .meta({ id: 'PlanNodeRunStatusSchema' })
 export type PlanNodeRunStatus = z.infer<typeof PlanNodeRunStatusSchema>
 
-export const PlanAttemptStatusSchema = z
-  .enum(['submitted', 'validated', 'completed', 'failed', 'rejected'])
-  .meta({ id: 'PlanAttemptStatusSchema' })
+export const PlanAttemptStatusSchema = z.enum(['completed', 'failed']).meta({ id: 'PlanAttemptStatusSchema' })
 export type PlanAttemptStatus = z.infer<typeof PlanAttemptStatusSchema>
 
 export const PlanValidationIssueSeveritySchema = z
@@ -177,8 +174,6 @@ export const PlanEventTypeSchema = z
     'escalation-triggered',
     'node-scheduled',
     'node-monitoring',
-    'cycle-started',
-    'cycle-completed',
     'feedback-analyzed',
   ])
   .meta({ id: 'PlanEventTypeSchema' })
@@ -320,8 +315,11 @@ export type PlanNodeEscalation = z.infer<typeof PlanNodeEscalationSchema>
 export const NotificationSeveritySchema = z.enum(['info', 'warning', 'urgent', 'critical'])
 export type NotificationSeverity = z.infer<typeof NotificationSeveritySchema>
 
-export const PlanScheduleStatusSchema = z.enum(['active', 'paused', 'completed', 'cancelled'])
-export type PlanScheduleStatus = z.infer<typeof PlanScheduleStatusSchema>
+const ActiveRecordStatusSchema = z.enum(['active', 'paused', 'completed', 'cancelled'])
+type ActiveRecordStatus = z.infer<typeof ActiveRecordStatusSchema>
+
+export const PlanScheduleStatusSchema = ActiveRecordStatusSchema
+export type PlanScheduleStatus = ActiveRecordStatus
 
 export const PlanScheduleRecordSchema = z.object({
   id: recordIdSchema,
@@ -359,8 +357,8 @@ export const CycleScheduleSchema = z
   .strict()
 export type CycleSchedule = z.infer<typeof CycleScheduleSchema>
 
-export const PlanCycleStatusSchema = z.enum(['active', 'paused', 'completed', 'cancelled'])
-export type PlanCycleStatus = z.infer<typeof PlanCycleStatusSchema>
+export const PlanCycleStatusSchema = ActiveRecordStatusSchema
+export type PlanCycleStatus = ActiveRecordStatus
 
 export const ExecutionModeSchema = z.enum(['linear', 'graph-lite', 'graph-full']).default('linear')
 export type ExecutionMode = z.infer<typeof ExecutionModeSchema>
@@ -549,7 +547,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(),
@@ -624,33 +622,11 @@ export const PlanSpecSchema = z.object({
 })
 export type PlanSpecRecord = z.infer<typeof PlanSpecSchema>
 
-export const PlanNodeSpecRecordSchema = z.object({
+export const PlanNodeSpecRecordSchema = PlanNodeSpecSchema.omit({ id: true }).extend({
   id: recordIdSchema,
   planSpecId: recordIdSchema,
-  nodeId: z.string(),
+  nodeId: PlanNodeSpecSchema.shape.id,
   position: z.number().int().nonnegative(),
-  type: PlanNodeTypeSchema,
-  label: z.string(),
-  owner: PlanNodeOwnerSchema,
-  objective: z.string(),
-  instructions: z.string(),
-  inputSchemaRef: z.string().optional(),
-  outputSchemaRef: z.string().optional(),
-  deliverables: z.array(PlanArtifactSpecSchema),
-  successCriteria: z.array(z.string()),
-  completionChecks: z.array(PlanCompletionCheckSchema),
-  retryPolicy: PlanRetryPolicySchema,
-  failurePolicy: z.array(PlanFailureRuleSchema),
-  timeoutMs: z.number().int().positive().optional(),
-  toolPolicy: PlanToolPolicySchema,
-  contextPolicy: PlanContextPolicySchema,
-  executionVisibility: PlanExecutionVisibilitySchema.default('auto'),
-  schedule: PlanScheduleSpecSchema.optional(),
-  deadline: DeadlineSpecSchema.optional(),
-  escalation: PlanNodeEscalationSchema.optional(),
-  monitoringConfig: MonitoringWindowConfigSchema.optional(),
-  delayAfterPredecessorMs: z.number().int().positive().optional(),
-  deliberationConfig: DeliberationForkConfigSchema.optional(),
   upstreamNodeIds: z.array(z.string()).default([]),
   downstreamNodeIds: z.array(z.string()).default([]),
   createdAt: dbDateTimeSchema,
@@ -799,24 +775,18 @@ export const PlanEventSchema = z.object({
 })
 export type PlanEventRecord = z.infer<typeof PlanEventSchema>
 
-export const SerializablePlanNodeSchema = z.object({
-  id: z.string(),
-  type: PlanNodeTypeSchema,
-  label: z.string(),
-  owner: PlanNodeOwnerSchema,
-  objective: z.string(),
-  instructions: z.string(),
+export const SerializablePlanNodeSchema = PlanNodeSpecRecordSchema.omit({
+  id: true,
+  planSpecId: true,
+  nodeId: true,
+  position: true,
+  createdAt: true,
+  updatedAt: true,
+}).extend({
+  id: PlanNodeSpecRecordSchema.shape.nodeId,
   inputSchemaRef: z.string().nullish(),
   outputSchemaRef: z.string().nullish(),
-  deliverables: z.array(PlanArtifactSpecSchema),
-  successCriteria: z.array(z.string()),
-  completionChecks: z.array(PlanCompletionCheckSchema),
-  retryPolicy: PlanRetryPolicySchema,
-  failurePolicy: z.array(PlanFailureRuleSchema),
   timeoutMs: z.number().int().positive().nullish(),
-  toolPolicy: PlanToolPolicySchema,
-  contextPolicy: PlanContextPolicySchema,
-  executionVisibility: PlanExecutionVisibilitySchema,
   schedule: PlanScheduleSpecSchema.nullish(),
   deadline: DeadlineSpecSchema.nullish(),
   escalation: PlanNodeEscalationSchema.nullish(),
@@ -832,8 +802,6 @@ export const SerializablePlanNodeSchema = z.object({
   handoffContext: PlanNodeHandoffContextSchema.nullish(),
   blockedReason: z.string().nullish(),
   failureClass: PlanFailureClassSchema.nullish(),
-  upstreamNodeIds: z.array(z.string()),
-  downstreamNodeIds: z.array(z.string()),
   readyAt: z.iso.datetime().nullish(),
   startedAt: z.iso.datetime().nullish(),
   completedAt: z.iso.datetime().nullish(),

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,18 +1,15 @@
 import { z } from 'zod'
 
+import { AgentPlanDraftSchema } from './agent-plan-draft'
 import { baseChatMessageSchema } from './chat-api'
 import type { AnyChatMessage } from './chat-message'
-import {
-  PlanDraftSchema,
-  PlanNodeResultSubmissionSchema,
-  PlanRunStatusSchema,
-  SerializableExecutionPlanSchema,
-} from './execution-plan'
+import { PlanNodeResultSubmissionSchema, PlanRunStatusSchema, SerializableExecutionPlanSchema } from './execution-plan'
 
 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,11 +57,26 @@ const ExecutionPlanToolActionSchema = z.enum([
   'none',
 ])
 
-export const CreateExecutionPlanArgsSchema = PlanDraftSchema
+export const CreateExecutionPlanArgsSchema = AgentPlanDraftSchema.extend({
+  targetWorkstreamId: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe('Target workstream ID. Defaults to the current workstream.'),
+}).strict()
 
-export const ReplaceExecutionPlanArgsSchema = PlanDraftSchema.extend({
-  runId: z.string().trim().min(1),
-  reason: z.string().trim().min(1).max(1000),
+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 = AgentPlanDraftSchema.extend({
+  runId: z.string().trim().min(1).describe('ID of the plan run to replace.'),
+  reason: z.string().trim().min(1).max(1000).describe('Why the plan is being replaced.'),
 }).strict()
 
 export const SubmitExecutionNodeResultArgsSchema = z
@@ -78,11 +90,11 @@ export const ListExecutionPlansArgsSchema = z.object({}).strict()
 export const GetActiveExecutionPlanArgsSchema = z
   .object({
     runId: z.string().trim().min(1).optional(),
-    includeEvents: z.boolean().default(true),
-    includeArtifacts: z.boolean().default(true),
-    includeApprovals: z.boolean().default(true),
-    includeCheckpoints: z.boolean().default(false),
-    includeValidationIssues: z.boolean().default(true),
+    includeEvents: z.boolean().default(true).describe('Include events'),
+    includeArtifacts: z.boolean().default(true).describe('Include artifacts'),
+    includeApprovals: z.boolean().default(true).describe('Include approvals'),
+    includeCheckpoints: z.boolean().default(false).describe('Include checkpoints'),
+    includeValidationIssues: z.boolean().default(true).describe('Include validation issues'),
   })
   .strict()
 
@@ -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 }

package/src/schemas/workstream.ts

@@ -5,24 +5,6 @@ import { recordIdSchema, recordIdStringSchema } from './common'
 export const sdkWorkstreamModeSchema = z.enum(['direct', 'group'])
 export const sdkWorkstreamStatusSchema = z.enum(['regular', 'archived'])
 
-export const sdkWorkstreamSchema = z.object({
-  id: recordIdStringSchema,
-  organizationId: recordIdStringSchema,
-  userId: recordIdStringSchema,
-  agentId: z.string().nullable().optional(),
-  mode: sdkWorkstreamModeSchema,
-  core: z.boolean(),
-  coreType: z.string().nullable().optional(),
-  title: z.string(),
-  status: sdkWorkstreamStatusSchema,
-  nameGenerated: z.boolean(), // Ideally `isNameGenerated`, but maps directly to SurrealDB column `nameGenerated`
-  isRunning: z.boolean(),
-  isCompacting: z.boolean(),
-  memoryBlock: z.string().optional(),
-  createdAt: z.iso.datetime(),
-  updatedAt: z.iso.datetime(),
-})
-
 export const sdkWorkstreamRecordSchema = z.object({
   id: recordIdSchema,
   organizationId: recordIdSchema,
@@ -36,15 +18,37 @@ export const sdkWorkstreamRecordSchema = z.object({
   memoryBlock: z.string().nullish(),
   memoryBlockSummary: z.string().nullish(),
   activeRunId: z.string().nullish(),
+  activeStreamId: z.string().nullish(),
   compactionSummary: z.string().nullish(),
   lastCompactedMessageId: z.string().nullish(),
   nameGenerated: z.boolean(), // Ideally `isNameGenerated`, but maps directly to SurrealDB column `nameGenerated`
   isCompacting: z.boolean().optional(),
   state: z.unknown().optional(),
+  turnCount: z.number().int(),
   createdAt: z.coerce.date(),
   updatedAt: z.coerce.date(),
 })
 
+export const sdkWorkstreamSchema = sdkWorkstreamRecordSchema
+  .pick({ agentId: true, mode: true, core: true, coreType: true, status: true, nameGenerated: true })
+  .extend({
+    id: recordIdStringSchema,
+    organizationId: recordIdStringSchema,
+    userId: recordIdStringSchema,
+    title: z.string(),
+    isRunning: z.boolean(),
+    isCompacting: z.boolean(),
+    memoryBlock: z.string().optional(),
+    createdAt: z.iso.datetime(),
+    updatedAt: z.iso.datetime(),
+  })
+
+export const sdkPublicWorkstreamSchema = sdkWorkstreamSchema.omit({
+  organizationId: true,
+  userId: true,
+  memoryBlock: true,
+})
+
 export const sdkWorkstreamMessageSchema = z.object({
   id: recordIdStringSchema,
   workstreamId: recordIdStringSchema,
@@ -70,7 +74,8 @@ export const sdkWorkstreamAttachmentSchema = z.object({
   updatedAt: z.iso.datetime(),
 })
 
-export type SdkWorkstream = z.infer<typeof sdkWorkstreamSchema>
 export type SdkWorkstreamRecord = z.infer<typeof sdkWorkstreamRecordSchema>
+export type SdkWorkstream = z.infer<typeof sdkWorkstreamSchema>
+export type SdkPublicWorkstream = z.infer<typeof sdkPublicWorkstreamSchema>
 export type SdkWorkstreamMessage = z.infer<typeof sdkWorkstreamMessageSchema>
 export type SdkWorkstreamAttachment = z.infer<typeof sdkWorkstreamAttachmentSchema>