// apps/cli/src/agent/types.ts

import type { Message, ToolContext } from '../shared/index.ts'

export type SubAgentType = 'general' | 'explore' | 'plan' | 'code-review'

export interface AgentFrontmatter {
  name: string
  description: string
  tools?: string // comma-separated allowlist
  disallowedTools?: string
  model?: string // 'sonnet' | 'opus' | 'haiku' | 'inherit' | full model ID
  // Hand-written union rather than `PermissionMode`: it also admits the legacy
  // `'bypass'` alias that `resolveAgentMode` normalizes. Adding a mode to
  // `PermissionMode` does **not** fail to compile here — keep the two in step.
  permissionMode?: 'default' | 'acceptEdits' | 'bypass' | 'plan' | 'auto' | 'bypassPermissions'
  maxTurns?: number
  skills?: string
  background?: boolean
  memory?: 'user' | 'project' | 'local' // agent memory scope
}

export interface AgentDefinition {
  name: string
  description: string
  systemPrompt: string // markdown body after frontmatter
  tools?: string
  disallowedTools?: string
  model: string
  permissionMode: string
  maxTurns?: number
  skills?: string[]
  /** Force background (true) or sync (false) execution. Unset inherits the tool default. */
  background?: boolean
  source: 'builtin' | 'project' | 'user'
  filePath?: string
  memory?: 'user' | 'project' | 'local' // agent memory scope
}

export interface SubAgentOptions {
  type?: SubAgentType
  agentDef?: AgentDefinition
  systemPrompt?: string
  allowedTools?: string[]
  modelOverride?: string
  /** Maximum tool-calling turns (default: 5) to prevent infinite loops. */
  maxTurns?: number
  /** When true, execute in background and return immediately with a task ID. */
  runInBackground?: boolean
  /** Optional callback for streaming progress chunks during background execution. */
  onProgress?: (chunk: string) => void
  /** Optional callback reporting cumulative token usage (input + output) from the API stream. */
  onTokenUsage?: (totalTokens: number) => void
  /** When set, tool executions use this path as cwd (git worktree isolation). */
  worktreePath?: string
  /** Seed the sub-agent with a parent conversation prefix (e.g., fork inheritance). */
  inheritContext?: { messages: Message[] }
  /**
   * Who authored the prompt. `'script'` marks text computed by a workflow
   * script — which is not the user speaking, even though it arrives as the
   * sub-agent's opening user turn. Defaults to `'user'`.
   */
  promptOrigin?: 'user' | 'script'
  /** CRSI: when false, skip pattern analysis after agent execution. Default true. */
  autoPatternAnalysis?: boolean
  /**
   * The caller's tool context, inherited by the sub-agent's own tool calls so
   * that services only the caller holds (skills, agents, artifacts, rules) keep
   * working one level down. The sub-agent's own per-run fields win over whatever
   * is passed through here, so only the services need to be supplied.
   */
  toolContext?: Partial<ToolContext>
}