@frontera-sdk/cli 1.46.6 → 1.47.0

package/src/forge/claude-skills.ts

@@ -0,0 +1,189 @@
+/**
+ * The skills Claude Code would load for a session, discovered the way it
+ * discovers them.
+ *
+ * Ported from T3 Code's `apps/server/src/provider/Drivers/ClaudeSkills.ts`,
+ * whose header states the reason plainly: the Agent SDK's init handshake
+ * surfaces skills only as slash commands without their filesystem paths, so
+ * the only way to show a name AND what it is for is to scan the same
+ * directories the CLI scans.
+ *
+ * Claude Code reads, in order: the config directory's `skills/`, then the
+ * workspace's `.agents/skills` and `.claude/skills`, with later roots winning
+ * on a name collision. Installed plugins add their own, namespaced
+ * `<plugin>:<skill>` — which is how the Frontera kit's eight appear once
+ * `frontera setup` has run.
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import type { ForgeSkill } from '@frontera-sdk/forge-contracts'
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/
+
+/**
+ * Enough YAML for a skill header, and no more.
+ *
+ * `name` and `description` are single-line scalars in every SKILL.md the
+ * hosts ship; pulling in a parser to read two keys would be the larger risk.
+ * A description that spans lines keeps its first line, which is what a menu
+ * row shows anyway.
+ */
+function parseFrontmatter(contents: string): { name?: string; description?: string } | null {
+  const match = FRONTMATTER.exec(contents)
+  if (!match) return null
+  const body = match[1] ?? ''
+  const read = (key: string): string | undefined => {
+    const line = new RegExp(`^${key}:\\s*(.+)$`, 'm').exec(body)
+    if (!line) return undefined
+    const raw = (line[1] ?? '').trim()
+    const unquoted = /^(['"])([\s\S]*)\1$/.exec(raw)
+    const value = (unquoted?.[2] ?? raw).trim()
+    return value || undefined
+  }
+  const name = read('name')
+  const description = read('description')
+  return {
+    ...(name ? { name } : {}),
+    ...(description ? { description } : {}),
+  }
+}
+
+function readSkillDir(dir: string): Array<{ dirName: string; path: string; contents: string }> {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return []
+  }
+  const out: Array<{ dirName: string; path: string; contents: string }> = []
+  for (const entry of [...entries].sort()) {
+    const path = join(dir, entry, 'SKILL.md')
+    try {
+      out.push({ dirName: entry, path, contents: readFileSync(path, 'utf8') })
+    } catch {
+      // Not a skill directory.
+    }
+  }
+  return out
+}
+
+/** The config directory the spawned CLI would use. */
+export function claudeConfigDir(env: NodeJS.ProcessEnv = process.env): string {
+  const configured = env.CLAUDE_CONFIG_DIR?.trim()
+  if (configured) return configured
+  return join(homedir(), '.claude')
+}
+
+/**
+ * Installed plugins, as `<marketplace>/<plugin>/<version>/skills`.
+ *
+ * Their skills are namespaced by plugin — `frontera:using-frontera` — because
+ * that is how Claude Code addresses them, and a bare `using-frontera` would
+ * collide with a project skill of the same name.
+ */
+function pluginSkillRoots(configDir: string): Array<{ plugin: string; dir: string }> {
+  const cache = join(configDir, 'plugins', 'cache')
+  const roots: Array<{ plugin: string; dir: string }> = []
+  let marketplaces: string[]
+  try {
+    marketplaces = readdirSync(cache)
+  } catch {
+    return []
+  }
+  for (const marketplace of marketplaces.sort()) {
+    let plugins: string[]
+    try {
+      plugins = readdirSync(join(cache, marketplace))
+    } catch {
+      continue
+    }
+    for (const plugin of plugins.sort()) {
+      let versions: string[]
+      try {
+        versions = readdirSync(join(cache, marketplace, plugin))
+      } catch {
+        continue
+      }
+      // Newest version wins when a cache holds more than one.
+      for (const version of versions.sort().reverse()) {
+        const dir = join(cache, marketplace, plugin, version, 'skills')
+        try {
+          if (statSync(dir).isDirectory()) {
+            roots.push({ plugin, dir })
+            break
+          }
+        } catch {
+          // Next version.
+        }
+      }
+    }
+  }
+  return roots
+}
+
+/**
+ * Every skill available to a session in `cwd`, in menu order.
+ *
+ * Keyed by the id the model is addressed with, so a project skill shadowing a
+ * user one collapses to a single row — the same resolution Claude Code
+ * applies when it loads them.
+ */
+export function discoverClaudeSkills(cwd: string, env: NodeJS.ProcessEnv = process.env): ForgeSkill[] {
+  const configDir = claudeConfigDir(env)
+  const byId = new Map<string, ForgeSkill>()
+
+  const roots: Array<{ dir: string; source: ForgeSkill['source']; plugin?: string }> = [
+    { dir: join(configDir, 'skills'), source: 'user' },
+    ...(cwd
+      ? [
+          { dir: join(cwd, '.agents', 'skills'), source: 'project' as const },
+          { dir: join(cwd, '.claude', 'skills'), source: 'project' as const },
+        ]
+      : []),
+    ...pluginSkillRoots(configDir).map((root) => ({
+      dir: root.dir,
+      source: 'plugin' as const,
+      plugin: root.plugin,
+    })),
+  ]
+
+  for (const root of roots) {
+    for (const found of readSkillDir(root.dir)) {
+      const frontmatter = parseFrontmatter(found.contents)
+      // No frontmatter means Claude Code will not load it either.
+      if (!frontmatter) continue
+      const name = frontmatter.name ?? found.dirName.trim()
+      if (!name) continue
+      const id = root.plugin ? `${root.plugin}:${name}` : name
+      byId.set(id, {
+        id,
+        name,
+        source: root.source,
+        path: found.path,
+        ...(root.plugin ? { plugin: root.plugin } : {}),
+        ...(frontmatter.description ? { description: frontmatter.description } : {}),
+      })
+    }
+  }
+
+  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id))
+}
+
+/** Cheap cache: a menu opens often, and the disk answer rarely changes. */
+const CACHE_MS = 30_000
+const cache = new Map<string, { at: number; skills: ForgeSkill[] }>()
+
+export function skillsFor(cwd: string, env: NodeJS.ProcessEnv = process.env): ForgeSkill[] {
+  const hit = cache.get(cwd)
+  if (hit && Date.now() - hit.at < CACHE_MS) return hit.skills
+  const skills = discoverClaudeSkills(cwd, env)
+  cache.set(cwd, { at: Date.now(), skills })
+  return skills
+}
+
+/** Exported for tests: forget what was read. */
+export function clearSkillCache(): void {
+  cache.clear()
+}

