@xortex/xcode 3.0.0

package/utils/activityManager.ts

@@ -0,0 +1,164 @@
+import { getActiveTimeCounter as getActiveTimeCounterImpl } from '../bootstrap/state.js'
+
+type ActivityManagerOptions = {
+  getNow?: () => number
+  getActiveTimeCounter?: typeof getActiveTimeCounterImpl
+}
+
+/**
+ * ActivityManager handles generic activity tracking for both user and CLI operations.
+ * It automatically deduplicates overlapping activities and provides separate metrics
+ * for user vs CLI active time.
+ */
+export class ActivityManager {
+  private activeOperations = new Set<string>()
+
+  private lastUserActivityTime: number = 0 // Start with 0 to indicate no activity yet
+  private lastCLIRecordedTime: number
+
+  private isCLIActive: boolean = false
+
+  private readonly USER_ACTIVITY_TIMEOUT_MS = 5000 // 5 seconds
+
+  private readonly getNow: () => number
+  private readonly getActiveTimeCounter: typeof getActiveTimeCounterImpl
+
+  private static instance: ActivityManager | null = null
+
+  constructor(options?: ActivityManagerOptions) {
+    this.getNow = options?.getNow ?? (() => Date.now())
+    this.getActiveTimeCounter =
+      options?.getActiveTimeCounter ?? getActiveTimeCounterImpl
+    this.lastCLIRecordedTime = this.getNow()
+  }
+
+  static getInstance(): ActivityManager {
+    if (!ActivityManager.instance) {
+      ActivityManager.instance = new ActivityManager()
+    }
+    return ActivityManager.instance
+  }
+
+  /**
+   * Reset the singleton instance (for testing purposes)
+   */
+  static resetInstance(): void {
+    ActivityManager.instance = null
+  }
+
+  /**
+   * Create a new instance with custom options (for testing purposes)
+   */
+  static createInstance(options?: ActivityManagerOptions): ActivityManager {
+    ActivityManager.instance = new ActivityManager(options)
+    return ActivityManager.instance
+  }
+
+  /**
+   * Called when user interacts with the CLI (typing, commands, etc.)
+   */
+  recordUserActivity(): void {
+    // Don't record user time if CLI is active (CLI takes precedence)
+    if (!this.isCLIActive && this.lastUserActivityTime !== 0) {
+      const now = this.getNow()
+      const timeSinceLastActivity = (now - this.lastUserActivityTime) / 1000
+
+      if (timeSinceLastActivity > 0) {
+        const activeTimeCounter = this.getActiveTimeCounter()
+        if (activeTimeCounter) {
+          const timeoutSeconds = this.USER_ACTIVITY_TIMEOUT_MS / 1000
+
+          // Only record time if within the timeout window
+          if (timeSinceLastActivity < timeoutSeconds) {
+            activeTimeCounter.add(timeSinceLastActivity, { type: 'user' })
+          }
+        }
+      }
+    }
+
+    // Update the last user activity timestamp
+    this.lastUserActivityTime = this.getNow()
+  }
+
+  /**
+   * Starts tracking CLI activity (tool execution, AI response, etc.)
+   */
+  startCLIActivity(operationId: string): void {
+    // If operation already exists, it likely means the previous one didn't clean up
+    // properly (e.g., component crashed/unmounted without calling end). Force cleanup
+    // to avoid overestimating time - better to underestimate than overestimate.
+    if (this.activeOperations.has(operationId)) {
+      this.endCLIActivity(operationId)
+    }
+
+    const wasEmpty = this.activeOperations.size === 0
+    this.activeOperations.add(operationId)
+
+    if (wasEmpty) {
+      this.isCLIActive = true
+      this.lastCLIRecordedTime = this.getNow()
+    }
+  }
+
+  /**
+   * Stops tracking CLI activity
+   */
+  endCLIActivity(operationId: string): void {
+    this.activeOperations.delete(operationId)
+
+    if (this.activeOperations.size === 0) {
+      // Last operation ended - CLI becoming inactive
+      // Record the CLI time before switching to inactive
+      const now = this.getNow()
+      const timeSinceLastRecord = (now - this.lastCLIRecordedTime) / 1000
+
+      if (timeSinceLastRecord > 0) {
+        const activeTimeCounter = this.getActiveTimeCounter()
+        if (activeTimeCounter) {
+          activeTimeCounter.add(timeSinceLastRecord, { type: 'cli' })
+        }
+      }
+
+      this.lastCLIRecordedTime = now
+      this.isCLIActive = false
+    }
+  }
+
+  /**
+   * Convenience method to track an async operation automatically (mainly for testing/debugging)
+   */
+  async trackOperation<T>(
+    operationId: string,
+    fn: () => Promise<T>,
+  ): Promise<T> {
+    this.startCLIActivity(operationId)
+    try {
+      return await fn()
+    } finally {
+      this.endCLIActivity(operationId)
+    }
+  }
+
+  /**
+   * Gets current activity states (mainly for testing/debugging)
+   */
+  getActivityStates(): {
+    isUserActive: boolean
+    isCLIActive: boolean
+    activeOperationCount: number
+  } {
+    const now = this.getNow()
+    const timeSinceUserActivity = (now - this.lastUserActivityTime) / 1000
+    const isUserActive =
+      timeSinceUserActivity < this.USER_ACTIVITY_TIMEOUT_MS / 1000
+
+    return {
+      isUserActive,
+      isCLIActive: this.isCLIActive,
+      activeOperationCount: this.activeOperations.size,
+    }
+  }
+}
+
+// Export singleton instance
+export const activityManager = ActivityManager.getInstance()

