@lota-sdk/core 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/core",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -28,18 +28,18 @@
   },
   "dependencies": {
     "@ai-sdk/devtools": "^0.0.15",
-    "@ai-sdk/openai": "^3.0.48",
+    "@ai-sdk/openai": "^3.0.50",
     "@chat-adapter/slack": "^4.23.0",
     "@chat-adapter/state-ioredis": "^4.23.0",
     "@logtape/logtape": "^2.0.5",
-    "@lota-sdk/shared": "0.2.1",
-    "@mendable/firecrawl-js": "^4.18.0",
+    "@lota-sdk/shared": "0.2.3",
+    "@mendable/firecrawl-js": "^4.18.1",
     "@surrealdb/node": "^3.0.3",
-    "ai": "^6.0.141",
-    "bullmq": "^5.71.1",
+    "ai": "^6.0.145",
+    "bullmq": "^5.73.0",
     "chat": "^4.23.0",
     "cron-parser": "^5.5.0",
-    "hono": "^4.12.9",
+    "hono": "^4.12.10",
     "ioredis": "5.9.3",
     "mammoth": "^1.12.0",
     "pdf-parse": "^2.4.5",

package/src/ai/definitions.ts

@@ -91,7 +91,7 @@ Do not call additional tools in the same response.
 Do not ask when reasonable defaults exist or information is retrievable.`,
 })
 
-const researchSkillTools = ['researchTopic', 'fetchWebpage', 'inspectWebsite'] as const
+const researchSkillTools = ['searchWeb', 'researchTopic', 'fetchWebpage', 'inspectWebsite'] as const
 
 export const researchSkill = defineSkill({
   name: 'research',
@@ -103,8 +103,9 @@ export const researchSkill = defineSkill({
 Use for external information: market research, competitive analysis, fact verification.
 
 ## Tools
-- \`researchTopic\` — delegate to research agent. For broad research, call 2-3 in parallel with different focused tasks.
-- \`fetchWebpage\` — only when user shares a specific URL. Do not use for general research.
+- \`searchWeb\` — fastest path for narrow current lookups, finding candidate sources, and checking recency-sensitive facts. Prefer this first when a quick answer is enough.
+- \`researchTopic\` — delegate to the research agent only when the task needs deeper multi-source synthesis or a structured research brief.
+- \`fetchWebpage\` — use when the user shares a specific URL or \`searchWeb\` surfaces a page worth reading in full.
 - \`inspectWebsite\` — structured analysis of a website. Pass URL in \`url\` field. Use \`forceRefresh: true\` to overwrite.
 
 ## Output

package/src/runtime/agent-identity-overrides.ts

@@ -0,0 +1,62 @@
+import { agentDisplayNames } from '../config/agent-defaults'
+import { asRecord, readOptionalString } from './workstream-chat-helpers'
+
+interface RuntimeAgentIdentityOverrides {
+  displayNamesById: Partial<Record<string, string>>
+  shortDisplayNamesById: Partial<Record<string, string>>
+  primaryLabelsById: Partial<Record<string, string>>
+  secondaryLabelsById: Partial<Record<string, string>>
+  templateRoleIdsByAgentId: Partial<Record<string, string>>
+  routingAliasesByAgentId: Partial<Record<string, string[]>>
+}
+
+function readStringRecord(value: unknown): Partial<Record<string, string>> {
+  const record = asRecord(value)
+  if (!record) return {}
+
+  return Object.fromEntries(
+    Object.entries(record)
+      .map(([key, entry]) => [key, readOptionalString(entry)] as const)
+      .filter((entry): entry is [string, string] => typeof entry[1] === 'string'),
+  )
+}
+
+function readStringArrayRecord(value: unknown): Partial<Record<string, string[]>> {
+  const record = asRecord(value)
+  if (!record) return {}
+
+  return Object.fromEntries(
+    Object.entries(record).map(([key, entry]) => [
+      key,
+      Array.isArray(entry)
+        ? entry.map((item) => readOptionalString(item)).filter((item): item is string => typeof item === 'string')
+        : [],
+    ]),
+  )
+}
+
+function readStringOverride(record: Partial<Record<string, string>>, key: string): string | undefined {
+  return Object.hasOwn(record, key) ? record[key] : undefined
+}
+
+export function readRuntimeAgentIdentityOverrides(
+  context: Record<string, unknown> | null | undefined,
+): RuntimeAgentIdentityOverrides {
+  return {
+    displayNamesById: readStringRecord(context?.agentDisplayNamesById),
+    shortDisplayNamesById: readStringRecord(context?.agentShortDisplayNamesById),
+    primaryLabelsById: readStringRecord(context?.agentPrimaryLabelsById),
+    secondaryLabelsById: readStringRecord(context?.agentSecondaryLabelsById),
+    templateRoleIdsByAgentId: readStringRecord(context?.agentTemplateRoleIdsById),
+    routingAliasesByAgentId: readStringArrayRecord(context?.agentRoutingAliasesById),
+  }
+}
+
+export function resolveRuntimeAgentDisplayName(overrides: RuntimeAgentIdentityOverrides, agentId: string): string {
+  const override = readStringOverride(overrides.displayNamesById, agentId)
+  if (override !== undefined) {
+    return override
+  }
+
+  return agentDisplayNames[agentId] ?? agentId
+}

package/src/runtime/post-turn-side-effects.ts

@@ -29,6 +29,17 @@ import type { NormalizedWorkstream, WorkstreamRecord } from '../services/workstr
 import { safeEnqueue } from '../utils/async'
 import { toIsoDateTimeString } from '../utils/date-time'
 
+function resolveDisplayName(agentId: string, overrides?: Partial<Record<string, string>>): string {
+  if (overrides && Object.hasOwn(overrides, agentId)) {
+    const override = overrides[agentId]
+    if (override !== undefined) {
+      return override
+    }
+  }
+
+  return agentDisplayNames[agentId] ?? agentId
+}
+
 function buildRecentActivityChatDeepLink(params: {
   workstream: NormalizedWorkstream
   workstreamId: string
@@ -44,9 +55,10 @@ function buildRecentActivityChatDeepLink(params: {
 function buildRecentActivityChatSystemTitle(params: {
   workstream: NormalizedWorkstream
   visibleAgentId: string
+  agentDisplayNamesById?: Partial<Record<string, string>>
 }): string {
   if (params.workstream.mode === 'direct') {
-    return `Conversation with ${agentDisplayNames[params.visibleAgentId]}`
+    return `Conversation with ${resolveDisplayName(params.visibleAgentId, params.agentDisplayNamesById)}`
   }
 
   return params.workstream.title.trim() || 'Workstream update'
@@ -77,6 +89,7 @@ interface PostTurnSideEffectsParams {
   defaultLeadAgentId: string
   latestWorkstreamRecord: WorkstreamRecord
   isUserTurn: boolean
+  agentDisplayNamesById?: Partial<Record<string, string>>
 }
 
 export async function runPostTurnSideEffects(params: PostTurnSideEffectsParams): Promise<void> {
@@ -140,8 +153,9 @@ export async function runPostTurnSideEffects(params: PostTurnSideEffectsParams):
           title: buildRecentActivityChatSystemTitle({
             workstream: params.workstream,
             visibleAgentId: effectiveAgentId,
+            agentDisplayNamesById: params.agentDisplayNamesById,
           }),
-          sourceLabel: agentDisplayNames[effectiveAgentId],
+          sourceLabel: resolveDisplayName(effectiveAgentId, params.agentDisplayNamesById),
           deepLink: buildRecentActivityChatDeepLink({
             workstream: params.workstream,
             workstreamId: params.workstreamIdString,
@@ -149,7 +163,7 @@ export async function runPostTurnSideEffects(params: PostTurnSideEffectsParams):
           }),
           metadata: {
             agentId: effectiveAgentId,
-            agentName: agentDisplayNames[effectiveAgentId],
+            agentName: resolveDisplayName(effectiveAgentId, params.agentDisplayNamesById),
             workstreamId: params.workstreamIdString,
             workstreamTitle: params.latestWorkstreamRecord.title ?? params.workstream.title,
             workstreamMode: params.workstream.mode,

package/src/runtime/team-consultation-orchestrator.ts

@@ -91,14 +91,25 @@ export interface CreateConsultTeamToolParams {
   systemWorkspaceDetails?: string
   getPreSeededMemoriesSection: (agentId: string) => Promise<string | undefined>
   retrievedKnowledgeSection?: string
+  displayNamesById?: Partial<Record<string, string>>
   abortSignal: AbortSignal
   participantRunner: TeamConsultationParticipantRunner
   onReadError?: (agentId: string, error: unknown) => void
 }
 
 export function createConsultTeamTool(params: CreateConsultTeamToolParams) {
+  const resolveDisplayName = (agentId: string) => {
+    if (params.displayNamesById && Object.hasOwn(params.displayNamesById, agentId)) {
+      const override = params.displayNamesById[agentId]
+      if (override !== undefined) {
+        return override
+      }
+    }
+
+    return agentDisplayNames[agentId] ?? agentId
+  }
   const participantNames = teamConsultParticipants
-    .map((agentId) => agentDisplayNames[agentId] ?? agentId)
+    .map((agentId) => resolveDisplayName(agentId))
     .filter((value) => value.trim().length > 0)
   const participantSummary =
     participantNames.length > 0 ? participantNames.join(', ') : 'the configured specialist participants'
@@ -110,7 +121,7 @@ export function createConsultTeamTool(params: CreateConsultTeamToolParams) {
       const uploadMetadataText = buildReadableUploadMetadataText(params.availableUploads)
       const responses: ConsultTeamResultData['responses'] = teamConsultParticipants.map((agentId) => ({
         agentId,
-        agentName: agentDisplayNames[agentId] ?? agentId,
+        agentName: resolveDisplayName(agentId),
         status: 'running',
       }))
       const queue: ConsultTeamResultData[] = []
@@ -125,7 +136,7 @@ export function createConsultTeamTool(params: CreateConsultTeamToolParams) {
       }
 
       const workerPromises = teamConsultParticipants.map(async (agentId, index) => {
-        const agentName = agentDisplayNames[agentId] ?? agentId
+        const agentName = resolveDisplayName(agentId)
         const timedAbort = createTimedAbortSignal(params.abortSignal, TEAM_CONSULTATION_TIMEOUT_MS)
         let latestMessage: ChatMessage | null = null
 

package/src/services/agent-executor.service.ts

@@ -21,7 +21,10 @@ import {
   buildOwnershipDispatchContextSection,
   buildOwnershipDispatchResponseGuard,
 } from '../runtime/agent-runtime-policy'
+import { mergeInstructionSections } from '../runtime/instruction-sections'
 import { buildIndexedRepositoriesContext, getPluginService } from '../runtime/plugin-resolution'
+import { getTurnHooks } from '../runtime/runtime-extensions'
+import { asRecord, readInstructionSections, readOptionalString } from '../runtime/workstream-chat-helpers'
 import { nodeWorkspaceService } from './node-workspace.service'
 import type { PlanValidationIssueInput } from './plan-validator.service'
 import { WorkstreamSchema } from './workstream.types'
@@ -145,25 +148,47 @@ class AgentExecutorService {
     const mode = params.executionMode ?? 'linear'
 
     const dispatchMode = workstream.mode === 'group' ? 'fixedWorkstreamMode' : 'direct'
+    const dispatchInstructionSections = [
+      buildOwnershipDispatchContextSection({
+        node: params.nodeSpec,
+        resolvedInput: params.resolvedInput,
+        inputArtifacts: params.inputArtifacts,
+        upstreamHandoffs: params.context.upstreamHandoffs,
+      }),
+    ]
+    const turnHooks = getTurnHooks()
+    const agentResolution = asRecord(
+      await turnHooks.resolveAgent?.({
+        agentId,
+        mode: dispatchMode,
+        workstream,
+        workstreamRef,
+        orgRef: organizationRef,
+        userRef,
+        userName,
+        onboardingActive: false,
+        linearInstalled: Boolean(linearInstallation),
+        githubInstalled: Boolean(githubInstallation),
+        additionalInstructionSections: dispatchInstructionSections,
+        context: null,
+      }),
+    )
+    const resolvedAgentId = readOptionalString(agentResolution?.agentId) ?? agentId
     const runtimeConfig = getAgentRuntimeConfig({
-      agentId,
+      agentId: resolvedAgentId,
       workstreamMode: workstream.mode,
       mode: dispatchMode,
       onboardingActive: false,
       linearInstalled: Boolean(linearInstallation),
-      additionalInstructionSections: [
-        buildOwnershipDispatchContextSection({
-          node: params.nodeSpec,
-          resolvedInput: params.resolvedInput,
-          inputArtifacts: params.inputArtifacts,
-          upstreamHandoffs: params.context.upstreamHandoffs,
-        }),
-      ],
+      additionalInstructionSections: mergeInstructionSections(
+        dispatchInstructionSections,
+        readInstructionSections(agentResolution?.additionalInstructionSections),
+      ),
       responseGuardSection: buildOwnershipDispatchResponseGuard({ node: params.nodeSpec, executionMode: mode }),
     }) as Record<string, unknown>
 
     const rawTools = (await buildAgentTools({
-      agentId,
+      agentId: resolvedAgentId,
       orgId: organizationRef,
       userId: userRef,
       userName,
@@ -175,7 +200,7 @@ class AgentExecutorService {
       onboardingActive: false,
       githubInstalled: Boolean(githubInstallation),
       provideRepoTool: indexedRepoContext.provideRepoTool,
-      defaultRepoSections: indexedRepoContext.defaultSectionsByAgent[agentId],
+      defaultRepoSections: indexedRepoContext.defaultSectionsByAgent[resolvedAgentId],
       memoryBlock: '',
       onAppendMemoryBlock: () => undefined,
       availableUploads: [],
@@ -183,9 +208,9 @@ class AgentExecutorService {
     })) as ToolSet
     const tools = applyToolPolicy(rawTools, params.nodeSpec)
 
-    const agentFactory = createAgent[agentId] as ((...args: unknown[]) => unknown) | undefined
+    const agentFactory = createAgent[resolvedAgentId] as ((...args: unknown[]) => unknown) | undefined
     if (!agentFactory) {
-      throw new Error(`Agent factory "${agentId}" is not registered.`)
+      throw new Error(`Agent factory "${resolvedAgentId}" is not registered.`)
     }
 
     const maxSteps = typeof runtimeConfig.maxSteps === 'number' ? runtimeConfig.maxSteps : 8

package/src/services/workstream-turn-preparation.service.ts

@@ -13,7 +13,6 @@ import type { PrepareStepFunction, StopCondition, ToolLoopAgent, ToolSet, UIMess
 
 import type { CoreWorkstreamProfile } from '../config/agent-defaults'
 import {
-  agentDisplayNames,
   agentRoster,
   buildAgentTools,
   createAgent,
@@ -28,6 +27,7 @@ import { recordIdToString } from '../db/record-id'
 import { TABLES } from '../db/tables'
 import { enqueueContextCompaction } from '../queues/context-compaction.queue'
 import { enqueueWorkstreamTitleGeneration } from '../queues/title-generation.queue'
+import { readRuntimeAgentIdentityOverrides, resolveRuntimeAgentDisplayName } from '../runtime/agent-identity-overrides'
 import { OWNERSHIP_DISPATCH_BLOCKED_TOOL_NAMES } from '../runtime/agent-runtime-policy'
 import { createAgentMessageMetadata, createServerRunAbortController } from '../runtime/agent-stream-helpers'
 import { hasApprovalRespondedParts } from '../runtime/approval-continuation'
@@ -260,6 +260,7 @@ async function streamAgentResponse(
   streamParams: StreamAgentResponseParams,
 ): Promise<ChatMessage> {
   const agentTimer = lotaDebugLogger.timer(`agent:${streamParams.agentId}`)
+  const agentIdentityOverrides = readRuntimeAgentIdentityOverrides(ctx.buildContextResult)
   // Skip full plan state during plan turns — the plan-turn sections already have the active node contract
   const executionPlanInstructionSections =
     streamParams.includeExecutionPlanTools === false ? undefined : await ctx.getExecutionPlanInstructionSections()
@@ -383,7 +384,10 @@ async function streamAgentResponse(
     originalMessages: streamParams.messages,
     sendReasoning: true,
     sendSources: true,
-    messageMetadata: createAgentMessageMetadata({ agentId: resolvedAgentId, agentName: config.displayName as string }),
+    messageMetadata: createAgentMessageMetadata({
+      agentId: resolvedAgentId,
+      agentName: resolveRuntimeAgentDisplayName(agentIdentityOverrides, resolvedAgentId),
+    }),
     onFinish: ({ responseMessage: finishedResponseMessage }: { responseMessage: ChatMessage }) => {
       responseMessage = withMessageCreatedAt(finishedResponseMessage, Date.now())
       resolveFinishedStream()
@@ -735,6 +739,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
     originalMessages,
     run: async (writer?: UIMessageStreamWriter<ChatMessage>) => {
       const executeRun = async (leaseAbortSignal?: AbortSignal): Promise<PreparedWorkstreamTurnResult | void> => {
+        const agentIdentityOverrides = readRuntimeAgentIdentityOverrides(buildContextResult)
         const runTimer = lotaDebugLogger.timer('run')
         const serverRunId = Bun.randomUUIDv7()
         const runAbortSignals = leaseAbortSignal ? [params.abortSignal, leaseAbortSignal] : [params.abortSignal]
@@ -828,7 +833,6 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
             filterTools?: (tools: ToolSet) => ToolSet
             includeExecutionPlanTools?: boolean
             metadataPatch?: NonNullable<MessageMetadata>
-            headless?: boolean
           }): Promise<ChatMessage> => {
             const visibleTimer = lotaDebugLogger.timer(`visible:${runParams.agentId}`)
             let runMemoryBlock = memoryBlock
@@ -864,7 +868,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
               skills: runParams.skills,
               additionalInstructionSections: runParams.additionalInstructionSections,
               includeExecutionPlanTools,
-              writer: runParams.headless ? undefined : writer,
+              writer,
             })
 
             visibleTimer.step('stream-agent-response')
@@ -873,7 +877,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
             return commitAssistantResponse(
               responseMessage,
               runParams.agentId,
-              agentDisplayNames[runParams.agentId] ?? runParams.agentId,
+              resolveRuntimeAgentDisplayName(agentIdentityOverrides, runParams.agentId),
               runParams.metadataPatch,
             )
           }
@@ -927,13 +931,13 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                 members,
                 messageText,
                 recentContext,
+                displayNamesById: agentIdentityOverrides.displayNamesById,
+                shortDisplayNamesById: agentIdentityOverrides.shortDisplayNamesById,
+                routingAliasesByAgentId: agentIdentityOverrides.routingAliasesByAgentId,
               })
               throwIfRunAborted()
 
-              const runGroupAgent = async (
-                agentId: string,
-                options?: { routingContext?: string; headless?: boolean },
-              ) => {
+              const runGroupAgent = async (agentId: string, options?: { routingContext?: string }) => {
                 const additionalSections = [...(coreInstructionSections ?? []), ...hookInstructionSections]
                 if (options?.routingContext) {
                   additionalSections.push(`<routing-context>\n${options.routingContext}\n</routing-context>`)
@@ -948,7 +952,6 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                   mode: 'workstreamMode',
                   skills: coreWorkstreamProfile?.skills ? [...coreWorkstreamProfile.skills] : undefined,
                   additionalInstructionSections: additionalSections,
-                  headless: options?.headless,
                 })
               }
 
@@ -965,8 +968,8 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                 respondedAgents.push(triageResult.agentId)
                 throwIfRunAborted()
 
-                // Follow-up specialists run headless, persist their own messages,
-                // and are surfaced by transient events plus cache refresh.
+                // Follow-up specialists stream visibly in order so the user can
+                // watch each specialist reply instead of waiting for a persisted refresh.
                 while (respondedAgents.length < 3) {
                   const lastResponseText = extractMessageText(lastResponse).slice(0, 500)
                   const checkResult = await checkForNextAgent({
@@ -975,6 +978,9 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                     messageText,
                     respondedAgents,
                     lastResponseSummary: lastResponseText,
+                    displayNamesById: agentIdentityOverrides.displayNamesById,
+                    shortDisplayNamesById: agentIdentityOverrides.shortDisplayNamesById,
+                    routingAliasesByAgentId: agentIdentityOverrides.routingAliasesByAgentId,
                   })
                   throwIfRunAborted()
 
@@ -983,7 +989,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                   writeMultiAgentEvent(writer, {
                     phase: 'waiting-for-agent',
                     agentId: checkResult.agentId,
-                    agentName: agentDisplayNames[checkResult.agentId] ?? checkResult.agentId,
+                    agentName: resolveRuntimeAgentDisplayName(agentIdentityOverrides, checkResult.agentId),
                     note: checkResult.routingContext,
                   })
 
@@ -1009,14 +1015,13 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
 
                   lastResponse = await runGroupAgent(checkResult.agentId, {
                     routingContext: checkResult.routingContext,
-                    headless: true,
                   })
                   respondedAgents.push(checkResult.agentId)
                   throwIfRunAborted()
                   writeMultiAgentEvent(writer, {
                     phase: 'agent-message-persisted',
                     agentId: checkResult.agentId,
-                    agentName: agentDisplayNames[checkResult.agentId] ?? checkResult.agentId,
+                    agentName: resolveRuntimeAgentDisplayName(agentIdentityOverrides, checkResult.agentId),
                     messageId: lastResponse.id,
                   })
                 }
@@ -1083,6 +1088,7 @@ export async function prepareWorkstreamRunCore(params: WorkstreamRunCoreParams):
                 defaultLeadAgentId,
                 latestWorkstreamRecord,
                 isUserTurn: params.kind === 'userTurn',
+                agentDisplayNamesById: agentIdentityOverrides.displayNamesById,
               })
             }
 

package/src/system-agents/workstream-router.agent.ts

@@ -3,13 +3,7 @@ import { z } from 'zod'
 
 import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayDirectCacheHeaders } from '../ai-gateway/cache-headers'
-import {
-  agentDescriptions,
-  agentDisplayNames,
-  agentShortDisplayNames,
-  resolveAgentNameAlias,
-  routerModelId,
-} from '../config/agent-defaults'
+import { agentDescriptions, agentDisplayNames, agentShortDisplayNames, routerModelId } from '../config/agent-defaults'
 
 // ---------------------------------------------------------------------------
 // Schemas
@@ -23,6 +17,8 @@ const CheckResultSchema = z.object({
   routingContext: z.string().optional(),
 })
 
+const ROUTER_OUTPUT_PREVIEW_CHARS = 300
+
 export type RouterTriageResult = z.infer<typeof TriageResultSchema>
 export type RouterCheckResult = z.infer<typeof CheckResultSchema>
 
@@ -30,10 +26,45 @@ export type RouterCheckResult = z.infer<typeof CheckResultSchema>
 // Helpers
 // ---------------------------------------------------------------------------
 
-function buildMembersDescription(members: readonly string[]): string {
+interface RouterDisplayOptions {
+  displayNamesById?: Partial<Record<string, string>>
+  shortDisplayNamesById?: Partial<Record<string, string>>
+  routingAliasesByAgentId?: Partial<Record<string, string[]>>
+}
+
+function readStringOverride(record: Partial<Record<string, string>> | undefined, key: string): string | undefined {
+  return record && Object.hasOwn(record, key) ? record[key] : undefined
+}
+
+function readStringArrayOverride(
+  record: Partial<Record<string, string[]>> | undefined,
+  key: string,
+): string[] | undefined {
+  return record && Object.hasOwn(record, key) ? record[key] : undefined
+}
+
+function readDisplayName(agentId: string, options?: RouterDisplayOptions): string {
+  const override = readStringOverride(options?.displayNamesById, agentId)
+  if (override !== undefined) {
+    return override
+  }
+
+  return agentDisplayNames[agentId] ?? agentId
+}
+
+function readShortDisplayName(agentId: string, options?: RouterDisplayOptions): string {
+  const override = readStringOverride(options?.shortDisplayNamesById, agentId)
+  if (override !== undefined) {
+    return override
+  }
+
+  return agentShortDisplayNames[agentId] ?? readDisplayName(agentId, options)
+}
+
+function buildMembersDescription(members: readonly string[], options?: RouterDisplayOptions): string {
   return members
     .map((id) => {
-      const display = agentDisplayNames[id] ?? id
+      const display = readDisplayName(id, options)
       const desc = agentDescriptions[id] ?? ''
       return `- ${display} (id: ${id}): ${desc}`
     })
@@ -44,12 +75,16 @@ function escapeRegex(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
-function buildExplicitAgentRoutingContext(agentId: string): string {
-  const displayName = agentDisplayNames[agentId] ?? agentId
+function buildExplicitAgentRoutingContext(agentId: string, options?: RouterDisplayOptions): string {
+  const displayName = readDisplayName(agentId, options)
   return `Respond directly to the part of the user's request explicitly addressed to ${displayName}.`
 }
 