package/src/forge/claude-translator.ts

@@ -0,0 +1,361 @@
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk'
+import type { UIMessageChunk } from 'ai'
+
+/**
+ * Claude Agent SDK messages → AI SDK v6 `UIMessageChunk`s, the vocabulary the
+ * platform's chat components already render. Mirrors the shape of the Codex
+ * translator in the service (`codex-events.ts`): a stateful object fed one
+ * native message at a time, returning the chunks it implies.
+ *
+ * With `includePartialMessages` the SDK forwards raw Anthropic stream events
+ * (`message_start`, `content_block_*`, `message_stop`) alongside the complete
+ * `assistant` messages. The stream events carry the deltas; the complete
+ * messages are only a safety net for tool inputs when a partial stream was
+ * absent. Tool results arrive as `user` messages holding `tool_result`
+ * blocks. Sub-agent traffic (`parent_tool_use_id` set) is dropped: the UI
+ * shows the parent `Task` tool card, not its inner conversation.
+ */
+
+type Chunk = UIMessageChunk
+
+interface ContentBlock {
+  type: string
+  id?: string
+  name?: string
+  text?: string
+  thinking?: string
+  input?: unknown
+  tool_use_id?: string
+  content?: unknown
+  is_error?: boolean
+}
+
+interface StreamEvent {
+  type: string
+  index?: number
+  content_block?: ContentBlock
+  delta?: { type?: string; text?: string; thinking?: string; partial_json?: string }
+}
+
+/** The fields this translator reads, typed loosely so a fixture is a plain object. */
+interface LooseMessage {
+  type: string
+  subtype?: string
+  session_id?: string
+  parent_tool_use_id?: string | null
+  isReplay?: boolean
+  event?: StreamEvent
+  message?: { content?: unknown }
+  is_error?: boolean
+  result?: string
+  errors?: string[]
+  usage?: { input_tokens?: number; output_tokens?: number; cache_read_input_tokens?: number }
+}
+
+interface OpenBlock {
+  kind: 'text' | 'thinking' | 'tool_use' | 'other'
+  id: string
+  toolName: string
+  json: string
+}
+
+export interface TranslatorUsage {
+  input: number
+  output: number
+  cachedInput: number
+}
+
+export function stringifyToolResult(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return content == null ? '' : JSON.stringify(content)
+  return content
+    .map((part: { type?: string; text?: string }) => {
+      if (part && part.type === 'text' && typeof part.text === 'string') return part.text
+      if (part && part.type === 'image') return '[image]'
+      return JSON.stringify(part)
+    })
+    .join('\n')
+}
+
+function parseInput(json: string): Record<string, unknown> {
+  if (!json.trim()) return {}
+  try {
+    const parsed = JSON.parse(json) as unknown
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : {}
+  } catch {
+    return {}
+  }
+}
+
+export class ClaudeEventTranslator {
+  private started = false
+  private stepOpen = false
+  private stepHasContent = false
+  private finished = false
+  private sawStreamEvents = false
+  private partCount = 0
+  private readonly blocks = new Map<number, OpenBlock>()
+  private readonly toolStarts = new Set<string>()
+  private readonly toolInputs = new Set<string>()
+
+  sessionId: string | null = null
+  failed = false
+  errorText: string | null = null
+  usage: TranslatorUsage | null = null
+
+  constructor(private readonly messageId: string) {}
+
+  get isFinished(): boolean {
+    return this.finished
+  }
+
+  translate(raw: SDKMessage): Chunk[] {
+    const msg = raw as unknown as LooseMessage
+    const out: Chunk[] = []
+    if (this.finished) return out
+
+    if (!this.sessionId && typeof msg.session_id === 'string' && msg.session_id) {
+      this.sessionId = msg.session_id
+    }
+
+    switch (msg.type) {
+      case 'stream_event':
+        if (msg.parent_tool_use_id) break
+        if (msg.event) this.onStreamEvent(msg.event, out)
+        break
+      case 'assistant':
+        if (msg.parent_tool_use_id) break
+        this.onAssistant(msg.message?.content, out)
+        break
+      case 'user':
+        if (msg.parent_tool_use_id || msg.isReplay) break
+        this.onUser(msg.message?.content, out)
+        break
+      case 'result':
+        this.onResult(msg, out)
+        break
+      default:
+        break
+    }
+    return out
+  }
+
+  /**
+   * A permission prompt can reach the adapter before this translator has
+   * consumed the stream events that introduce the tool call — the SDK answers
+   * control requests as they arrive while messages queue for the consumer.
+   * The approval chunk needs the tool part to exist, so the adapter asks for
+   * it here; if the events already came through, nothing is emitted twice.
+   */
+  ensureToolCall(toolCallId: string, toolName: string, input: unknown): Chunk[] {
+    const out: Chunk[] = []
+    this.ensureStarted(out)
+    this.ensureStep(out)
+    out.push(...this.toolStart(toolCallId, toolName))
+    out.push(...this.toolInput(toolCallId, toolName, input))
+    return out
+  }
+
+  /** The host threw; say so in the stream and close it. */
+  fail(errorText: string): Chunk[] {
+    const out: Chunk[] = []
+    if (this.finished) return out
+    this.failed = true
+    this.errorText = errorText
+    this.ensureStarted(out)
+    out.push({ type: 'error', errorText } as Chunk)
+    out.push(...this.finish())
+    return out
+  }
+
+  /** Close the stream if the host ended without a `result`. */
+  finish(): Chunk[] {
+    const out: Chunk[] = []
+    if (this.finished) return out
+    this.ensureStarted(out)
+    this.closeStep(out)
+    out.push({ type: 'finish' } as Chunk)
+    this.finished = true
+    return out
+  }
+
+  // -- internals ------------------------------------------------------------
+
+  private nextId(prefix: string): string {
+    return `${this.messageId}_${prefix}${this.partCount++}`
+  }
+
+  private ensureStarted(out: Chunk[]): void {
+    if (this.started) return
+    this.started = true
+    out.push({ type: 'start', messageId: this.messageId } as Chunk)
+  }
+
+  private ensureStep(out: Chunk[]): void {
+    if (this.stepOpen) return
+    this.stepOpen = true
+    this.stepHasContent = false
+    out.push({ type: 'start-step' } as Chunk)
+  }
+
+  private closeStep(out: Chunk[]): void {
+    if (!this.stepOpen) return
+    this.stepOpen = false
+    out.push({ type: 'finish-step' } as Chunk)
+  }
+
+  /** A new API message is a new step, unless the open one is still empty. */
+  private newStep(out: Chunk[]): void {
+    if (this.stepOpen && this.stepHasContent) this.closeStep(out)
+    this.ensureStep(out)
+  }
+
+  private toolStart(toolCallId: string, toolName: string): Chunk[] {
+    if (this.toolStarts.has(toolCallId)) return []
+    this.toolStarts.add(toolCallId)
+    this.stepHasContent = true
+    return [{ type: 'tool-input-start', toolCallId, toolName } as Chunk]
+  }
+
+  private toolInput(toolCallId: string, toolName: string, input: unknown): Chunk[] {
+    if (this.toolInputs.has(toolCallId)) return []
+    this.toolInputs.add(toolCallId)
+    return [{ type: 'tool-input-available', toolCallId, toolName, input: input ?? {} } as Chunk]
+  }
+
+  private onStreamEvent(ev: StreamEvent, out: Chunk[]): void {
+    this.sawStreamEvents = true
+    switch (ev.type) {
+      case 'message_start': {
+        this.ensureStarted(out)
+        this.newStep(out)
+        this.blocks.clear()
+        break
+      }
+      case 'content_block_start': {
+        const block = ev.content_block
+        if (!block || ev.index === undefined) break
+        this.ensureStarted(out)
+        this.ensureStep(out)
+        if (block.type === 'text') {
+          const id = this.nextId('t')
+          this.blocks.set(ev.index, { kind: 'text', id, toolName: '', json: '' })
+          this.stepHasContent = true
+          out.push({ type: 'text-start', id } as Chunk)
+        } else if (block.type === 'thinking' || block.type === 'redacted_thinking') {
+          const id = this.nextId('r')
+          this.blocks.set(ev.index, { kind: 'thinking', id, toolName: '', json: '' })
+          this.stepHasContent = true
+          out.push({ type: 'reasoning-start', id } as Chunk)
+        } else if (block.type === 'tool_use' || block.type === 'server_tool_use' || block.type === 'mcp_tool_use') {
+          const id = block.id ?? this.nextId('call')
+          const toolName = block.name ?? 'tool'
+          this.blocks.set(ev.index, { kind: 'tool_use', id, toolName, json: '' })
+          out.push(...this.toolStart(id, toolName))
+        } else {
+          this.blocks.set(ev.index, { kind: 'other', id: '', toolName: '', json: '' })
+        }
+        break
+      }
+      case 'content_block_delta': {
+        if (ev.index === undefined) break
+        const block = this.blocks.get(ev.index)
+        const delta = ev.delta
+        if (!block || !delta) break
+        if (block.kind === 'text' && delta.type === 'text_delta' && typeof delta.text === 'string') {
+          out.push({ type: 'text-delta', id: block.id, delta: delta.text } as Chunk)
+        } else if (block.kind === 'thinking' && delta.type === 'thinking_delta' && typeof delta.thinking === 'string') {
+          out.push({ type: 'reasoning-delta', id: block.id, delta: delta.thinking } as Chunk)
+        } else if (block.kind === 'tool_use' && delta.type === 'input_json_delta' && typeof delta.partial_json === 'string') {
+          block.json += delta.partial_json
+          if (!this.toolInputs.has(block.id)) {
+            out.push({ type: 'tool-input-delta', toolCallId: block.id, inputTextDelta: delta.partial_json } as Chunk)
+          }
+        }
+        break
+      }
+      case 'content_block_stop': {
+        if (ev.index === undefined) break
+        const block = this.blocks.get(ev.index)
+        if (!block) break
+        this.blocks.delete(ev.index)
+        if (block.kind === 'text') out.push({ type: 'text-end', id: block.id } as Chunk)
+        else if (block.kind === 'thinking') out.push({ type: 'reasoning-end', id: block.id } as Chunk)
+        else if (block.kind === 'tool_use') out.push(...this.toolInput(block.id, block.toolName, parseInput(block.json)))
+        break
+      }
+      default:
+        // message_delta / message_stop / ping carry nothing the UI shows.
+        break
+    }
+  }
+
+  private onAssistant(content: unknown, out: Chunk[]): void {
+    if (!Array.isArray(content)) return
+    this.ensureStarted(out)
+    if (!this.sawStreamEvents) this.newStep(out)
+    for (const block of content as ContentBlock[]) {
+      if (!block || typeof block !== 'object') continue
+      if (block.type === 'tool_use' || block.type === 'server_tool_use' || block.type === 'mcp_tool_use') {
+        const id = block.id ?? this.nextId('call')
+        const toolName = block.name ?? 'tool'
+        this.ensureStep(out)
+        out.push(...this.toolStart(id, toolName))
+        out.push(...this.toolInput(id, toolName, block.input ?? {}))
+        continue
+      }
+      // Text and thinking already streamed as deltas when partials are on;
+      // repeating them here would double every paragraph.
+      if (this.sawStreamEvents) continue
+      if (block.type === 'text' && typeof block.text === 'string') {
+        const id = this.nextId('t')
+        this.stepHasContent = true
+        out.push({ type: 'text-start', id } as Chunk)
+        out.push({ type: 'text-delta', id, delta: block.text } as Chunk)
+        out.push({ type: 'text-end', id } as Chunk)
+      } else if (block.type === 'thinking' && typeof block.thinking === 'string') {
+        const id = this.nextId('r')
+        this.stepHasContent = true
+        out.push({ type: 'reasoning-start', id } as Chunk)
+        out.push({ type: 'reasoning-delta', id, delta: block.thinking } as Chunk)
+        out.push({ type: 'reasoning-end', id } as Chunk)
+      }
+    }
+  }
+
+  private onUser(content: unknown, out: Chunk[]): void {
+    if (!Array.isArray(content)) return
+    for (const block of content as ContentBlock[]) {
+      if (!block || block.type !== 'tool_result' || typeof block.tool_use_id !== 'string') continue
+      // A result for a call the stream never introduced has no part to land
+      // on; the AI SDK reducer throws on it, so it is dropped rather than sent.
+      if (!this.toolStarts.has(block.tool_use_id)) continue
+      const text = stringifyToolResult(block.content)
+      if (block.is_error) {
+        out.push({ type: 'tool-output-error', toolCallId: block.tool_use_id, errorText: text || 'tool failed' } as Chunk)
+      } else {
+        out.push({ type: 'tool-output-available', toolCallId: block.tool_use_id, output: text } as Chunk)
+      }
+    }
+  }
+
+  private onResult(msg: LooseMessage, out: Chunk[]): void {
+    this.ensureStarted(out)
+    if (msg.usage) {
+      this.usage = {
+        input: msg.usage.input_tokens ?? 0,
+        output: msg.usage.output_tokens ?? 0,
+        cachedInput: msg.usage.cache_read_input_tokens ?? 0,
+      }
+    }
+    if (msg.is_error || (msg.subtype && msg.subtype !== 'success')) {
+      this.failed = true
+      this.errorText =
+        (msg.errors && msg.errors.length > 0 ? msg.errors.join('\n') : null)
+        ?? (typeof msg.result === 'string' && msg.result ? msg.result : null)
+        ?? `Claude Code ended the turn with ${msg.subtype ?? 'an error'}`
+      out.push({ type: 'error', errorText: this.errorText } as Chunk)
+    }
+    out.push(...this.finish())
+  }
+}

