@lota-sdk/shared 0.1.5

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@lota-sdk/shared",
+  "version": "0.1.5",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./constants/*": {
+      "bun": "./src/constants/*.ts",
+      "import": "./src/constants/*.ts",
+      "types": "./src/constants/*.ts"
+    },
+    "./runtime/*": {
+      "bun": "./src/runtime/*.ts",
+      "import": "./src/runtime/*.ts",
+      "types": "./src/runtime/*.ts"
+    },
+    "./schemas/*": {
+      "bun": "./src/schemas/*.ts",
+      "import": "./src/schemas/*.ts",
+      "types": "./src/schemas/*.ts"
+    },
+    "./utils/*": {
+      "bun": "./src/utils/*.ts",
+      "import": "./src/utils/*.ts",
+      "types": "./src/utils/*.ts"
+    }
+  },
+  "scripts": {
+    "lint": "node ../node_modules/oxlint/bin/oxlint --fix -c ../oxlint.config.ts src",
+    "format": "bunx oxfmt src",
+    "typecheck": "bunx tsgo --noEmit"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "ai": "^6.0.116",
+    "zod": "^4.3.6"
+  }
+}

package/src/constants/attachments.ts

@@ -0,0 +1,50 @@
+export const ATTACHMENT_MAX_FILE_SIZE_MB = 100
+export const ATTACHMENT_MAX_PER_MESSAGE = 5
+export const ATTACHMENT_MAX_TOTAL_SIZE_MB = 1024
+
+export const ATTACHMENT_MAX_FILE_SIZE_BYTES = ATTACHMENT_MAX_FILE_SIZE_MB * 1024 * 1024
+export const ATTACHMENT_MAX_TOTAL_SIZE_BYTES = ATTACHMENT_MAX_TOTAL_SIZE_MB * 1024 * 1024
+
+export const SUPPORTED_ATTACHMENT_MIME_TYPES = new Set([
+  'application/pdf',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  'text/plain',
+  'text/markdown',
+  'text/x-markdown',
+])
+
+export const SUPPORTED_ATTACHMENT_EXTENSIONS = new Set(['pdf', 'docx', 'txt', 'md', 'markdown'])
+
+export const ATTACHMENT_ACCEPT =
+  'application/pdf,application/vnd.openxmlformats-officedocument.wordprocessingml.document,text/plain,text/markdown,text/x-markdown,.pdf,.docx,.txt,.md,.markdown'
+
+export interface AttachmentDescriptor {
+  name: string
+  type?: string | null
+}
+
+export function getAttachmentExtension(name: string): string | null {
+  const trimmed = name.trim()
+  const lastDot = trimmed.lastIndexOf('.')
+  if (lastDot <= 0 || lastDot === trimmed.length - 1) return null
+  return trimmed.slice(lastDot + 1).toLowerCase()
+}
+
+export function isSupportedAttachment(file: AttachmentDescriptor): boolean {
+  const mimeType = file.type?.toLowerCase() ?? ''
+  if (SUPPORTED_ATTACHMENT_MIME_TYPES.has(mimeType)) return true
+  const extension = getAttachmentExtension(file.name)
+  return extension ? SUPPORTED_ATTACHMENT_EXTENSIONS.has(extension) : false
+}
+
+export function inferContentType(file: AttachmentDescriptor | string): string {
+  if (typeof file !== 'string' && file.type?.trim()) return file.type
+  const extension = getAttachmentExtension(typeof file === 'string' ? file : file.name)
+  if (extension === 'pdf') return 'application/pdf'
+  if (extension === 'docx') {
+    return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+  }
+  if (extension === 'md' || extension === 'markdown') return 'text/markdown'
+  if (extension === 'txt') return 'text/plain'
+  return 'application/octet-stream'
+}

package/src/constants/workstream.ts

@@ -0,0 +1,20 @@
+export const WORKSTREAM = {
+  DEFAULT_TITLE: 'New Workstream',
+  DEFAULT_PAGE_LIMIT: 15,
+  DEFAULT_MESSAGE_PAGE_LIMIT: 6,
+  MAX_MESSAGES_PER_PAGE: 100,
+  STREAMING_THROTTLE_MS: 50,
+  STREAM_RENDER_THROTTLE_MS: 16,
+  STREAM_REVEAL_PROFILE: 'natural-fast',
+  STREAM_REVEAL_BASE_MS: 18,
+  STREAM_REVEAL_CHAR_DELAY_FACTOR: 0.6,
+  STREAM_REVEAL_MAX_CHAR_DELAY_MS: 22,
+  STREAM_REVEAL_PUNCTUATION_PAUSE_MS: 18,
+  STREAM_REVEAL_MIN_CHARS: 8,
+  STREAM_REVEAL_MAX_CHARS: 24,
+  STREAM_REVEAL_MAX_TAIL_LATENCY_MS: 900,
+  STREAM_EMIT_MIN_CHARS: 36,
+  STREAM_EMIT_MAX_CHARS: 72,
+  MESSAGE_SEND_THROTTLE_MS: 250,
+  LLM_TIMEOUT_MS: 30_000,
+} as const

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from './constants/attachments'
+export * from './constants/workstream'
+export * from './runtime/chat-message-metadata'
+export * from './schemas/chat-api'
+export * from './schemas/chat-message'
+export * from './schemas/common'
+export * from './schemas/document'
+export * from './schemas/error'
+export * from './schemas/execution-plan'
+export * from './schemas/recent-activity'
+export * from './schemas/repository-structure'
+export * from './schemas/tools'
+export * from './utils/assistant-text'
+export * from './utils/markdown-normalization'
+export * from './utils/string'

package/src/runtime/chat-message-metadata.ts

@@ -0,0 +1,47 @@
+export interface MessageMetadataLike {
+  createdAt?: unknown
+  [key: string]: unknown
+}
+
+export function toTimestamp(value: unknown): number {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string') {
+    const parsed = Date.parse(value)
+    if (Number.isFinite(parsed)) return parsed
+  }
+  if (value instanceof Date) return value.getTime()
+  return Date.now()
+}
+
+export function getMessageCreatedAt(
+  message: { metadata?: MessageMetadataLike },
+  options?: { fallback?: number },
+): number {
+  const createdAt = toTimestamp(message.metadata?.createdAt)
+  if (Number.isFinite(createdAt)) return createdAt
+  return options?.fallback ?? Date.now()
+}
+
+export function withCreatedAtMetadata<TMetadata extends MessageMetadataLike | undefined>(
+  metadata: TMetadata,
+  fallback = Date.now(),
+): NonNullable<TMetadata> & { createdAt: number } {
+  const next =
+    metadata && typeof metadata === 'object'
+      ? ({ ...(metadata as Record<string, unknown>) } as NonNullable<TMetadata>)
+      : ({} as NonNullable<TMetadata>)
+
+  if (typeof next.createdAt !== 'number' || !Number.isFinite(next.createdAt)) {
+    next.createdAt = fallback
+  }
+
+  return next as NonNullable<TMetadata> & { createdAt: number }
+}
+
+export function withMessageCreatedAt<TMessage extends { metadata?: MessageMetadataLike }>(
+  message: TMessage,
+  fallback = Date.now(),
+): TMessage {
+  const metadata = withCreatedAtMetadata(message.metadata, fallback)
+  return { ...message, metadata }
+}

package/src/schemas/chat-api.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod'
+
+import { messageMetadataSchema } from './chat-message'
+
+const textChatMessagePartSchema = z.object({ type: z.literal('text'), text: z.string() }).passthrough()
+const reasoningChatMessagePartSchema = z
+  .object({ type: z.literal('reasoning'), text: z.string(), state: z.enum(['streaming', 'done']).optional() })
+  .passthrough()
+const genericChatMessagePartSchema = z
+  .object({ type: z.string().refine((value) => value !== 'text' && value !== 'reasoning', 'Unsupported message part') })
+  .passthrough()
+
+export const baseChatMessagePartSchema = z.union([
+  textChatMessagePartSchema,
+  reasoningChatMessagePartSchema,
+  genericChatMessagePartSchema,
+])
+
+export const baseChatMessageSchema = z
+  .object({
+    id: z.string(),
+    role: z.enum(['system', 'user', 'assistant']),
+    parts: z.array(baseChatMessagePartSchema),
+    metadata: messageMetadataSchema,
+  })
+  .passthrough()

package/src/schemas/chat-message.ts

@@ -0,0 +1,55 @@
+import type { UIDataTypes, UIMessage, UITools } from 'ai'
+import { z } from 'zod'
+
+import type { CoreChatTools } from './tools'
+
+const publicWorkstreamStateSchema = z.record(z.string(), z.unknown())
+
+export const messageMetadataSchema = z
+  .object({
+    agentId: z.string().optional(),
+    agentName: z.string().optional(),
+    reasoningProfile: z.enum(['fast', 'standard', 'deep']).optional(),
+    highImpactClasses: z.array(z.string()).optional(),
+    policyClasses: z.array(z.string()).optional(),
+    semanticTerminationReason: z.enum(['none', 'conflict', 'cycle-detected']).optional(),
+    inputTokens: z.number().optional(),
+    outputTokens: z.number().optional(),
+    totalTokens: z.number().optional(),
+    cost: z.number().optional(),
+    upstreamInferenceCost: z.number().optional(),
+    finishReason: z.string().optional(),
+    isCompacted: z.boolean().optional(),
+    createdAt: z.number().optional(),
+  })
+  .optional()
+
+export type MessageMetadata = z.infer<typeof messageMetadataSchema>
+
+export function parseRowMetadata(raw: unknown): MessageMetadata {
+  if (!raw || typeof raw !== 'object') return undefined
+  const result = messageMetadataSchema.safeParse(raw)
+  return result.success ? result.data : undefined
+}
+
+export const dataPartsSchema = { workstreamTracker: publicWorkstreamStateSchema }
+
+export type CustomDataParts = { workstreamTracker: z.infer<typeof publicWorkstreamStateSchema> }
+
+export type AnyChatTools = Record<string, { input: unknown; output: unknown }>
+export type HostExtensionChatTools = AnyChatTools
+export type ChatUITools = CoreChatTools & HostExtensionChatTools
+
+export type BaseChatMessage<
+  TDataParts extends UIDataTypes = CustomDataParts,
+  TTools extends UITools = AnyChatTools,
+> = UIMessage<MessageMetadata, TDataParts, TTools>
+
+export type BaseChatMessagePart<
+  TDataParts extends UIDataTypes = CustomDataParts,
+  TTools extends UITools = AnyChatTools,
+> = BaseChatMessage<TDataParts, TTools>['parts'][number]
+
+export type AnyChatMessage = BaseChatMessage
+export type ChatMessage = BaseChatMessage<CustomDataParts, ChatUITools>
+export type ChatMessagePart = BaseChatMessagePart<CustomDataParts, ChatUITools>

package/src/schemas/common.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod'
+
+import { WORKSTREAM } from '../constants/workstream'
+
+export const unixTimestampSchema = z.coerce.date()
+
+const SURREALDB_RECORD_ID_CLASSES = new Set(['RecordId', 'StringRecordId'])
+
+function coerceRecordIdToString(val: unknown): unknown {
+  if (val === null || val === undefined) return val
+  if (typeof val === 'string') return val
+  if (typeof val === 'object') {
+    const constructorName = val.constructor.name
+    if (constructorName && SURREALDB_RECORD_ID_CLASSES.has(constructorName)) {
+      return (val as { toString(): string }).toString()
+    }
+  }
+  return val
+}
+
+/**
+ * Record ID schema that accepts:
+ * - String format: "table:id" or just "id"
+ * - Object format: { tb: string, id: string | number }
+ * - SurrealDB RecordId/StringRecordId objects (coerced via toString)
+ */
+export const recordIdSchema = z.preprocess(
+  (val) => {
+    if (val === null || val === undefined) return val
+    if (typeof val === 'string') return val
+    if (typeof val === 'object') {
+      const constructorName = val.constructor.name
+      // Only coerce known SurrealDB RecordId classes
+      if (constructorName && SURREALDB_RECORD_ID_CLASSES.has(constructorName)) {
+        return (val as { toString(): string }).toString()
+      }
+      // Handle plain { tb, id } objects
+      const record = val as { tb?: unknown; id?: unknown }
+      if (typeof record.tb === 'string' && (typeof record.id === 'string' || typeof record.id === 'number')) {
+        return val
+      }
+    }
+    return val
+  },
+  z.union([z.string(), z.object({ tb: z.string(), id: z.union([z.string(), z.number()]) })]),
+)
+
+export const recordIdStringSchema = z.preprocess(coerceRecordIdToString, z.string())
+
+export const paginationTakeSchema = z.coerce.number().int().min(1).max(WORKSTREAM.MAX_MESSAGES_PER_PAGE)
+export const paginationPageSchema = z.coerce.number().int().min(1)
+export const paginationCursorSchema = z.preprocess((value) => value, recordIdSchema)
+
+export const paginationSchemaBase = z.object({
+  page: paginationPageSchema.optional(),
+  cursor: paginationCursorSchema.optional(),
+  take: paginationTakeSchema.default(WORKSTREAM.DEFAULT_PAGE_LIMIT),
+})
+
+export const paginationSchema = paginationSchemaBase.refine(
+  (value) => !(value.page !== undefined && value.cursor !== undefined),
+  { message: 'Provide either page or cursor, not both', path: ['cursor'] },
+)
+
+export const installUrlResponseSchema = z.object({ url: z.string().url() }).meta({ id: 'InstallUrlResponseSchema' })
+
+export type InstallUrlResponse = z.infer<typeof installUrlResponseSchema>
+
+export const successResponseSchema = z.object({ success: z.boolean() }).meta({ id: 'SuccessResponseSchema' })
+
+export type SuccessResponse = z.infer<typeof successResponseSchema>

