@xortex/xcode 3.0.1 → 3.0.3

package/types/hooks.ts

@@ -0,0 +1,290 @@
+// biome-ignore-all assist/source/organizeImports: ANT-ONLY import markers must not be reordered
+import { z } from 'zod/v4'
+import { lazySchema } from '../utils/lazySchema.js'
+import {
+  type HookEvent,
+  HOOK_EVENTS,
+  type HookInput,
+  type PermissionUpdate,
+} from 'src/entrypoints/agentSdkTypes.js'
+import type {
+  HookJSONOutput,
+  AsyncHookJSONOutput,
+  SyncHookJSONOutput,
+} from 'src/entrypoints/agentSdkTypes.js'
+import type { Message } from 'src/types/message.js'
+import type { PermissionResult } from 'src/utils/permissions/PermissionResult.js'
+import { permissionBehaviorSchema } from 'src/utils/permissions/PermissionRule.js'
+import { permissionUpdateSchema } from 'src/utils/permissions/PermissionUpdateSchema.js'
+import type { AppState } from '../state/AppState.js'
+import type { AttributionState } from '../utils/commitAttribution.js'
+
+export function isHookEvent(value: string): value is HookEvent {
+  return HOOK_EVENTS.includes(value as HookEvent)
+}
+
+// Prompt elicitation protocol types. The `prompt` key acts as discriminator
+// (mirroring the {async:true} pattern), with the id as its value.
+export const promptRequestSchema = lazySchema(() =>
+  z.object({
+    prompt: z.string(), // request id
+    message: z.string(),
+    options: z.array(
+      z.object({
+        key: z.string(),
+        label: z.string(),
+        description: z.string().optional(),
+      }),
+    ),
+  }),
+)
+
+export type PromptRequest = z.infer<ReturnType<typeof promptRequestSchema>>
+
+export type PromptResponse = {
+  prompt_response: string // request id
+  selected: string
+}
+
+// Sync hook response schema
+export const syncHookResponseSchema = lazySchema(() =>
+  z.object({
+    continue: z
+      .boolean()
+      .describe('Whether Claude should continue after hook (default: true)')
+      .optional(),
+    suppressOutput: z
+      .boolean()
+      .describe('Hide stdout from transcript (default: false)')
+      .optional(),
+    stopReason: z
+      .string()
+      .describe('Message shown when continue is false')
+      .optional(),
+    decision: z.enum(['approve', 'block']).optional(),
+    reason: z.string().describe('Explanation for the decision').optional(),
+    systemMessage: z
+      .string()
+      .describe('Warning message shown to the user')
+      .optional(),
+    hookSpecificOutput: z
+      .union([
+        z.object({
+          hookEventName: z.literal('PreToolUse'),
+          permissionDecision: permissionBehaviorSchema().optional(),
+          permissionDecisionReason: z.string().optional(),
+          updatedInput: z.record(z.string(), z.unknown()).optional(),
+          additionalContext: z.string().optional(),
+        }),
+        z.object({
+          hookEventName: z.literal('UserPromptSubmit'),
+          additionalContext: z.string().optional(),
+        }),
+        z.object({
+          hookEventName: z.literal('SessionStart'),
+          additionalContext: z.string().optional(),
+          initialUserMessage: z.string().optional(),
+          watchPaths: z
+            .array(z.string())
+            .describe('Absolute paths to watch for FileChanged hooks')
+            .optional(),
+        }),
+        z.object({
+          hookEventName: z.literal('Setup'),
+          additionalContext: z.string().optional(),
+        }),
+        z.object({
+          hookEventName: z.literal('SubagentStart'),
+          additionalContext: z.string().optional(),
+        }),
+        z.object({
+          hookEventName: z.literal('PostToolUse'),
+          additionalContext: z.string().optional(),
+          updatedMCPToolOutput: z
+            .unknown()
+            .describe('Updates the output for MCP tools')
+            .optional(),
+        }),
+        z.object({
+          hookEventName: z.literal('PostToolUseFailure'),
+          additionalContext: z.string().optional(),
+        }),
+        z.object({
+          hookEventName: z.literal('PermissionDenied'),
+          retry: z.boolean().optional(),
+        }),
+        z.object({
+          hookEventName: z.literal('Notification'),
+          additionalContext: z.string().optional(),
+        }),
+        z.object({
+          hookEventName: z.literal('PermissionRequest'),
+          decision: z.union([
+            z.object({
+              behavior: z.literal('allow'),
+              updatedInput: z.record(z.string(), z.unknown()).optional(),
+              updatedPermissions: z.array(permissionUpdateSchema()).optional(),
+            }),
+            z.object({
+              behavior: z.literal('deny'),
+              message: z.string().optional(),
+              interrupt: z.boolean().optional(),
+            }),
+          ]),
+        }),
+        z.object({
+          hookEventName: z.literal('Elicitation'),
+          action: z.enum(['accept', 'decline', 'cancel']).optional(),
+          content: z.record(z.string(), z.unknown()).optional(),
+        }),
+        z.object({
+          hookEventName: z.literal('ElicitationResult'),
+          action: z.enum(['accept', 'decline', 'cancel']).optional(),
+          content: z.record(z.string(), z.unknown()).optional(),
+        }),
+        z.object({
+          hookEventName: z.literal('CwdChanged'),
+          watchPaths: z
+            .array(z.string())
+            .describe('Absolute paths to watch for FileChanged hooks')
+            .optional(),
+        }),
+        z.object({
+          hookEventName: z.literal('FileChanged'),
+          watchPaths: z
+            .array(z.string())
+            .describe('Absolute paths to watch for FileChanged hooks')
+            .optional(),
+        }),
+        z.object({
+          hookEventName: z.literal('WorktreeCreate'),
+          worktreePath: z.string(),
+        }),
+      ])
+      .optional(),
+  }),
+)
+
+// Zod schema for hook JSON output validation
+export const hookJSONOutputSchema = lazySchema(() => {
+  // Async hook response schema
+  const asyncHookResponseSchema = z.object({
+    async: z.literal(true),
+    asyncTimeout: z.number().optional(),
+  })
+  return z.union([asyncHookResponseSchema, syncHookResponseSchema()])
+})
+
+// Infer the TypeScript type from the schema
+type SchemaHookJSONOutput = z.infer<ReturnType<typeof hookJSONOutputSchema>>
+
+// Type guard function to check if response is sync
+export function isSyncHookJSONOutput(
+  json: HookJSONOutput,
+): json is SyncHookJSONOutput {
+  return !('async' in json && json.async === true)
+}
+
+// Type guard function to check if response is async
+export function isAsyncHookJSONOutput(
+  json: HookJSONOutput,
+): json is AsyncHookJSONOutput {
+  return 'async' in json && json.async === true
+}
+
+// Compile-time assertion that SDK and Zod types match
+import type { IsEqual } from 'type-fest'
+type Assert<T extends true> = T
+type _assertSDKTypesMatch = Assert<
+  IsEqual<SchemaHookJSONOutput, HookJSONOutput>
+>
+
+/** Context passed to callback hooks for state access */
+export type HookCallbackContext = {
+  getAppState: () => AppState
+  updateAttributionState: (
+    updater: (prev: AttributionState) => AttributionState,
+  ) => void
+}
+
+/** Hook that is a callback. */
+export type HookCallback = {
+  type: 'callback'
+  callback: (
+    input: HookInput,
+    toolUseID: string | null,
+    abort: AbortSignal | undefined,
+    /** Hook index for SessionStart hooks to compute CLAUDE_ENV_FILE path */
+    hookIndex?: number,
+    /** Optional context for accessing app state */
+    context?: HookCallbackContext,
+  ) => Promise<HookJSONOutput>
+  /** Timeout in seconds for this hook */
+  timeout?: number
+  /** Internal hooks (e.g. session file access analytics) are excluded from tengu_run_hook metrics */
+  internal?: boolean
+}
+
+export type HookCallbackMatcher = {
+  matcher?: string
+  hooks: HookCallback[]
+  pluginName?: string
+}
+
+export type HookProgress = {
+  type: 'hook_progress'
+  hookEvent: HookEvent
+  hookName: string
+  command: string
+  promptText?: string
+  statusMessage?: string
+}
+
+export type HookBlockingError = {
+  blockingError: string
+  command: string
+}
+
+export type PermissionRequestResult =
+  | {
+      behavior: 'allow'
+      updatedInput?: Record<string, unknown>
+      updatedPermissions?: PermissionUpdate[]
+    }
+  | {
+      behavior: 'deny'
+      message?: string
+      interrupt?: boolean
+    }
+
+export type HookResult = {
+  message?: Message
+  systemMessage?: Message
+  blockingError?: HookBlockingError
+  outcome: 'success' | 'blocking' | 'non_blocking_error' | 'cancelled'
+  preventContinuation?: boolean
+  stopReason?: string
+  permissionBehavior?: 'ask' | 'deny' | 'allow' | 'passthrough'
+  hookPermissionDecisionReason?: string
+  additionalContext?: string
+  initialUserMessage?: string
+  updatedInput?: Record<string, unknown>
+  updatedMCPToolOutput?: unknown
+  permissionRequestResult?: PermissionRequestResult
+  retry?: boolean
+}
+
+export type AggregatedHookResult = {
+  message?: Message
+  blockingErrors?: HookBlockingError[]
+  preventContinuation?: boolean
+  stopReason?: string
+  hookPermissionDecisionReason?: string
+  permissionBehavior?: PermissionResult['behavior']
+  additionalContexts?: string[]
+  initialUserMessage?: string
+  updatedInput?: Record<string, unknown>
+  updatedMCPToolOutput?: unknown
+  permissionRequestResult?: PermissionRequestResult
+  retry?: boolean
+}

