@xyz-agent/extension-protocol 0.5.1 → 0.7.0

package/dist/index.d.mts

@@ -309,4 +309,170 @@ declare function getAskUserOther(answers: AskUserAnswers, question: AskUserQuest
  */
 declare function isAskUserQuestion(value: unknown): value is AskUserQuestion;
 
-export { ASK_USER_MARKER, type AskUserAnswers, type AskUserOption, type AskUserQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, PROTOCOL_VERSION, type StatItem, type TreeItem, type TreeItemIcon, type WidgetMeta, askUserInteract, extractGui, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult };
+/**
+ * session-manager 请求的 title marker。runtime event-adapter 和 handler
+ * 检测此 marker 区分 session-manager 请求与普通 select。
+ *
+ * NUL 前缀确保不会与 extension 正常的 select title 冲突。
+ * 与 ASK_USER_MARKER / GUI_WIDGET_MARKER 同理。
+ */
+declare const SESSION_MANAGER_MARKER = "\0XYZ_SESSION_MANAGER";
+/**
+ * 6 个 action 的运行时集合（与 SessionManagerAction 类型同源——types.ts 从此派生）。
+ * event-adapter 用它把 JSON 解析出的 action 字符串收窄为联合类型，
+ * 非法值折叠为 '__malformed__' 哨兵（与 handler default 分支同走 cancelled）。
+ */
+declare const SESSION_MANAGER_ACTIONS: readonly ["create", "send", "history", "status", "list", "abort"];
+
+/**
+ * session-manager extension 的类型定义。
+ *
+ * 6 个 action 的请求 params 和结果类型，供 handler 和 extension 共用。
+ * marker 检测后按 action 分发到对应 handler 分支。
+ */
+
+/** session-manager 支持的 6 个 action（从 SESSION_MANAGER_ACTIONS 集合派生，值与类型同源） */
+type SessionManagerAction = (typeof SESSION_MANAGER_ACTIONS)[number];
+/** session-manager 请求的统一形状（extension → runtime via select 通道） */
+interface SessionManagerRequest {
+    action: SessionManagerAction;
+    params: SessionManagerParams[SessionManagerAction];
+}
+/** 各 action 的请求参数映射 */
+interface SessionManagerParams {
+    create: SessionManagerCreateParams;
+    send: SessionManagerSendParams;
+    history: SessionManagerHistoryParams;
+    status: SessionManagerStatusParams;
+    list: SessionManagerListParams;
+    abort: SessionManagerAbortParams;
+}
+/** create action 参数 */
+interface SessionManagerCreateParams {
+    /** session 工作目录 */
+    cwd?: string;
+    /** session 标签 */
+    label?: string;
+    /** 初始 prompt（可选；提供时 create 后立即注入——设计文档 §5.2 原子性决策） */
+    prompt?: string;
+    /** 模型覆盖（可选，透传 SessionService.create 的 modelOverride） */
+    model?: string;
+    /** thinking 级别覆盖（可选，透传 thinkingOverride） */
+    thinkingLevel?: string;
+}
+/** send action 参数 */
+interface SessionManagerSendParams {
+    sessionId: string;
+    prompt: string;
+}
+/** history action 参数 */
+interface SessionManagerHistoryParams {
+    sessionId: string;
+    /** 截断尾部 turn 数（0 = 不截断） */
+    tailTurns?: number;
+}
+/** status action 参数 */
+interface SessionManagerStatusParams {
+    sessionId: string;
+}
+/** list action 参数 */
+interface SessionManagerListParams {
+    /** 按 spawnSource 过滤 */
+    spawnSource?: 'user' | 'agent';
+    /** 按 parentAgentSessionId 过滤（handler 一律以路由上下文父 id 为准，此字段仅作显式收窄提示） */
+    parentAgentSessionId?: string;
+}
+/** abort action 参数 */
+interface SessionManagerAbortParams {
+    sessionId: string;
+}
+/** create：全字段可选 string */
+declare function isSessionManagerCreateParams(v: unknown): v is SessionManagerCreateParams;
+/** send：sessionId + prompt 必填 */
+declare function isSessionManagerSendParams(v: unknown): v is SessionManagerSendParams;
+/** history：sessionId 必填、tailTurns 可选 number */
+declare function isSessionManagerHistoryParams(v: unknown): v is SessionManagerHistoryParams;
+/** status / abort：sessionId 必填 */
+declare function isSessionManagerStatusParams(v: unknown): v is SessionManagerStatusParams;
+declare function isSessionManagerAbortParams(v: unknown): v is SessionManagerAbortParams;
+/** list：两过滤字段可选（spawnSource 限枚举） */
+declare function isSessionManagerListParams(v: unknown): v is SessionManagerListParams;
+/** create 结果 */
+interface SessionManagerCreateResult {
+    sessionId: string;
+    status: 'created';
+    modelId?: string;
+}
+/**
+ * send 结果（sd-u5 起）：消息已入队/已投递——目标 busy 时在下一 turn 边界注入。
+ * 失败形状走 SessionManagerErrorResult（error + hint），不再出现旧的 {blocked, rejected}。
+ */
+interface SessionManagerSendResult {
+    queued: true;
+}
+/** history 结果 */
+interface SessionManagerHistoryResult {
+    messages: unknown[];
+    truncated: boolean;
+}
+/** status 结果 */
+interface SessionManagerStatusResult {
+    status: string;
+    modelId?: string;
+}
+/** list 结果 */
+interface SessionManagerListResult {
+    sessions: SessionManagerSessionSummary[];
+}
+/** list 返回的 session 摘要（精简版） */
+interface SessionManagerSessionSummary {
+    id: string;
+    label: string;
+    cwd: string;
+    status: string;
+    spawnSource?: 'user' | 'agent';
+    parentAgentSessionId?: string;
+}
+/** abort 结果 */
+interface SessionManagerAbortResult {
+    success: boolean;
+}
+/** 错误响应形状（send 同步失败时 = { error, hint }；create 已成功时另附 sessionId） */
+interface SessionManagerErrorResult {
+    error: string;
+    /** create 已成功时附 sessionId + hint */
+    sessionId?: string;
+    hint?: string;
+}
+
+/**
+ * 子代理引擎契约（U7 引擎可发现性 + GUI 引擎选择）。
+ *
+ * 契约两端：
+ *   - 写侧：@zhushanwen/pi-subagent-workflow extension（pi 进程内，engine registry 权威）
+ *     在 session_start 时把注册引擎列表同步到 <agentDir>/subagents/engines.json；
+ *   - 读侧：xyz-agent runtime（subagent.getEngineConfig / subagent.setDefaultEngine RPC）
+ *     → renderer Settings「子代理」页引擎下拉（动态选项，不硬编码）。
+ *
+ * defaultEngine 的权威存储仍是 <agentDir>/subagents/config.json（extension 的
+ * ModelConfigService 读同文件——GUI 写入经 runtime 读改写，单一文件双端共识）。
+ */
+/** 引擎列表状态文件名（相对 <agentDir>/subagents/，与 config.json 同目录）。 */
+declare const SUBAGENTS_ENGINES_FILENAME: "engines.json";
+/** 引擎列表状态文件形状（写侧 extension 权威；读侧运行时 guard，坏形状降级空列表）。 */
+interface SubagentEnginesFile {
+    v: 1;
+    /** 已注册引擎 id 清单（注册序稳定；展示名即 id——'pi'/'zcode' 本身是品牌名）。 */
+    engines: string[];
+    /** 写入时间（ms epoch；诊断用，读侧不依赖）。 */
+    updatedAt: number;
+}
+/** getEngineConfig RPC 返回形状（engines.json + config.json defaultEngine 的合成视图）。 */
+interface SubagentEngineConfigView {
+    /** 可选引擎 id（动态发现；engines.json 缺失/损坏时为 ['pi'] 兜底——pi 恒可用）。 */
+    engines: string[];
+    /** 当前 defaultEngine（config.json 值；缺省 'pi'）。 */
+    defaultEngine: string;
+}
+
+export { ASK_USER_MARKER, type AskUserAnswers, type AskUserOption, type AskUserQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, PROTOCOL_VERSION, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SUBAGENTS_ENGINES_FILENAME, type SessionManagerAbortParams, type SessionManagerAbortResult, type SessionManagerAction, type SessionManagerCreateParams, type SessionManagerCreateResult, type SessionManagerErrorResult, type SessionManagerHistoryParams, type SessionManagerHistoryResult, type SessionManagerListParams, type SessionManagerListResult, type SessionManagerParams, type SessionManagerRequest, type SessionManagerSendParams, type SessionManagerSendResult, type SessionManagerSessionSummary, type SessionManagerStatusParams, type SessionManagerStatusResult, type StatItem, type SubagentEngineConfigView, type SubagentEnginesFile, type TreeItem, type TreeItemIcon, type WidgetMeta, askUserInteract, extractGui, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult, isSessionManagerAbortParams, isSessionManagerCreateParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerSendParams, isSessionManagerStatusParams };

package/dist/index.mjs

@@ -112,10 +112,49 @@ function isAskUserQuestion(value) {
   const q = value;
   return typeof q.question === "string" && (q.header === void 0 || typeof q.header === "string") && (q.options === void 0 || Array.isArray(q.options)) && (q.multiSelect === void 0 || typeof q.multiSelect === "boolean") && (q.allowOther === void 0 || typeof q.allowOther === "boolean");
 }
+
+// src/extensions/session-manager/types.ts
+function isRecord(v) {
+  return typeof v === "object" && v !== null;
+}
+function isOptionalString(v) {
+  return v === void 0 || typeof v === "string";
+}
+function isSessionIdParams(v) {
+  return isRecord(v) && typeof v.sessionId === "string";
+}
+function isSessionManagerCreateParams(v) {
+  return isRecord(v) && isOptionalString(v.cwd) && isOptionalString(v.label) && isOptionalString(v.prompt) && isOptionalString(v.model) && isOptionalString(v.thinkingLevel);
+}
+function isSessionManagerSendParams(v) {
+  return isRecord(v) && typeof v.sessionId === "string" && typeof v.prompt === "string";
+}
+function isSessionManagerHistoryParams(v) {
+  return isRecord(v) && typeof v.sessionId === "string" && (v.tailTurns === void 0 || typeof v.tailTurns === "number");
+}
+function isSessionManagerStatusParams(v) {
+  return isSessionIdParams(v);
+}
+function isSessionManagerAbortParams(v) {
+  return isSessionIdParams(v);
+}
+function isSessionManagerListParams(v) {
+  return isRecord(v) && (v.spawnSource === void 0 || v.spawnSource === "user" || v.spawnSource === "agent") && isOptionalString(v.parentAgentSessionId);
+}
+
+// src/extensions/session-manager/marker.ts
+var SESSION_MANAGER_MARKER = "\0XYZ_SESSION_MANAGER";
+var SESSION_MANAGER_ACTIONS = ["create", "send", "history", "status", "list", "abort"];
+
+// src/extensions/subagent-engine/contract.ts
+var SUBAGENTS_ENGINES_FILENAME = "engines.json";
 export {
   ASK_USER_MARKER,
   GUI_WIDGET_MARKER,
   PROTOCOL_VERSION,
+  SESSION_MANAGER_ACTIONS,
+  SESSION_MANAGER_MARKER,
+  SUBAGENTS_ENGINES_FILENAME,
   askUserInteract,
   extractGui,
   getAskUserAnswer,
@@ -126,5 +165,11 @@ export {
   isAskUserQuestion,
   isGuiCapable,
   isGuiComponent,
-  isGuiRenderResult
+  isGuiRenderResult,
+  isSessionManagerAbortParams,
+  isSessionManagerCreateParams,
+  isSessionManagerHistoryParams,
+  isSessionManagerListParams,
+  isSessionManagerSendParams,
+  isSessionManagerStatusParams
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xyz-agent/extension-protocol",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Extension GUI rendering protocol: types and helpers for pi extension dual-mode (TUI/GUI) rendering",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",