@xortex/xcode 3.0.0 → 3.0.2

package/remote/sdkMessageAdapter.ts

@@ -0,0 +1,302 @@
+import type {
+  SDKAssistantMessage,
+  SDKCompactBoundaryMessage,
+  SDKMessage,
+  SDKPartialAssistantMessage,
+  SDKResultMessage,
+  SDKStatusMessage,
+  SDKSystemMessage,
+  SDKToolProgressMessage,
+} from '../entrypoints/agentSdkTypes.js'
+import type {
+  AssistantMessage,
+  Message,
+  StreamEvent,
+  SystemMessage,
+} from '../types/message.js'
+import { logForDebugging } from '../utils/debug.js'
+import { fromSDKCompactMetadata } from '../utils/messages/mappers.js'
+import { createUserMessage } from '../utils/messages.js'
+
+/**
+ * Converts SDKMessage from CCR to REPL Message types.
+ *
+ * The CCR backend sends SDK-format messages via WebSocket. The REPL expects
+ * internal Message types for rendering. This adapter bridges the two.
+ */
+
+/**
+ * Convert an SDKAssistantMessage to an AssistantMessage
+ */
+function convertAssistantMessage(msg: SDKAssistantMessage): AssistantMessage {
+  return {
+    type: 'assistant',
+    message: msg.message,
+    uuid: msg.uuid,
+    requestId: undefined,
+    timestamp: new Date().toISOString(),
+    error: msg.error,
+  }
+}
+
+/**
+ * Convert an SDKPartialAssistantMessage (streaming) to a StreamEvent
+ */
+function convertStreamEvent(msg: SDKPartialAssistantMessage): StreamEvent {
+  return {
+    type: 'stream_event',
+    event: msg.event,
+  }
+}
+
+/**
+ * Convert an SDKResultMessage to a SystemMessage
+ */
+function convertResultMessage(msg: SDKResultMessage): SystemMessage {
+  const isError = msg.subtype !== 'success'
+  const content = isError
+    ? msg.errors?.join(', ') || 'Unknown error'
+    : 'Session completed successfully'
+
+  return {
+    type: 'system',
+    subtype: 'informational',
+    content,
+    level: isError ? 'warning' : 'info',
+    uuid: msg.uuid,
+    timestamp: new Date().toISOString(),
+  }
+}
+
+/**
+ * Convert an SDKSystemMessage (init) to a SystemMessage
+ */
+function convertInitMessage(msg: SDKSystemMessage): SystemMessage {
+  return {
+    type: 'system',
+    subtype: 'informational',
+    content: `Remote session initialized (model: ${msg.model})`,
+    level: 'info',
+    uuid: msg.uuid,
+    timestamp: new Date().toISOString(),
+  }
+}
+
+/**
+ * Convert an SDKStatusMessage to a SystemMessage
+ */
+function convertStatusMessage(msg: SDKStatusMessage): SystemMessage | null {
+  if (!msg.status) {
+    return null
+  }
+
+  return {
+    type: 'system',
+    subtype: 'informational',
+    content:
+      msg.status === 'compacting'
+        ? 'Compacting conversation…'
+        : `Status: ${msg.status}`,
+    level: 'info',
+    uuid: msg.uuid,
+    timestamp: new Date().toISOString(),
+  }
+}
+
+/**
+ * Convert an SDKToolProgressMessage to a SystemMessage.
+ * We use a system message instead of ProgressMessage since the Progress type
+ * is a complex union that requires tool-specific data we don't have from CCR.
+ */
+function convertToolProgressMessage(
+  msg: SDKToolProgressMessage,
+): SystemMessage {
+  return {
+    type: 'system',
+    subtype: 'informational',
+    content: `Tool ${msg.tool_name} running for ${msg.elapsed_time_seconds}s…`,
+    level: 'info',
+    uuid: msg.uuid,
+    timestamp: new Date().toISOString(),
+    toolUseID: msg.tool_use_id,
+  }
+}
+
+/**
+ * Convert an SDKCompactBoundaryMessage to a SystemMessage
+ */
+function convertCompactBoundaryMessage(
+  msg: SDKCompactBoundaryMessage,
+): SystemMessage {
+  return {
+    type: 'system',
+    subtype: 'compact_boundary',
+    content: 'Conversation compacted',
+    level: 'info',
+    uuid: msg.uuid,
+    timestamp: new Date().toISOString(),
+    compactMetadata: fromSDKCompactMetadata(msg.compact_metadata),
+  }
+}
+
+/**
+ * Result of converting an SDKMessage
+ */
+export type ConvertedMessage =
+  | { type: 'message'; message: Message }
+  | { type: 'stream_event'; event: StreamEvent }
+  | { type: 'ignored' }
+
+type ConvertOptions = {
+  /** Convert user messages containing tool_result content blocks into UserMessages.
+   * Used by direct connect mode where tool results come from the remote server
+   * and need to be rendered locally. CCR mode ignores user messages since they
+   * are handled differently. */
+  convertToolResults?: boolean
+  /**
+   * Convert user text messages into UserMessages for display. Used when
+   * converting historical events where user-typed messages need to be shown.
+   * In live WS mode these are already added locally by the REPL so they're
+   * ignored by default.
+   */
+  convertUserTextMessages?: boolean
+}
+
+/**
+ * Convert an SDKMessage to REPL message format
+ */
+export function convertSDKMessage(
+  msg: SDKMessage,
+  opts?: ConvertOptions,
+): ConvertedMessage {
+  switch (msg.type) {
+    case 'assistant':
+      return { type: 'message', message: convertAssistantMessage(msg) }
+
+    case 'user': {
+      const content = msg.message?.content
+      // Tool result messages from the remote server need to be converted so
+      // they render and collapse like local tool results. Detect via content
+      // shape (tool_result blocks) — parent_tool_use_id is NOT reliable: the
+      // agent-side normalizeMessage() hardcodes it to null for top-level
+      // tool results, so it can't distinguish tool results from prompt echoes.
+      const isToolResult =
+        Array.isArray(content) && content.some(b => b.type === 'tool_result')
+      if (opts?.convertToolResults && isToolResult) {
+        return {
+          type: 'message',
+          message: createUserMessage({
+            content,
+            toolUseResult: msg.tool_use_result,
+            uuid: msg.uuid,
+            timestamp: msg.timestamp,
+          }),
+        }
+      }
+      // When converting historical events, user-typed messages need to be
+      // rendered (they weren't added locally by the REPL). Skip tool_results
+      // here — already handled above.
+      if (opts?.convertUserTextMessages && !isToolResult) {
+        if (typeof content === 'string' || Array.isArray(content)) {
+          return {
+            type: 'message',
+            message: createUserMessage({
+              content,
+              toolUseResult: msg.tool_use_result,
+              uuid: msg.uuid,
+              timestamp: msg.timestamp,
+            }),
+          }
+        }
+      }
+      // User-typed messages (string content) are already added locally by REPL.
+      // In CCR mode, all user messages are ignored (tool results handled differently).
+      return { type: 'ignored' }
+    }
+
+    case 'stream_event':
+      return { type: 'stream_event', event: convertStreamEvent(msg) }
+
+    case 'result':
+      // Only show result messages for errors. Success results are noise
+      // in multi-turn sessions (isLoading=false is sufficient signal).
+      if (msg.subtype !== 'success') {
+        return { type: 'message', message: convertResultMessage(msg) }
+      }
+      return { type: 'ignored' }
+
+    case 'system':
+      if (msg.subtype === 'init') {
+        return { type: 'message', message: convertInitMessage(msg) }
+      }
+      if (msg.subtype === 'status') {
+        const statusMsg = convertStatusMessage(msg)
+        return statusMsg
+          ? { type: 'message', message: statusMsg }
+          : { type: 'ignored' }
+      }
+      if (msg.subtype === 'compact_boundary') {
+        return {
+          type: 'message',
+          message: convertCompactBoundaryMessage(msg),
+        }
+      }
+      // hook_response and other subtypes
+      logForDebugging(
+        `[sdkMessageAdapter] Ignoring system message subtype: ${msg.subtype}`,
+      )
+      return { type: 'ignored' }
+
+    case 'tool_progress':
+      return { type: 'message', message: convertToolProgressMessage(msg) }
+
+    case 'auth_status':
+      // Auth status is handled separately, not converted to a display message
+      logForDebugging('[sdkMessageAdapter] Ignoring auth_status message')
+      return { type: 'ignored' }
+
+    case 'tool_use_summary':
+      // Tool use summaries are SDK-only events, not displayed in REPL
+      logForDebugging('[sdkMessageAdapter] Ignoring tool_use_summary message')
+      return { type: 'ignored' }
+
+    case 'rate_limit_event':
+      // Rate limit events are SDK-only events, not displayed in REPL
+      logForDebugging('[sdkMessageAdapter] Ignoring rate_limit_event message')
+      return { type: 'ignored' }
+
+    default: {
+      // Gracefully ignore unknown message types. The backend may send new
+      // types before the client is updated; logging helps with debugging
+      // without crashing or losing the session.
+      logForDebugging(
+        `[sdkMessageAdapter] Unknown message type: ${(msg as { type: string }).type}`,
+      )
+      return { type: 'ignored' }
+    }
+  }
+}
+
+/**
+ * Check if an SDKMessage indicates the session has ended
+ */
+export function isSessionEndMessage(msg: SDKMessage): boolean {
+  return msg.type === 'result'
+}
+
+/**
+ * Check if an SDKResultMessage indicates success
+ */
+export function isSuccessResult(msg: SDKResultMessage): boolean {
+  return msg.subtype === 'success'
+}
+
+/**
+ * Extract the result text from a successful SDKResultMessage
+ */
+export function getResultText(msg: SDKResultMessage): string | null {
+  if (msg.subtype === 'success') {
+    return msg.result
+  }
+  return null
+}