package/types/ids.ts

@@ -0,0 +1,44 @@
+/**
+ * Branded types for session and agent IDs.
+ * These prevent accidentally mixing up session IDs and agent IDs at compile time.
+ */
+
+/**
+ * A session ID uniquely identifies a Claude Code session.
+ * Returned by getSessionId().
+ */
+export type SessionId = string & { readonly __brand: 'SessionId' }
+
+/**
+ * An agent ID uniquely identifies a subagent within a session.
+ * Returned by createAgentId().
+ * When present, indicates the context is a subagent (not the main session).
+ */
+export type AgentId = string & { readonly __brand: 'AgentId' }
+
+/**
+ * Cast a raw string to SessionId.
+ * Use sparingly - prefer getSessionId() when possible.
+ */
+export function asSessionId(id: string): SessionId {
+  return id as SessionId
+}
+
+/**
+ * Cast a raw string to AgentId.
+ * Use sparingly - prefer createAgentId() when possible.
+ */
+export function asAgentId(id: string): AgentId {
+  return id as AgentId
+}
+
+const AGENT_ID_PATTERN = /^a(?:.+-)?[0-9a-f]{16}$/
+
+/**
+ * Validate and brand a string as AgentId.
+ * Matches the format produced by createAgentId(): `a` + optional `<label>-` + 16 hex chars.
+ * Returns null if the string doesn't match (e.g. teammate names, team-addressing).
+ */
+export function toAgentId(s: string): AgentId | null {
+  return AGENT_ID_PATTERN.test(s) ? (s as AgentId) : null
+}

