gaza/src/protocol.ts

/** 协议对象允许保留服务端新增字段，GUI 不应因未知字段而拒绝整个对象。 */
export interface Extensible {
  readonly [extension: string]: unknown;
}

declare const brand: unique symbol;
export type Brand<Value, Name extends string> = Value & { readonly [brand]: Name };
export type ServerId = Brand<string, "ServerId">;
export type ProjectId = Brand<string, "ProjectId">;
export type SessionId = Brand<string, "SessionId">;
export type TaskId = Brand<string, "TaskId">;
export type EventId = Brand<string, "EventId">;
export type ArtifactId = Brand<string, "ArtifactId">;
export type AuditId = Brand<string, "AuditId">;
export type CapabilityId = Brand<string, "CapabilityId">;

export type Timestamp = Brand<string, "Timestamp">;
export type Cursor = Brand<string, "Cursor">;

/** 已知值保留自动补全，同时允许服务端返回未来新增值。 */
export type ForwardCompatible<Known extends string> = Known | (string & {});

export interface ProtocolVersion extends Extensible {
  readonly major: number;
  readonly minor: number;
  readonly patch: number;
}

export interface ProtocolEnvelope extends Extensible {
  readonly protocol_version: ProtocolVersion;
  readonly request_id?: string;
}

export interface ServerContext extends Extensible {
  readonly server_id: ServerId;
}

export interface ProjectContext extends ServerContext {
  readonly project_id: ProjectId;
}

export interface SessionContext extends ProjectContext {
  readonly session_id: SessionId;
}

export interface PageRequest extends Extensible {
  readonly cursor?: Cursor;
  readonly page_size?: number;
}

export interface PageInfo extends Extensible {
  readonly next_cursor?: Cursor;
  readonly has_more: boolean;
}

export interface Page<T> extends Extensible {
  readonly items: readonly T[];
  readonly page_info: PageInfo;
}

export type ConnectionState = ForwardCompatible<
  | "DISCONNECTED" | "CONNECTING" | "TLS_HANDSHAKE" | "AUTHENTICATING"
  | "NEGOTIATING" | "SYNCHRONIZING" | "CONNECTED" | "DEGRADED"
  | "RECONNECTING" | "AUTH_EXPIRED" | "FAILED"
>;

export interface Teamserver extends ServerContext, Extensible {
  readonly name: string;
  readonly protocol_version: ProtocolVersion;
  readonly connection_state: ConnectionState;
  readonly capabilities: readonly CapabilityId[];
}

export interface Project extends ProjectContext, Extensible {
  readonly name: string;
  readonly description?: string;
  readonly capabilities: readonly CapabilityId[];
}

export type SessionState = ForwardCompatible<"ONLINE" | "OFFLINE" | "DORMANT" | "LOST">;

export interface Session extends SessionContext, Extensible {
  readonly name: string;
  readonly state: SessionState;
  readonly hostname?: string;
  readonly username?: string;
  readonly os?: string;
  readonly architecture?: string;
  readonly first_seen_at: Timestamp;
  readonly last_active_at: Timestamp;
  readonly tags: readonly string[];
  readonly capabilities: readonly CapabilityId[];
}

export type JsonSchema = Readonly<Record<string, unknown>>;

export interface Capability extends ProjectContext, Extensible {
  readonly capability_id: CapabilityId;
  readonly name: string;
  readonly description?: string;
  readonly input_schema: JsonSchema;
  readonly output_schema?: JsonSchema;
  readonly supports_batch: boolean;
}

export type TaskState = ForwardCompatible<
  "PENDING" | "RUNNING" | "SUCCEEDED" | "FAILED" | "CANCELLED"
>;

export interface Task extends SessionContext, Extensible {
  readonly task_id: TaskId;
  readonly capability_id: CapabilityId;
  readonly state: TaskState;
  readonly cancellable: boolean;
  readonly created_at: Timestamp;
  readonly updated_at: Timestamp;
  readonly result?: unknown;
  readonly error?: ProtocolError;
}

export interface EventContext extends ServerContext, Extensible {
  readonly project_id?: ProjectId;
  readonly session_id?: SessionId;
  readonly task_id?: TaskId;
}

export interface Event extends Extensible {
  readonly event_id: EventId;
  readonly type: ForwardCompatible<"SESSION_UPDATED" | "TASK_UPDATED" | "TASK_OUTPUT" | "ARTIFACT_CREATED">;
  readonly timestamp: Timestamp;
  readonly cursor: Cursor;
  readonly sequence?: number;
  readonly context: EventContext;
  readonly payload: unknown;
}

export interface Artifact extends SessionContext, Extensible {
  readonly artifact_id: ArtifactId;
  readonly task_id?: TaskId;
  readonly name: string;
  readonly media_type: string;
  readonly size_bytes: number;
  readonly sha256?: string;
  readonly created_at: Timestamp;
}

export interface AuditRecord extends ProjectContext, Extensible {
  readonly audit_id: AuditId;
  readonly actor: string;
  readonly action: string;
  readonly target: Readonly<Record<string, string>>;
  readonly parameter_summary?: Readonly<Record<string, unknown>>;
  readonly outcome: ForwardCompatible<"SUCCEEDED" | "FAILED" | "DENIED">;
  readonly request_id: string;
  readonly timestamp: Timestamp;
}

export interface ProtocolError extends Extensible {
  readonly code: ForwardCompatible<
    "NETWORK" | "TLS" | "AUTHENTICATION" | "INCOMPATIBLE_VERSION" |
    "PERMISSION_DENIED" | "RATE_LIMITED" | "TIMEOUT" | "INVALID_MESSAGE" | "INTERNAL"
  >;
  readonly message: string;
  readonly retryable: boolean;
  readonly details?: Readonly<Record<string, unknown>>;
}