package/skills/bundled/batch.ts

@@ -0,0 +1,124 @@
+import { AGENT_TOOL_NAME } from '../../tools/AgentTool/constants.js'
+import { ASK_USER_QUESTION_TOOL_NAME } from '../../tools/AskUserQuestionTool/prompt.js'
+import { ENTER_PLAN_MODE_TOOL_NAME } from '../../tools/EnterPlanModeTool/constants.js'
+import { EXIT_PLAN_MODE_TOOL_NAME } from '../../tools/ExitPlanModeTool/constants.js'
+import { SKILL_TOOL_NAME } from '../../tools/SkillTool/constants.js'
+import { getIsGit } from '../../utils/git.js'
+import { registerBundledSkill } from '../bundledSkills.js'
+
+const MIN_AGENTS = 5
+const MAX_AGENTS = 30
+
+const WORKER_INSTRUCTIONS = `After you finish implementing the change:
+1. **Simplify** — Invoke the \`${SKILL_TOOL_NAME}\` tool with \`skill: "simplify"\` to review and clean up your changes.
+2. **Run unit tests** — Run the project's test suite (check for package.json scripts, Makefile targets, or common commands like \`npm test\`, \`bun test\`, \`pytest\`, \`go test\`). If tests fail, fix them.
+3. **Test end-to-end** — Follow the e2e test recipe from the coordinator's prompt (below). If the recipe says to skip e2e for this unit, skip it.
+4. **Commit and push** — Commit all changes with a clear message, push the branch, and create a PR with \`gh pr create\`. Use a descriptive title. If \`gh\` is not available or the push fails, note it in your final message.
+5. **Report** — End with a single line: \`PR: <url>\` so the coordinator can track it. If no PR was created, end with \`PR: none — <reason>\`.`
+
+function buildPrompt(instruction: string): string {
+  return `# Batch: Parallel Work Orchestration
+
+You are orchestrating a large, parallelizable change across this codebase.
+
+## User Instruction
+
+${instruction}
+
+## Phase 1: Research and Plan (Plan Mode)
+
+Call the \`${ENTER_PLAN_MODE_TOOL_NAME}\` tool now to enter plan mode, then:
+
+1. **Understand the scope.** Launch one or more subagents (in the foreground — you need their results) to deeply research what this instruction touches. Find all the files, patterns, and call sites that need to change. Understand the existing conventions so the migration is consistent.
+
+2. **Decompose into independent units.** Break the work into ${MIN_AGENTS}–${MAX_AGENTS} self-contained units. Each unit must:
+   - Be independently implementable in an isolated git worktree (no shared state with sibling units)
+   - Be mergeable on its own without depending on another unit's PR landing first
+   - Be roughly uniform in size (split large units, merge trivial ones)
+
+   Scale the count to the actual work: few files → closer to ${MIN_AGENTS}; hundreds of files → closer to ${MAX_AGENTS}. Prefer per-directory or per-module slicing over arbitrary file lists.
+
+3. **Determine the e2e test recipe.** Figure out how a worker can verify its change actually works end-to-end — not just that unit tests pass. Look for:
+   - A \`claude-in-chrome\` skill or browser-automation tool (for UI changes: click through the affected flow, screenshot the result)
+   - A \`tmux\` or CLI-verifier skill (for CLI changes: launch the app interactively, exercise the changed behavior)
+   - A dev-server + curl pattern (for API changes: start the server, hit the affected endpoints)
+   - An existing e2e/integration test suite the worker can run
+
+   If you cannot find a concrete e2e path, use the \`${ASK_USER_QUESTION_TOOL_NAME}\` tool to ask the user how to verify this change end-to-end. Offer 2–3 specific options based on what you found (e.g., "Screenshot via chrome extension", "Run \`bun run dev\` and curl the endpoint", "No e2e — unit tests are sufficient"). Do not skip this — the workers cannot ask the user themselves.
+
+   Write the recipe as a short, concrete set of steps that a worker can execute autonomously. Include any setup (start a dev server, build first) and the exact command/interaction to verify.
+
+4. **Write the plan.** In your plan file, include:
+   - A summary of what you found during research
+   - A numbered list of work units — for each: a short title, the list of files/directories it covers, and a one-line description of the change
+   - The e2e test recipe (or "skip e2e because …" if the user chose that)
+   - The exact worker instructions you will give each agent (the shared template)
+
+5. Call \`${EXIT_PLAN_MODE_TOOL_NAME}\` to present the plan for approval.
+
+## Phase 2: Spawn Workers (After Plan Approval)
+
+Once the plan is approved, spawn one background agent per work unit using the \`${AGENT_TOOL_NAME}\` tool. **All agents must use \`isolation: "worktree"\` and \`run_in_background: true\`.** Launch them all in a single message block so they run in parallel.
+
+For each agent, the prompt must be fully self-contained. Include:
+- The overall goal (the user's instruction)
+- This unit's specific task (title, file list, change description — copied verbatim from your plan)
+- Any codebase conventions you discovered that the worker needs to follow
+- The e2e test recipe from your plan (or "skip e2e because …")
+- The worker instructions below, copied verbatim:
+
+\`\`\`
+${WORKER_INSTRUCTIONS}
+\`\`\`
+
+Use \`subagent_type: "general-purpose"\` unless a more specific agent type fits.
+
+## Phase 3: Track Progress
+
+After launching all workers, render an initial status table:
+
+| # | Unit | Status | PR |
+|---|------|--------|----|
+| 1 | <title> | running | — |
+| 2 | <title> | running | — |
+
+As background-agent completion notifications arrive, parse the \`PR: <url>\` line from each agent's result and re-render the table with updated status (\`done\` / \`failed\`) and PR links. Keep a brief failure note for any agent that did not produce a PR.
+
+When all agents have reported, render the final table and a one-line summary (e.g., "22/24 units landed as PRs").
+`
+}
+
+const NOT_A_GIT_REPO_MESSAGE = `This is not a git repository. The \`/batch\` command requires a git repo because it spawns agents in isolated git worktrees and creates PRs from each. Initialize a repo first, or run this from inside an existing one.`
+
+const MISSING_INSTRUCTION_MESSAGE = `Provide an instruction describing the batch change you want to make.
+
+Examples:
+  /batch migrate from react to vue
+  /batch replace all uses of lodash with native equivalents
+  /batch add type annotations to all untyped function parameters`
+
+export function registerBatchSkill(): void {
+  registerBundledSkill({
+    name: 'batch',
+    description:
+      'Research and plan a large-scale change, then execute it in parallel across 5–30 isolated worktree agents that each open a PR.',
+    whenToUse:
+      'Use when the user wants to make a sweeping, mechanical change across many files (migrations, refactors, bulk renames) that can be decomposed into independent parallel units.',
+    argumentHint: '<instruction>',
+    userInvocable: true,
+    disableModelInvocation: true,
+    async getPromptForCommand(args) {
+      const instruction = args.trim()
+      if (!instruction) {
+        return [{ type: 'text', text: MISSING_INSTRUCTION_MESSAGE }]
+      }
+
+      const isGit = await getIsGit()
+      if (!isGit) {
+        return [{ type: 'text', text: NOT_A_GIT_REPO_MESSAGE }]
+      }
+
+      return [{ type: 'text', text: buildPrompt(instruction) }]
+    },
+  })
+}