package/utils/advisor.ts

@@ -0,0 +1,145 @@
+import type { BetaUsage } from '@anthropic-ai/sdk/resources/beta/messages/messages.mjs'
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../services/analytics/growthbook.js'
+import { shouldIncludeFirstPartyOnlyBetas } from './betas.js'
+import { isEnvTruthy } from './envUtils.js'
+import { getInitialSettings } from './settings/settings.js'
+
+// The SDK does not yet have types for advisor blocks.
+// TODO(hackyon): Migrate to the real anthropic SDK types when this feature ships publicly
+export type AdvisorServerToolUseBlock = {
+  type: 'server_tool_use'
+  id: string
+  name: 'advisor'
+  input: { [key: string]: unknown }
+}
+
+export type AdvisorToolResultBlock = {
+  type: 'advisor_tool_result'
+  tool_use_id: string
+  content:
+    | {
+        type: 'advisor_result'
+        text: string
+      }
+    | {
+        type: 'advisor_redacted_result'
+        encrypted_content: string
+      }
+    | {
+        type: 'advisor_tool_result_error'
+        error_code: string
+      }
+}
+
+export type AdvisorBlock = AdvisorServerToolUseBlock | AdvisorToolResultBlock
+
+export function isAdvisorBlock(param: {
+  type: string
+  name?: string
+}): param is AdvisorBlock {
+  return (
+    param.type === 'advisor_tool_result' ||
+    (param.type === 'server_tool_use' && param.name === 'advisor')
+  )
+}
+
+type AdvisorConfig = {
+  enabled?: boolean
+  canUserConfigure?: boolean
+  baseModel?: string
+  advisorModel?: string
+}
+
+function getAdvisorConfig(): AdvisorConfig {
+  return getFeatureValue_CACHED_MAY_BE_STALE<AdvisorConfig>(
+    'tengu_sage_compass',
+    {},
+  )
+}
+
+export function isAdvisorEnabled(): boolean {
+  if (isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_ADVISOR_TOOL)) {
+    return false
+  }
+  // The advisor beta header is first-party only (Bedrock/Vertex 400 on it).
+  if (!shouldIncludeFirstPartyOnlyBetas()) {
+    return false
+  }
+  return getAdvisorConfig().enabled ?? false
+}
+
+export function canUserConfigureAdvisor(): boolean {
+  return isAdvisorEnabled() && (getAdvisorConfig().canUserConfigure ?? false)
+}
+
+export function getExperimentAdvisorModels():
+  | { baseModel: string; advisorModel: string }
+  | undefined {
+  const config = getAdvisorConfig()
+  return isAdvisorEnabled() &&
+    !canUserConfigureAdvisor() &&
+    config.baseModel &&
+    config.advisorModel
+    ? { baseModel: config.baseModel, advisorModel: config.advisorModel }
+    : undefined
+}
+
+// @[MODEL LAUNCH]: Add the new model if it supports the advisor tool.
+// Checks whether the main loop model supports calling the advisor tool.
+export function modelSupportsAdvisor(model: string): boolean {
+  const m = model.toLowerCase()
+  return (
+    m.includes('opus-4-6') ||
+    m.includes('sonnet-4-6') ||
+    process.env.USER_TYPE === 'ant'
+  )
+}
+
+// @[MODEL LAUNCH]: Add the new model if it can serve as an advisor model.
+export function isValidAdvisorModel(model: string): boolean {
+  const m = model.toLowerCase()
+  return (
+    m.includes('opus-4-6') ||
+    m.includes('sonnet-4-6') ||
+    process.env.USER_TYPE === 'ant'
+  )
+}
+
+export function getInitialAdvisorSetting(): string | undefined {
+  if (!isAdvisorEnabled()) {
+    return undefined
+  }
+  return getInitialSettings().advisorModel
+}
+
+export function getAdvisorUsage(
+  usage: BetaUsage,
+): Array<BetaUsage & { model: string }> {
+  const iterations = usage.iterations as
+    | Array<{ type: string }>
+    | null
+    | undefined
+  if (!iterations) {
+    return []
+  }
+  return iterations.filter(
+    it => it.type === 'advisor_message',
+  ) as unknown as Array<BetaUsage & { model: string }>
+}
+
+export const ADVISOR_TOOL_INSTRUCTIONS = `# Advisor Tool
+
+You have access to an \`advisor\` tool backed by a stronger reviewer model. It takes NO parameters -- when you call it, your entire conversation history is automatically forwarded. The advisor sees the task, every tool call you've made, every result you've seen.
+
+Call advisor BEFORE substantive work -- before writing code, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, reading code, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.
+
+Also call advisor:
+- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, stage the change, save the result. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
+- When stuck -- errors recurring, approach not converging, results that don't fit.
+- When considering a change of approach.
+
+On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.
+
+Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the code does Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.
+
+If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.`