package/src/schemas/document.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod'
+
+export const DocumentRenderModeSchema = z.enum(['markdown', 'text', 'pdf']).meta({ id: 'DocumentRenderModeSchema' })
+
+export const DocumentKnowledgeStatusSchema = z
+  .enum(['processing', 'ready', 'error'])
+  .meta({ id: 'DocumentKnowledgeStatusSchema' })
+
+export const DocumentRecordSchema = z
+  .object({
+    id: z.string().optional(),
+    title: z.string(),
+    relativePath: z.string(),
+    mediaType: z.string(),
+    renderMode: DocumentRenderModeSchema,
+    knowledgeStatus: DocumentKnowledgeStatusSchema,
+    storageKey: z.string(),
+    sizeBytes: z.number().int().nonnegative().optional(),
+    createdAt: z.iso.datetime(),
+    updatedAt: z.iso.datetime(),
+  })
+  .meta({ id: 'DocumentRecordSchema' })
+
+export const DocumentChunkRecordSchema = z
+  .object({
+    id: z.string().optional(),
+    documentId: z.string(),
+    sourceCanonicalKey: z.string(),
+    sourceVersionKey: z.string(),
+    chunkKey: z.string(),
+    chunkIndex: z.number().int(),
+    sectionPath: z.string().optional(),
+    pageStart: z.number().int().positive().optional(),
+    pageEnd: z.number().int().positive().optional(),
+    content: z.string(),
+    embedding: z.array(z.number()).optional(),
+    contentHash: z.string(),
+    tokenEstimate: z.number().int(),
+    summary: z.string().optional(),
+    keywords: z.array(z.string()).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    archivedAt: z.iso.datetime().optional(),
+    createdAt: z.iso.datetime(),
+    updatedAt: z.iso.datetime(),
+  })
+  .meta({ id: 'DocumentChunkRecordSchema' })
+
+export type DocumentRenderMode = z.infer<typeof DocumentRenderModeSchema>
+export type DocumentKnowledgeStatus = z.infer<typeof DocumentKnowledgeStatusSchema>
+export type DocumentRecord = z.infer<typeof DocumentRecordSchema>
+export type DocumentChunkRecord = z.infer<typeof DocumentChunkRecordSchema>

