@cuongtran001/kanna 1.2.0 → 1.3.1

package/src/shared/subagent-types.ts

@@ -0,0 +1,198 @@
+// Subagent domain types: definitions, runtime snapshots, loop progress.
+// Extracted from types.ts to keep the barrel lean.
+// All external consumers importing from "../shared/types" continue to work unchanged.
+
+import type { AgentProvider } from "./core-types"
+import type { ClaudeModelOptions, CodexModelOptions } from "./provider-model-types"
+import type { TranscriptEntry } from "./transcript-types"
+
+export type SubagentContextScope = "previous-assistant-reply" | "full-transcript"
+
+export type SubagentTriggerMode = "auto" | "manual"
+
+export interface SubagentRestriction {
+  workingDir?: string
+  allowedPaths?: string[]
+}
+
+export interface Subagent {
+  id: string
+  name: string
+  description?: string
+  provider: AgentProvider
+  model: string
+  modelOptions: ClaudeModelOptions | CodexModelOptions
+  systemPrompt: string
+  contextScope: SubagentContextScope
+  triggerMode: SubagentTriggerMode
+  workingDir?: string
+  allowedPaths?: string[]
+  // Per-subagent agentic-turn bound — the analog of Claude Code's agent
+  // frontmatter `maxTurns`. Unset = unbounded (Claude Code's default).
+  // Claude-SDK runs pass it natively to query() (graceful stop, output kept);
+  // PTY/Codex runs get a host-side tool-call-count backstop (hard abort).
+  maxTurns?: number
+  createdAt: number
+  updatedAt: number
+}
+
+export interface SubagentInput {
+  name: string
+  description?: string
+  provider: AgentProvider
+  model: string
+  modelOptions: ClaudeModelOptions | CodexModelOptions
+  systemPrompt: string
+  contextScope: SubagentContextScope
+  triggerMode?: SubagentTriggerMode
+  workingDir?: string
+  allowedPaths?: string[]
+  maxTurns?: number
+}
+
+export interface SubagentPatch {
+  name?: string
+  description?: string | null
+  provider?: AgentProvider
+  model?: string
+  modelOptions?: Partial<ClaudeModelOptions> | Partial<CodexModelOptions>
+  systemPrompt?: string
+  contextScope?: SubagentContextScope
+  triggerMode?: SubagentTriggerMode
+  workingDir?: string | null
+  allowedPaths?: string[] | null
+  maxTurns?: number | null
+}
+
+export type SubagentValidationErrorCode =
+  | "EMPTY_NAME"
+  | "INVALID_CHAR"
+  | "RESERVED_NAME"
+  | "DUPLICATE_NAME"
+  | "TOO_LONG"
+  | "NOT_FOUND"
+  | "RESTRICTION_NOT_SUPPORTED"
+  | "INVALID_PATH"
+  | "PATH_ESCAPE"
+  | "EMPTY_ALLOWED_PATHS"
+
+export interface SubagentValidationError {
+  code: SubagentValidationErrorCode
+  message: string
+}
+
+export type SubagentErrorCode =
+  | "AUTH_REQUIRED"
+  | "UNKNOWN_SUBAGENT"
+  | "MANUAL_ONLY"
+  | "LOOP_DETECTED"
+  | "DEPTH_EXCEEDED"
+  | "TIMEOUT"
+  | "MAX_TURNS"
+  | "PROVIDER_ERROR"
+  | "INTERRUPTED"
+  | "USER_CANCELLED"
+  | "CAP_EXCEEDED"
+  | "NO_LIVE_SESSION"
+
+export type SubagentRunStatus = "running" | "completed" | "failed" | "cancelled"
+
+export interface ProviderUsage {
+  inputTokens?: number
+  outputTokens?: number
+  cachedInputTokens?: number
+  costUsd?: number
+}
+
+export interface SubagentPendingTool {
+  toolUseId: string
+  toolKind: "ask_user_question" | "exit_plan_mode"
+  input: Record<string, unknown>
+  requestedAt: number
+}
+
+export interface SubagentRunSnapshot {
+  runId: string
+  chatId: string
+  subagentId: string | null
+  subagentName: string
+  /**
+   * Short human label for this run, derived from the first line of the spawn
+   * prompt (e.g. "Migrate useKannaState.ts"). Null for runs started before this
+   * field existed or by error paths that never carried a prompt. Drives the
+   * Loop Progress panel rows so each round reads as the chunk it worked on
+   * rather than an opaque run id.
+   */
+  label: string | null
+  provider: AgentProvider
+  model: string
+  status: SubagentRunStatus
+  parentUserMessageId: string
+  parentRunId: string | null
+  depth: number
+  startedAt: number
+  finishedAt: number | null
+  finalText: string | null
+  error: { code: SubagentErrorCode; message: string } | null
+  usage: ProviderUsage | null
+  /**
+   * Every TranscriptEntry the subagent produced, in arrival order. Includes
+   * tool_call, tool_result, system_init, account_info, result. assistant_text
+   * entries also live here in addition to being concatenated into finalText
+   * via subagent_message_delta — clients should prefer entries[] for rich
+   * rendering, finalText only as a quick text-only summary.
+   */
+  entries: TranscriptEntry[]
+  /**
+   * Set while the subagent is awaiting a user response to an
+   * interactive tool call (AskUserQuestion / ExitPlanMode). Null
+   * otherwise. The orchestrator's wall-clock timeout is paused while
+   * this is non-null.
+   */
+  pendingTool: SubagentPendingTool | null
+}
+
+export type LoopRowStatus = "pending" | "running" | "done" | "failed"
+
+export interface LoopRow {
+  runId: string
+  label: string
+  status: LoopRowStatus
+  startedAt: number
+  finishedAt: number | null
+}
+
+export interface LoopRateLimitInfo {
+  /** The live auto-continue schedule id, so the panel's Resume action can accept it. */
+  scheduleId: string
+  /** epoch ms the usage limit resets (and the resume is/would be scheduled for) */
+  resetAt: number
+  tz: string
+  /**
+   * true  → an auto-continue is already scheduled to fire at `resetAt`
+   *         (the loop resumes on its own).
+   * false → the resume is only proposed and waits on the user
+   *         (auto-resume setting off) — render a "Resume" action.
+   */
+  scheduled: boolean
+}
+
+export interface LoopProgressSnapshot {
+  chatId: string
+  /** Whether a loop is currently armed for this chat. */
+  armed: boolean
+  /** Latest first — most recent delegation at the top, mirroring PROGRESS.md. */
+  rows: LoopRow[]
+  /** Non-null while the loop is paused on a Claude usage limit. */
+  rateLimit: LoopRateLimitInfo | null
+}
+
+// Type guards
+
+export function isSubagentContextScope(value: string): value is SubagentContextScope {
+  return value === "previous-assistant-reply" || value === "full-transcript"
+}
+
+export function isSubagentTriggerMode(value: string): value is SubagentTriggerMode {
+  return value === "auto" || value === "manual"
+}

