@vibe-forge/workspace-assets 3.2.0 → 3.2.2-alpha.0

package/src/skill-dependencies.ts

@@ -1,14 +1,9 @@
 /* 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 { formatSkillsSpec, parseSkillsSpec, resolveRelativePath } from '@vibe-forge/utils'
+import { parseScopedReference } from '@vibe-forge/definition-core'
+import type { Config, Skill, WorkspaceAsset } from '@vibe-forge/types'
+import { formatSkillsSpec, parseSkillsSpec } from '@vibe-forge/utils'
 
 import { HOME_BRIDGE_RESOLVED_BY } from './home-bridge'
-import { installSkillsCliDependency } from './skills-cli-dependency'
 
 type SkillAsset = Extract<WorkspaceAsset, { kind: 'skill' }>
 
@@ -106,39 +101,6 @@ const findSkillAssetByRef = (
   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 createResolvedSkillAsset = (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
-}
-
 export const normalizeSkillDependency = (value: unknown): NormalizedSkillDependency | undefined => {
   const stringValue = asNonEmptyString(value)
   if (stringValue != null) return parseSkillsSpec(stringValue)
@@ -230,8 +192,6 @@ export const expandSkillAssetDependenciesWithRemoteResolution = async (
 ) => {
   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)
@@ -239,54 +199,6 @@ export const expandSkillAssetDependenciesWithRemoteResolution = async (
     removeHomeBridgeSkillDuplicates(selected, displayName)
   }
 
-  const installDependencyAsset = async (
-    dependency: NormalizedSkillDependency,
-    currentInstancePath?: string
-  ) => {
-    const fetchKey = dependency.ref
-    if (!fetchedDependencyRefs.has(fetchKey)) {
-      fetchedDependencyRefs.add(fetchKey)
-      const installed = await installSkillsCliDependency({
-        cwd: params.cwd,
-        configs: params.configs,
-        dependency
-      })
-      const definition = await parseFrontmatterSkill(installed.skillPath)
-      const dependencyAsset = createResolvedSkillAsset({
-        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
@@ -311,25 +223,15 @@ export const expandSkillAssetDependenciesWithRemoteResolution = async (
         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
-        ) {
-          return localOrBridgedDependency
-        }
-        throw error
-      }) ?? (
-        dependency.source == null
-          ? localOrBridgedDependency
-          : undefined
-      )
+      const dependencyAsset = dependency.source == null
+        ? localOrBridgedDependency
+        : undefined
 
       if (dependencyAsset == null) {
-        throw new Error(`Failed to resolve skill dependency ${dependency.ref} declared by ${asset.displayName}`)
+        throw new Error(
+          `Skill dependency ${dependency.ref} declared by ${asset.displayName} is missing. ` +
+            'Run vf skills install or vf skills update to materialize project skill dependencies.'
+        )
       }
       await addAsset(dependencyAsset)
     }

package/src/task-tool-guidance.ts

@@ -1,19 +1,32 @@
+import process from 'node:process'
+
+export const resolveRuntimeProtocolCliCommand = (env: NodeJS.ProcessEnv = process.env) => {
+  const prefix = env.__VF_CLI_RESUME_COMMAND_PREFIX__?.trim()
+  if (prefix == null || prefix === '') {
+    return 'vf run'
+  }
+  return prefix.split(/\s+/).at(-1) === 'run' ? prefix : `${prefix} run`
+}
+
 export const buildManagedTaskToolGuidance = () => {
+  const runtimeCliCommand = resolveRuntimeProtocolCliCommand()
+  const runtimeProtocolCommand = `${runtimeCliCommand} --input-format stream-json --output-format stream-json`
+
   return [
     'Agent runtime guide:',
-    '- Use unified CLI protocol mode, `vf run --input-format stream-json --output-format stream-json`, to start a child runtime session when the work should run in a separate entity or continue independently from the current turn.',
-    '- Send typed runtime protocol envelopes such as `session.start`, `session.message`, `session.status`, `session.events`, `session.submit`, and `session.stop`; do not treat dedicated `vf agent ...` subcommands as the standard integration surface.',
+    `- Use unified CLI protocol mode, \`${runtimeProtocolCommand}\`, to start a child runtime session when the work should run in a separate entity or continue independently from the current turn.`,
+    '- Send typed runtime protocol envelopes such as `session.start`, `session.message`, `session.status`, `session.events`, `session.submit`, and `session.stop`; do not treat dedicated agent subcommands as the standard integration surface.',
     '- Ordinary new sessions stay session-scoped. A room is created or discovered only when a unified CLI runtime protocol start command launches a child runtime session from a server-managed host session and the server projects runtime store metadata/events.',
-    '- Do not use MCP task tools, `vf agent ...`, legacy StartTasks, hand-written DB edits, or ad-hoc TS scripts as the task consumer surface. Use CLI protocol mode and the runtime protocol/store for start, status, events, follow-up messages, input submission, and cancellation.',
+    '- Do not use MCP task tools, dedicated agent subcommands, legacy StartTasks, hand-written DB edits, or ad-hoc TS scripts as the task consumer surface. Use CLI protocol mode and the runtime protocol/store for start, status, events, follow-up messages, input submission, and cancellation.',
     '- Server-managed host sessions inject the current adapter, model, effort, and permission mode as runtime protocol defaults. Omit these fields to inherit the host selection, or set them explicitly only when a child task must use a different runtime profile.',
     '- Copyable JSONL example; write one `session.start` line per child task, and use multiple lines for multiple subtasks:',
     '```bash',
-    "cat <<'JSONL' | vf run --input-format stream-json --output-format stream-json",
+    `cat <<'JSONL' | ${runtimeProtocolCommand}`,
     '{"commandId":"start-planner","type":"session.start","payload":{"title":"Plan Agent Room UI fix","message":"Plan the frontend changes and tests for the Agent Room UI fix.","entity":"dev-planner","background":true},"title":"Plan Agent Room UI fix","message":"Plan the frontend changes and tests for the Agent Room UI fix.","entity":"dev-planner","background":true}',
     '{"commandId":"start-reviewer","type":"session.start","payload":{"title":"Review Agent Room UI fix","message":"Review the implemented Agent Room UI fix for regressions and missing tests.","entity":"dev-reviewer","background":true},"title":"Review Agent Room UI fix","message":"Review the implemented Agent Room UI fix for regressions and missing tests.","entity":"dev-reviewer","background":true}',
     'JSONL',
     '```',
-    '- Keep `payload.title`, `payload.message`, `payload.entity`, and `payload.background: true` explicit in each start envelope. The mirrored top-level fields make the JSONL executable by the current `vf run` protocol reader.',
+    '- Keep `payload.title`, `payload.message`, `payload.entity`, and `payload.background: true` explicit in each start envelope. The mirrored top-level fields make the JSONL executable by the current runtime protocol reader.',
     '- Include a short `title` when the task prompt is long; it becomes the child session title and room run label. Put any room or workspace context in the title and initial message.',
     '- Read the returned `sessionId` and use it for follow-up protocol commands. Read the latest runtime snapshot from the runtime store or a `session.status` protocol command, and read progress from runtime events or a `session.events` protocol command.',
     '- Use a follow/read-events workflow when you need to watch progress instead of repeatedly restarting work.',
@@ -21,7 +34,7 @@ export const buildManagedTaskToolGuidance = () => {
     '- When the chat UI sends a `[ROOM_TASK_MESSAGE] ... [/ROOM_TASK_MESSAGE]` block, treat it as a runtime relay envelope instead of ordinary prose. Parse the `sessionId` or legacy `taskId`, `message`, and optional `mode` / `request` fields. If the envelope indicates `mode: interaction`, or runtime status shows `waiting_input` / pending input, use a `session.submit` protocol command. Otherwise use `session.message`. Do not reply inline instead of routing the relay.',
     '- Use `session.submit` only when a runtime session is waiting for an explicit input or approval request. Do not use it for ordinary follow-up instructions.',
     '- Use a `session.stop` protocol command for graceful cancellation and set `mode` to `force` only when stop cannot recover the session.',
-    '- Compatibility aliases such as `vf agent start/status/events/send/submit/stop` may exist for debugging or legacy scripts, but they are not the primary guidance for new agent workflows.',
+    '- Compatibility aliases such as dedicated agent start/status/events/send/submit/stop subcommands may exist for debugging or legacy scripts, but they are not the primary guidance for new agent workflows.',
     '- When a session is still making progress, use `wait` between checks and inspect status/events instead of starting a replacement session.'
   ].join('\n')
 }

package/src/workspace-prompt.ts

@@ -1,7 +1,7 @@
 import type { WorkspaceDefinitionPayload } from '@vibe-forge/types'
 import { resolvePromptPath } from '@vibe-forge/utils'
 
-import { buildManagedTaskToolGuidance } from './task-tool-guidance'
+import { buildManagedTaskToolGuidance, resolveRuntimeProtocolCliCommand } from './task-tool-guidance'
 
 export const generateWorkspaceRoutePrompt = (
   cwd: string,
@@ -9,6 +9,8 @@ export const generateWorkspaceRoutePrompt = (
 ) => {
   if (workspaces.length === 0) return ''
   const taskToolGuidance = buildManagedTaskToolGuidance()
+  const runtimeProtocolCommand =
+    `${resolveRuntimeProtocolCliCommand()} --input-format stream-json --output-format stream-json`
 
   const workspaceList = workspaces
     .map((workspace) => {
@@ -25,7 +27,7 @@ export const generateWorkspaceRoutePrompt = (
     '<system-prompt>\n' +
     'The project includes the following registered workspaces:\n' +
     `${workspaceList}\n` +
-    'When a user request targets one of these workspaces, start a child runtime session with `vf run --input-format stream-json --output-format stream-json` and a `session.start` envelope; include the workspace identifier and path in the title and message. ' +
+    `When a user request targets one of these workspaces, start a child runtime session with \`${runtimeProtocolCommand}\` and a \`session.start\` envelope; include the workspace identifier and path in the title and message. ` +
     'Do not directly edit files inside a registered workspace from the current session unless the user explicitly asks this session to work in that directory.\n' +
     `${taskToolGuidance}\n` +
     '</system-prompt>\n'

package/src/skills-cli-dependency-helpers.ts

@@ -1,94 +0,0 @@
-import { access, copyFile, lstat, mkdir, readdir } from 'node:fs/promises'
-import { dirname, resolve } from 'node:path'
-import process from 'node:process'
-
-import { withDirectoryInstallLock } from '@vibe-forge/utils/install-lock'
-import { resolveProjectSharedCachePath } from '@vibe-forge/utils/project-cache-path'
-import { toSkillSlug } from '@vibe-forge/utils/skills-cli'
-
-const toCacheSegment = (value: string) => (
-  value
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9._-]+/g, '-')
-    .replace(/^-+|-+$/g, '') || 'default'
-)
-
-export const pathExists = async (targetPath: string) => {
-  try {
-    await access(targetPath)
-    return true
-  } catch {
-    return false
-  }
-}
-
-export const withInstallLock = async <T>(lockDir: string, callback: () => Promise<T>) => {
-  try {
-    return await withDirectoryInstallLock({ lockDir }, callback)
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
-    throw new Error(
-      message.replace('Timed out waiting for install lock', 'Timed out waiting for skill dependency install lock')
-    )
-  }
-}
-
-export const copyRegularFiles = async (sourceDir: string, targetDir: string) => {
-  let fileCount = 0
-  const entries = await readdir(sourceDir, { withFileTypes: true })
-
-  await mkdir(targetDir, { recursive: true })
-
-  for (const entry of entries) {
-    const sourcePath = resolve(sourceDir, entry.name)
-    const targetPath = resolve(targetDir, entry.name)
-    const stat = await lstat(sourcePath)
-
-    if (stat.isDirectory()) {
-      fileCount += await copyRegularFiles(sourcePath, targetPath)
-      continue
-    }
-
-    if (!stat.isFile()) continue
-
-    await mkdir(dirname(targetPath), { recursive: true })
-    await copyFile(sourcePath, targetPath)
-    fileCount += 1
-  }
-
-  return fileCount
-}
-
-export const pickSearchResult = <T extends { skill: string }>(
-  results: T[],
-  name: string
-) => {
-  const slug = toSkillSlug(name)
-  return results.find(result => (
-    result.skill === name ||
-    toSkillSlug(result.skill) === slug
-  )) ?? results[0]
-}
-
-export const buildInstallDir = (params: {
-  cwd: string
-  registry?: string
-  skill: string
-  source: string
-  version?: string
-}) => {
-  const registry = params.registry ?? 'default'
-  return resolveProjectSharedCachePath(
-    params.cwd,
-    process.env,
-    'skill-dependencies',
-    'skills-cli',
-    toCacheSegment('skills'),
-    toCacheSegment('latest'),
-    toCacheSegment(registry),
-    ...params.source.split('/').map(toCacheSegment),
-    toCacheSegment(params.version ?? 'latest'),
-    toCacheSegment(params.skill)
-  )
-}

package/src/skills-cli-dependency.ts

@@ -1,125 +0,0 @@
-import { mkdir, rename, rm } from 'node:fs/promises'
-import { resolve } from 'node:path'
-import process from 'node:process'
-
-import type { Config } from '@vibe-forge/types'
-import { findSkillsCli, installSkillsCliRefToTemp, installSkillsCliSkillToTemp } from '@vibe-forge/utils/skills-cli'
-
-import type { NormalizedSkillDependency } from './skill-dependencies'
-import {
-  buildInstallDir,
-  copyRegularFiles,
-  pathExists,
-  pickSearchResult,
-  withInstallLock
-} from './skills-cli-dependency-helpers'
-
-const resolveAutoDownloadDependenciesEnabled = (
-  projectConfig: Config | undefined,
-  userConfig: Config | undefined
-) => userConfig?.skills?.autoDownloadDependencies ?? projectConfig?.skills?.autoDownloadDependencies ?? true
-
-export const installSkillsCliDependency = async (params: {
-  cwd: string
-  configs: [Config?, Config?]
-  dependency: NormalizedSkillDependency
-}) => {
-  const [projectConfig, userConfig] = params.configs
-  const autoDownloadDependenciesEnabled = resolveAutoDownloadDependenciesEnabled(projectConfig, userConfig)
-  const resolvedTarget = await (async () => {
-    if (params.dependency.source != null) {
-      return {
-        skill: params.dependency.name,
-        source: params.dependency.source
-      }
-    }
-
-    if (!autoDownloadDependenciesEnabled) {
-      throw new Error(
-        `Skill dependency automatic downloads are disabled; cannot resolve ${params.dependency.ref} without a source`
-      )
-    }
-
-    return await (async () => {
-      const searchResults = await findSkillsCli({
-        registry: params.dependency.registry,
-        query: params.dependency.name
-      })
-      const selected = pickSearchResult(searchResults, params.dependency.name)
-      if (selected == null) {
-        throw new Error(`Skill ${params.dependency.name} was not found by the skills CLI search.`)
-      }
-
-      return {
-        installRef: selected.installRef,
-        skill: selected.skill,
-        source: selected.source
-      }
-    })()
-  })()
-
-  const installDir = buildInstallDir({
-    cwd: params.cwd,
-    registry: params.dependency.registry,
-    skill: resolvedTarget.skill,
-    source: resolvedTarget.source,
-    version: params.dependency.version
-  })
-  const skillPath = resolve(installDir, 'SKILL.md')
-
-  return await withInstallLock(`${installDir}.lock`, async () => {
-    if (await pathExists(skillPath)) {
-      return {
-        installDir,
-        skillPath
-      }
-    }
-
-    if (!autoDownloadDependenciesEnabled) {
-      throw new Error(`Skill dependency automatic downloads are disabled; cache not found for ${params.dependency.ref}`)
-    }
-
-    const tempInstallDir = `${installDir}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`
-    await rm(tempInstallDir, { recursive: true, force: true })
-    await mkdir(tempInstallDir, { recursive: true })
-
-    const installResult = 'installRef' in resolvedTarget
-      ? params.dependency.version == null
-        ? await installSkillsCliRefToTemp({
-          installRef: resolvedTarget.installRef,
-          registry: params.dependency.registry
-        })
-        : await installSkillsCliSkillToTemp({
-          registry: params.dependency.registry,
-          skill: resolvedTarget.skill,
-          source: resolvedTarget.source,
-          version: params.dependency.version
-        })
-      : await installSkillsCliSkillToTemp({
-        registry: params.dependency.registry,
-        skill: resolvedTarget.skill,
-        source: resolvedTarget.source,
-        version: params.dependency.version
-      })
-
-    try {
-      await copyRegularFiles(installResult.installedSkill.sourcePath, tempInstallDir)
-      if (!await pathExists(resolve(tempInstallDir, 'SKILL.md'))) {
-        throw new Error(`Skill dependency ${params.dependency.ref} did not include SKILL.md`)
-      }
-
-      await rm(installDir, { recursive: true, force: true })
-      await rename(tempInstallDir, installDir)
-    } catch (error) {
-      await rm(tempInstallDir, { recursive: true, force: true })
-      throw error
-    } finally {
-      await rm(installResult.tempDir, { recursive: true, force: true })
-    }
-
-    return {
-      installDir,
-      skillPath
-    }
-  })
-}