package/utils/agentContext.ts

@@ -0,0 +1,178 @@
+/**
+ * Agent context for analytics attribution using AsyncLocalStorage.
+ *
+ * This module provides a way to track agent identity across async operations
+ * without parameter drilling. Supports two agent types:
+ *
+ * 1. Subagents (Agent tool): Run in-process for quick, delegated tasks.
+ *    Context: SubagentContext with agentType: 'subagent'
+ *
+ * 2. In-process teammates: Part of a swarm with team coordination.
+ *    Context: TeammateAgentContext with agentType: 'teammate'
+ *
+ * For swarm teammates in separate processes (tmux/iTerm2), use environment
+ * variables instead: CLAUDE_CODE_AGENT_ID, CLAUDE_CODE_PARENT_SESSION_ID
+ *
+ * WHY AsyncLocalStorage (not AppState):
+ * When agents are backgrounded (ctrl+b), multiple agents can run concurrently
+ * in the same process. AppState is a single shared state that would be
+ * overwritten, causing Agent A's events to incorrectly use Agent B's context.
+ * AsyncLocalStorage isolates each async execution chain, so concurrent agents
+ * don't interfere with each other.
+ */
+
+import { AsyncLocalStorage } from 'async_hooks'
+import type { AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS } from '../services/analytics/index.js'
+import { isAgentSwarmsEnabled } from './agentSwarmsEnabled.js'
+
+/**
+ * Context for subagents (Agent tool agents).
+ * Subagents run in-process for quick, delegated tasks.
+ */
+export type SubagentContext = {
+  /** The subagent's UUID (from createAgentId()) */
+  agentId: string
+  /** The team lead's session ID (from CLAUDE_CODE_PARENT_SESSION_ID env var), undefined for main REPL subagents */
+  parentSessionId?: string
+  /** Agent type - 'subagent' for Agent tool agents */
+  agentType: 'subagent'
+  /** The subagent's type name (e.g., "Explore", "Bash", "code-reviewer") */
+  subagentName?: string
+  /** Whether this is a built-in agent (vs user-defined custom agent) */
+  isBuiltIn?: boolean
+  /** The request_id in the invoking agent that spawned or resumed this agent.
+   *  For nested subagents this is the immediate invoker, not the root —
+   *  session_id already bundles the whole tree. Updated on each resume. */
+  invokingRequestId?: string
+  /** Whether this invocation is the initial spawn or a subsequent resume
+   *  via SendMessage. Undefined when invokingRequestId is absent. */
+  invocationKind?: 'spawn' | 'resume'
+  /** Mutable flag: has this invocation's edge been emitted to telemetry yet?
+   *  Reset to false on each spawn/resume; flipped true by
+   *  consumeInvokingRequestId() on the first terminal API event. */
+  invocationEmitted?: boolean
+}
+
+/**
+ * Context for in-process teammates.
+ * Teammates are part of a swarm and have team coordination.
+ */
+export type TeammateAgentContext = {
+  /** Full agent ID, e.g., "researcher@my-team" */
+  agentId: string
+  /** Display name, e.g., "researcher" */
+  agentName: string
+  /** Team name this teammate belongs to */
+  teamName: string
+  /** UI color assigned to this teammate */
+  agentColor?: string
+  /** Whether teammate must enter plan mode before implementing */
+  planModeRequired: boolean
+  /** The team lead's session ID for transcript correlation */
+  parentSessionId: string
+  /** Whether this agent is the team lead */
+  isTeamLead: boolean
+  /** Agent type - 'teammate' for swarm teammates */
+  agentType: 'teammate'
+  /** The request_id in the invoking agent that spawned or resumed this
+   *  teammate. Undefined for teammates started outside a tool call
+   *  (e.g. session start). Updated on each resume. */
+  invokingRequestId?: string
+  /** See SubagentContext.invocationKind. */
+  invocationKind?: 'spawn' | 'resume'
+  /** Mutable flag: see SubagentContext.invocationEmitted. */
+  invocationEmitted?: boolean
+}
+
+/**
+ * Discriminated union for agent context.
+ * Use agentType to distinguish between subagent and teammate contexts.
+ */
+export type AgentContext = SubagentContext | TeammateAgentContext
+
+const agentContextStorage = new AsyncLocalStorage<AgentContext>()
+
+/**
+ * Get the current agent context, if any.
+ * Returns undefined if not running within an agent context (subagent or teammate).
+ * Use type guards isSubagentContext() or isTeammateAgentContext() to narrow the type.
+ */
+export function getAgentContext(): AgentContext | undefined {
+  return agentContextStorage.getStore()
+}
+
+/**
+ * Run an async function with the given agent context.
+ * All async operations within the function will have access to this context.
+ */
+export function runWithAgentContext<T>(context: AgentContext, fn: () => T): T {
+  return agentContextStorage.run(context, fn)
+}
+
+/**
+ * Type guard to check if context is a SubagentContext.
+ */
+export function isSubagentContext(
+  context: AgentContext | undefined,
+): context is SubagentContext {
+  return context?.agentType === 'subagent'
+}
+
+/**
+ * Type guard to check if context is a TeammateAgentContext.
+ */
+export function isTeammateAgentContext(
+  context: AgentContext | undefined,
+): context is TeammateAgentContext {
+  if (isAgentSwarmsEnabled()) {
+    return context?.agentType === 'teammate'
+  }
+  return false
+}
+
+/**
+ * Get the subagent name suitable for analytics logging.
+ * Returns the agent type name for built-in agents, "user-defined" for custom agents,
+ * or undefined if not running within a subagent context.
+ *
+ * Safe for analytics metadata: built-in agent names are code constants,
+ * and custom agents are always mapped to the literal "user-defined".
+ */
+export function getSubagentLogName():
+  | AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
+  | undefined {
+  const context = getAgentContext()
+  if (!isSubagentContext(context) || !context.subagentName) {
+    return undefined
+  }
+  return (
+    context.isBuiltIn ? context.subagentName : 'user-defined'
+  ) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
+}
+
+/**
+ * Get the invoking request_id for the current agent context — once per
+ * invocation. Returns the id on the first call after a spawn/resume, then
+ * undefined until the next boundary. Also undefined on the main thread or
+ * when the spawn path had no request_id.
+ *
+ * Sparse edge semantics: invokingRequestId appears on exactly one
+ * tengu_api_success/error per invocation, so a non-NULL value downstream
+ * marks a spawn/resume boundary.
+ */
+export function consumeInvokingRequestId():
+  | {
+      invokingRequestId: string
+      invocationKind: 'spawn' | 'resume' | undefined
+    }
+  | undefined {
+  const context = getAgentContext()
+  if (!context?.invokingRequestId || context.invocationEmitted) {
+    return undefined
+  }
+  context.invocationEmitted = true
+  return {
+    invokingRequestId: context.invokingRequestId,
+    invocationKind: context.invocationKind,
+  }
+}