package/src/shared/tool-call-types.ts

@@ -0,0 +1,314 @@
+/**
+ * Tool call shapes (raw + hydrated) — extracted from shared/types.ts.
+ * Completely self-contained: no imports from types.ts.
+ * Imported via the re-export barrel in types.ts; all external consumers
+ * continue to import from "../shared/types" unchanged.
+ */
+
+// ---------------------------------------------------------------------------
+// AskUserQuestion / TodoWrite payload primitives
+// ---------------------------------------------------------------------------
+
+export interface AskUserQuestionOption {
+  label: string
+  description?: string
+}
+
+export interface AskUserQuestionItem {
+  id?: string
+  question: string
+  header?: string
+  options?: AskUserQuestionOption[]
+  multiSelect?: boolean
+}
+
+export type AskUserQuestionAnswerMap = Record<string, string[]>
+
+export interface TodoItem {
+  content: string
+  status: "pending" | "in_progress" | "completed"
+  activeForm: string
+}
+
+// ---------------------------------------------------------------------------
+// Raw tool call shapes
+// ---------------------------------------------------------------------------
+
+interface ToolCallBase<TKind extends string, TInput> {
+  kind: "tool"
+  toolKind: TKind
+  toolName: string
+  toolId: string
+  input: TInput
+  rawInput?: Record<string, unknown>
+}
+
+export interface AskUserQuestionToolCall
+  extends ToolCallBase<"ask_user_question", { questions: AskUserQuestionItem[] }> { }
+
+export interface ExitPlanModeToolCall
+  extends ToolCallBase<"exit_plan_mode", { plan?: string; summary?: string }> { }
+
+export interface TodoWriteToolCall
+  extends ToolCallBase<"todo_write", { todos: TodoItem[] }> { }
+
+export interface SkillToolCall
+  extends ToolCallBase<"skill", { skill: string }> { }
+
+export interface GlobToolCall
+  extends ToolCallBase<"glob", { pattern: string }> { }
+
+export interface GrepToolCall
+  extends ToolCallBase<"grep", { pattern: string; outputMode?: string }> { }
+
+export interface BashToolCall
+  extends ToolCallBase<"bash", { command: string; description?: string; timeoutMs?: number; runInBackground?: boolean }> { }
+
+export interface WebSearchToolCall
+  extends ToolCallBase<"web_search", { query: string }> { }
+
+export interface ReadFileToolCall
+  extends ToolCallBase<"read_file", { filePath: string }> { }
+
+export interface WriteFileToolCall
+  extends ToolCallBase<"write_file", { filePath: string; content: string }> { }
+
+export interface EditFileToolCall
+  extends ToolCallBase<"edit_file", { filePath: string; oldString: string; newString: string }> { }
+
+export interface DeleteFileToolCall
+  extends ToolCallBase<"delete_file", { filePath: string; content: string }> { }
+
+export interface SubagentTaskToolCall
+  extends ToolCallBase<"subagent_task", { subagentType?: string }> { }
+
+export interface McpGenericToolCall
+  extends ToolCallBase<"mcp_generic", { server: string; tool: string; payload: Record<string, unknown> }> { }
+
+export interface OfferDownloadToolCall
+  extends ToolCallBase<"offer_download", { path: string; label?: string }> { }
+
+export interface OfferDownloadToolResult {
+  contentUrl: string
+  relativePath: string
+  fileName: string
+  displayName: string
+  size: number
+  mimeType?: string
+}
+
+export interface PreviewFileToolCall
+  extends ToolCallBase<"preview_file", { path: string; label?: string }> { }
+
+export interface PreviewFileToolResult {
+  contentUrl: string
+  relativePath: string
+  fileName: string
+  displayName: string
+  size: number
+  mimeType: string
+}
+
+export type ImageGenerationStatus = "in_progress" | "completed" | "failed"
+
+export interface ImageGenerationToolCall
+  extends ToolCallBase<"image_generation", { revisedPrompt: string | null; status: ImageGenerationStatus }> { }
+
+export interface ImageGenerationToolResult {
+  contentUrl: string
+  relativePath: string
+  fileName: string
+}
+
+export interface UnknownToolCall
+  extends ToolCallBase<"unknown_tool", { payload: Record<string, unknown> }> { }
+
+export interface WorkflowToolCall
+  extends ToolCallBase<"workflow", { name?: string; description?: string; scriptPath?: string }> { }
+
+export type NormalizedToolCall =
+  | AskUserQuestionToolCall
+  | ExitPlanModeToolCall
+  | TodoWriteToolCall
+  | SkillToolCall
+  | GlobToolCall
+  | GrepToolCall
+  | BashToolCall
+  | WebSearchToolCall
+  | ReadFileToolCall
+  | WriteFileToolCall
+  | EditFileToolCall
+  | DeleteFileToolCall
+  | SubagentTaskToolCall
+  | McpGenericToolCall
+  | OfferDownloadToolCall
+  | PreviewFileToolCall
+  | ImageGenerationToolCall
+  | WorkflowToolCall
+  | UnknownToolCall
+
+// ---------------------------------------------------------------------------
+// Hydrated tool call shapes
+// ---------------------------------------------------------------------------
+
+export interface HydratedToolCallBase<TKind extends string, TInput, TResult> {
+  id: string
+  messageId?: string
+  hidden?: boolean
+  kind: "tool"
+  toolKind: TKind
+  toolName: string
+  toolId: string
+  input: TInput
+  result?: TResult
+  rawResult?: string | Record<string, unknown> | readonly unknown[] | null
+  isError?: boolean
+  /**
+   * Set when the underlying tool_result entry was persisted to disk
+   * via the subagent payload cap. Mirrored from
+   * ToolResultEntry.persisted during hydration.
+   */
+  persisted?: {
+    filePath: string
+    originalSize: number
+    isJson: boolean
+    truncated: true
+  }
+  timestamp: string
+}
+
+export interface AskUserQuestionToolResult {
+  answers: AskUserQuestionAnswerMap
+  discarded?: boolean
+}
+
+export interface ExitPlanModeToolResult {
+  confirmed?: boolean
+  clearContext?: boolean
+  message?: string
+  discarded?: boolean
+}
+
+export type HydratedAskUserQuestionToolCall =
+  HydratedToolCallBase<"ask_user_question", AskUserQuestionToolCall["input"], AskUserQuestionToolResult>
+
+export type HydratedExitPlanModeToolCall =
+  HydratedToolCallBase<"exit_plan_mode", ExitPlanModeToolCall["input"], ExitPlanModeToolResult>
+
+export type HydratedTodoWriteToolCall =
+  HydratedToolCallBase<"todo_write", TodoWriteToolCall["input"], unknown>
+
+export type HydratedSkillToolCall =
+  HydratedToolCallBase<"skill", SkillToolCall["input"], unknown>
+
+export type HydratedGlobToolCall =
+  HydratedToolCallBase<"glob", GlobToolCall["input"], unknown>
+
+export type HydratedGrepToolCall =
+  HydratedToolCallBase<"grep", GrepToolCall["input"], unknown>
+
+export type HydratedBashToolCall =
+  HydratedToolCallBase<"bash", BashToolCall["input"], unknown>
+
+export type HydratedWebSearchToolCall =
+  HydratedToolCallBase<"web_search", WebSearchToolCall["input"], unknown>
+
+export interface ReadFileTextBlock {
+  type: "text"
+  text: string
+}
+
+export interface ReadFileImageBlock {
+  type: "image"
+  data: string
+  mimeType?: string
+}
+
+export interface ReadFileToolResult {
+  content: string
+  blocks?: Array<ReadFileTextBlock | ReadFileImageBlock>
+}
+
+export type HydratedReadFileToolCall =
+  HydratedToolCallBase<"read_file", ReadFileToolCall["input"], ReadFileToolResult | string>
+
+export type HydratedWriteFileToolCall =
+  HydratedToolCallBase<"write_file", WriteFileToolCall["input"], unknown>
+
+export type HydratedEditFileToolCall =
+  HydratedToolCallBase<"edit_file", EditFileToolCall["input"], unknown>
+
+export type HydratedDeleteFileToolCall =
+  HydratedToolCallBase<"delete_file", DeleteFileToolCall["input"], unknown>
+
+export interface SubagentToolStats {
+  readCount?: number
+  searchCount?: number
+  bashCount?: number
+  editFileCount?: number
+  linesAdded?: number
+  linesRemoved?: number
+  otherToolCount?: number
+}
+
+// Parsed from the `Agent`/`Task` tool_result's top-level `toolUseResult`
+// sidecar (camelCase, written by claude-code into the transcript JSONL and
+// preserved on the tool_result entry's debugRaw). All fields optional — the
+// SDK driver / older transcripts / in-flight calls may omit it entirely.
+export interface SubagentTaskResult {
+  agentId?: string
+  agentType?: string
+  status?: string
+  totalTokens?: number
+  totalDurationMs?: number
+  totalToolUseCount?: number
+  toolStats?: SubagentToolStats
+  content?: string
+}
+
+export type HydratedSubagentTaskToolCall =
+  HydratedToolCallBase<"subagent_task", SubagentTaskToolCall["input"], SubagentTaskResult>
+
+export type HydratedMcpGenericToolCall =
+  HydratedToolCallBase<"mcp_generic", McpGenericToolCall["input"], unknown>
+
+export type HydratedOfferDownloadToolCall =
+  HydratedToolCallBase<"offer_download", OfferDownloadToolCall["input"], OfferDownloadToolResult>
+
+export type HydratedPreviewFileToolCall =
+  HydratedToolCallBase<"preview_file", PreviewFileToolCall["input"], PreviewFileToolResult>
+
+export type HydratedImageGenerationToolCall =
+  HydratedToolCallBase<"image_generation", ImageGenerationToolCall["input"], ImageGenerationToolResult>
+
+export interface WorkflowToolResult {
+  taskId?: string
+  text: string
+}
+
+export type HydratedWorkflowToolCall =
+  HydratedToolCallBase<"workflow", WorkflowToolCall["input"], WorkflowToolResult>
+
+export type HydratedUnknownToolCall =
+  HydratedToolCallBase<"unknown_tool", UnknownToolCall["input"], unknown>
+
+export type HydratedToolCall =
+  | HydratedAskUserQuestionToolCall
+  | HydratedExitPlanModeToolCall
+  | HydratedTodoWriteToolCall
+  | HydratedSkillToolCall
+  | HydratedGlobToolCall
+  | HydratedGrepToolCall
+  | HydratedBashToolCall
+  | HydratedWebSearchToolCall
+  | HydratedReadFileToolCall
+  | HydratedWriteFileToolCall
+  | HydratedEditFileToolCall
+  | HydratedDeleteFileToolCall
+  | HydratedSubagentTaskToolCall
+  | HydratedMcpGenericToolCall
+  | HydratedOfferDownloadToolCall
+  | HydratedPreviewFileToolCall
+  | HydratedImageGenerationToolCall
+  | HydratedWorkflowToolCall
+  | HydratedUnknownToolCall