-function extractExplicitAgentTargets(messageText: string, members: readonly string[]): string[] {
+function extractExplicitAgentTargets(
+  messageText: string,
+  members: readonly string[],
+  options?: RouterDisplayOptions,
+): string[] {
   const normalizedMessage = messageText.trim()
   if (!normalizedMessage) return []
 
@@ -57,7 +92,14 @@ function extractExplicitAgentTargets(messageText: string, members: readonly stri
   const aliases = new Map<string, string>()
 
   for (const member of members) {
-    for (const rawAlias of [member, agentDisplayNames[member], agentShortDisplayNames[member]]) {
+    for (const rawAlias of [
+      member,
+      agentDisplayNames[member],
+      agentShortDisplayNames[member],
+      readDisplayName(member, options),
+      readShortDisplayName(member, options),
+      ...(readStringArrayOverride(options?.routingAliasesByAgentId, member) ?? []),
+    ]) {
       if (typeof rawAlias !== 'string') continue
       const alias = rawAlias.trim().toLowerCase()
       if (!alias) continue
@@ -70,13 +112,13 @@ function extractExplicitAgentTargets(messageText: string, members: readonly stri
   const orderedAliases = [...aliases.keys()].sort((left, right) => right.length - left.length)
   const matches: Array<{ agentId: string; index: number }> = []
   const directAddressRegex = new RegExp(
-    `(^|[^\\w@])(?<alias>${orderedAliases.map(escapeRegex).join('|')})(?=\\s*(?::|\\-|—))`,
+    `(^|[\\s([{>,"'])(?<alias>${orderedAliases.map(escapeRegex).join('|')})(?=\\s*(?::|[—–-](?=\\s)))`,
     'gi',
   )
 
   for (const match of normalizedMessage.matchAll(directAddressRegex)) {
     const alias = match.groups?.alias
-    const agentId = alias ? resolveAgentNameAlias(alias) : undefined
+    const agentId = alias ? aliases.get(alias.trim().toLowerCase()) : undefined
     if (!agentId || !memberSet.has(agentId)) continue
 
     const prefix = match[1]
@@ -125,6 +167,12 @@ function extractResultText(result: { text?: string; reasoning?: unknown }): stri
   return ''
 }
 
+function logRouterRaw(label: 'triage' | 'check', text: string): void {
+  const preview = text.trim().slice(0, ROUTER_OUTPUT_PREVIEW_CHARS)
+  if (!preview) return
+  console.log(`[workstream-router] ${label} raw:`, preview)
+}
+
 // ---------------------------------------------------------------------------
 // Prompts
 // ---------------------------------------------------------------------------
@@ -166,7 +214,7 @@ function createRouterAgent(systemPrompt: string) {
     id: 'workstream-router',
     model: aiGatewayChatModel(modelId),
     headers: buildAiGatewayDirectCacheHeaders('workstream-router'),
-    providerOptions: { openai: { reasoningEffort: 'high' } },
+    providerOptions: { openai: { reasoningEffort: 'low' } },
     instructions: systemPrompt,
     maxOutputTokens: 256,
   })
@@ -177,14 +225,25 @@ export async function triageWorkstreamMessage(params: {
   members: readonly string[]
   messageText: string
   recentContext?: string
+  displayNamesById?: Partial<Record<string, string>>
+  shortDisplayNamesById?: Partial<Record<string, string>>
+  routingAliasesByAgentId?: Partial<Record<string, string[]>>
 }): Promise<RouterTriageResult | null> {
-  const explicitTargets = extractExplicitAgentTargets(params.messageText, params.members)
+  const displayOptions: RouterDisplayOptions = {
+    displayNamesById: params.displayNamesById,
+    shortDisplayNamesById: params.shortDisplayNamesById,
+    routingAliasesByAgentId: params.routingAliasesByAgentId,
+  }
+  const explicitTargets = extractExplicitAgentTargets(params.messageText, params.members, displayOptions)
   const firstExplicitTarget = explicitTargets[0]
   if (firstExplicitTarget) {
-    return { agentId: firstExplicitTarget, routingContext: buildExplicitAgentRoutingContext(firstExplicitTarget) }
+    return {
+      agentId: firstExplicitTarget,
+      routingContext: buildExplicitAgentRoutingContext(firstExplicitTarget, displayOptions),
+    }
   }
 
-  const membersDesc = buildMembersDescription(params.members)
+  const membersDesc = buildMembersDescription(params.members, displayOptions)
   const prompt = [
     `Workstream: "${params.workstreamTitle}"`,
     `Members:\n${membersDesc}`,
@@ -204,8 +263,14 @@ export async function triageWorkstreamMessage(params: {
   }
 
   const effectiveText = extractResultText(result as { text?: string; reasoning?: unknown })
-  console.log('[workstream-router] triage raw:', effectiveText.slice(0, 300))
+  logRouterRaw('triage', effectiveText)
   const json = extractJson(effectiveText)
+  if (json === null) {
+    if (effectiveText.trim()) {
+      console.log('[workstream-router] triage ignored non-json output')
+    }
+    return null
+  }
   const parsed = TriageResultSchema.safeParse(json)
   if (!parsed.success) {
     console.log('[workstream-router] triage parse failed:', JSON.stringify(parsed.error.issues))
@@ -230,22 +295,30 @@ export async function checkForNextAgent(params: {
   messageText: string
   respondedAgents: string[]
   lastResponseSummary: string
+  displayNamesById?: Partial<Record<string, string>>
+  shortDisplayNamesById?: Partial<Record<string, string>>
+  routingAliasesByAgentId?: Partial<Record<string, string[]>>
 }): Promise<RouterCheckResult> {
-  const explicitTargets = extractExplicitAgentTargets(params.messageText, params.members)
+  const displayOptions: RouterDisplayOptions = {
+    displayNamesById: params.displayNamesById,
+    shortDisplayNamesById: params.shortDisplayNamesById,
+    routingAliasesByAgentId: params.routingAliasesByAgentId,
+  }
+  const explicitTargets = extractExplicitAgentTargets(params.messageText, params.members, displayOptions)
   const nextExplicitTarget = explicitTargets.find((agentId) => !params.respondedAgents.includes(agentId))
   if (nextExplicitTarget) {
     return {
       done: false,
       agentId: nextExplicitTarget,
-      routingContext: buildExplicitAgentRoutingContext(nextExplicitTarget),
+      routingContext: buildExplicitAgentRoutingContext(nextExplicitTarget, displayOptions),
     }
   }
 
   const remainingMembers = params.members.filter((id) => !params.respondedAgents.includes(id))
   if (remainingMembers.length === 0) return { done: true }
 
-  const membersDesc = buildMembersDescription(remainingMembers)
-  const respondedList = params.respondedAgents.map((id) => agentDisplayNames[id] ?? id).join(', ')
+  const membersDesc = buildMembersDescription(remainingMembers, displayOptions)
+  const respondedList = params.respondedAgents.map((id) => readDisplayName(id, displayOptions)).join(', ')
 
   const prompt = [
     `Workstream: "${params.workstreamTitle}"`,
@@ -265,8 +338,14 @@ export async function checkForNextAgent(params: {
   }
 
   const effectiveText = extractResultText(result as { text?: string; reasoning?: unknown })
-  console.log('[workstream-router] check raw:', effectiveText.slice(0, 300))
+  logRouterRaw('check', effectiveText)
   const json = extractJson(effectiveText)
+  if (json === null) {
+    if (effectiveText.trim()) {
+      console.log('[workstream-router] check ignored non-json output')
+    }
+    return { done: true }
+  }
   const parsed = CheckResultSchema.safeParse(json)
   if (!parsed.success) {
     console.log('[workstream-router] check parse failed:', JSON.stringify(parsed.error.issues))

package/src/tools/execution-plan.tool.ts

@@ -68,10 +68,16 @@ export function createExecutionPlanTool(params: {
         'create-project': async () => {
           const targetWorkstream = targetWorkstreamId
             ? await resolvedWsService.getWorkstream(targetWorkstreamId)
-            : await resolvedWsService.createWorkstream(params.userId, params.orgId, {
-                title: projectTitle!,
-                mode: 'group',
-              })
+            : await (() => {
+                if (!projectTitle) {
+                  throw new Error('projectTitle is required when action is "create-project".')
+                }
+
+                return resolvedWsService.createWorkstream(params.userId, params.orgId, {
+                  title: projectTitle,
+                  mode: 'group',
+                })
+              })()
 
           if (targetWorkstream.organizationId !== recordIdToString(params.orgId, TABLES.ORGANIZATION)) {
             throw new Error('Target workstream belongs to a different organization.')
@@ -110,19 +116,27 @@ export function createExecutionPlanTool(params: {
         },
 
         replace: async () => {
+          if (!runId || !reason) {
+            throw new Error('runId and reason are required when action is "replace".')
+          }
+
           return await resolvedEpService.replacePlan({
             organizationId: params.orgId,
             workstreamId: params.workstreamId,
             leadAgentId: params.agentId,
-            input: { runId: runId!, reason: reason!, ...draft },
+            input: { runId, reason, ...draft },
           })
         },
 
         resume: async () => {
+          if (!runId) {
+            throw new Error('runId is required when action is "resume".')
+          }
+
           return await resolvedEpService.resumeRun({
             workstreamId: params.workstreamId,
             emittedBy: params.agentId,
-            input: { runId: runId! },
+            input: { runId },
           })
         },
       }

package/src/tools/research-topic.tool.ts

@@ -1,8 +1,8 @@
 import { aiGatewayChatModel } from '../ai-gateway/ai-gateway'
 import { buildAiGatewayStrictSemanticCacheHeaders } from '../ai-gateway/cache-headers'
 import {
-  OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
   OPENROUTER_FAST_REASONING_MODEL_ID,
+  OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
 } from '../config/model-constants'
 import { createDelegatedAgentTool } from '../system-agents/delegated-agent-factory'
 import { RESEARCHER_PROMPT } from '../system-agents/researcher.agent'
@@ -14,7 +14,7 @@ export const researchTopicTool = createDelegatedAgentTool({
   description:
     'Delegate a research task to a dedicated research agent that searches the web, fetches pages, and returns a synthesized markdown report.',
   model: () => aiGatewayChatModel(OPENROUTER_FAST_REASONING_MODEL_ID),
-  providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+  providerOptions: OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
   headers: buildAiGatewayStrictSemanticCacheHeaders('researchTopic'),
   instructions: RESEARCHER_PROMPT,
   tools: { searchWeb: searchWebTool.create(), fetchWebpage: fetchWebpageTool.create() },

package/src/tools/team-think.tool.ts

@@ -7,12 +7,14 @@ import { aiLogger } from '../config/logger'
 import type { RecordIdRef } from '../db/record-id'
 import { recordIdToString } from '../db/record-id'
 import { TABLES } from '../db/tables'
+import { readRuntimeAgentIdentityOverrides } from '../runtime/agent-identity-overrides'
 import { mergeInstructionSections } from '../runtime/instruction-sections'
-import { getRuntimeAdapters } from '../runtime/runtime-extensions'
+import { getRuntimeAdapters, getTurnHooks } from '../runtime/runtime-extensions'
 import type { LotaRuntimeTeamThinkToolsParams } from '../runtime/runtime-extensions'
 import { createConsultTeamTool as createConsultTeamToolSdk } from '../runtime/team-consultation-orchestrator'
 import type { DefaultRepoSections, TeamConsultationParticipantRunner } from '../runtime/team-consultation-orchestrator'
 import { buildTeamConsultationResponseGuard } from '../runtime/team-consultation-prompts'
+import { asRecord, readInstructionSections, readOptionalString } from '../runtime/workstream-chat-helpers'
 import type { ReadableUploadMetadata } from '../services/attachment.service'
 
 async function buildTeamThinkAgentTools(
@@ -49,11 +51,33 @@ export function createTeamThinkTool(params: {
   toolProviders?: ToolSet
   abortSignal: AbortSignal
 }) {
+  const agentIdentityOverrides = readRuntimeAgentIdentityOverrides(
+    (params.context as Record<string, unknown> | null | undefined) ?? null,
+  )
   const participantRunner: TeamConsultationParticipantRunner = {
     async buildParticipantAgent(agentId, runParams) {
       const dynamicInstructionSections = await params.getAdditionalInstructionSections?.()
+      const agentResolution = asRecord(
+        await getTurnHooks().resolveAgent?.({
+          agentId,
+          mode: 'fixedWorkstreamMode',
+          workstream: null,
+          workstreamRef: params.workstreamId,
+          orgRef: params.orgId,
+          userRef: params.userId,
+          onboardingActive: false,
+          linearInstalled: false,
+          githubInstalled: params.githubInstalled,
+          additionalInstructionSections: mergeInstructionSections(
+            dynamicInstructionSections,
+            params.additionalInstructionSections,
+          ),
+          context: (params.context as Record<string, unknown> | null | undefined) ?? null,
+        }),
+      )
+      const resolvedAgentId = readOptionalString(agentResolution?.agentId) ?? agentId
       const config = getAgentRuntimeConfig({
-        agentId,
+        agentId: resolvedAgentId,
         workstreamMode: 'group' as const,
         mode: 'fixedWorkstreamMode',
         onboardingActive: false,
@@ -64,24 +88,25 @@ export function createTeamThinkTool(params: {
         additionalInstructionSections: mergeInstructionSections(
           dynamicInstructionSections,
           params.additionalInstructionSections,
+          readInstructionSections(agentResolution?.additionalInstructionSections),
         ),
-        responseGuardSection: buildTeamConsultationResponseGuard({ agentId, task: runParams.task }),
+        responseGuardSection: buildTeamConsultationResponseGuard({ agentId: resolvedAgentId, task: runParams.task }),
       })
       const { tools } = await buildTeamThinkAgentTools({
-        agentId,
+        agentId: resolvedAgentId,
         workspaceId: params.orgId,
         userId: params.userId,
         workspaceIdString: recordIdToString(params.orgId, TABLES.ORGANIZATION),
         workstreamId: params.workstreamId,
         githubInstalled: params.githubInstalled,
-        provideRepoTool: agentId !== 'mentor' && params.provideRepoTool,
+        provideRepoTool: resolvedAgentId !== 'mentor' && params.provideRepoTool,
         availableUploads: params.availableUploads,
-        defaultRepoSections: params.defaultRepoSectionsByAgent[agentId],
+        defaultRepoSections: params.defaultRepoSectionsByAgent[resolvedAgentId],
         context: params.context,
         toolProviders: params.toolProviders,
       })
       const agentConfig = config as Record<string, unknown>
-      const agentId_ = typeof agentConfig.id === 'string' ? agentConfig.id : agentId
+      const agentId_ = typeof agentConfig.id === 'string' ? agentConfig.id : resolvedAgentId
       const configuredMaxSteps = typeof agentConfig.maxSteps === 'number' ? agentConfig.maxSteps : 10
       const maxSteps = Math.min(configuredMaxSteps, TEAM_THINK_AGENT_MAX_STEPS)
       const agent = createAgent[agentId_]({
@@ -117,6 +142,7 @@ export function createTeamThinkTool(params: {
     systemWorkspaceDetails: params.systemWorkspaceDetails,
     getPreSeededMemoriesSection: params.getPreSeededMemoriesSection,
     retrievedKnowledgeSection: params.retrievedKnowledgeSection,
+    displayNamesById: agentIdentityOverrides.displayNamesById,
     abortSignal: params.abortSignal,
     participantRunner,
     onReadError: (agentId, error) => {