package/utils/agentId.ts

@@ -0,0 +1,99 @@
+/**
+ * Deterministic Agent ID System
+ *
+ * This module provides helper functions for formatting and parsing deterministic
+ * agent IDs used in the swarm/teammate system.
+ *
+ * ## ID Formats
+ *
+ * **Agent IDs**: `agentName@teamName`
+ * - Example: `team-lead@my-project`, `researcher@my-project`
+ * - The @ symbol acts as a separator between agent name and team name
+ *
+ * **Request IDs**: `{requestType}-{timestamp}@{agentId}`
+ * - Example: `shutdown-1702500000000@researcher@my-project`
+ * - Used for shutdown requests, plan approvals, etc.
+ *
+ * ## Why Deterministic IDs?
+ *
+ * Deterministic IDs provide several benefits:
+ *
+ * 1. **Reproducibility**: The same agent spawned with the same name in the same team
+ *    always gets the same ID, enabling reconnection after crashes/restarts.
+ *
+ * 2. **Human-readable**: IDs are meaningful and debuggable (e.g., `tester@my-project`).
+ *
+ * 3. **Predictable**: Team leads can compute a teammate's ID without looking it up,
+ *    simplifying message routing and task assignment.
+ *
+ * ## Constraints
+ *
+ * - Agent names must NOT contain `@` (it's used as the separator)
+ * - Use `sanitizeAgentName()` from TeammateTool.ts to strip @ from names
+ */
+
+/**
+ * Formats an agent ID in the format `agentName@teamName`.
+ */
+export function formatAgentId(agentName: string, teamName: string): string {
+  return `${agentName}@${teamName}`
+}
+
+/**
+ * Parses an agent ID into its components.
+ * Returns null if the ID doesn't contain the @ separator.
+ */
+export function parseAgentId(
+  agentId: string,
+): { agentName: string; teamName: string } | null {
+  const atIndex = agentId.indexOf('@')
+  if (atIndex === -1) {
+    return null
+  }
+  return {
+    agentName: agentId.slice(0, atIndex),
+    teamName: agentId.slice(atIndex + 1),
+  }
+}
+
+/**
+ * Formats a request ID in the format `{requestType}-{timestamp}@{agentId}`.
+ */
+export function generateRequestId(
+  requestType: string,
+  agentId: string,
+): string {
+  const timestamp = Date.now()
+  return `${requestType}-${timestamp}@${agentId}`
+}
+
+/**
+ * Parses a request ID into its components.
+ * Returns null if the request ID doesn't match the expected format.
+ */
+export function parseRequestId(
+  requestId: string,
+): { requestType: string; timestamp: number; agentId: string } | null {
+  const atIndex = requestId.indexOf('@')
+  if (atIndex === -1) {
+    return null
+  }
+
+  const prefix = requestId.slice(0, atIndex)
+  const agentId = requestId.slice(atIndex + 1)
+
+  const lastDashIndex = prefix.lastIndexOf('-')
+  if (lastDashIndex === -1) {
+    return null
+  }
+
+  const requestType = prefix.slice(0, lastDashIndex)
+  const timestampStr = prefix.slice(lastDashIndex + 1)
+  const timestamp = parseInt(timestampStr, 10)
+
+  if (isNaN(timestamp)) {
+    return null
+  }
+
+  return { requestType, timestamp, agentId }
+}

