@lota-sdk/shared 0.1.24 → 0.1.26

package/package.json

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

package/src/constants/execution-plan.ts

@@ -1,5 +1,9 @@
 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.

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/schemas/agent-plan-draft.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
 
-import { SILENT_EXECUTION_VISIBILITY } from '../constants/execution-plan'
+import { SILENT_EXECUTION_VISIBILITY, STRUCTURAL_NODE_TYPES } from '../constants/execution-plan'
 import type { PlanArtifactSpec, PlanCompletionCheck, PlanDraft, PlanNodeOwner, PlanNodeType } from './execution-plan'
 import {
   ExecutionModeSchema,
@@ -16,7 +16,7 @@ import {
   PlanToolPolicySchema,
 } from './execution-plan'
 
-const STRUCTURAL_NODE_TYPES = new Set<PlanNodeType>(['switch', 'join', 'deliberation-fork'])
+const STRUCTURAL_NODE_TYPE_SET = new Set<PlanNodeType>(STRUCTURAL_NODE_TYPES)
 
 const agentPlanOwnerStringSchema = z.string().trim().min(1).max(200)
 
@@ -86,7 +86,7 @@ function toDeliverableName(value: string, fallback: string): string {
 }
 
 function isStructuralNodeType(type: PlanNodeType): boolean {
-  return STRUCTURAL_NODE_TYPES.has(type)
+  return STRUCTURAL_NODE_TYPE_SET.has(type)
 }
 
 function buildDefaultDeliverables(node: AgentPlanNodeDraft): PlanArtifactSpec[] {
@@ -223,9 +223,9 @@ export function expandAgentPlanDraft(draft: AgentPlanDraft): PlanDraft {
     title: draft.title,
     objective: draft.objective,
     schemas: {},
-    defaultExecutionVisibility: SILENT_EXECUTION_VISIBILITY,
+    defaultExecutionVisibility: 'auto',
     nodes: expandedNodes,
-    edges: draft.edges.map((edge) => PlanEdgeSpecSchema.parse({ ...edge, map: {} })),
+    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>
@@ -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/tools.ts

@@ -3,12 +3,7 @@ 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
@@ -62,8 +57,13 @@ const ExecutionPlanToolActionSchema = z.enum([
   'none',
 ])
 
-export const CreateExecutionPlanArgsSchema = PlanDraftSchema.extend({
-  targetWorkstreamId: z.string().trim().min(1).optional(),
+export const CreateExecutionPlanArgsSchema = AgentPlanDraftSchema.extend({
+  targetWorkstreamId: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe('Target workstream ID. Defaults to the current workstream.'),
 }).strict()
 
 export const CreateProjectWithPlanArgsSchema = AgentPlanDraftSchema.extend({
@@ -74,9 +74,9 @@ export const CreateProjectWithPlanArgsSchema = AgentPlanDraftSchema.extend({
   path: ['projectTitle'],
 })
 
-export const ReplaceExecutionPlanArgsSchema = PlanDraftSchema.extend({
-  runId: z.string().trim().min(1),
-  reason: z.string().trim().min(1).max(1000),
+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
@@ -90,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()
 

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>