atomix-cli 1.0.0 → 1.1.0

package/dist/session.d.ts

@@ -0,0 +1,360 @@
+/**
+ * 会话库的公开类型面（docs/session-api-v1.md §4 / §6）。
+ *
+ * 自包含:不 import atomix-core 的任何类型。原因是 `atomix-cli/session` 的 d.ts 要发给消费方,
+ * 而 atomix-core 是未发布的 fork,其类型又牵着 @anthropic-ai/sdk;这里用结构等价的本地定义,
+ * session.ts 里有编译期断言保证与 core 的定义一致(PermissionMode 等)。
+ * `core` 字段对外只承诺 SessionCoreApi 这个子集;运行时就是完整的 AtomixCore,内部模块用泛型参数拿到全类型。
+ */
+export type PermissionMode = "step-by-step" | "action-check" | "free-style";
+export type LogLevel = "debug" | "info" | "warn" | "error" | "none";
+export interface Usage {
+	useTokens: number;
+	maxTokens: number;
+	promptTokens: number;
+}
+/** core `session:ready` 事件数据（结构同 atomix-core 的 SessionReadyData） */
+export interface SessionReadyInfo {
+	workingDir: string;
+	sessionId: string;
+	historyLoaded: boolean;
+	usage: Usage;
+	projectInputHistory: string[];
+}
+/** 对外承诺的 core 子集:事件、权限应答、中断、释放。完整 AtomixCore 仍可用,但不在类型面上承诺 */
+export interface SessionCoreApi {
+	on<T>(event: string, listener: (data: T) => void): unknown;
+	once<T>(event: string, listener: (data: T) => void): unknown;
+	off<T>(event: string, listener: (data: T) => void): unknown;
+	updatePermissionMode(mode: PermissionMode): void;
+	getPermissionMode(): PermissionMode;
+	interruptSession(): unknown;
+	getCurrentSessionId(): string | null;
+	respondToToolPermission(response: {
+		toolName: string;
+		selected: string;
+		agentId?: string;
+	}): unknown;
+	respondToAskQuestion(response: {
+		agentId: string;
+		answers: Record<string, string>;
+	}): unknown;
+	respondToForm(response: {
+		agentId: string;
+		values: Record<string, unknown>;
+		submitted: boolean;
+	}): unknown;
+	dispose(): Promise<void>;
+}
+export interface SessionCoreOptions {
+	cwd: string;
+	/** 缺省:interactive → step-by-step;headless → free-style(与现行 -p 一致,决策 1) */
+	permissionMode?: PermissionMode;
+	/** true = 有人值守(权限/提问/表单由宿主 UI 应答);false(默认)= 无人值守,自动应答器 fail-closed 接管(决策 1) */
+	interactive?: boolean;
+	/** 一进程多会话宿主传 true(core multiSession,session-api-v1 §3.2);交互入口保持缺省 */
+	multiSession?: boolean;
+	/** 缺省跟随 interactive */
+	stream?: boolean;
+	/** 是否加载 hooks(交互入口 true;-p 现状 false);缺省跟随 interactive */
+	hooks?: boolean;
+	systemPrompt?: string;
+	logLevel?: LogLevel;
+}
+export interface StartSessionOptions {
+	/** 会话级 harness 覆盖(不读不写项目态);缺省读 <cwd>/.atomix/harness-state.json;名字不存在直接抛错 */
+	harness?: string;
+	/** create-or-resume(决策 2):不存在即新建,存在即续;缺省新建 */
+	sessionId?: string;
+}
+export type OpenSessionOptions = SessionCoreOptions & StartSessionOptions;
+declare const SESSION_HANDLE_BRAND: unique symbol;
+/** createSessionCore 的产物(不透明句柄):只读元数据 + core 子集;完整内容只有库内部知道 */
+export interface SessionCoreHandle {
+	readonly [SESSION_HANDLE_BRAND]: true;
+	readonly core: SessionCoreApi;
+	readonly cwd: string;
+	readonly interactive: boolean;
+	readonly permissionMode: PermissionMode;
+	/** 构造阶段的备注(如 marketplace 项目域与首个 session 不一致) */
+	readonly notes: string[];
+}
+export interface BlockedItem {
+	kind: "permission" | "question" | "form";
+	/** 工具名 / 表单标题 */
+	name: string;
+	title?: string;
+	agentId?: string;
+}
+export interface SendResult {
+	/** 主代理最后一条完整回复(无则空串) */
+	text: string;
+	/** 本轮内所有主代理完整回复(多轮工具调用间可能有多条) */
+	texts: string[];
+	/** 无人值守下被拒绝的权限请求 / 被跳过的提问与表单 */
+	blocked: BlockedItem[];
+	usage?: Usage;
+	/** type:会话错误类型 | 'timeout' | 'aborted'(调用方 signal)| 'disposed'(执行中被 dispose) */
+	error?: {
+		type: string;
+		message: string;
+	};
+}
+export interface SendOptions {
+	timeoutMs?: number;
+	signal?: AbortSignal;
+}
+export interface AtomixSession<C extends SessionCoreApi = SessionCoreApi> {
+	readonly core: C;
+	readonly sessionId: string;
+	readonly cwd: string;
+	readonly harness: string;
+	readonly permissionMode: PermissionMode;
+	/** session:ready 原始数据(交互入口要 projectInputHistory) */
+	readonly ready: SessionReadyInfo;
+	/** harness 加载告警、agent 名单应用失败、MCP override 备注、构造期备注 */
+	readonly notes: string[];
+	/** 发送一条用户输入,等到本轮 idle 后返回。多次调用按序排队 */
+	send(input: string, opts?: SendOptions): Promise<SendResult>;
+	on<T>(event: string, listener: (data: T) => void): void;
+	off<T>(event: string, listener: (data: T) => void): void;
+	/** 立即结束:中断进行中的一轮(其 send 以 error.type='disposed' 返回),排队中的 send 拒绝,再释放 core */
+	dispose(): Promise<void>;
+}
+export type StreamEvent = {
+	type: "state";
+	state: string;
+} | {
+	type: "text";
+	delta: string;
+} | {
+	type: "thinking";
+	delta: string;
+} | {
+	type: "message";
+	agentId: string;
+	content: string;
+	hasToolCalls: boolean;
+} | {
+	type: "tool_complete";
+	agentId: string;
+	toolName: string;
+	title: string;
+	summary: string;
+} | {
+	type: "tool_error";
+	agentId: string;
+	toolName: string;
+	title: string;
+	content: string;
+} | {
+	type: "permission_request";
+	agentId: string;
+	toolName: string;
+	title: string;
+} | {
+	type: "agent_start";
+	taskId: string;
+	subagentType: string;
+	description: string;
+} | {
+	type: "agent_end";
+	taskId: string;
+	status: string;
+	content: string;
+} | {
+	type: "usage";
+	agentId: string;
+	usage: Usage;
+} | {
+	type: "compact";
+	phase: "start" | "done";
+	agentId: string;
+	messageCount?: number;
+	tokenBefore?: number;
+	tokenCompact?: number;
+	error?: string;
+} | {
+	type: "interrupted";
+	agentId: string;
+	content: string;
+} | {
+	type: "error";
+	errorType: string;
+	message: string;
+};
+/** 历史会话条目(resume.ts listSessions) */
+export interface SessionEntry {
+	sessionId: string;
+	file: string;
+	date: string;
+	mtime: Date;
+	/** 首条用户消息摘要 */
+	preview: string;
+}
+export interface ServeOpenParams {
+	/** 缺省 = serve 启动时的 -C / 进程 cwd */
+	cwd?: string;
+	harness?: string;
+	permissionMode?: PermissionMode;
+	/** create-or-resume;同一 serve 进程内同一 id 只能打开一次 */
+	sessionId?: string;
+	systemPrompt?: string;
+	hooks?: boolean;
+}
+export type ServeRequest = {
+	id: string | number;
+	op: "session.open";
+	params: ServeOpenParams;
+} | {
+	id: string | number;
+	op: "session.send";
+	params: {
+		session: string;
+		input: string;
+		timeoutMs?: number;
+	};
+} | {
+	id: string | number;
+	op: "session.interrupt";
+	params: {
+		session: string;
+	};
+}
+/** close 排在该会话前面的 send 之后;force = 先中止进行中与排队中的 send(它们以 aborted 返回)再关 */
+ | {
+	id: string | number;
+	op: "session.close";
+	params: {
+		session: string;
+		force?: boolean;
+	};
+} | {
+	id: string | number;
+	op: "session.list";
+	params?: Record<string, never>;
+} | {
+	id: string | number;
+	op: "history.list";
+	params: {
+		cwd?: string;
+	};
+} | {
+	id: string | number;
+	op: "harness.list";
+	params?: Record<string, never>;
+} | {
+	id: string | number;
+	op: "server.ping";
+	params?: Record<string, never>;
+} | {
+	id: string | number;
+	op: "server.shutdown";
+	params?: Record<string, never>;
+};
+export type ServeOp = ServeRequest["op"];
+/** 本进程内一个活跃会话的摘要 */
+export interface ServeSessionInfo {
+	sessionId: string;
+	cwd: string;
+	harness: string;
+	permissionMode: PermissionMode;
+	/** 进行中 + 排队中的 send 数 */
+	pending: number;
+}
+export interface ServeOpenResult extends ServeSessionInfo {
+	notes: string[];
+	historyLoaded: boolean;
+	usage: Usage;
+}
+export interface ServeSendResult extends SendResult {
+	sessionId: string;
+}
+export type ServeResult = ServeOpenResult | ServeSendResult | {
+	sessionId: string;
+	interrupted: number;
+} | {
+	sessionId: string;
+	closed: true;
+} | {
+	sessions: ServeSessionInfo[];
+} | {
+	cwd: string;
+	sessions: Array<Omit<SessionEntry, "mtime"> & {
+		mtime: string;
+	}>;
+} | {
+	harnesses: string[];
+} | {
+	pong: true;
+	version: string;
+	sessions: number;
+} | {
+	shutdown: true;
+};
+/**
+ * error.type:'protocol'(不是合法 JSON / 不是对象 / 缺 id(id 须为非空 string 或安全整数)/ id 在途重复 / 未知 op
+ * / 超单行上限 / 正在关闭)| 'args'(参数缺失或类型不对:boolean / number 严格按类型,cwd 必须是目录)
+ * | 'not_found'(session 不存在)| 'conflict'(session id 已打开)
+ * | 'limit'(活跃会话数 / 在途请求数超上限;shutdown / ping / interrupt / force close 不受在途上限约束)
+ * | 'init'(打开失败)| 'internal'
+ */
+export type ServeResponse = {
+	type: "response";
+	id: string | number | null;
+	ok: true;
+	result: ServeResult;
+} | {
+	type: "response";
+	id: string | number | null;
+	ok: false;
+	error: {
+		type: string;
+		message: string;
+	};
+};
+export interface ServeEventRecord {
+	type: "event";
+	session: string;
+	event: StreamEvent;
+}
+export interface ServeServerRecord {
+	type: "server";
+	status: "ready" | "shutdown";
+	version: string;
+	pid: number;
+	cwd: string;
+}
+export type ServeRecord = ServeResponse | ServeEventRecord | ServeServerRecord;
+/** 一步到位:构造 + 装配(无人值守缺省)。模型未配置 / session id 非法 / harness 不存在直接抛错 */
+export declare const openSession: (opts: OpenSessionOptions) => Promise<AtomixSession>;
+/** 两段式第一步:只构造 core(交互入口在此之后跑模型向导)。返回不透明句柄 */
+export declare const createSessionCore: (opts: SessionCoreOptions) => SessionCoreHandle;
+/** 两段式第二步:harness → createSession → 启停名单 → MCP override。句柄必须来自 createSessionCore */
+export declare const startSession: (handle: SessionCoreHandle, opts?: StartSessionOptions) => Promise<AtomixSession>;
+/** 构造了 core 但不再启动时释放 */
+export declare const discardSessionCore: (handle: SessionCoreHandle) => Promise<void>;
+/** 模型是否已配置(未配置时 openSession 会抛错;两段式调用方可先查) */
+export declare const isModelConfigured: (handle: SessionCoreHandle) => Promise<boolean>;
+/** 进程级准备(openSession / createSessionCore 内部会调;显式调用可提前拿到项目域备注) */
+export declare const prepareProcess: (cwd: string) => string | null;
+/** session id 规则:1–128 个字母 / 数字 / 点 / 下划线 / 连字符;不合规抛错(CLI 与库共用) */
+export declare const validateSessionId: (id: string) => void;
+export declare const SESSION_ID_PATTERN: RegExp;
+export declare const DEFAULT_SYSTEM_PROMPT: string;
+export declare const DEFAULT_SEND_TIMEOUT_MS: number;
+/** 订阅 core 事件并转成 stream-json 形状(与 `-p --output-format stream-json` / serve 同一套) */
+export declare const attachStreamEvents: (core: SessionCoreApi, emit: (e: StreamEvent) => void) => () => void;
+/** 列出某工作目录的历史会话(新 → 旧) */
+export declare const listSessions: (cwd: string) => SessionEntry[];
+/** 列出可用 harness(base 恒在首位) */
+export declare const listHarnesses: () => string[];
+export declare const BASE_HARNESS: string;
+export declare const PERMISSION_MODE_ORDER: readonly PermissionMode[];
+export declare const DEFAULT_PERMISSION_MODE: PermissionMode;
+/** 解析权限模式参数:全名 / 唯一前缀 / 缩写;无法解析返回 null */
+export declare const parsePermissionMode: (arg: string | undefined) => PermissionMode | null;
+/** ~/.atomix(或 ATOMIX_ROOT) */
+export declare const getAtomixRoot: () => string;
+
+export {};