package/src/schemas/error.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod'
+
+export const ErrorResponseSchema = z
+  .object({
+    error: z.object({
+      code: z.string(),
+      message: z.string(),
+      issues: z.array(z.object({ path: z.string(), message: z.string() })).optional(),
+    }),
+  })
+  .meta({ id: 'ErrorResponseSchema' })

package/src/schemas/execution-plan.ts

@@ -0,0 +1,183 @@
+import { z } from 'zod'
+
+import { recordIdSchema, unixTimestampSchema } from './common'
+
+export const ExecutionPlanStatusSchema = z
+  .enum(['draft', 'executing', 'blocked', 'completed', 'aborted'])
+  .meta({ id: 'ExecutionPlanStatusSchema' })
+export type ExecutionPlanStatus = z.infer<typeof ExecutionPlanStatusSchema>
+
+export const ExecutionPlanTaskStatusSchema = z
+  .enum(['pending', 'in-progress', 'completed', 'blocked', 'skipped', 'failed'])
+  .meta({ id: 'ExecutionPlanTaskStatusSchema' })
+export type ExecutionPlanTaskStatus = z.infer<typeof ExecutionPlanTaskStatusSchema>
+
+export const ExecutionPlanTaskResultStatusSchema = z
+  .enum(['not-started', 'success', 'partial', 'failed'])
+  .meta({ id: 'ExecutionPlanTaskResultStatusSchema' })
+export type ExecutionPlanTaskResultStatus = z.infer<typeof ExecutionPlanTaskResultStatusSchema>
+
+export const ExecutionPlanTaskKindSchema = z
+  .enum(['agent', 'user-input', 'plugin'])
+  .meta({ id: 'ExecutionPlanTaskKindSchema' })
+export type ExecutionPlanTaskKind = z.infer<typeof ExecutionPlanTaskKindSchema>
+
+export const ExecutionPlanTaskOwnerTypeSchema = z
+  .enum(['agent', 'plugin', 'user'])
+  .meta({ id: 'ExecutionPlanTaskOwnerTypeSchema' })
+export type ExecutionPlanTaskOwnerType = z.infer<typeof ExecutionPlanTaskOwnerTypeSchema>
+
+export const ExecutionPlanEventTypeSchema = z
+  .enum([
+    'plan-created',
+    'plan-replaced',
+    'plan-status-changed',
+    'task-started',
+    'task-progress',
+    'task-completed',
+    'task-failed',
+    'task-blocked',
+    'task-skipped',
+    'task-restarted',
+    'replan',
+  ])
+  .meta({ id: 'ExecutionPlanEventTypeSchema' })
+export type ExecutionPlanEventType = z.infer<typeof ExecutionPlanEventTypeSchema>
+
+export const ExecutionPlanTaskInputSchema = z.union([z.string(), z.record(z.string(), z.unknown())])
+export type ExecutionPlanTaskInput = z.infer<typeof ExecutionPlanTaskInputSchema>
+
+export const ExecutionPlanSchema = z.object({
+  id: recordIdSchema,
+  organizationId: recordIdSchema,
+  workstreamId: recordIdSchema,
+  title: z.string(),
+  objective: z.string(),
+  status: ExecutionPlanStatusSchema,
+  leadAgentId: z.string(),
+  currentTaskId: recordIdSchema.optional(),
+  restartFromTaskId: recordIdSchema.optional(),
+  replacedPlanId: recordIdSchema.optional(),
+  failureCount: z.number().int().nonnegative(),
+  createdAt: unixTimestampSchema,
+  updatedAt: unixTimestampSchema.optional(),
+  startedAt: unixTimestampSchema.optional(),
+  completedAt: unixTimestampSchema.optional(),
+})
+export type ExecutionPlanRecord = z.infer<typeof ExecutionPlanSchema>
+
+export const ExecutionPlanTaskSchema = z.object({
+  id: recordIdSchema,
+  planId: recordIdSchema,
+  organizationId: recordIdSchema,
+  workstreamId: recordIdSchema,
+  position: z.number().int().nonnegative(),
+  title: z.string(),
+  rationale: z.string(),
+  kind: ExecutionPlanTaskKindSchema,
+  ownerType: ExecutionPlanTaskOwnerTypeSchema,
+  ownerRef: z.string(),
+  status: ExecutionPlanTaskStatusSchema,
+  resultStatus: ExecutionPlanTaskResultStatusSchema,
+  input: ExecutionPlanTaskInputSchema.optional(),
+  outputSummary: z.string().optional(),
+  blockedReason: z.string().optional(),
+  externalRef: z.string().optional(),
+  retryCount: z.number().int().nonnegative(),
+  idempotencyKey: z.string(),
+  createdAt: unixTimestampSchema,
+  updatedAt: unixTimestampSchema.optional(),
+  startedAt: unixTimestampSchema.optional(),
+  completedAt: unixTimestampSchema.optional(),
+})
+export type ExecutionPlanTaskRecord = z.infer<typeof ExecutionPlanTaskSchema>
+
+export const ExecutionPlanEventSchema = z.object({
+  id: recordIdSchema,
+  planId: recordIdSchema,
+  taskId: recordIdSchema.optional(),
+  eventType: ExecutionPlanEventTypeSchema,
+  fromStatus: z.string().optional(),
+  toStatus: z.string().optional(),
+  message: z.string(),
+  detail: z.record(z.string(), z.unknown()).optional(),
+  emittedBy: z.string(),
+  createdAt: unixTimestampSchema,
+})
+export type ExecutionPlanEventRecord = z.infer<typeof ExecutionPlanEventSchema>
+
+export const SerializableExecutionPlanTaskSchema = z.object({
+  id: z.string(),
+  position: z.number().int().nonnegative(),
+  title: z.string(),
+  rationale: z.string(),
+  kind: ExecutionPlanTaskKindSchema,
+  ownerType: ExecutionPlanTaskOwnerTypeSchema,
+  ownerRef: z.string(),
+  status: ExecutionPlanTaskStatusSchema,
+  resultStatus: ExecutionPlanTaskResultStatusSchema,
+  input: ExecutionPlanTaskInputSchema.optional(),
+  outputSummary: z.string().nullish(),
+  blockedReason: z.string().nullish(),
+  externalRef: z.string().nullish(),
+  retryCount: z.number().int().nonnegative(),
+  idempotencyKey: z.string(),
+  startedAt: z.iso.datetime().nullish(),
+  completedAt: z.iso.datetime().nullish(),
+})
+export type SerializableExecutionPlanTask = z.infer<typeof SerializableExecutionPlanTaskSchema>
+
+export const SerializableExecutionPlanEventSchema = z.object({
+  id: z.string(),
+  taskId: z.string().nullish(),
+  eventType: ExecutionPlanEventTypeSchema,
+  fromStatus: z.string().nullish(),
+  toStatus: z.string().nullish(),
+  message: z.string(),
+  detail: z.record(z.string(), z.unknown()).nullish(),
+  emittedBy: z.string(),
+  createdAt: z.iso.datetime(),
+})
+export type SerializableExecutionPlanEvent = z.infer<typeof SerializableExecutionPlanEventSchema>
+
+export const SerializableExecutionPlanCarriedTaskSchema = z.object({
+  planId: z.string(),
+  taskId: z.string(),
+  title: z.string(),
+  resultStatus: ExecutionPlanTaskResultStatusSchema,
+  outputSummary: z.string(),
+})
+export type SerializableExecutionPlanCarriedTask = z.infer<typeof SerializableExecutionPlanCarriedTaskSchema>
+
+export const SerializableExecutionPlanProgressSchema = z.object({
+  total: z.number().int().nonnegative(),
+  pending: z.number().int().nonnegative(),
+  inProgress: z.number().int().nonnegative(),
+  completed: z.number().int().nonnegative(),
+  blocked: z.number().int().nonnegative(),
+  failed: z.number().int().nonnegative(),
+  skipped: z.number().int().nonnegative(),
+  completionRatio: z.number().min(0).max(1).nullish(),
+})
+export type SerializableExecutionPlanProgress = z.infer<typeof SerializableExecutionPlanProgressSchema>
+
+export const SerializableExecutionPlanSchema = z.object({
+  planId: z.string(),
+  workstreamId: z.string(),
+  organizationId: z.string(),
+  title: z.string(),
+  objective: z.string(),
+  status: ExecutionPlanStatusSchema,
+  leadAgentId: z.string(),
+  currentTaskId: z.string().nullish(),
+  restartFromTaskId: z.string().nullish(),
+  replacedPlanId: z.string().nullish(),
+  failureCount: z.number().int().nonnegative(),
+  startedAt: z.iso.datetime().nullish(),
+  completedAt: z.iso.datetime().nullish(),
+  progress: SerializableExecutionPlanProgressSchema,
+  tasks: z.array(SerializableExecutionPlanTaskSchema),
+  recentEvents: z.array(SerializableExecutionPlanEventSchema),
+  carriedTasks: z.array(SerializableExecutionPlanCarriedTaskSchema),
+})
+export type SerializableExecutionPlan = z.infer<typeof SerializableExecutionPlanSchema>

