feat: add session subagent cli control

src/common/types.ts

@@ -29,6 +29,9 @@ export type CommandState = "pending" | "acknowledged" | "completed" | "failed" |
 export type TerminalStatus = "completed" | "failed" | "blocked" | "cancelled";
 export type BackendProfile = "codex" | "deepseek" | "minimax-m3";
 export type QueueTaskState = "pending" | "running" | "completed" | "failed" | "blocked" | "cancelled";
+export type SessionExecutionState = "idle" | "running" | "terminal";
+export type SessionAttentionState = "active" | "unread" | "read";
+export type SessionListState = "default" | "running" | "unread" | "terminal" | "idle" | "all";
 
 export interface WorkspaceRef extends JsonRecord {
   kind: "git-worktree" | "host-path" | "kubernetes-pvc" | "opaque";
@@ -179,11 +182,54 @@ export interface SessionRecord extends JsonRecord {
   conversationId: string | null;
   threadId: string | null;
   metadata: JsonRecord;
+  version: number;
+  executionState: SessionExecutionState;
+  lastRunId: string | null;
+  lastCommandId: string | null;
+  activeRunId: string | null;
+  activeCommandId: string | null;
+  lastEventSeq: number;
+  terminalStatus: TerminalStatus | null;
+  failureKind: FailureKind | null;
+  title: string | null;
+  summary: JsonRecord;
+  lastActivityAt: string | null;
   createdAt: string;
   updatedAt: string;
   expiresAt: string | null;
 }
 
+export interface SessionReadCursorRecord extends JsonRecord {
+  sessionId: string;
+  readerId: string;
+  sessionVersion: number;
+  readAt: string;
+}
+
+export interface SessionSummary extends SessionRecord {
+  sessionPath: string;
+  readerId: string | null;
+  readCursor: SessionReadCursorRecord | null;
+  attentionState: SessionAttentionState;
+  unread: boolean;
+  active: boolean;
+}
+
+export interface SessionListResult extends JsonRecord {
+  items: SessionSummary[];
+  count: number;
+  cursor: string | null;
+  filters: JsonRecord;
+}
+
+export interface SessionEventPage extends JsonRecord {
+  sessionId: string;
+  runId: string | null;
+  items: RunEvent[];
+  count: number;
+  cursor: string | null;
+}
+
 export interface RunnerJobRecord extends JsonRecord {
   id: string;
   runId: string;

src/common/validation.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import type { BackendProfile, CreateCommandInput, CreateQueueTaskInput, CreateRunInput, ExecutionPolicy, JsonRecord, JsonValue, QueueTaskState, ResourceBundleRef, SecretRef, SessionRef } from "./types.js";
+import type { BackendProfile, CreateCommandInput, CreateQueueTaskInput, CreateRunInput, ExecutionPolicy, JsonRecord, JsonValue, QueueTaskState, ResourceBundleRef, SecretRef, SessionListState, SessionRef } from "./types.js";
 import { AgentRunError } from "./errors.js";
 import { backendProfileSpec, backendProfiles, isBackendProfile } from "./backend-profiles.js";
 
@@ -328,3 +328,13 @@ export function validateQueueTaskState(value: string): QueueTaskState {
   if (value === "pending" || value === "running" || value === "completed" || value === "failed" || value === "blocked" || value === "cancelled") return value;
   throw new AgentRunError("schema-invalid", `queue task state ${value} is not supported`, { httpStatus: 400 });
 }
+
+export function validateSessionListState(value: string): SessionListState {
+  if (value === "default" || value === "running" || value === "unread" || value === "terminal" || value === "idle" || value === "all") return value;
+  throw new AgentRunError("schema-invalid", `session state ${value} is not supported`, { httpStatus: 400 });
+}
+
+export function validateBackendProfile(value: string): BackendProfile {
+  if (isBackendProfile(value)) return value;
+  throw new AgentRunError("schema-invalid", `backendProfile ${value} is not supported in v0.1`, { httpStatus: 400, details: { allowedBackends: [...backendProfiles] } });
+}