Artifacts

/**
 * Types for the HQ01 Session Manager.
 *
 * A "session" is a single Claude CLI process running on HQ01 on behalf of an
 * executive (e.g. Agent Z). The session manager is a management interface — it
 * starts, observes and stops these processes. It is not an orchestrator and it
 * does not make decisions; the files on disk are the source of truth.
 */

/**
 * Lifecycle of a session process.
 *   - starting → spawn requested, PID not yet confirmed.
 *   - running  → process is alive.
 *   - stopped  → operator stopped it (SIGTERM/SIGKILL).
 *   - exited   → process ended on its own (work finished, or it crashed).
 *   - failed   → the process could not be spawned at all.
 *   - unknown  → state could not be determined.
 */
export type SessionStatus =
  | "starting"
  | "running"
  | "stopped"
  | "exited"
  | "failed"
  | "unknown"
  // Report-aware terminal states for sessions that are expected to produce a
  // report.md (e.g. dispatched executive sessions):
  | "completed"
  | "completed_missing_report"
  | "terminated";

/**
 * The live, mutable record of a session — persisted as `session.json`. This is
 * the primary shape the UI renders.
 */
export interface Session {
  id: string;
  name: string;
  /** The executive this session runs as, e.g. "agent-z". */
  executive: string;
  status: SessionStatus;
  pid: number | null;
  /** ISO timestamp the process was started. */
  started_at: string | null;
  /** ISO timestamp the process stopped or exited, if it has. */
  stopped_at: string | null;
  /** Process exit code, when known. */
  exit_code: number | null;
  /** Absolute path of the repository the session runs in. */
  working_directory: string;
  /** Git branch the session is meant to operate on, if any. */
  branch: string | null;
  /** Linked mission id, e.g. "MS-0001". */
  mission_id: string | null;
  /** Linked assignment id, if any. */
  assignment_id: string | null;
  /** Absolute path of the stdout log (the primary log surfaced in the UI). */
  log_path: string;
  /** Absolute path of the stderr log. */
  stderr_path: string;
  /** ISO timestamp of the most recent log write — a cheap "is it working" signal. */
  last_activity: string | null;
  /** The executable that was launched. */
  command: string;
  /** Arguments passed to the executable. */
  args: string[];
  // --- Execution permission manifest (Part 3) ---------------------------------
  /** Claude permission mode applied, e.g. "acceptEdits". Null when unset. */
  permission_mode: string | null;
  /** Tools the session was allowed to use, e.g. ["Read","Write","Edit","LS"]. */
  allowed_tools: string[];
  /** The only directory the session may write into (its runtime workspace). */
  runtime_write_root: string | null;
  /** Whether the session was permitted to write repository source. */
  repository_write_allowed: boolean;
  /** Whether a final report.md is expected (drives report-aware status). */
  expects_report: boolean;
}

/**
 * The immutable creation record of a session — persisted as `metadata.json`.
 * Whereas `session.json` changes as the process lives and dies, this captures
 * the original intent and provenance and is never rewritten.
 */
export interface SessionMetadata {
  id: string;
  name: string;
  executive: string;
  mission_id: string | null;
  assignment_id: string | null;
  working_directory: string;
  branch: string | null;
  command: string;
  args: string[];
  /** The prompt/mission text the session was launched with, if any. */
  prompt: string | null;
  /** ISO timestamp the session was created. */
  created_at: string;
  /** Who requested the session (operator note). */
  created_by: string;
}

/** Input accepted by the start-session endpoint / manager. */
export interface StartSessionInput {
  name: string;
  executive?: string;
  working_directory: string;
  branch?: string | null;
  mission_id?: string | null;
  assignment_id?: string | null;
  /** Mission/prompt text. For the Claude CLI this becomes `--print <prompt>`. */
  prompt?: string | null;
  /** Override the executable (defaults to the configured Claude binary). */
  command?: string;
  /** Override the full argument list (defaults are derived from `prompt`). */
  args?: string[];
  /** Operator note recorded in metadata. */
  created_by?: string;
  // --- Execution permission manifest (set by the dispatch layer) --------------
  permission_mode?: string | null;
  allowed_tools?: string[];
  runtime_write_root?: string | null;
  repository_write_allowed?: boolean;
  expects_report?: boolean;
}

/** Tail of a session's logs. */
export interface SessionLogs {
  id: string;
  status: SessionStatus;
  last_activity: string | null;
  stdout: string;
  stderr: string;
}