@lota-sdk/shared 0.4.0 → 0.4.2

package/package.json

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

package/src/constants/model.ts

@@ -1,7 +1,7 @@
 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_TEAM_AGENT_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

package/src/index.ts

@@ -5,6 +5,7 @@ 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/artifact'
 export * from './schemas/chat-api'
 export * from './schemas/chat-message'
 export * from './schemas/common'

package/src/runtime/agent-types.ts

@@ -3,6 +3,7 @@ import type {
   Output,
   PrepareStepFunction,
   StopCondition,
+  ToolCallRepairFunction,
   ToolLoopAgentOnFinishCallback,
   ToolSet,
 } from 'ai'
@@ -16,6 +17,7 @@ export interface CreateRoutedAgentOptions<TTools extends ToolSet = ToolSet> {
   headers?: Record<string, string>
   stopWhen?: StopCondition<TTools> | Array<StopCondition<TTools>>
   prepareStep?: PrepareStepFunction<TTools>
+  repairToolCall?: ToolCallRepairFunction<TTools>
   maxRetries?: number
   output?: Output.Output
   modelOverride?: { model: LanguageModel; providerOptions?: Record<string, unknown> }

package/src/schemas/artifact.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod'
+
+import { recordIdSchema } from './common'
+
+const dbDateTimeSchema = z.coerce.date()
+const apiDateTimeSchema = z.string().datetime({ offset: true })
+
+export const ArtifactKindSchema = z
+  .enum(['document', 'plan', 'brief', 'report', 'analysis', 'spec'])
+  .meta({ id: 'ArtifactKindSchema' })
+export type ArtifactKind = z.infer<typeof ArtifactKindSchema>
+
+export const ArtifactStatusSchema = z.enum(['active', 'superseded', 'archived']).meta({ id: 'ArtifactStatusSchema' })
+export type ArtifactStatus = z.infer<typeof ArtifactStatusSchema>
+
+export const ArtifactReferenceTargetSchema = z
+  .enum(['artifact', 'document'])
+  .meta({ id: 'ArtifactReferenceTargetSchema' })
+export type ArtifactReferenceTarget = z.infer<typeof ArtifactReferenceTargetSchema>
+
+export const ArtifactReferenceSchema = z
+  .object({
+    uri: z.string().trim().min(1).max(1000),
+    targetType: ArtifactReferenceTargetSchema,
+    targetId: z.string().trim().min(1).max(255),
+  })
+  .strict()
+  .meta({ id: 'ArtifactReferenceSchema' })
+export type ArtifactReference = z.infer<typeof ArtifactReferenceSchema>
+
+export const ArtifactRecordSchema = z
+  .object({
+    id: recordIdSchema,
+    organizationId: recordIdSchema,
+    authorAgentId: z.string(),
+    title: z.string(),
+    artifactKind: ArtifactKindSchema,
+    templateId: z.string(),
+    canonicalKey: z.string(),
+    version: z.number().int().positive(),
+    status: ArtifactStatusSchema,
+    supersededBy: recordIdSchema.optional(),
+    storageKey: z.string(),
+    description: z.string().optional(),
+    tags: z.array(z.string()).default([]),
+    references: z.array(ArtifactReferenceSchema).default([]),
+    sourceThreadId: recordIdSchema.optional(),
+    sourcePlanRunId: recordIdSchema.optional(),
+    sourcePlanNodeId: z.string().optional(),
+    createdAt: dbDateTimeSchema,
+    updatedAt: dbDateTimeSchema.optional(),
+  })
+  .meta({ id: 'ArtifactRecordSchema' })
+export type ArtifactRecord = z.infer<typeof ArtifactRecordSchema>
+
+export const ArtifactVersionSummarySchema = z
+  .object({
+    id: z.string(),
+    title: z.string(),
+    version: z.number().int().positive(),
+    status: ArtifactStatusSchema,
+    createdAt: apiDateTimeSchema,
+  })
+  .strict()
+  .meta({ id: 'ArtifactVersionSummarySchema' })
+export type ArtifactVersionSummary = z.infer<typeof ArtifactVersionSummarySchema>
+
+export const PublishArtifactArgsSchema = z
+  .object({
+    organizationId: z.string().trim().min(1).max(255),
+    authorAgentId: z.string().trim().min(1).max(255),
+    title: z.string().trim().min(1).max(300),
+    artifactKind: ArtifactKindSchema,
+    templateId: z.string().trim().min(1).max(255),
+    content: z
+      .string()
+      .min(1)
+      .refine((value) => value.trim().length > 0, 'Content is required.'),
+    canonicalKey: z.string().trim().min(1).max(255).optional(),
+    description: z.string().trim().min(1).max(1000).optional(),
+    tags: z.array(z.string().trim().min(1).max(100)).optional().default([]),
+    sourceThreadId: z.string().trim().min(1).max(255).optional(),
+    sourcePlanRunId: z.string().trim().min(1).max(255).optional(),
+    sourcePlanNodeId: z.string().trim().min(1).max(255).optional(),
+    deliverableName: z.string().trim().min(1).max(200).optional(),
+  })
+  .strict()
+  .meta({ id: 'PublishArtifactArgsSchema' })
+export type PublishArtifactArgs = z.infer<typeof PublishArtifactArgsSchema>
+
+export const GetArtifactResultSchema = z
+  .object({
+    artifact: ArtifactRecordSchema,
+    content: z.string(),
+    versions: z.array(ArtifactVersionSummarySchema),
+    backlinks: z.array(ArtifactRecordSchema),
+  })
+  .meta({ id: 'GetArtifactResultSchema' })
+export type GetArtifactResult = z.infer<typeof GetArtifactResultSchema>

package/src/schemas/execution-plan.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 
+import { ArtifactKindSchema } from './artifact'
 import { recordIdSchema } from './common'
 
 /** For DB record schemas — accepts Date objects from SurrealDB and coerces strings */
@@ -220,6 +221,14 @@ export const PlanArtifactSpecSchema = z
     required: z.boolean().default(true),
     schemaRef: z.string().trim().min(1).max(200).optional(),
     description: z.string().trim().min(1).max(1000),
+    publishAs: z
+      .object({
+        artifactKind: ArtifactKindSchema,
+        templateId: z.string().trim().min(1).max(255),
+        canonicalKey: z.string().trim().min(1).max(255).optional(),
+      })
+      .strict()
+      .optional(),
   })
   .strict()
 export type PlanArtifactSpec = z.infer<typeof PlanArtifactSpecSchema>