package/utils/agentSwarmsEnabled.ts

@@ -0,0 +1,44 @@
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../services/analytics/growthbook.js'
+import { isEnvTruthy } from './envUtils.js'
+
+/**
+ * Check if --agent-teams flag is provided via CLI.
+ * Checks process.argv directly to avoid import cycles with bootstrap/state.
+ * Note: The flag is only shown in help for ant users, but if external users
+ * pass it anyway, it will work (subject to the killswitch).
+ */
+function isAgentTeamsFlagSet(): boolean {
+  return process.argv.includes('--agent-teams')
+}
+
+/**
+ * Centralized runtime check for agent teams/teammate features.
+ * This is the single gate that should be checked everywhere teammates
+ * are referenced (prompts, code, tools isEnabled, UI, etc.).
+ *
+ * Ant builds: always enabled.
+ * External builds require both:
+ * 1. Opt-in via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var OR --agent-teams flag
+ * 2. GrowthBook gate 'tengu_amber_flint' enabled (killswitch)
+ */
+export function isAgentSwarmsEnabled(): boolean {
+  // Ant: always on
+  if (process.env.USER_TYPE === 'ant') {
+    return true
+  }
+
+  // External: require opt-in via env var or --agent-teams flag
+  if (
+    !isEnvTruthy(process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) &&
+    !isAgentTeamsFlagSet()
+  ) {
+    return false
+  }
+
+  // Killswitch — always respected for external users
+  if (!getFeatureValue_CACHED_MAY_BE_STALE('tengu_amber_flint', true)) {
+    return false
+  }
+
+  return true
+}