package/src/forge/codex-adapter.ts

@@ -0,0 +1,28 @@
+import type { UIMessageChunk } from 'ai'
+
+import type { ApprovalDecision, Emit, HostAdapter, TurnContext, TurnOutcome } from './adapter'
+
+const NOT_WIRED = 'Codex is not wired in this build yet — use Claude Code'
+
+/**
+ * Placeholder until the Codex app-server adapter lands. It speaks the same
+ * `HostAdapter` contract so the run manager, the store and the surface need
+ * no change when it does; the only thing it says today is why it cannot run.
+ */
+export class CodexAdapter implements HostAdapter {
+  async startTurn(ctx: TurnContext, emit: Emit): Promise<TurnOutcome> {
+    const chunks: UIMessageChunk[] = [
+      { type: 'start', messageId: ctx.messageId } as UIMessageChunk,
+      { type: 'error', errorText: NOT_WIRED } as UIMessageChunk,
+      { type: 'finish' } as UIMessageChunk,
+    ]
+    for (const chunk of chunks) emit(chunk)
+    return { error: NOT_WIRED }
+  }
+
+  async interrupt(): Promise<void> {}
+
+  respondApproval(_approvalId: string, _decision: ApprovalDecision): boolean {
+    return false
+  }
+}

package/src/forge/env.ts