@@ -419,7 +428,13 @@ export const PlanArtifactSubmissionSchema = z
     name: z.string().trim().min(1).max(200),
     kind: PlanArtifactKindSchema,
     description: z.string().trim().max(1000).optional(),
+    content: z
+      .string()
+      .min(1)
+      .refine((value) => value.trim().length > 0, 'Content is required.')
+      .optional(),
     payload: planStructuredPayloadSchema.optional(),
+    publishedArtifactId: z.string().trim().min(1).max(255).optional(),
   })
   .strict()
 export type PlanArtifactSubmission = z.infer<typeof PlanArtifactSubmissionSchema>
@@ -471,7 +486,7 @@ export const PlanDependencyTriggerModeSchema = z.enum(['block', 'notify', 'best-
 export type PlanDependencyTriggerMode = z.infer<typeof PlanDependencyTriggerModeSchema>
 
 export const PlanDependencySchema = z.object({
-  sourcePlanTitle: z.string().trim().min(1).max(200),
+  sourcePlanSpecId: z.string().trim().min(1).max(255),
   sourceNodeId: z.string().trim().min(1).max(200),
   artifactName: z.string().trim().min(1).max(200),
   triggerMode: PlanDependencyTriggerModeSchema.default('block'),
@@ -685,7 +700,9 @@ export const PlanArtifactSchema = z.object({
   pointer: z.string(),
   schemaRef: z.string().optional(),
   description: z.string().optional(),
+  content: z.string().optional(),
   payload: planStructuredPayloadSchema.optional(),
+  publishedArtifactId: recordIdSchema.optional(),
   createdAt: dbDateTimeSchema,
 })
 export type PlanArtifactRecord = z.infer<typeof PlanArtifactSchema>
@@ -796,7 +813,9 @@ export const SerializablePlanArtifactSchema = z.object({
   pointer: z.string(),
   schemaRef: z.string().nullish(),
   description: z.string().nullish(),
+  content: z.string().nullish(),
   payload: planStructuredPayloadSchema.nullish(),
+  publishedArtifactId: z.string().nullish(),
   createdAt: z.iso.datetime(),
 })
 export type SerializablePlanArtifact = z.infer<typeof SerializablePlanArtifactSchema>
@@ -908,18 +927,28 @@ export const SerializableExecutionPlanSchema = z.object({
 })
 export type SerializableExecutionPlan = z.infer<typeof SerializableExecutionPlanSchema>
 
-export const PlanTemplateRecordSchema = z.object({
-  id: recordIdSchema,
-  organizationId: recordIdSchema,
-  name: z.string(),
-  description: z.string().optional(),
-  draft: PlanDraftSchema,
-  tags: z.array(z.string()).default([]),
-  source: PlanTemplateSourceSchema,
-  sourceRef: z.string().optional(),
-  createdAt: dbDateTimeSchema,
-  updatedAt: dbDateTimeSchema.optional(),
-})
+export const PlanTemplateRecordSchema = z
+  .object({
+    id: recordIdSchema,
+    organizationId: recordIdSchema,
+    name: z.string(),
+    description: z.string().optional(),
+    draft: PlanDraftSchema,
+    tags: z.array(z.string()).default([]),
+    source: PlanTemplateSourceSchema,
+    sourceRef: z.string().optional(),
+    createdAt: dbDateTimeSchema,
+    updatedAt: dbDateTimeSchema.optional(),
+  })
+  .superRefine((value, ctx) => {
+    if (value.source !== 'user' && (!value.sourceRef || value.sourceRef.trim().length === 0)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['sourceRef'],
+        message: `sourceRef is required when source is "${value.source}".`,
+      })
+    }
+  })
 export type PlanTemplateRecord = z.infer<typeof PlanTemplateRecordSchema>
 
 export const PlanCycleRecordSchema = z.object({

package/src/schemas/graph-designer.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 
-import { PlanArtifactKindSchema, PlanDraftSchema } from './execution-plan'
+import { ArtifactKindSchema } from './artifact'
+import { PlanDraftSchema } from './execution-plan'
 
 export const GraphDesignRequestSchema = z.object({
   objective: z.string().trim().min(1).max(4000),
@@ -8,7 +9,7 @@ export const GraphDesignRequestSchema = z.object({
   availableAgents: z.array(z.object({ agentId: z.string(), capabilities: z.array(z.string()) })),
   availablePlugins: z.array(z.object({ pluginRef: z.string(), operations: z.array(z.string()) })),
   contextArtifacts: z
-    .array(z.object({ name: z.string(), kind: PlanArtifactKindSchema, summary: z.string().optional() }))
+    .array(z.object({ name: z.string(), kind: ArtifactKindSchema, summary: z.string().optional() }))
     .default([]),
 })
 export type GraphDesignRequest = z.infer<typeof GraphDesignRequestSchema>

package/src/schemas/tools.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
 
-import { AgentPlanDraftSchema } from './agent-plan-draft'
+import { AgentPlanDraftSchema, AgentPlanEdgeDraftSchema } from './agent-plan-draft'
 import { baseChatMessageSchema } from './chat-api'
 import type { AnyChatMessage } from './chat-message'
 import {
@@ -87,34 +87,123 @@ const targetThreadIdSchema = z
 const runIdSchema = z.string().trim().min(1)
 const replaceReasonSchema = z.string().trim().min(1).max(1000)
 
-const ExecutionPlanCreateArgsSchema = AgentPlanDraftSchema.extend({
+export const ExecutionPlanCreateArgsSchema = AgentPlanDraftSchema.extend({
   action: z.literal('create'),
   targetThreadId: targetThreadIdSchema.optional(),
 }).strict()
 
-const ExecutionPlanCreateProjectArgsSchema = AgentPlanDraftSchema.extend({
+export const ExecutionPlanCreateProjectArgsSchema = AgentPlanDraftSchema.extend({
   action: z.literal('create-project'),
   projectTitle: projectTitleSchema.optional(),
   targetThreadId: targetThreadIdSchema.optional(),
 }).strict()
 
-const ExecutionPlanReplaceArgsSchema = AgentPlanDraftSchema.extend({
+export const ExecutionPlanReplaceArgsSchema = AgentPlanDraftSchema.extend({
   action: z.literal('replace'),
   runId: runIdSchema.describe('Required for replace and resume.'),
   reason: replaceReasonSchema.describe('Required for replace.'),
 }).strict()
 
-const ExecutionPlanResumeArgsSchema = z
+export const ExecutionPlanResumeArgsSchema = z
   .object({ action: z.literal('resume'), runId: runIdSchema.describe('Required for replace and resume.') })
   .strict()
 
-export const ExecutionPlanArgsSchema = z.discriminatedUnion('action', [
-  ExecutionPlanCreateArgsSchema,
-  ExecutionPlanCreateProjectArgsSchema,
-  ExecutionPlanReplaceArgsSchema,
-  ExecutionPlanResumeArgsSchema,
-])
-export type ExecutionPlanArgs = z.infer<typeof ExecutionPlanArgsSchema>
+const ExecutionPlanBaseArgsSchema = z
+  .object({
+    action: ExecutionPlanActionSchema,
+    title: AgentPlanDraftSchema.shape.title.optional(),
+    objective: AgentPlanDraftSchema.shape.objective.optional(),
+    nodes: AgentPlanDraftSchema.shape.nodes.optional(),
+    edges: z.array(AgentPlanEdgeDraftSchema).optional(),
+    projectTitle: projectTitleSchema.optional(),
+    targetThreadId: targetThreadIdSchema.optional(),
+    runId: runIdSchema.describe('Required for replace and resume.').optional(),
+    reason: replaceReasonSchema.describe('Required for replace.').optional(),
+  })
+  .strict()
+
+function addMissingExecutionPlanFieldIssue(ctx: z.RefinementCtx, path: string, message: string) {
+  ctx.addIssue({ code: z.ZodIssueCode.custom, path: [path], message })
+}
+
+function addUnexpectedExecutionPlanFieldIssue(ctx: z.RefinementCtx, path: string, message: string) {
+  ctx.addIssue({ code: z.ZodIssueCode.custom, path: [path], message })
+}
+
+export const ExecutionPlanArgsSchema = ExecutionPlanBaseArgsSchema.superRefine((value, ctx) => {
+  const requiresDraft = value.action === 'create' || value.action === 'create-project' || value.action === 'replace'
+
+  if (requiresDraft) {
+    if (value.title === undefined) {
+      addMissingExecutionPlanFieldIssue(ctx, 'title', 'title is required for create, create-project, and replace.')
+    }
+    if (value.objective === undefined) {
+      addMissingExecutionPlanFieldIssue(
+        ctx,
+        'objective',
+        'objective is required for create, create-project, and replace.',
+      )
+    }
+    if (value.nodes === undefined) {
+      addMissingExecutionPlanFieldIssue(ctx, 'nodes', 'nodes is required for create, create-project, and replace.')
+    }
+  }
+
+  if (value.action === 'replace') {
+    if (value.runId === undefined) {
+      addMissingExecutionPlanFieldIssue(ctx, 'runId', 'runId is required for replace.')
+    }
+    if (value.reason === undefined) {
+      addMissingExecutionPlanFieldIssue(ctx, 'reason', 'reason is required for replace.')
+    }
+  }
+
+  if (value.action === 'resume') {
+    if (value.runId === undefined) {
+      addMissingExecutionPlanFieldIssue(ctx, 'runId', 'runId is required for resume.')
+    }
+
+    for (const path of ['title', 'objective', 'nodes', 'edges', 'projectTitle', 'targetThreadId', 'reason'] as const) {
+      if (value[path] !== undefined) {
+        addUnexpectedExecutionPlanFieldIssue(
+          ctx,
+          path,
+          `${path} is not allowed when action is "resume". Use only action and runId.`,
+        )
+      }
+    }
+  }
+
+  if (value.action === 'create') {
+    for (const path of ['projectTitle', 'runId', 'reason'] as const) {
+      if (value[path] !== undefined) {
+        addUnexpectedExecutionPlanFieldIssue(ctx, path, `${path} is not allowed when action is "create".`)
+      }
+    }
+  }
+
+  if (value.action === 'create-project') {
+    for (const path of ['runId', 'reason'] as const) {
+      if (value[path] !== undefined) {
+        addUnexpectedExecutionPlanFieldIssue(ctx, path, `${path} is not allowed when action is "create-project".`)
+      }
+    }
+  }
+
+  if (value.action === 'replace') {
+    for (const path of ['projectTitle', 'targetThreadId'] as const) {
+      if (value[path] !== undefined) {
+        addUnexpectedExecutionPlanFieldIssue(ctx, path, `${path} is not allowed when action is "replace".`)
+      }
+    }
+  }
+})
+
+export type ExecutionPlanArgs =
+  | z.infer<typeof ExecutionPlanCreateArgsSchema>
+  | z.infer<typeof ExecutionPlanCreateProjectArgsSchema>
+  | z.infer<typeof ExecutionPlanReplaceArgsSchema>
+  | z.infer<typeof ExecutionPlanResumeArgsSchema>
 
 export const ExecutionPlanQueryArgsSchema = z
   .object({