Schemas

Shared host-facing schemas live in @lota-sdk/shared. Core runtime-only types stay in @lota-sdk/core.

The schema layer provides the typed contract between the SDK and host applications. Host code should import from @lota-sdk/shared for all public-facing types and only reach into @lota-sdk/core for runtime-internal types when building SDK extensions.

Chat Messages

The chat message schema extends the AI SDK UIMessage with typed metadata for agent identity, model info, token usage, and cost tracking. This is the primary type used for reading and rendering conversation messages.

import type { ChatMessage, ChatMessagePart, MessageMetadata } from '@lota-sdk/shared/schemas/chat-message'

ChatMessage extends AI SDK UIMessage with typed metadata and tool-part typing.

Key Types

interface ChatMessage extends UIMessage {
  metadata?: MessageMetadata
}

interface MessageMetadata {
  agentId?: string                 // Which agent produced this message
  model?: string                   // Model used for generation
  reasoningProfile?: string        // Reasoning profile applied (e.g. 'high', 'auto')
  tokenUsage?: {
    promptTokens: number
    completionTokens: number
    totalTokens: number
  }
  cost?: {
    inputCost: number              // Cost in USD for input tokens
    outputCost: number             // Cost in USD for output tokens
    totalCost: number
  }
  isCompacted?: boolean            // Whether this message was part of a compaction cycle
}

ChatMessagePart defines the typed union of message content parts, including text, tool calls, tool results, and reasoning traces. Host UIs use this type to render each part of a message appropriately.

Tool Schemas

Tool argument and result schemas define the contract for built-in SDK tools. Host applications use these types to build custom tool UIs or to process tool results.

import type {
  ConsultSpecialistArgs,
  ConsultTeamArgs,
  CreateExecutionPlanArgs,
  ExecutionPlanToolResultData,
  GetActiveExecutionPlanArgs,
  ReplaceExecutionPlanArgs,
  ResumeExecutionPlanRunArgs,
  SubmitExecutionNodeResultArgs,
  UserQuestionsArgs,
} from '@lota-sdk/shared/schemas/tools'

Schema	Description
ConsultSpecialistArgs	Arguments for the consult-specialist tool (agent-to-agent delegation)
ConsultTeamArgs	Arguments for the consult-team tool (multi-agent consultation)
CreateExecutionPlanArgs	PlanDraft input for creating a compiled execution plan
ReplaceExecutionPlanArgs	PlanDraft plus runId and reason for replacing the active run
SubmitExecutionNodeResultArgs	Node result submission with structured output, artifacts, and notes
GetActiveExecutionPlanArgs	Flags for including events, artifacts, approvals, checkpoints, and validation issues
ResumeExecutionPlanRunArgs	Input for resuming an interrupted run
ExecutionPlanToolResultData	Result payload returned by execution plan operations
UserQuestionsArgs	Arguments for the user-questions tool (asking clarifying questions)

Execution Plans

Execution plan schemas define the serializable structure of compiled specs, execution runs, nodes, artifacts, approvals, checkpoints, and events. These are used for rendering plan UIs and tracking executor-owned state.

import type {
  PlanApprovalStatus,
  PlanAttemptStatus,
  PlanNodeRunStatus,
  PlanNodeType,
  PlanRunStatus,
  SerializableExecutionPlan,
  SerializablePlanApproval,
  SerializablePlanArtifact,
  SerializablePlanCheckpoint,
  SerializablePlanEvent,
  SerializablePlanNode,
  SerializablePlanValidationIssue,
} from '@lota-sdk/shared/schemas/execution-plan'

Schema	Description
SerializableExecutionPlan	Complete execution run with spec metadata, progress, nodes, artifacts, approvals, checkpoints, and events
SerializablePlanNode	Serialized execution node contract plus runtime state
SerializablePlanArtifact	Serialized output artifact produced by a node attempt
SerializablePlanValidationIssue	Warning or blocking validation finding
SerializablePlanApproval	Durable human approval state and response
SerializablePlanCheckpoint	Latest checkpoint snapshot for restart-safe execution
SerializablePlanEvent	Audit event for plan, node, approval, or checkpoint changes
PlanRunStatus	Run-level status enum: running, awaiting-human, blocked, completed, failed, aborted
PlanNodeRunStatus	Node-level status enum: pending, ready, running, awaiting-human, completed, partial, blocked, failed, skipped
PlanAttemptStatus	Attempt status enum: submitted, validated, completed, failed, rejected
PlanApprovalStatus	Approval status enum: pending, approved, rejected, changes-requested
PlanNodeType	Node type enum including action, human-input, human-approval, human-review-edit, human-decision, switch, join, subgraph

Recent Activity

Recent activity schemas track notable events across workstreams and agents, used for building activity feeds and providing agents with awareness of recent system activity.

import type {
  RecentActivity,
  RecentActivityEvent,
  RecentActivityEventInput,
} from '@lota-sdk/shared/schemas/recent-activity'

Schema	Description
RecentActivity	Aggregated activity feed for an organization
RecentActivityEvent	A single activity event (turn completed, plan created, etc.)
RecentActivityEventInput	Input type for recording new activity events

Memory and Runtime State

Memory and workstream state types are internal to @lota-sdk/core and used when building SDK extensions or custom memory pipelines.

import type { Durability, MemoryRecord, MemoryType } from '@lota-sdk/core/db/memory-types'
import type { WorkstreamState, WorkstreamStateDelta } from '@lota-sdk/core/runtime/workstream-state'

Schema	Description
MemoryRecord	A stored memory with content, embedding, scope, type, and durability
MemoryType	Memory classification: fact, preference, interaction, procedure, relationship
Durability	Memory persistence level: core (never expires), standard, ephemeral
WorkstreamState	Structured state attached to a workstream (flexible key-value)
WorkstreamStateDelta	Incremental state update produced by a turn

Working with Schemas

API Response Types

Use shared schemas to type your API responses:

import type { SdkWorkstream, SdkWorkstreamMessage } from '@lota-sdk/shared/schemas/workstream'
import type { SerializableExecutionPlan } from '@lota-sdk/shared/schemas/execution-plan'

// Use in API response types
type WorkstreamListResponse = {
  workstreams: SdkWorkstream[]
  hasMore: boolean
}

type WorkstreamDetailResponse = {
  workstream: SdkWorkstream
  messages: SdkWorkstreamMessage[]
  activePlan?: SerializableExecutionPlan
}

Re-exporting from Host Packages

Host applications should re-export SDK schemas rather than duplicating them:

// In your host shared package
export type { ChatMessage, MessageMetadata } from '@lota-sdk/shared/schemas/chat-message'
export type { SerializableExecutionPlan } from '@lota-sdk/shared/schemas/execution-plan'

// Extend only product-specific fields
export interface AppWorkstream extends SdkWorkstream {
  organizationName: string    // Product-specific addition
  teamMembers: string[]       // Product-specific addition
}

UI Helper Ownership

Reusable host-facing helpers live in:

• @lota-sdk/ui/chat/* — chat message rendering, streaming state, message grouping
• @lota-sdk/ui/runtime/* — headless runtime client, connection management
• @lota-sdk/ui/tools/* — tool result rendering helpers, tool UI type maps