@@ -0,0 +1,42 @@
+import { homedir } from 'node:os'
+import { delimiter, dirname, join } from 'node:path'
+
+import { dataDir } from '../paths'
+
+/**
+ * The PATH every process Forge spawns sees: hosts, terminals, and the hosts'
+ * own subprocesses.
+ *
+ * `frontera` goes first so the agent and the person type the same command and
+ * reach the same binary — the CLI that owns this daemon, not whichever older
+ * copy a package manager left on the machine. The well-known tool directories
+ * follow because a daemon launched by a GUI app inherits the login PATH, not
+ * the shell's, and that is where `claude` and `codex` usually live.
+ */
+export function forgePath(base: string | undefined = process.env.PATH): string {
+  const home = homedir()
+  const first = [join(dataDir(), 'bin'), dirname(process.execPath)]
+  const wellKnown = [
+    join(home, '.local', 'bin'),
+    join(home, '.bun', 'bin'),
+    join(home, '.claude', 'local'),
+    '/opt/homebrew/bin',
+    '/usr/local/bin',
+  ]
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const dir of [...first, ...(base ? base.split(delimiter) : []), ...wellKnown]) {
+    if (!dir || seen.has(dir)) continue
+    seen.add(dir)
+    out.push(dir)
+  }
+  return out.join(delimiter)
+}
+
+export function forgeEnv(extra: Record<string, string | undefined> = {}): Record<string, string | undefined> {
+  const env: Record<string, string | undefined> = { ...process.env, PATH: forgePath(), ...extra }
+  // Set by an Electron parent to run its own binary as Node; inherited by a
+  // child it turns every `electron`-based tool on PATH into a bare Node.
+  delete env.ELECTRON_RUN_AS_NODE
+  return env
+}