package/types/logs.ts

@@ -0,0 +1,330 @@
+import type { UUID } from 'crypto'
+import type { FileHistorySnapshot } from 'src/utils/fileHistory.js'
+import type { ContentReplacementRecord } from 'src/utils/toolResultStorage.js'
+import type { AgentId } from './ids.js'
+import type { Message } from './message.js'
+import type { QueueOperationMessage } from './messageQueueTypes.js'
+
+export type SerializedMessage = Message & {
+  cwd: string
+  userType: string
+  entrypoint?: string // CLAUDE_CODE_ENTRYPOINT — distinguishes cli/sdk-ts/sdk-py/etc.
+  sessionId: string
+  timestamp: string
+  version: string
+  gitBranch?: string
+  slug?: string // Session slug for files like plans (used for resume)
+}
+
+export type LogOption = {
+  date: string
+  messages: SerializedMessage[]
+  fullPath?: string
+  value: number
+  created: Date
+  modified: Date
+  firstPrompt: string
+  messageCount: number
+  fileSize?: number // File size in bytes (for display)
+  isSidechain: boolean
+  isLite?: boolean // True for lite logs (messages not loaded)
+  sessionId?: string // Session ID for lite logs
+  teamName?: string // Team name if this is a spawned agent session
+  agentName?: string // Agent's custom name (from /rename or swarm)
+  agentColor?: string // Agent's color (from /rename or swarm)
+  agentSetting?: string // Agent definition used (from --agent flag or settings.agent)
+  isTeammate?: boolean // Whether this session was created by a swarm teammate
+  leafUuid?: UUID // If given, this uuid must appear in the DB
+  summary?: string // Optional conversation summary
+  customTitle?: string // Optional user-set custom title
+  tag?: string // Optional tag for the session (searchable in /resume)
+  fileHistorySnapshots?: FileHistorySnapshot[] // Optional file history snapshots
+  attributionSnapshots?: AttributionSnapshotMessage[] // Optional attribution snapshots
+  contextCollapseCommits?: ContextCollapseCommitEntry[] // Ordered — commit B may reference commit A's summary
+  contextCollapseSnapshot?: ContextCollapseSnapshotEntry // Last-wins — staged queue + spawn state
+  gitBranch?: string // Git branch at the end of the session
+  projectPath?: string // Original project directory path
+  prNumber?: number // GitHub PR number linked to this session
+  prUrl?: string // Full URL to the linked PR
+  prRepository?: string // Repository in "owner/repo" format
+  mode?: 'coordinator' | 'normal' // Session mode for coordinator/normal detection
+  worktreeSession?: PersistedWorktreeSession | null // Worktree state at session end (null = exited, undefined = never entered)
+  contentReplacements?: ContentReplacementRecord[] // Replacement decisions for resume reconstruction
+}
+
+export type SummaryMessage = {
+  type: 'summary'
+  leafUuid: UUID
+  summary: string
+}
+
+export type CustomTitleMessage = {
+  type: 'custom-title'
+  sessionId: UUID
+  customTitle: string
+}
+
+/**
+ * AI-generated session title. Distinct from CustomTitleMessage so that:
+ * - User renames (custom-title) always win over AI titles in read preference
+ * - reAppendSessionMetadata never re-appends AI titles (they're ephemeral/
+ *   regeneratable; re-appending would clobber user renames on resume)
+ * - VS Code's onlyIfNoCustomTitle CAS check only matches user titles,
+ *   allowing AI to overwrite its own previous AI title but not user titles
+ */
+export type AiTitleMessage = {
+  type: 'ai-title'
+  sessionId: UUID
+  aiTitle: string
+}
+
+export type LastPromptMessage = {
+  type: 'last-prompt'
+  sessionId: UUID
+  lastPrompt: string
+}
+
+/**
+ * Periodic fork-generated summary of what the agent is currently doing.
+ * Written every min(5 steps, 2min) by forking the main thread mid-turn so
+ * `claude ps` can show something more useful than the last user prompt
+ * (which is often "ok go" or "fix it").
+ */
+export type TaskSummaryMessage = {
+  type: 'task-summary'
+  sessionId: UUID
+  summary: string
+  timestamp: string
+}
+
+export type TagMessage = {
+  type: 'tag'
+  sessionId: UUID
+  tag: string
+}
+
+export type AgentNameMessage = {
+  type: 'agent-name'
+  sessionId: UUID
+  agentName: string
+}
+
+export type AgentColorMessage = {
+  type: 'agent-color'
+  sessionId: UUID
+  agentColor: string
+}
+
+export type AgentSettingMessage = {
+  type: 'agent-setting'
+  sessionId: UUID
+  agentSetting: string
+}
+
+/**
+ * PR link message stored in session transcript.
+ * Links a session to a GitHub pull request for tracking and navigation.
+ */
+export type PRLinkMessage = {
+  type: 'pr-link'
+  sessionId: UUID
+  prNumber: number
+  prUrl: string
+  prRepository: string // e.g., "owner/repo"
+  timestamp: string // ISO timestamp when linked
+}
+
+export type ModeEntry = {
+  type: 'mode'
+  sessionId: UUID
+  mode: 'coordinator' | 'normal'
+}
+
+/**
+ * Worktree session state persisted to the transcript for resume.
+ * Subset of WorktreeSession from utils/worktree.ts — excludes ephemeral
+ * fields (creationDurationMs, usedSparsePaths) that are only used for
+ * first-run analytics.
+ */
+export type PersistedWorktreeSession = {
+  originalCwd: string
+  worktreePath: string
+  worktreeName: string
+  worktreeBranch?: string
+  originalBranch?: string
+  originalHeadCommit?: string
+  sessionId: string
+  tmuxSessionName?: string
+  hookBased?: boolean
+}
+
+/**
+ * Records whether the session is currently inside a worktree created by
+ * EnterWorktree or --worktree. Last-wins: an enter writes the session,
+ * an exit writes null. On --resume, restored only if the worktreePath
+ * still exists on disk (the /exit dialog may have removed it).
+ */
+export type WorktreeStateEntry = {
+  type: 'worktree-state'
+  sessionId: UUID
+  worktreeSession: PersistedWorktreeSession | null
+}
+
+/**
+ * Records content blocks whose in-context representation was replaced with a
+ * smaller stub (the full content was persisted elsewhere). Replayed on resume
+ * for prompt cache stability. Written once per enforcement pass that replaces
+ * at least one block. When agentId is set, the record belongs to a subagent
+ * sidechain (AgentTool resume reads these); when absent, it's main-thread
+ * (/resume reads these).
+ */
+export type ContentReplacementEntry = {
+  type: 'content-replacement'
+  sessionId: UUID
+  agentId?: AgentId
+  replacements: ContentReplacementRecord[]
+}
+
+export type FileHistorySnapshotMessage = {
+  type: 'file-history-snapshot'
+  messageId: UUID
+  snapshot: FileHistorySnapshot
+  isSnapshotUpdate: boolean
+}
+
+/**
+ * Per-file attribution state tracking Claude's character contributions.
+ */
+export type FileAttributionState = {
+  contentHash: string // SHA-256 hash of file content
+  claudeContribution: number // Characters written by Claude
+  mtime: number // File modification time
+}
+
+/**
+ * Attribution snapshot message stored in session transcript.
+ * Tracks character-level contributions by Claude for commit attribution.
+ */
+export type AttributionSnapshotMessage = {
+  type: 'attribution-snapshot'
+  messageId: UUID
+  surface: string // Client surface (cli, ide, web, api)
+  fileStates: Record<string, FileAttributionState>
+  promptCount?: number // Total prompts in session
+  promptCountAtLastCommit?: number // Prompts at last commit
+  permissionPromptCount?: number // Total permission prompts shown
+  permissionPromptCountAtLastCommit?: number // Permission prompts at last commit
+  escapeCount?: number // Total ESC presses (cancelled permission prompts)
+  escapeCountAtLastCommit?: number // ESC presses at last commit
+}
+
+export type TranscriptMessage = SerializedMessage & {
+  parentUuid: UUID | null
+  logicalParentUuid?: UUID | null // Preserves logical parent when parentUuid is nullified for session breaks
+  isSidechain: boolean
+  gitBranch?: string
+  agentId?: string // Agent ID for sidechain transcripts to enable resuming agents
+  teamName?: string // Team name if this is a spawned agent session
+  agentName?: string // Agent's custom name (from /rename or swarm)
+  agentColor?: string // Agent's color (from /rename or swarm)
+  promptId?: string // Correlates with OTel prompt.id for user prompt messages
+}
+
+export type SpeculationAcceptMessage = {
+  type: 'speculation-accept'
+  timestamp: string
+  timeSavedMs: number
+}
+
+/**
+ * Persisted context-collapse commit. The archived messages themselves are
+ * NOT persisted — they're already in the transcript as ordinary user/
+ * assistant messages. We only persist enough to reconstruct the splice
+ * instruction (boundary uuids) and the summary placeholder (which is NOT
+ * in the transcript because it's never yielded to the REPL).
+ *
+ * On restore, the store reconstructs CommittedCollapse with archived=[];
+ * projectView lazily fills the archive the first time it finds the span.
+ *
+ * Discriminator is obfuscated to match the gate name. sessionStorage.ts
+ * isn't feature-gated (it's the generic transcript plumbing used by every
+ * entry type), so a descriptive string here would leak into external builds
+ * via the appendEntry dispatch / loadTranscriptFile parser even though
+ * nothing in an external build ever writes or reads this entry.
+ */
+export type ContextCollapseCommitEntry = {
+  type: 'marble-origami-commit'
+  sessionId: UUID
+  /** 16-digit collapse ID. Max across entries reseeds the ID counter. */
+  collapseId: string
+  /** The summary placeholder's uuid — registerSummary() needs it. */
+  summaryUuid: string
+  /** Full <collapsed id="...">text</collapsed> string for the placeholder. */
+  summaryContent: string
+  /** Plain summary text for ctx_inspect. */
+  summary: string
+  /** Span boundaries — projectView finds these in the resumed Message[]. */
+  firstArchivedUuid: string
+  lastArchivedUuid: string
+}
+
+/**
+ * Snapshot of the staged queue and spawn trigger state. Unlike commits
+ * (append-only, replay-all), snapshots are last-wins — only the most
+ * recent snapshot entry is applied on restore. Written after every
+ * ctx-agent spawn resolves (when staged contents may have changed).
+ *
+ * Staged boundaries are UUIDs (session-stable), not collapse IDs (which
+ * reset with the uuidToId bimap). Restoring a staged span issues fresh
+ * collapse IDs for those messages on the next decorate/display, but the
+ * span itself resolves correctly.
+ */
+export type ContextCollapseSnapshotEntry = {
+  type: 'marble-origami-snapshot'
+  sessionId: UUID
+  staged: Array<{
+    startUuid: string
+    endUuid: string
+    summary: string
+    risk: number
+    stagedAt: number
+  }>
+  /** Spawn trigger state — so the +interval clock picks up where it left off. */
+  armed: boolean
+  lastSpawnTokens: number
+}
+
+export type Entry =
+  | TranscriptMessage
+  | SummaryMessage
+  | CustomTitleMessage
+  | AiTitleMessage
+  | LastPromptMessage
+  | TaskSummaryMessage
+  | TagMessage
+  | AgentNameMessage
+  | AgentColorMessage
+  | AgentSettingMessage
+  | PRLinkMessage
+  | FileHistorySnapshotMessage
+  | AttributionSnapshotMessage
+  | QueueOperationMessage
+  | SpeculationAcceptMessage
+  | ModeEntry
+  | WorktreeStateEntry
+  | ContentReplacementEntry
+  | ContextCollapseCommitEntry
+  | ContextCollapseSnapshotEntry
+
+export function sortLogs(logs: LogOption[]): LogOption[] {
+  return logs.sort((a, b) => {
+    // Sort by modified date (newest first)
+    const modifiedDiff = b.modified.getTime() - a.modified.getTime()
+    if (modifiedDiff !== 0) {
+      return modifiedDiff
+    }
+
+    // If modified dates are equal, sort by created date (newest first)
+    return b.created.getTime() - a.created.getTime()
+  })
+}