@vibe-forge/workspace-assets 2.0.0 → 2.0.2

package/src/skill-dependencies.ts

@@ -0,0 +1,361 @@
+/* eslint-disable max-lines -- dependency normalization and graph expansion share the same local helpers */
+import { readFile } from 'node:fs/promises'
+
+import fm from 'front-matter'
+
+import { parseScopedReference, resolveSkillIdentifier } from '@vibe-forge/definition-core'
+import type { Config, Definition, Skill, WorkspaceAsset } from '@vibe-forge/types'
+import { resolveRelativePath } from '@vibe-forge/utils'
+
+import { HOME_BRIDGE_RESOLVED_BY } from './home-bridge'
+import { installRegistrySkillDependency } from './skill-registry'
+
+type SkillAsset = Extract<WorkspaceAsset, { kind: 'skill' }>
+
+export interface NormalizedSkillDependency {
+  ref: string
+  name: string
+  source?: string
+  registry?: string
+}
+
+interface DependencyExpansionParams {
+  allAssets: WorkspaceAsset[]
+  configs: [Config?, Config?]
+  cwd: string
+  excludedIds?: Set<string>
+  selectedAssets: SkillAsset[]
+  skillAssets: SkillAsset[]
+}
+
+const asNonEmptyString = (value: unknown) => (
+  typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+)
+
+const toSkillSlug = (value: string) => (
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+)
+
+const resolveUniqueSkillByName = (assets: SkillAsset[], name: string) => {
+  const nameSlug = toSkillSlug(name)
+  const matches = assets.filter(asset => asset.name === name || toSkillSlug(asset.name) === nameSlug)
+  if (matches.length === 0) return undefined
+
+  const unscopedMatches = matches.filter(asset => asset.scope == null)
+  if (unscopedMatches.length === 1) return unscopedMatches[0]
+
+  if (matches.length > 1) {
+    throw new Error(
+      `Ambiguous skill dependency ${name}. Candidates: ${matches.map(match => match.displayName).join(', ')}`
+    )
+  }
+
+  return matches[0]
+}
+
+const filterSearchableSkillAssets = (
+  assets: SkillAsset[],
+  options?: {
+    includeHomeBridge?: boolean
+  }
+) => (
+  options?.includeHomeBridge === false
+    ? assets.filter(asset => asset.resolvedBy !== HOME_BRIDGE_RESOLVED_BY)
+    : assets
+)
+
+const removeHomeBridgeSkillDuplicates = (
+  assets: WorkspaceAsset[],
+  displayName: string
+) => {
+  for (let index = assets.length - 1; index >= 0; index--) {
+    const asset = assets[index]
+    if (asset.kind !== 'skill') continue
+    if (asset.resolvedBy !== HOME_BRIDGE_RESOLVED_BY) continue
+    if (asset.displayName !== displayName) continue
+    assets.splice(index, 1)
+  }
+}
+
+const findSkillAssetByRef = (
+  assets: SkillAsset[],
+  ref: string,
+  currentInstancePath?: string,
+  options?: {
+    includeHomeBridge?: boolean
+  }
+) => {
+  const searchableAssets = filterSearchableSkillAssets(assets, options)
+  const scoped = parseScopedReference(ref, { pathSuffixes: ['.md', '.json', '.yaml', '.yml'] })
+  if (scoped != null) {
+    return searchableAssets.find(asset => asset.scope === scoped.scope && asset.name === scoped.name)
+  }
+
+  if (currentInstancePath != null) {
+    const local = searchableAssets.find(asset => asset.instancePath === currentInstancePath && asset.name === ref)
+    if (local != null) return local
+  }
+
+  return resolveUniqueSkillByName(searchableAssets, ref)
+}
+
+const resolveDisplayName = (name: string, scope?: string) => (
+  scope != null && scope.trim() !== '' ? `${scope}/${name}` : name
+)
+
+const parseFrontmatterSkill = async (path: string): Promise<Definition<Skill>> => {
+  const content = await readFile(path, 'utf-8')
+  const { body, attributes } = fm<Skill>(content)
+  return {
+    path,
+    body,
+    attributes
+  }
+}
+
+const createRegistrySkillAsset = (params: {
+  cwd: string
+  definition: Definition<Skill>
+}) => {
+  const name = resolveSkillIdentifier(params.definition.path, params.definition.attributes.name)
+  const displayName = resolveDisplayName(name)
+  return {
+    id: `skill:workspace:workspace:${displayName}:${resolveRelativePath(params.cwd, params.definition.path)}`,
+    kind: 'skill',
+    name,
+    displayName,
+    origin: 'workspace',
+    sourcePath: params.definition.path,
+    payload: {
+      definition: params.definition
+    }
+  } satisfies SkillAsset
+}
+
+const parseStringDependency = (value: string): NormalizedSkillDependency => {
+  const ref = value.trim()
+  const atIndex = ref.lastIndexOf('@')
+  if (atIndex > 0 && atIndex < ref.length - 1) {
+    return {
+      ref,
+      source: ref.slice(0, atIndex),
+      name: ref.slice(atIndex + 1)
+    }
+  }
+
+  const sourcePathMatch = ref.match(/^([^/\s]+\/[^/\s]+)\/([^/\s]+)$/)
+  if (sourcePathMatch != null) {
+    return {
+      ref,
+      source: sourcePathMatch[1],
+      name: sourcePathMatch[2]
+    }
+  }
+
+  return {
+    ref,
+    name: ref
+  }
+}
+
+export const normalizeSkillDependency = (value: unknown): NormalizedSkillDependency | undefined => {
+  const stringValue = asNonEmptyString(value)
+  if (stringValue != null) return parseStringDependency(stringValue)
+
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const record = value as Record<string, unknown>
+  const name = asNonEmptyString(record.name)
+  if (name == null) return undefined
+
+  const source = asNonEmptyString(record.source)
+  return {
+    ref: source == null ? name : `${source}@${name}`,
+    name,
+    ...(source == null ? {} : { source }),
+    ...(asNonEmptyString(record.registry) == null ? {} : { registry: asNonEmptyString(record.registry) })
+  }
+}
+
+export const normalizeSkillDependencies = (value: Skill['dependencies'] | undefined) => (
+  Array.isArray(value)
+    ? value
+      .map(normalizeSkillDependency)
+      .filter((dependency): dependency is NormalizedSkillDependency => dependency != null)
+    : []
+)
+
+export const findSkillDependencyAsset = (
+  assets: SkillAsset[],
+  dependency: NormalizedSkillDependency,
+  currentInstancePath?: string,
+  options?: {
+    includeHomeBridge?: boolean
+  }
+) => {
+  const candidateRefs = Array.from(
+    new Set([
+      dependency.ref,
+      dependency.name
+    ])
+  )
+
+  for (const ref of candidateRefs) {
+    const asset = findSkillAssetByRef(assets, ref, currentInstancePath, options)
+    if (asset != null) return asset
+  }
+
+  return undefined
+}
+
+export const expandSkillAssetDependencies = (
+  assets: SkillAsset[],
+  selectedAssets: SkillAsset[],
+  options: {
+    excludedIds?: Set<string>
+  } = {}
+) => {
+  const selected: SkillAsset[] = []
+  const seen = new Set<string>()
+
+  const addAsset = (asset: SkillAsset) => {
+    if (options.excludedIds?.has(asset.id)) return
+    if (seen.has(asset.id)) return
+    seen.add(asset.id)
+    selected.push(asset)
+
+    for (const dependency of normalizeSkillDependencies(asset.payload.definition.attributes.dependencies)) {
+      const dependencyAsset = findSkillDependencyAsset(assets, dependency, asset.instancePath)
+      if (dependencyAsset == null) {
+        throw new Error(`Failed to resolve skill dependency ${dependency.ref} declared by ${asset.displayName}`)
+      }
+      addAsset(dependencyAsset)
+    }
+  }
+
+  selectedAssets.forEach(addAsset)
+  return selected
+}
+
+export const expandSkillAssetDependenciesWithRegistry = async (
+  params: DependencyExpansionParams
+) => {
+  const selected: SkillAsset[] = []
+  const seen = new Set<string>()
+  const fetchedDependencyRefs = new Set<string>()
+
+  const removeSupersededHomeBridgeSkill = (displayName: string) => {
+    removeHomeBridgeSkillDuplicates(params.allAssets, displayName)
+    removeHomeBridgeSkillDuplicates(params.skillAssets, displayName)
+    removeHomeBridgeSkillDuplicates(params.selectedAssets, displayName)
+    removeHomeBridgeSkillDuplicates(selected, displayName)
+  }
+
+  const installDependencyAsset = async (
+    dependency: NormalizedSkillDependency,
+    currentInstancePath?: string
+  ) => {
+    const fetchKey = `${dependency.registry ?? ''}:${dependency.ref}`
+    if (!fetchedDependencyRefs.has(fetchKey)) {
+      fetchedDependencyRefs.add(fetchKey)
+      const installed = await installRegistrySkillDependency({
+        cwd: params.cwd,
+        configs: params.configs,
+        dependency
+      })
+      const definition = await parseFrontmatterSkill(installed.skillPath)
+      const dependencyAsset = createRegistrySkillAsset({
+        cwd: params.cwd,
+        definition
+      })
+      const existingAsset = findSkillDependencyAsset(
+        params.skillAssets,
+        dependency,
+        currentInstancePath,
+        { includeHomeBridge: false }
+      ) ??
+        params.skillAssets.find(existing => (
+          existing.resolvedBy !== HOME_BRIDGE_RESOLVED_BY &&
+          existing.displayName === dependencyAsset.displayName
+        ))
+      if (existingAsset != null) {
+        removeSupersededHomeBridgeSkill(existingAsset.displayName)
+        return existingAsset
+      }
+
+      removeSupersededHomeBridgeSkill(dependencyAsset.displayName)
+      params.allAssets.push(dependencyAsset)
+      params.skillAssets.push(dependencyAsset)
+      return dependencyAsset
+    }
+
+    // After the first fetch attempt, reuse whichever asset is now visible in the
+    // skill set: a newly installed registry skill, or a home-bridge fallback
+    // that was accepted by an earlier plain-name dependency resolution.
+    const resolvedAsset = findSkillDependencyAsset(params.skillAssets, dependency, currentInstancePath)
+    if (resolvedAsset != null && resolvedAsset.resolvedBy !== HOME_BRIDGE_RESOLVED_BY) {
+      removeSupersededHomeBridgeSkill(resolvedAsset.displayName)
+    }
+    return resolvedAsset
+  }
+
+  const addAsset = async (asset: SkillAsset): Promise<void> => {
+    if (params.excludedIds?.has(asset.id)) return
+    if (seen.has(asset.id)) return
+    seen.add(asset.id)
+    selected.push(asset)
+
+    for (const dependency of normalizeSkillDependencies(asset.payload.definition.attributes.dependencies)) {
+      const localOrBridgedDependency = findSkillDependencyAsset(
+        params.skillAssets,
+        dependency,
+        asset.instancePath
+      )
+      const directDependency = findSkillDependencyAsset(
+        params.skillAssets,
+        dependency,
+        asset.instancePath,
+        { includeHomeBridge: false }
+      )
+
+      if (directDependency != null) {
+        await addAsset(directDependency)
+        continue
+      }
+
+      // Keep registry-backed dependencies ahead of home-bridge skills. We only
+      // fall back to a bridged home skill for plain-name dependencies when the
+      // registry path is unavailable.
+      const dependencyAsset = await installDependencyAsset(dependency, asset.instancePath).catch((error: unknown) => {
+        if (
+          localOrBridgedDependency != null &&
+          dependency.source == null &&
+          dependency.registry == null
+        ) {
+          return localOrBridgedDependency
+        }
+        throw error
+      }) ?? (
+        dependency.source == null && dependency.registry == null
+          ? localOrBridgedDependency
+          : undefined
+      )
+
+      if (dependencyAsset == null) {
+        throw new Error(`Failed to resolve skill dependency ${dependency.ref} declared by ${asset.displayName}`)
+      }
+      await addAsset(dependencyAsset)
+    }
+  }
+
+  for (const asset of params.selectedAssets) {
+    await addAsset(asset)
+  }
+
+  return selected
+}