package/src/schemas/recent-activity.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod'
+
+export const RecentActivityEventKindSchema = z.enum([
+  'workstream.opened',
+  'document.opened',
+  'website-intelligence.viewed',
+  'chat.turn.completed',
+])
+
+export const RecentActivityTargetKindSchema = z.enum(['workstream', 'document', 'website-intelligence', 'chat-turn'])
+
+export const RecentActivityTitleSourceSchema = z.enum(['system', 'chief'])
+
+export const RecentActivitySourceSchema = z.enum(['client', 'system'])
+
+export const RecentActivityDeepLinkSearchSchema = z.object({
+  chat: z.string().optional(),
+  agent: z.string().optional(),
+  tab: z.string().optional(),
+  docId: z.string().optional(),
+})
+
+export const RecentActivityDeepLinkSchema = z.object({
+  route: z.literal('/chat'),
+  search: RecentActivityDeepLinkSearchSchema.default({}),
+})
+
+export const RecentActivityMetadataSchema = z
+  .object({
+    agentId: z.string().optional(),
+    agentName: z.string().optional(),
+    workstreamId: z.string().optional(),
+    workstreamTitle: z.string().optional(),
+    workstreamMode: z.string().optional(),
+    coreType: z.string().optional(),
+    documentTitle: z.string().optional(),
+    documentFolder: z.string().optional(),
+    documentSource: z.string().optional(),
+    normalizedWebsiteUrl: z.string().optional(),
+    userMessageText: z.string().optional(),
+    assistantSummary: z.string().optional(),
+    messageId: z.string().optional(),
+  })
+  .partial()
+
+export const RecentActivityEventInputSchema = z.object({
+  sourceEventId: z.string().trim().min(1).max(200),
+  kind: RecentActivityEventKindSchema,
+  targetKind: RecentActivityTargetKindSchema,
+  targetId: z.string().trim().min(1).max(200).optional(),
+  mergeKey: z.string().trim().min(1).max(200),
+  title: z.string().trim().min(1).max(140),
+  sourceLabel: z.string().trim().min(1).max(40),
+  deepLink: RecentActivityDeepLinkSchema,
+  metadata: RecentActivityMetadataSchema.optional(),
+  occurredAt: z.string().optional(),
+})
+
+export const RecentActivitySchema = z.object({
+  id: z.string(),
+  kind: RecentActivityEventKindSchema,
+  targetKind: RecentActivityTargetKindSchema,
+  targetId: z.string().optional(),
+  mergeKey: z.string(),
+  title: z.string(),
+  systemTitle: z.string(),
+  titleSource: RecentActivityTitleSourceSchema,
+  sourceLabel: z.string(),
+  deepLink: RecentActivityDeepLinkSchema,
+  metadata: RecentActivityMetadataSchema.optional(),
+  latestEventAt: z.string(),
+  titleRefinedAt: z.string().optional(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+})
+
+export const RecentActivityEventSchema = z.object({
+  id: z.string(),
+  sourceEventId: z.string(),
+  source: RecentActivitySourceSchema,
+  kind: RecentActivityEventKindSchema,
+  targetKind: RecentActivityTargetKindSchema,
+  targetId: z.string().optional(),
+  mergeKey: z.string(),
+  title: z.string(),
+  sourceLabel: z.string(),
+  deepLink: RecentActivityDeepLinkSchema,
+  metadata: RecentActivityMetadataSchema.optional(),
+  occurredAt: z.string(),
+  createdAt: z.string(),
+})
+
+export type RecentActivityEventKind = z.infer<typeof RecentActivityEventKindSchema>
+export type RecentActivityTargetKind = z.infer<typeof RecentActivityTargetKindSchema>
+export type RecentActivityTitleSource = z.infer<typeof RecentActivityTitleSourceSchema>
+export type RecentActivitySource = z.infer<typeof RecentActivitySourceSchema>
+export type RecentActivityDeepLinkSearch = z.infer<typeof RecentActivityDeepLinkSearchSchema>
+export type RecentActivityDeepLink = z.infer<typeof RecentActivityDeepLinkSchema>
+export type RecentActivityMetadata = z.infer<typeof RecentActivityMetadataSchema>
+export type RecentActivityEventInput = z.infer<typeof RecentActivityEventInputSchema>
+export type RecentActivity = z.infer<typeof RecentActivitySchema>
+export type RecentActivityEvent = z.infer<typeof RecentActivityEventSchema>

package/src/schemas/repository-structure.ts

@@ -0,0 +1,122 @@
+import { z } from 'zod'
+
+export const RepositoryStructureShapeSchema = z
+  .enum(['single-project', 'monorepo', 'library', 'docs-only', 'uncertain'])
+  .meta({ id: 'RepositoryStructureShapeSchema' })
+
+export const RepositoryStructureSignalSchema = z
+  .object({
+    key: z.string().trim().min(1).max(120),
+    label: z.string().trim().min(1).max(200),
+    reason: z.string().trim().min(1).max(1_000),
+    evidencePaths: z.array(z.string().trim().min(1).max(500)).max(20).default([]),
+  })
+  .meta({ id: 'RepositoryStructureSignalSchema' })
+
+export const RepositoryStructureComponentKindSchema = z
+  .enum(['app', 'service', 'package', 'library', 'docs', 'unknown'])
+  .meta({ id: 'RepositoryStructureComponentKindSchema' })
+
+export const RepositoryStructureComponentSchema = z
+  .object({
+    kind: RepositoryStructureComponentKindSchema,
+    name: z.string().trim().min(1).max(200),
+    path: z.string().trim().min(1).max(500),
+    packageManager: z.string().trim().min(1).max(80).optional(),
+    languages: z.array(z.string().trim().min(1).max(80)).max(20).default([]),
+    frameworks: z.array(z.string().trim().min(1).max(80)).max(20).default([]),
+    reason: z.string().trim().min(1).max(1_000),
+    evidencePaths: z.array(z.string().trim().min(1).max(500)).max(20).default([]),
+  })
+  .meta({ id: 'RepositoryStructureComponentSchema' })
+
+export const RepositoryStructureRepositorySchema = z
+  .object({
+    repositoryKey: z.string().trim().min(1).max(200),
+    repositoryFullName: z.string().trim().min(1).max(200),
+    defaultBranch: z.string().trim().min(1).max(120),
+    indexBranch: z.string().trim().min(1).max(120),
+    commitSha: z.string().trim().min(1).max(120).optional(),
+  })
+  .meta({ id: 'RepositoryStructureRepositorySchema' })
+
+export const RepositoryStructureArtifactSchema = z
+  .object({
+    schemaVersion: z.literal('repository-structure.v1'),
+    extractorVersion: z.string().trim().min(1).max(120),
+    generatedAt: z.string().datetime().optional(),
+    repository: RepositoryStructureRepositorySchema,
+    topLevelEntries: z.array(z.string().trim().min(1).max(200)).max(200).default([]),
+    repoShape: z.object({
+      kind: RepositoryStructureShapeSchema,
+      reason: z.string().trim().min(1).max(1_000),
+      evidencePaths: z.array(z.string().trim().min(1).max(500)).max(20).default([]),
+    }),
+    packageManagers: z.array(RepositoryStructureSignalSchema).max(40).default([]),
+    languages: z.array(RepositoryStructureSignalSchema).max(40).default([]),
+    frameworks: z.array(RepositoryStructureSignalSchema).max(60).default([]),
+    components: z.array(RepositoryStructureComponentSchema).max(200).default([]),
+    entryPoints: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    routeSignals: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    apiSignals: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    databaseSignals: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    authSignals: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    jobSignals: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    envFiles: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    dockerFiles: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    ciCdFiles: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    deploymentFiles: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    testSignals: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    lintSignals: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    formatSignals: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    typecheckSignals: z.array(RepositoryStructureSignalSchema).max(80).default([]),
+    unknowns: z.array(z.string().trim().min(1).max(500)).max(40).default([]),
+  })
+  .meta({ id: 'RepositoryStructureArtifactSchema' })
+
+export const RepositoryStructureSummarySchema = z
+  .object({
+    schemaVersion: z.literal('repository-structure-summary.v1'),
+    extractorVersion: z.string().trim().min(1).max(120),
+    generatedAt: z.string().datetime().optional(),
+    repository: RepositoryStructureRepositorySchema,
+    repoShape: RepositoryStructureShapeSchema,
+    topLevelEntries: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    packageManagers: z.array(z.string().trim().min(1).max(80)).max(20).default([]),
+    languages: z.array(z.string().trim().min(1).max(80)).max(20).default([]),
+    frameworks: z.array(z.string().trim().min(1).max(80)).max(20).default([]),
+    components: z
+      .array(
+        z.object({
+          kind: RepositoryStructureComponentKindSchema,
+          name: z.string().trim().min(1).max(200),
+          path: z.string().trim().min(1).max(500),
+        }),
+      )
+      .max(40)
+      .default([]),
+    entryPoints: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    routeSignals: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    apiSignals: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    databaseSignals: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    authSignals: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    jobSignals: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    envFiles: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    dockerFiles: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    ciCdFiles: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    testSignals: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    lintSignals: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    formatSignals: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    typecheckSignals: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    deploymentSignals: z.array(z.string().trim().min(1).max(200)).max(20).default([]),
+    unknowns: z.array(z.string().trim().min(1).max(500)).max(20).default([]),
+  })
+  .meta({ id: 'RepositoryStructureSummarySchema' })
+
+export type RepositoryStructureShape = z.infer<typeof RepositoryStructureShapeSchema>
+export type RepositoryStructureSignal = z.infer<typeof RepositoryStructureSignalSchema>
+export type RepositoryStructureComponentKind = z.infer<typeof RepositoryStructureComponentKindSchema>
+export type RepositoryStructureComponent = z.infer<typeof RepositoryStructureComponentSchema>
+export type RepositoryStructureRepository = z.infer<typeof RepositoryStructureRepositorySchema>
+export type RepositoryStructureArtifact = z.infer<typeof RepositoryStructureArtifactSchema>
+export type RepositoryStructureSummary = z.infer<typeof RepositoryStructureSummarySchema>

package/src/schemas/tools.ts

@@ -0,0 +1,163 @@
+import { z } from 'zod'
+
+import { baseChatMessageSchema } from './chat-api'
+import type { AnyChatMessage } from './chat-message'
+import {
+  ExecutionPlanStatusSchema,
+  ExecutionPlanTaskInputSchema,
+  ExecutionPlanTaskResultStatusSchema,
+  ExecutionPlanTaskStatusSchema,
+  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 REPLACE_EXECUTION_PLAN_TOOL_NAME = 'replaceExecutionPlan' as const
+export const SET_EXECUTION_TASK_STATUS_TOOL_NAME = 'setExecutionTaskStatus' as const
+export const GET_ACTIVE_EXECUTION_PLAN_TOOL_NAME = 'getActiveExecutionPlan' as const
+export const RESTART_EXECUTION_TASK_TOOL_NAME = 'restartExecutionTask' as const
+
+const UserQuestionItemSchema = z
+  .object({
+    question: z.string(),
+    type: z.enum(['single-select', 'multi-select', 'input']),
+    options: z.array(z.string()).optional(),
+    allowCustomAnswer: z.boolean().optional(),
+  })
+  .strict()
+
+export const UserQuestionsArgsSchema = z.object({ questions: z.array(UserQuestionItemSchema).min(1) }).strict()
+
+export const ConsultSpecialistArgsSchema = z
+  .object({ agentId: z.string(), task: z.string().trim().min(1).max(4000) })
+  .strict()
+
+export const ConsultSpecialistResultDataSchema = baseChatMessageSchema
+
+export const ConsultTeamResponseSchema = z
+  .object({
+    agentId: z.string(),
+    agentName: z.string().trim().min(1),
+    status: z.enum(['running', 'complete', 'error']),
+    summary: z.string().trim().optional(),
+    error: z.string().trim().optional(),
+    message: baseChatMessageSchema.optional(),
+  })
+  .strict()
+
+export const ConsultTeamArgsSchema = z.object({ task: z.string().trim().min(1).max(6000) }).strict()
+
+const ExecutionPlanCreateTaskKindSchema = z.enum(['agent', 'user-input'])
+const ExecutionPlanCreateTaskOwnerTypeSchema = z.enum(['agent', 'user'])
+
+const ExecutionPlanTaskDefinitionSchema = z
+  .object({
+    title: z.string().trim().min(1).max(300),
+    rationale: z.string().trim().min(1).max(500),
+    kind: ExecutionPlanCreateTaskKindSchema,
+    ownerType: ExecutionPlanCreateTaskOwnerTypeSchema,
+    ownerRef: z.string().trim().min(1).max(200),
+    input: ExecutionPlanTaskInputSchema.optional(),
+  })
+  .strict()
+  .refine(
+    (task) =>
+      (task.kind === 'agent' && task.ownerType === 'agent') ||
+      (task.kind === 'user-input' && task.ownerType === 'user'),
+    {
+      message: 'agent tasks must be owned by an agent and user-input tasks must be owned by a user.',
+      path: ['ownerType'],
+    },
+  )
+
+const ExecutionPlanToolActionSchema = z.enum([
+  'created',
+  'replaced',
+  'loaded',
+  'task-status-updated',
+  'task-restarted',
+  'none',
+])
+
+export const CreateExecutionPlanArgsSchema = z
+  .object({
+    title: z.string().trim().min(1).max(200),
+    objective: z.string().trim().min(1).max(1500),
+    tasks: z.array(ExecutionPlanTaskDefinitionSchema).min(1).max(10),
+  })
+  .strict()
+
+export const ReplaceExecutionPlanArgsSchema = z
+  .object({
+    planId: z.string().trim().min(1),
+    reason: z.string().trim().min(1).max(1000),
+    title: z.string().trim().min(1).max(200),
+    objective: z.string().trim().min(1).max(1500),
+    tasks: CreateExecutionPlanArgsSchema.shape.tasks,
+  })
+  .strict()
+
+export const SetExecutionTaskStatusArgsSchema = z
+  .object({
+    planId: z.string().trim().min(1),
+    taskId: z.string().trim().min(1),
+    status: ExecutionPlanTaskStatusSchema,
+    resultStatus: ExecutionPlanTaskResultStatusSchema.optional(),
+    outputSummary: z.string().trim().max(1500).optional(),
+    blockedReason: z.string().trim().max(1000).optional(),
+    externalRef: z.string().trim().max(300).optional(),
+  })
+  .strict()
+
+export const GetActiveExecutionPlanArgsSchema = z
+  .object({ includeEvents: z.boolean().optional().default(false) })
+  .strict()
+
+export const RestartExecutionTaskArgsSchema = z
+  .object({
+    planId: z.string().trim().min(1),
+    taskId: z.string().trim().min(1),
+    resetDownstream: z.boolean().optional().default(true),
+  })
+  .strict()
+
+export const ExecutionPlanToolResultDataSchema = z
+  .object({
+    action: ExecutionPlanToolActionSchema,
+    message: z.string().trim().min(1).optional(),
+    changedTaskId: z.string().nullish(),
+    plan: SerializableExecutionPlanSchema.nullish(),
+    hasPlan: z.boolean(),
+    status: ExecutionPlanStatusSchema.nullish(),
+  })
+  .strict()
+
+export const ConsultTeamResultDataSchema = z.object({ responses: z.array(ConsultTeamResponseSchema) }).strict()
+
+export type UserQuestionItem = z.infer<typeof UserQuestionItemSchema>
+export type UserQuestionsArgs = z.infer<typeof UserQuestionsArgsSchema>
+export type ConsultSpecialistArgs = z.infer<typeof ConsultSpecialistArgsSchema>
+export type ConsultSpecialistResultData = AnyChatMessage
+export type ConsultTeamArgs = z.infer<typeof ConsultTeamArgsSchema>
+export type ConsultTeamResponseData = Omit<z.infer<typeof ConsultTeamResponseSchema>, 'message'> & {
+  message?: AnyChatMessage
+}
+export type ConsultTeamResultData = { responses: ConsultTeamResponseData[] }
+export type CreateExecutionPlanArgs = z.infer<typeof CreateExecutionPlanArgsSchema>
+export type ReplaceExecutionPlanArgs = z.infer<typeof ReplaceExecutionPlanArgsSchema>
+export type SetExecutionTaskStatusArgs = z.infer<typeof SetExecutionTaskStatusArgsSchema>
+export type GetActiveExecutionPlanArgs = z.infer<typeof GetActiveExecutionPlanArgsSchema>
+export type RestartExecutionTaskArgs = z.infer<typeof RestartExecutionTaskArgsSchema>
+export type ExecutionPlanToolResultData = z.infer<typeof ExecutionPlanToolResultDataSchema>
+export type CoreChatTools = {
+  userQuestions: { input: UserQuestionsArgs; output: unknown }
+  consultSpecialist: { input: ConsultSpecialistArgs; output: ConsultSpecialistResultData }
+  consultTeam: { input: ConsultTeamArgs; output: ConsultTeamResultData }
+  createExecutionPlan: { input: CreateExecutionPlanArgs; output: ExecutionPlanToolResultData }
+  replaceExecutionPlan: { input: ReplaceExecutionPlanArgs; output: ExecutionPlanToolResultData }
+  setExecutionTaskStatus: { input: SetExecutionTaskStatusArgs; output: ExecutionPlanToolResultData }
+  getActiveExecutionPlan: { input: GetActiveExecutionPlanArgs; output: ExecutionPlanToolResultData }
+  restartExecutionTask: { input: RestartExecutionTaskArgs; output: ExecutionPlanToolResultData }
+}

package/src/utils/assistant-text.ts

@@ -0,0 +1,129 @@
+const INTERNAL_BLOCK_PATTERNS = [
+  /<compacted-context[\s\S]*?<\/compacted-context>/gi,
+  /<assistant-message[\s\S]*?<\/assistant-message>/gi,
+  /<system-message[\s\S]*?<\/system-message>/gi,
+  /<run-context[\s\S]*?<\/run-context>/gi,
+  /<response-instructions[\s\S]*?<\/response-instructions>/gi,
+  /<tool-outcome[\s\S]*?<\/tool-outcome>/gi,
+  /<part\b[^>]*type\s*=\s*["']tool[_-](?:call|result|outcome)["'][^>]*>[\s\S]*?<\/part>/gi,
+]
+
+const DANGLING_INTERNAL_BLOCK_PATTERNS = [
+  /<compacted-context[\s\S]*$/gi,
+  /<assistant-message[\s\S]*$/gi,
+  /<system-message[\s\S]*$/gi,
+  /<run-context[\s\S]*$/gi,
+  /<response-instructions[\s\S]*$/gi,
+  /<tool-outcome[\s\S]*$/gi,
+  /<part\b[^>]*type\s*=\s*["']tool[_-](?:call|result|outcome)["'][^>]*[\s\S]*$/gi,
+]
+
+const RAW_TOOL_OBJECT_START_PATTERN = /\{\s*"type"\s*:\s*"tool(?:_|-)(?:call|result|outcome)"/gi
+
+function findJsonObjectEnd(input: string, startIndex: number): number | null {
+  if (startIndex < 0 || startIndex >= input.length) return null
+  if (input[startIndex] !== '{') return null
+
+  let depth = 0
+  let inString = false
+  let isEscaped = false
+
+  for (let index = startIndex; index < input.length; index += 1) {
+    const character = input[index]
+    if (inString) {
+      if (isEscaped) {
+        isEscaped = false
+        continue
+      }
+
+      if (character === '\\') {
+        isEscaped = true
+        continue
+      }
+
+      if (character === '"') {
+        inString = false
+      }
+      continue
+    }
+
+    if (character === '"') {
+      inString = true
+      continue
+    }
+
+    if (character === '{') {
+      depth += 1
+      continue
+    }
+
+    if (character === '}') {
+      depth -= 1
+      if (depth === 0) return index
+      continue
+    }
+  }
+
+  return null
+}
+
+function stripRawToolPayloadObjects(value: string): string {
+  if (!value) return value
+
+  let cursor = 0
+  let result = ''
+
+  while (cursor < value.length) {
+    RAW_TOOL_OBJECT_START_PATTERN.lastIndex = cursor
+    const match = RAW_TOOL_OBJECT_START_PATTERN.exec(value)
+    if (!match) {
+      result += value.slice(cursor)
+      break
+    }
+
+    const start = match.index
+    result += value.slice(cursor, start)
+
+    const end = findJsonObjectEnd(value, start)
+    if (end === null) {
+      cursor = value.length
+      break
+    }
+
+    const candidate = value.slice(start, end + 1)
+    const looksInternalPayload =
+      (/"toolCallId"\s*:/.test(candidate) && /"toolName"\s*:/.test(candidate)) || /"toolResults"\s*:/.test(candidate)
+    if (!looksInternalPayload) {
+      result += candidate
+    }
+
+    cursor = end + 1
+  }
+
+  return result
+}
+
+export function sanitizeAssistantVisibleText(value: string): string {
+  let next = value
+
+  next = next.replace(/\[REDACTED\]/gi, '')
+
+  for (const pattern of INTERNAL_BLOCK_PATTERNS) {
+    next = next.replace(pattern, '')
+  }
+
+  for (const pattern of DANGLING_INTERNAL_BLOCK_PATTERNS) {
+    next = next.replace(pattern, '')
+  }
+
+  next = stripRawToolPayloadObjects(next)
+
+  next = next
+    .split('\n')
+    .filter((line) => line.trim().toLowerCase() !== '[redacted]')
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+
+  return next
+}

package/src/utils/markdown-normalization.ts

@@ -0,0 +1,39 @@
+type EvidenceGapsPayload = Partial<Record<'evidence' | 'gaps', string>>
+
+const COMBINED_EVIDENCE_GAPS_LANGUAGE = 'evidence-gaps'
+const ADJACENT_EVIDENCE_GAPS_PATTERN = /```(evidence|gaps)\s*\n([\s\S]*?)```\s*```(evidence|gaps)\s*\n([\s\S]*?)```/gi
+const EVIDENCE_GAPS_FENCE_PATTERN = /```(?:evidence-gaps|evidence|gaps)\s*\n[\s\S]*?(?:```|$)/gi
+
+function buildCombinedEvidenceGapsFence(
+  firstLanguage: string,
+  firstCode: string,
+  secondLanguage: string,
+  secondCode: string,
+): string {
+  const payload: EvidenceGapsPayload = {
+    evidence: firstLanguage === 'evidence' ? firstCode.trim() : secondLanguage === 'evidence' ? secondCode.trim() : '',
+    gaps: firstLanguage === 'gaps' ? firstCode.trim() : secondLanguage === 'gaps' ? secondCode.trim() : '',
+  }
+
+  return `\`\`\`${COMBINED_EVIDENCE_GAPS_LANGUAGE}\n${JSON.stringify(payload)}\n\`\`\``
+}
+
+export function normalizeAssistantMarkdown(markdown: string): string {
+  return markdown.replace(
+    ADJACENT_EVIDENCE_GAPS_PATTERN,
+    (match, firstLanguage: string, firstCode: string, secondLanguage: string, secondCode: string) => {
+      if (firstLanguage === secondLanguage) {
+        return match
+      }
+
+      return buildCombinedEvidenceGapsFence(firstLanguage, firstCode, secondLanguage, secondCode)
+    },
+  )
+}
+
+export function stripEvidenceGapsMarkdown(markdown: string): string {
+  return normalizeAssistantMarkdown(markdown)
+    .replace(EVIDENCE_GAPS_FENCE_PATTERN, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}

package/src/utils/string.ts

@@ -0,0 +1,18 @@
+/**
+ * Convert camelCase, PascalCase, kebab-case, or snake_case to human-readable title case.
+ *
+ * Examples:
+ *   memoryRemember       → Memory Remember
+ *   consultSpecialist    → Consult Specialist
+ *   researchTopic        → Research Topic
+ *   memory-block-append  → Memory Block Append
+ *   user_questions       → User Questions
+ */
+export function toHumanCase(str: string): string {
+  return str
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/[-_]/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+    .trim()
+}