atomix-cli 1.2.0 → 1.3.0

package/dist/session.d.ts

@@ -1,3 +1,5 @@
+/// <reference types="node" />
+
 /**
  * 会话库的公开类型面（docs/session-api-v1.md §4 / §6）。
  *
@@ -46,12 +48,79 @@ export interface SessionCoreApi {
 	}): unknown;
 	dispose(): Promise<void>;
 }
+export type PermissionDecision = "allow" | "deny";
+/** 无人值守下一次工具权限请求(core `tool:permission:request` 的公开子集) */
+export interface PermissionRequestInfo {
+	agentId: string;
+	toolName: string;
+	title: string;
+	/** 权限说明:字符串或结构化内容(Edit / Write 是 patch 对象) */
+	content: string | Record<string, unknown>;
+	/** core 提供的可选操作字典(仅供展示;应答只有 allow / deny 两档) */
+	options: Record<string, string>;
+}
+/**
+ * 无人值守权限策略(session-api-v1 §9.7,S5):自动应答器遇权限请求先问它,'allow' = 同意一次,'deny' = 拒绝。
+ * 抛错 / 返回其他值一律按 deny(fail-closed 不变,只是把"关"之前的窗口让给调用方)。缺省 = 一律 deny
+ */
+export type PermissionPolicy = (req: PermissionRequestInfo) => PermissionDecision | Promise<PermissionDecision>;
+export interface AskQuestionOptionInfo {
+	label: string;
+	description: string;
+}
+export interface AskQuestionInfo {
+	question: string;
+	/** 问题标签(最多 12 字符) */
+	header: string;
+	/** 2–4 个选项 */
+	options: AskQuestionOptionInfo[];
+	multiSelect: boolean;
+}
+/** 无人值守下一次 AskUserQuestion(core `ask:question:request` 的公开子集) */
+export interface QuestionRequestInfo {
+	agentId: string;
+	/** 1–4 个问题 */
+	questions: AskQuestionInfo[];
+}
+/** 问题文本 → 答案(多选用逗号分隔;也可以是选项之外的自由文本);空对象 = 跳过(记入 blocked) */
+export type QuestionAnswers = Record<string, string>;
+/** 无人值守提问策略:抛错 / 非对象一律按跳过 */
+export type QuestionPolicy = (req: QuestionRequestInfo) => QuestionAnswers | Promise<QuestionAnswers>;
+/** FormUI 字段(公开面只固定公共属性;type 对应 core FormField 的各成员,其余属性原样透传) */
+export interface FormFieldInfo {
+	type: string;
+	key?: string;
+	label?: string;
+	required?: boolean;
+	help?: string;
+}
+/** 无人值守下一次 FormUI(core `form:request` 的公开子集) */
+export interface FormRequestInfo {
+	agentId: string;
+	title: string;
+	surface: "inline" | "dock";
+	submitLabel: string;
+	fields: FormFieldInfo[];
+}
+/** 字段 key → 值;submitted:false = 跳过(记入 blocked) */
+export interface FormAnswer {
+	values: Record<string, unknown>;
+	submitted: boolean;
+}
+/** 无人值守表单策略:抛错 / 非对象一律按跳过 */
+export type FormPolicy = (req: FormRequestInfo) => FormAnswer | Promise<FormAnswer>;
 export interface SessionCoreOptions {
 	cwd: string;
 	/** 缺省:interactive → step-by-step;headless → free-style(与现行 -p 一致,决策 1) */
 	permissionMode?: PermissionMode;
 	/** true = 有人值守(权限/提问/表单由宿主 UI 应答);false(默认)= 无人值守,自动应答器 fail-closed 接管(决策 1) */
 	interactive?: boolean;
+	/** 无人值守下的权限策略;interactive 时忽略 */
+	permissionPolicy?: PermissionPolicy;
+	/** 无人值守下的 AskUserQuestion 策略;缺省跳过(空答案);interactive 时忽略 */
+	questionPolicy?: QuestionPolicy;
+	/** 无人值守下的 FormUI 策略;缺省跳过(未提交);interactive 时忽略 */
+	formPolicy?: FormPolicy;
 	/** 一进程多会话宿主传 true(core multiSession,session-api-v1 §3.2);交互入口保持缺省 */
 	multiSession?: boolean;
 	/** 缺省跟随 interactive */
@@ -60,6 +129,11 @@ export interface SessionCoreOptions {
 	hooks?: boolean;
 	systemPrompt?: string;
 	logLevel?: LogLevel;
+	/**
+	 * 宿主侧 sessionId 占用检查(同步):/clear 换新 id 时 core 会问候选 id 是否已被本宿主占用(serve 传进程内会话表),
+	 * true 则重新生成。与提交切换在同一同步段完成(session-api-v1 §10)
+	 */
+	isSessionIdTaken?: (sessionId: string) => boolean;
 }
 export interface StartSessionOptions {
 	/** 会话级 harness 覆盖(不读不写项目态);缺省读 <cwd>/.atomix/harness-state.json;名字不存在直接抛错 */
@@ -120,6 +194,7 @@ export interface SessionModelInfo {
 }
 export interface AtomixSession<C extends SessionCoreApi = SessionCoreApi> {
 	readonly core: C;
+	/** 当前 sessionId(实时值:send('/clear') 后换新 id;ready.sessionId 保持打开时的原值) */
 	readonly sessionId: string;
 	readonly cwd: string;
 	readonly harness: string;
@@ -163,11 +238,33 @@ export type StreamEvent = {
 	toolName: string;
 	title: string;
 	content: string;
-} | {
+}
+/** serve 的 permissionPrompt:'ask' 下带 requestId / content / options,用 session.permit 应答 */
+ | {
 	type: "permission_request";
 	agentId: string;
 	toolName: string;
 	title: string;
+	requestId?: string;
+	content?: string | Record<string, unknown>;
+	options?: Record<string, string>;
+}
+/** AskUserQuestion;serve 的 permissionPrompt:'ask' 下带 requestId,用 session.answer 应答 */
+ | {
+	type: "question_request";
+	agentId: string;
+	questions: AskQuestionInfo[];
+	requestId?: string;
+}
+/** FormUI;serve 的 permissionPrompt:'ask' 下带 requestId,用 session.form 应答 */
+ | {
+	type: "form_request";
+	agentId: string;
+	title: string;
+	surface: "inline" | "dock";
+	submitLabel: string;
+	fields: FormFieldInfo[];
+	requestId?: string;
 } | {
 	type: "agent_start";
 	taskId: string;
@@ -198,6 +295,13 @@ export type StreamEvent = {
 	type: "error";
 	errorType: string;
 	message: string;
+}
+/** /clear 完成:上下文已清空且换了新 sessionId(旧会话历史文件保留,可 resume);之后按新 id 寻址(serve 下旧 id 仍可用) */
+ | {
+	type: "session_cleared";
+	sessionId: string;
+	previousSessionId: string | null;
+	usage: Usage;
 };
 /** 历史会话条目(resume.ts listSessions) */
 export interface SessionEntry {
@@ -217,6 +321,14 @@ export interface ServeOpenParams {
 	sessionId?: string;
 	systemPrompt?: string;
 	hooks?: boolean;
+	/**
+	 * 人在回路(§9.7):'refuse'(缺省)= 无人值守 fail-closed:权限直接拒、AskUser 空答、FormUI 不提交;
+	 * 'ask' = 把 permission_request / question_request / form_request(带 requestId)推给持有者,
+	 * 等 session.permit / session.answer / session.form 应答;permitTimeoutMs 内未应答、会话无主、本轮结束一律按拒绝 / 跳过
+	 */
+	permissionPrompt?: "refuse" | "ask";
+	/** 覆盖本会话的应答等待时长(缺省取 serve 的 --permit-timeout,60000) */
+	permitTimeoutMs?: number;
 }
 export type ServeRequest = {
 	id: string | number;
@@ -245,6 +357,45 @@ export type ServeRequest = {
 		session: string;
 		force?: boolean;
 	};
+}
+/** ws 多连接:接管无主(持有者已断线)的会话,成为持有者并按序回放断线期间缓冲的事件;有主 → conflict */
+ | {
+	id: string | number;
+	op: "session.attach";
+	params: {
+		session: string;
+	};
+}
+/** 应答 permissionPrompt:'ask' 下的权限请求;requestId 不存在或已超时 → not_found;只有持有者能应答 */
+ | {
+	id: string | number;
+	op: "session.permit";
+	params: {
+		session: string;
+		requestId: string;
+		decision: PermissionDecision;
+	};
+}
+/** 应答 question_request:answers = 问题文本 → 答案(多选逗号分隔);空对象 = 跳过 */
+ | {
+	id: string | number;
+	op: "session.answer";
+	params: {
+		session: string;
+		requestId: string;
+		answers: QuestionAnswers;
+	};
+}
+/** 应答 form_request:values = 字段 key → 值;submitted 缺省 true,false = 跳过 */
+ | {
+	id: string | number;
+	op: "session.form";
+	params: {
+		session: string;
+		requestId: string;
+		values: Record<string, unknown>;
+		submitted?: boolean;
+	};
 } | {
 	id: string | number;
 	op: "session.list";
@@ -278,6 +429,10 @@ export interface ServeSessionInfo {
 	model: SessionModelInfo;
 	/** 进行中 + 排队中的 send 数 */
 	pending: number;
+	/** 本连接是否持有该会话(stdio 恒 true) */
+	owned: boolean;
+	/** 当前无主(持有者已断线,等待 attach 或 detach-ttl 到期;stdio 恒 false) */
+	detached: boolean;
 }
 export interface ServeOpenResult extends ServeSessionInfo {
 	notes: string[];
@@ -287,12 +442,30 @@ export interface ServeOpenResult extends ServeSessionInfo {
 export interface ServeSendResult extends SendResult {
 	sessionId: string;
 }
+export interface ServeAttachResult extends ServeSessionInfo {
+	/** 回放的缓冲事件条数 */
+	replayed: number;
+	/** 缓冲超限被丢弃的最早事件条数(>0 时回放前先推一条 dropped 事件) */
+	dropped: number;
+}
 export type ServeResult = ServeOpenResult | ServeSendResult | {
 	sessionId: string;
 	interrupted: number;
 } | {
 	sessionId: string;
 	closed: true;
+} | ServeAttachResult | {
+	sessionId: string;
+	requestId: string;
+	decision: PermissionDecision;
+} | {
+	sessionId: string;
+	requestId: string;
+	answered: true;
+} | {
+	sessionId: string;
+	requestId: string;
+	submitted: boolean;
 } | {
 	sessions: ServeSessionInfo[];
 } | {
@@ -312,7 +485,8 @@ export type ServeResult = ServeOpenResult | ServeSendResult | {
 /**
  * error.type:'protocol'(不是合法 JSON / 不是对象 / 缺 id(id 须为非空 string 或安全整数)/ id 在途重复 / 未知 op
  * / 超单行上限 / 正在关闭)| 'args'(参数缺失或类型不对:boolean / number 严格按类型,cwd 必须是目录)
- * | 'not_found'(session 不存在)| 'conflict'(session id 已打开)
+ * | 'not_found'(session 不存在 / permit 的 requestId 不存在或已超时)| 'conflict'(session id 已打开 / attach 有主会话)
+ * | 'forbidden'(ws 多连接:对非本连接持有的会话 send / interrupt / close;无主会话须先 attach)
  * | 'limit'(活跃会话数 / 在途请求数超上限;shutdown / ping / interrupt / force close 不受在途上限约束)
  * | 'init'(打开失败)| 'internal'
  */
@@ -330,10 +504,24 @@ export type ServeResponse = {
 		message: string;
 	};
 };
+/** 接管无主会话时,断线期间缓冲超限被丢弃的最早事件条数(回放前推一条) */
+export interface ServeDroppedEvent {
+	type: "dropped";
+	count: number;
+}
+export type ServeEvent = StreamEvent | ServeDroppedEvent;
 export interface ServeEventRecord {
 	type: "event";
 	session: string;
-	event: StreamEvent;
+	event: ServeEvent;
+}
+/** `--listen` 模式 stdout 的 ready 记录附带接入信息(宿主 spawn 后读第一行即可) */
+export interface ServeListenInfo {
+	url: string;
+	/** 未用 --token-file 时在此回传(自动生成或 --token 指定) */
+	token?: string;
+	/** --token-file:token 已写入该文件(0600),不回传 */
+	tokenFile?: string;
 }
 export interface ServeServerRecord {
 	type: "server";
@@ -341,8 +529,65 @@ export interface ServeServerRecord {
 	version: string;
 	pid: number;
 	cwd: string;
+	listen?: ServeListenInfo;
+	/** 每个连接的 ready 记录带:单条请求字节上限(stdio 单行 / ws 单帧);stdout 的两条 server 记录不带 */
+	limits?: {
+		maxRequestBytes: number;
+	};
 }
 export type ServeRecord = ServeResponse | ServeEventRecord | ServeServerRecord;
+/** ws url(`ws://host:port`,token 走 Authorization 头)或带 stdin / stdout 的对象(ChildProcess 或任意流对) */
+export type ServeTarget = string | {
+	stdin: NodeJS.WritableStream | null;
+	stdout: NodeJS.ReadableStream | null;
+};
+export interface ServeClientOptions {
+	/** ws 接入 token(stdout ready 记录里的 listen.token);stdio 不需要 */
+	token?: string;
+	/** 握手 + 等 ready 记录的超时(缺省 10000) */
+	connectTimeoutMs?: number;
+	/** 每个请求的缺省超时(缺省不超时:send 可能很长);到点以 type:'timeout' 拒绝,迟到的响应丢弃 */
+	requestTimeoutMs?: number;
+}
+export interface ServeRequestOptions {
+	/** 覆盖本次请求的超时 */
+	timeoutMs?: number;
+}
+/** 连接断开信息:ws 带关闭码与原因;stdio 只表示 stdout 结束 */
+export interface ServeCloseInfo {
+	code?: number;
+	reason?: string;
+}
+export interface ServeClient {
+	/** 连接后收到的第一条 ready 记录 */
+	readonly ready: ServeServerRecord;
+	readonly closed: boolean;
+	/** 服务端 ready 记录里给的单条请求字节上限(旧服务端没给时取 1 MiB) */
+	readonly maxRequestBytes: number;
+	/**
+	 * 发一个请求,resolve 为 result;ok:false 时 reject ServeRequestError(带 error.type);连接断开时在途请求全部以
+	 * type:'closed' reject;序列化后超过 maxRequestBytes 的请求在本地以 type:'protocol' reject、不上线(服务端对超限
+	 * 请求回的是没有 id 的 protocol 错误,客户端无法关联)
+	 */
+	request<R = ServeResult>(op: ServeOp, params?: Record<string, unknown>, opts?: ServeRequestOptions): Promise<R>;
+	/** 会话事件(所有会话;按 rec.session 自行分流);返回取消订阅函数 */
+	onEvent(listener: (rec: ServeEventRecord) => void): () => void;
+	/** 服务端回的无法关联到请求的错误(id 为 null 的 response):本客户端只发合法请求,正常不会出现;出现即协议层异常 */
+	onProtocolError(listener: (error: {
+		type: string;
+		message: string;
+	}) => void): () => void;
+	/** ready 之后的 server 记录(shutdown) */
+	onServer(listener: (rec: ServeServerRecord) => void): () => void;
+	onClose(listener: (info: ServeCloseInfo) => void): () => void;
+	/** 关闭连接:ws 发 1000;stdio 结束 stdin(服务端排空后退出) */
+	close(): Promise<void>;
+}
+declare class ServeRequestError extends Error {
+	readonly type: string;
+	readonly op: ServeOp;
+	constructor(type: string, message: string, op: ServeOp);
+}
 /** 一步到位:构造 + 装配(无人值守缺省)。模型未配置 / session id 非法 / harness 不存在直接抛错 */
 export declare const openSession: (opts: OpenSessionOptions) => Promise<AtomixSession>;
 /** 两段式第一步:只构造 core(交互入口在此之后跑模型向导)。返回不透明句柄 */
@@ -373,5 +618,13 @@ export declare const DEFAULT_PERMISSION_MODE: PermissionMode;
 export declare const parsePermissionMode: (arg: string | undefined) => PermissionMode | null;
 /** ~/.atomix(或 ATOMIX_ROOT) */
 export declare const getAtomixRoot: () => string;
+/** serve 薄客户端:ws url 或带 stdin/stdout 的子进程 → request(op, params) + onEvent;两种传输同一用法 */
+export declare const connectServe: (target: ServeTarget, opts?: ServeClientOptions) => Promise<ServeClient>;
+/** request 的 ok:false 结果:type = 协议的 error.type('closed' = 连接断开) */
+declare const ServeRequestError$1: typeof ServeRequestError;
+
+export {
+	ServeRequestError$1 as ServeRequestError,
+};
 
 export {};