package/src/skill-registry.ts

@@ -0,0 +1,329 @@
+/* eslint-disable max-lines -- registry install logic keeps URL resolution, locking, and cache writes together */
+import { access, mkdir, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+import process from 'node:process'
+import { setTimeout as delay } from 'node:timers/promises'
+
+import type { Config } from '@vibe-forge/types'
+import { resolveProjectSharedCachePath } from '@vibe-forge/utils/project-cache-path'
+
+import type { NormalizedSkillDependency } from './skill-dependencies'
+
+interface RegistryOptions {
+  enabled: boolean
+  searchBaseUrl: string
+  downloadBaseUrl: string
+}
+
+interface RegistrySearchSkill {
+  id?: string
+  name?: string
+  skillId?: string
+  source?: string
+}
+
+interface RegistryDownloadFile {
+  path?: string
+  contents?: string
+}
+
+interface RegistryDownloadResponse {
+  files?: RegistryDownloadFile[]
+}
+
+const DEFAULT_SKILL_REGISTRY_URL = 'https://skills.sh'
+const FETCH_TIMEOUT_MS = 10_000
+const INSTALL_LOCK_TIMEOUT_MS = 30_000
+const INSTALL_LOCK_RETRY_MS = 100
+
+const asNonEmptyString = (value: unknown) => (
+  typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+)
+
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '')
+
+const toSkillSlug = (value: string) => (
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+)
+
+const toCacheSegment = (value: string) => (
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'registry'
+)
+
+const resolveConfiguredRegistry = (
+  projectConfig: Config | undefined,
+  userConfig: Config | undefined
+) => userConfig?.skills?.registry ?? projectConfig?.skills?.registry
+
+const resolveRegistryOptions = (params: {
+  configs: [Config?, Config?]
+  registry?: string
+}): RegistryOptions => {
+  const [projectConfig, userConfig] = params.configs
+  const configuredRegistry = params.registry ?? resolveConfiguredRegistry(projectConfig, userConfig)
+  const envSearchBaseUrl = asNonEmptyString(process.env.SKILLS_API_URL)
+  const envDownloadBaseUrl = asNonEmptyString(process.env.SKILLS_DOWNLOAD_URL)
+
+  if (typeof configuredRegistry === 'string' && configuredRegistry.trim() !== '') {
+    const baseUrl = normalizeBaseUrl(configuredRegistry.trim())
+    return {
+      enabled: true,
+      searchBaseUrl: baseUrl,
+      downloadBaseUrl: baseUrl
+    }
+  }
+
+  if (configuredRegistry != null && typeof configuredRegistry === 'object') {
+    const baseUrl = normalizeBaseUrl(
+      asNonEmptyString(configuredRegistry.url) ?? DEFAULT_SKILL_REGISTRY_URL
+    )
+    return {
+      enabled: configuredRegistry.enabled !== false,
+      searchBaseUrl: normalizeBaseUrl(asNonEmptyString(configuredRegistry.searchUrl) ?? baseUrl),
+      downloadBaseUrl: normalizeBaseUrl(asNonEmptyString(configuredRegistry.downloadUrl) ?? baseUrl)
+    }
+  }
+
+  const baseUrl = normalizeBaseUrl(envSearchBaseUrl ?? DEFAULT_SKILL_REGISTRY_URL)
+  return {
+    enabled: true,
+    searchBaseUrl: baseUrl,
+    downloadBaseUrl: normalizeBaseUrl(envDownloadBaseUrl ?? baseUrl)
+  }
+}
+
+const fetchJson = async <T>(url: string): Promise<T> => {
+  const response = await fetch(url, {
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+  })
+  if (!response.ok) {
+    throw new Error(`Request failed with status ${response.status}`)
+  }
+  return await response.json() as T
+}
+
+const parseSourceAndSlugFromId = (id: string | undefined) => {
+  if (id == null) return undefined
+  const segments = id.split('/').filter(Boolean)
+  if (segments.length < 3) return undefined
+  return {
+    source: `${segments[0]}/${segments[1]}`,
+    slug: segments.slice(2).join('/')
+  }
+}
+
+const pickSearchResult = (
+  skills: RegistrySearchSkill[],
+  name: string
+) => {
+  const slug = toSkillSlug(name)
+  return skills.find(skill => (
+    skill.skillId === slug ||
+    skill.name === name ||
+    toSkillSlug(skill.name ?? '') === slug ||
+    parseSourceAndSlugFromId(skill.id)?.slug === slug
+  )) ?? skills[0]
+}
+
+const resolveRegistrySkillTarget = async (
+  dependency: NormalizedSkillDependency,
+  registry: RegistryOptions
+) => {
+  if (dependency.source != null) {
+    return {
+      source: dependency.source,
+      slug: toSkillSlug(dependency.name)
+    }
+  }
+
+  const searchUrl = `${registry.searchBaseUrl}/api/search?q=${encodeURIComponent(dependency.name)}&limit=10`
+  const searchResult = await fetchJson<{
+    skills?: RegistrySearchSkill[]
+  }>(searchUrl)
+  const skills = Array.isArray(searchResult.skills) ? searchResult.skills : []
+  const picked = pickSearchResult(skills, dependency.name)
+  if (picked == null) {
+    throw new Error(`Skill ${dependency.name} was not found in ${registry.searchBaseUrl}`)
+  }
+
+  const parsed = parseSourceAndSlugFromId(picked.id)
+  const source = asNonEmptyString(picked.source) ?? parsed?.source
+  const slug = asNonEmptyString(picked.skillId) ?? parsed?.slug ?? toSkillSlug(picked.name ?? dependency.name)
+  if (source == null || slug === '') {
+    throw new Error(`Registry search result for ${dependency.name} did not include a source and skill id`)
+  }
+
+  return {
+    source,
+    slug
+  }
+}
+
+const toSafeRelativePath = (filePath: string) => {
+  const normalized = filePath.replace(/\\/g, '/')
+  if (normalized.startsWith('/') || normalized.split('/').includes('..')) {
+    throw new Error(`Unsafe skill dependency file path ${filePath}`)
+  }
+  return normalized
+}
+
+const assertInside = (root: string, target: string) => {
+  const relativePath = relative(root, target)
+  if (
+    relativePath === '' ||
+    (
+      relativePath !== '..' &&
+      !relativePath.startsWith(`..${sep}`) &&
+      !isAbsolute(relativePath)
+    )
+  ) {
+    return
+  }
+  throw new Error(`Skill dependency file resolves outside ${root}`)
+}
+
+const pathExists = async (path: string) => {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const withInstallLock = async <T>(lockDir: string, callback: () => Promise<T>) => {
+  const start = Date.now()
+  await mkdir(dirname(lockDir), { recursive: true })
+
+  while (true) {
+    try {
+      await mkdir(lockDir)
+      break
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+      if (Date.now() - start > INSTALL_LOCK_TIMEOUT_MS) {
+        throw new Error(`Timed out waiting for skill dependency install lock ${lockDir}`)
+      }
+      await delay(INSTALL_LOCK_RETRY_MS)
+    }
+  }
+
+  try {
+    return await callback()
+  } finally {
+    await rm(lockDir, { recursive: true, force: true })
+  }
+}
+
+const buildInstallDir = (params: {
+  cwd: string
+  registry: RegistryOptions
+  source: string
+  slug: string
+}) => {
+  let registryKey = params.registry.downloadBaseUrl
+  try {
+    const parsed = new URL(params.registry.downloadBaseUrl)
+    registryKey = `${parsed.hostname}${parsed.pathname}`
+  } catch {
+  }
+
+  return resolveProjectSharedCachePath(
+    params.cwd,
+    process.env,
+    'skill-dependencies',
+    toCacheSegment(registryKey),
+    ...params.source.split('/').map(toCacheSegment),
+    toCacheSegment(params.slug)
+  )
+}
+
+export const installRegistrySkillDependency = async (params: {
+  cwd: string
+  configs: [Config?, Config?]
+  dependency: NormalizedSkillDependency
+}) => {
+  const registry = resolveRegistryOptions({
+    configs: params.configs,
+    registry: params.dependency.registry
+  })
+  if (!registry.enabled) {
+    throw new Error(`Skill dependency registry is disabled; cannot install ${params.dependency.ref}`)
+  }
+
+  const target = await resolveRegistrySkillTarget(params.dependency, registry)
+  const [owner, repo] = target.source.split('/')
+  if (owner == null || repo == null || owner === '' || repo === '') {
+    throw new Error(`Skill dependency source ${target.source} must use owner/repo format`)
+  }
+
+  const downloadUrl = `${registry.downloadBaseUrl}/api/download/${encodeURIComponent(owner)}/${
+    encodeURIComponent(repo)
+  }/${encodeURIComponent(target.slug)}`
+  const installDir = buildInstallDir({
+    cwd: params.cwd,
+    registry,
+    source: target.source,
+    slug: target.slug
+  })
+  const skillPath = resolve(installDir, 'SKILL.md')
+
+  return await withInstallLock(`${installDir}.lock`, async () => {
+    if (await pathExists(skillPath)) {
+      return {
+        installDir,
+        skillPath
+      }
+    }
+
+    const response = await fetchJson<RegistryDownloadResponse>(downloadUrl)
+    const files = Array.isArray(response.files) ? response.files : []
+    if (files.length === 0) {
+      throw new Error(`Skill dependency ${params.dependency.ref} did not include any files`)
+    }
+
+    const tempDir = `${installDir}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    await rm(tempDir, { recursive: true, force: true })
+    await mkdir(tempDir, { recursive: true })
+
+    try {
+      let hasSkillMd = false
+      for (const file of files) {
+        const filePath = asNonEmptyString(file.path)
+        if (filePath == null || typeof file.contents !== 'string') continue
+        const relativePath = toSafeRelativePath(filePath)
+        if (relativePath.toLowerCase() === 'skill.md') hasSkillMd = true
+
+        const targetPath = resolve(tempDir, relativePath)
+        assertInside(tempDir, targetPath)
+        await mkdir(dirname(targetPath), { recursive: true })
+        await writeFile(targetPath, file.contents, 'utf8')
+      }
+
+      if (!hasSkillMd) {
+        throw new Error(`Skill dependency ${params.dependency.ref} did not include SKILL.md`)
+      }
+
+      await rm(installDir, { recursive: true, force: true })
+      await rename(tempDir, installDir)
+    } catch (error) {
+      await rm(tempDir, { recursive: true, force: true })
+      throw error
+    }
+
+    return {
+      installDir,
+      skillPath
+    }
+  })
+}

package/src/task-tool-guidance.ts

@@ -0,0 +1,15 @@
+export const buildManagedTaskToolGuidance = (serverName: string) => {
+  return [
+    'Task tool guide:',
+    `- Use \`${serverName}.StartTasks\` to start a new child task when the work should run in a separate entity or workspace, or when it needs to continue independently from the current turn.`,
+    `- After starting a task, use \`${serverName}.GetTaskInfo\` with \`{ taskId }\` to inspect one task. It is also the right tool when a task seems stalled, failed, or might be waiting for input.`,
+    '- By default, `GetTaskInfo` returns the 10 most recent log entries in descending order, so newer entries appear earlier in the `logs` array. Pass `logLimit` to inspect a different number of recent logs, and set `logOrder` to `"asc"` when you want the selected log window in oldest-to-newest order.',
+    `- Use \`${serverName}.ListTasks\` with the same \`logLimit\` and \`logOrder\` fields when you need to find a taskId or inspect multiple tasks at once.`,
+    `- Use \`${serverName}.SendTaskMessage\` with \`{ taskId, message, mode }\` when you want to continue the same task without starting a replacement task.`,
+    '- Choose `mode: "direct"` when the task is `running` and the new instruction should be delivered immediately into the current task.',
+    '- Choose `mode: "steer"` when the task should finish its current run naturally first, and the follow-up should be queued for the same task afterward.',
+    `- Use \`${serverName}.SubmitTaskInput\` only when \`${serverName}.GetTaskInfo\` or \`${serverName}.ListTasks\` shows \`pendingInput\` or \`pendingInteraction\`, or the task status is \`waiting_input\`. Do not use it for ordinary follow-up instructions or queued steer turns.`,
+    '- If a task is `completed` or `failed`, start a new task instead of trying to continue the old one.',
+    '- When a task is still making progress, use `wait` between checks instead of repeatedly restarting it.'
+  ].join('\n')
+}