Types

Core type definitions from @ysa-ai/ysa/types.

TaskStatus

type TaskStatus = "queued" | "running" | "completed" | "failed" | "stopped" | "archived";

TaskState

Full state of a task (as stored in the database):

interface TaskState {
  task_id: string;          // UUID
  prompt: string;
  status: TaskStatus;
  branch: string;
  worktree: string;         // absolute path
  session_id: string | null;
  error: string | null;
  failure_reason: "max_turns" | "infrastructure" | "agent_aborted" | null;
  log_path: string;
  started_at: string;       // ISO 8601
  finished_at: string | null;
}

RunConfig

What you pass to runTask(). See the runTask reference for full field descriptions.

interface RunConfig {
  taskId: string;
  prompt: string;
  branch: string;
  projectRoot: string;
  worktreePrefix: string;
  provider?: string;
  model?: string;
  maxTurns?: number;
  allowedTools?: string[];
  resumeSessionId?: string;
  resumePrompt?: string;
  resumeWorktree?: string;
  networkPolicy?: "none" | "strict";
  promptUrl?: string;
  shadowDirs?: string[];
  depInstallCmd?: string;
  depsCacheKey?: string;
  miseVolume?: string;
  worktreeFiles?: string[];
  extraEnv?: Record<string, string>;
  extraLabels?: Record<string, string>;
  proxyRules?: ScopedAllowRule[];
  serverPort?: number;
  allowCommit?: boolean;
}

TaskHandle

Returned immediately by runTask() — container may still be running:

interface TaskHandle {
  taskId: string;
  logPath: string;
  shadowVolumes: string[];   // dep cache volumes (stable across tasks with same depsCacheKey)
  wait(): Promise<RunResult>;
  stop(): Promise<void>;
}

RunOptions

interface RunOptions {
  onProgress?: (message: string) => void;
  onEvent?: (event: ParsedLogEntry) => void;
  onComplete?: (result: RunResult) => void;
  onError?: (error: Error) => void;
}

RunResult

What handle.wait() / onComplete delivers:

interface RunResult {
  task_id: string;
  status: TaskStatus;
  session_id: string | null;
  error: string | null;
  failure_reason: "max_turns" | "infrastructure" | "agent_aborted" | null;
  log_path: string;
  duration_ms: number;
}

CoreConfig

Minimal config for embedding ysa in a platform:

interface CoreConfig {
  projectRoot: string;
  worktreePrefix: string;
  branchPrefix: string;
  dataDir: string; // e.g. ~/.ysa/
}

ParsedLogEntry

Structured log event emitted via onEvent:

interface ParsedLogEntry {
  type: "assistant" | "tool_call" | "tool_result" | "system";
  text?: string;
  tool?: string;
}