package/skills/bundled/claudeApi.ts

@@ -0,0 +1,196 @@
+import { readdir } from 'fs/promises'
+import { getCwd } from '../../utils/cwd.js'
+import { registerBundledSkill } from '../bundledSkills.js'
+
+// claudeApiContent.js bundles 247KB of .md strings. Lazy-load inside
+// getPromptForCommand so they only enter memory when /claude-api is invoked.
+type SkillContent = typeof import('./claudeApiContent.js')
+
+type DetectedLanguage =
+  | 'python'
+  | 'typescript'
+  | 'java'
+  | 'go'
+  | 'ruby'
+  | 'csharp'
+  | 'php'
+  | 'curl'
+
+const LANGUAGE_INDICATORS: Record<DetectedLanguage, string[]> = {
+  python: ['.py', 'requirements.txt', 'pyproject.toml', 'setup.py', 'Pipfile'],
+  typescript: ['.ts', '.tsx', 'tsconfig.json', 'package.json'],
+  java: ['.java', 'pom.xml', 'build.gradle'],
+  go: ['.go', 'go.mod'],
+  ruby: ['.rb', 'Gemfile'],
+  csharp: ['.cs', '.csproj'],
+  php: ['.php', 'composer.json'],
+  curl: [],
+}
+
+async function detectLanguage(): Promise<DetectedLanguage | null> {
+  const cwd = getCwd()
+  let entries: string[]
+  try {
+    entries = await readdir(cwd)
+  } catch {
+    return null
+  }
+
+  for (const [lang, indicators] of Object.entries(LANGUAGE_INDICATORS) as [
+    DetectedLanguage,
+    string[],
+  ][]) {
+    if (indicators.length === 0) continue
+    for (const indicator of indicators) {
+      if (indicator.startsWith('.')) {
+        if (entries.some(e => e.endsWith(indicator))) return lang
+      } else {
+        if (entries.includes(indicator)) return lang
+      }
+    }
+  }
+  return null
+}
+
+function getFilesForLanguage(
+  lang: DetectedLanguage,
+  content: SkillContent,
+): string[] {
+  return Object.keys(content.SKILL_FILES).filter(
+    path => path.startsWith(`${lang}/`) || path.startsWith('shared/'),
+  )
+}
+
+function processContent(md: string, content: SkillContent): string {
+  // Strip HTML comments. Loop to handle nested comments.
+  let out = md
+  let prev
+  do {
+    prev = out
+    out = out.replace(/<!--[\s\S]*?-->\n?/g, '')
+  } while (out !== prev)
+
+  out = out.replace(
+    /\{\{(\w+)\}\}/g,
+    (match, key: string) =>
+      (content.SKILL_MODEL_VARS as Record<string, string>)[key] ?? match,
+  )
+  return out
+}
+
+function buildInlineReference(
+  filePaths: string[],
+  content: SkillContent,
+): string {
+  const sections: string[] = []
+  for (const filePath of filePaths.sort()) {
+    const md = content.SKILL_FILES[filePath]
+    if (!md) continue
+    sections.push(
+      `<doc path="${filePath}">\n${processContent(md, content).trim()}\n</doc>`,
+    )
+  }
+  return sections.join('\n\n')
+}
+
+const INLINE_READING_GUIDE = `## Reference Documentation
+
+The relevant documentation for your detected language is included below in \`<doc>\` tags. Each tag has a \`path\` attribute showing its original file path. Use this to find the right section:
+
+### Quick Task Reference
+
+**Single text classification/summarization/extraction/Q&A:**
+→ Refer to \`{lang}/claude-api/README.md\`
+
+**Chat UI or real-time response display:**
+→ Refer to \`{lang}/claude-api/README.md\` + \`{lang}/claude-api/streaming.md\`
+
+**Long-running conversations (may exceed context window):**
+→ Refer to \`{lang}/claude-api/README.md\` — see Compaction section
+
+**Prompt caching / optimize caching / "why is my cache hit rate low":**
+→ Refer to \`shared/prompt-caching.md\` + \`{lang}/claude-api/README.md\` (Prompt Caching section)
+
+**Function calling / tool use / agents:**
+→ Refer to \`{lang}/claude-api/README.md\` + \`shared/tool-use-concepts.md\` + \`{lang}/claude-api/tool-use.md\`
+
+**Batch processing (non-latency-sensitive):**
+→ Refer to \`{lang}/claude-api/README.md\` + \`{lang}/claude-api/batches.md\`
+
+**File uploads across multiple requests:**
+→ Refer to \`{lang}/claude-api/README.md\` + \`{lang}/claude-api/files-api.md\`
+
+**Agent with built-in tools (file/web/terminal) (Python & TypeScript only):**
+→ Refer to \`{lang}/agent-sdk/README.md\` + \`{lang}/agent-sdk/patterns.md\`
+
+**Error handling:**
+→ Refer to \`shared/error-codes.md\`
+
+**Latest docs via WebFetch:**
+→ Refer to \`shared/live-sources.md\` for URLs`
+
+function buildPrompt(
+  lang: DetectedLanguage | null,
+  args: string,
+  content: SkillContent,
+): string {
+  // Take the SKILL.md content up to the "Reading Guide" section
+  const cleanPrompt = processContent(content.SKILL_PROMPT, content)
+  const readingGuideIdx = cleanPrompt.indexOf('## Reading Guide')
+  const basePrompt =
+    readingGuideIdx !== -1
+      ? cleanPrompt.slice(0, readingGuideIdx).trimEnd()
+      : cleanPrompt
+
+  const parts: string[] = [basePrompt]
+
+  if (lang) {
+    const filePaths = getFilesForLanguage(lang, content)
+    const readingGuide = INLINE_READING_GUIDE.replace(/\{lang\}/g, lang)
+    parts.push(readingGuide)
+    parts.push(
+      '---\n\n## Included Documentation\n\n' +
+        buildInlineReference(filePaths, content),
+    )
+  } else {
+    // No language detected — include all docs and let the model ask
+    parts.push(INLINE_READING_GUIDE.replace(/\{lang\}/g, 'unknown'))
+    parts.push(
+      'No project language was auto-detected. Ask the user which language they are using, then refer to the matching docs below.',
+    )
+    parts.push(
+      '---\n\n## Included Documentation\n\n' +
+        buildInlineReference(Object.keys(content.SKILL_FILES), content),
+    )
+  }
+
+  // Preserve the "When to Use WebFetch" and "Common Pitfalls" sections
+  const webFetchIdx = cleanPrompt.indexOf('## When to Use WebFetch')
+  if (webFetchIdx !== -1) {
+    parts.push(cleanPrompt.slice(webFetchIdx).trimEnd())
+  }
+
+  if (args) {
+    parts.push(`## User Request\n\n${args}`)
+  }
+
+  return parts.join('\n\n')
+}
+
+export function registerClaudeApiSkill(): void {
+  registerBundledSkill({
+    name: 'claude-api',
+    description:
+      'Build apps with the Claude API or Anthropic SDK.\n' +
+      'TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`/`claude_agent_sdk`, or user asks to use Claude API, Anthropic SDKs, or Agent SDK.\n' +
+      'DO NOT TRIGGER when: code imports `openai`/other AI SDK, general programming, or ML/data-science tasks.',
+    allowedTools: ['Read', 'Grep', 'Glob', 'WebFetch'],
+    userInvocable: true,
+    async getPromptForCommand(args) {
+      const content = await import('./claudeApiContent.js')
+      const lang = await detectLanguage()
+      const prompt = buildPrompt(lang, args, content)
+      return [{ type: 'text', text: prompt }]
+    },
+  })
+}