@zhushanwen/extension-protocol 0.11.0

package/dist/index.js

@@ -0,0 +1,389 @@
+import {
+  BACKGROUND_TASK_ID_PREFIX,
+  BACKGROUND_TASK_REGISTRY_FILENAME,
+  BACKGROUND_TASK_REGISTRY_VERSION,
+  BASE_TOOL_ENHANCE_DIRNAME,
+  MAX_TERMINAL_REGISTRY_ENTRIES,
+  isActiveBackgroundTaskState,
+  isBackgroundTaskRegistryEntry,
+  isTerminalBackgroundTaskState
+} from "./chunk-NJ3E4ISR.js";
+
+// src/core/types.ts
+var PROTOCOL_VERSION = 1;
+
+// src/core/markers.ts
+var GUI_WIDGET_MARKER = "\0TAIJI_GUI_WIDGET:";
+
+// src/core/helpers.ts
+function isGuiCapable(ctx) {
+  return ctx.mode === "rpc";
+}
+function guiResult(component, meta) {
+  const result = {
+    v: PROTOCOL_VERSION,
+    component: stripUndefined(component)
+  };
+  if (meta !== void 0) result.meta = stripUndefined(meta);
+  return result;
+}
+function guiComponent(type, props) {
+  return { type, props };
+}
+function guiSetWidget(ctx, key, result) {
+  if (!ctx.ui?.setWidget) return;
+  if (result) {
+    const encoded = [GUI_WIDGET_MARKER + JSON.stringify(stripUndefined(result))];
+    ctx.ui.setWidget(key, encoded);
+  } else {
+    ctx.ui.setWidget(key, void 0);
+  }
+}
+function setWidgetDual(ctx, key, content) {
+  if (!ctx.ui?.setWidget) return;
+  if (content === void 0) {
+    ctx.ui.setWidget(key, void 0);
+    return;
+  }
+  if (isGuiCapable(ctx)) {
+    guiSetWidget(ctx, key, content.gui);
+  } else {
+    ctx.ui.setWidget(key, content.text);
+  }
+}
+function extractGui(details) {
+  const g = details?.__gui__;
+  if (g && typeof g === "object" && "v" in g && "component" in g && g.v === PROTOCOL_VERSION) {
+    return g;
+  }
+  return void 0;
+}
+function isGuiComponent(value) {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value;
+  return typeof obj.type === "string" && obj.props !== null && obj.props !== void 0 && typeof obj.props === "object";
+}
+function isGuiRenderResult(value) {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value;
+  return obj.v === PROTOCOL_VERSION && isGuiComponent(obj.component);
+}
+function firstContentText(result) {
+  const first = result.content[0];
+  return first?.type === "text" ? first.text ?? "" : "";
+}
+function stripUndefined(obj) {
+  if (obj === null || obj === void 0) return obj;
+  if (typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(stripUndefined);
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== void 0) {
+      result[key] = typeof value === "object" ? stripUndefined(value) : value;
+    }
+  }
+  return result;
+}
+
+// src/core/select-rpc.ts
+var RESPONSE_PREVIEW_LENGTH = 200;
+function isChannelErrorResult(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v) && typeof v.error === "string";
+}
+function formatChannelErrorText(err) {
+  return err.hint ? `${err.error}
+hint: ${err.hint}` : err.error;
+}
+function emitRpcLog(opts, msg, detail) {
+  opts?.log?.(msg, detail);
+}
+async function callMarkerRpc(ctx, marker, payload, opts) {
+  const select = ctx.ui?.select;
+  if (!select) {
+    throw new Error(
+      `callMarkerRpc() requires ctx.ui.select (marker ${JSON.stringify(marker)}). Non-GUI ctx must be gated by the caller first \u2014 see askUserInteract precedent (isGuiCapable(ctx) && ctx.ui?.select, or a mode check).`
+    );
+  }
+  let value;
+  try {
+    value = await select(marker, [payload], { signal: opts?.signal, timeout: opts?.timeout });
+  } catch (err) {
+    emitRpcLog(opts, `select channel threw (marker ${JSON.stringify(marker)})`, {
+      reason: err instanceof Error ? err.message : String(err)
+    });
+    return { ok: false, reason: "channel-error" };
+  }
+  if (value === void 0 || value === null) {
+    return { ok: false, reason: opts?.signal?.aborted ? "cancelled" : "timeout" };
+  }
+  if (typeof value !== "string") {
+    emitRpcLog(opts, `select resolved non-string value (marker ${JSON.stringify(marker)})`, {
+      valueType: typeof value
+    });
+    return { ok: false, reason: "channel-error" };
+  }
+  try {
+    JSON.parse(value);
+  } catch {
+    emitRpcLog(opts, `non-JSON response (marker ${JSON.stringify(marker)})`, {
+      responseHead: value.slice(0, RESPONSE_PREVIEW_LENGTH)
+    });
+    return { ok: false, reason: "non-json" };
+  }
+  return { ok: true, value };
+}
+
+// src/extensions/ask-user/marker.ts
+var ASK_USER_MARKER = "\0TAIJI_ASK_USER";
+
+// src/extensions/ask-user/helpers.ts
+async function askUserInteract(ctx, questions, options) {
+  if (questions.length === 0) return {};
+  if (isGuiCapable(ctx) && ctx.ui?.select) {
+    const payload = JSON.stringify(stripUndefined({
+      questions,
+      allowCancel: options?.allowCancel ?? true
+    }));
+    const value = await ctx.ui.select(
+      ASK_USER_MARKER,
+      // title = marker，runtime/前端据此识别
+      [payload],
+      // options[0] = JSON payload（runtime 解析）
+      { signal: options?.signal }
+    );
+    if (value === void 0) return null;
+    try {
+      return JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  throw new Error(
+    "askUserInteract() is only available in RPC mode. In TUI mode, use ctx.ui.custom() with your own Component directly."
+  );
+}
+function askUserKey(question) {
+  return question.header ?? question.question;
+}
+function getAskUserAnswer(answers, question) {
+  const key = askUserKey(question);
+  const raw = answers[key];
+  if (raw === void 0) return void 0;
+  if (question.multiSelect) {
+    try {
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed : [raw];
+    } catch {
+      return [raw];
+    }
+  }
+  return raw;
+}
+function getAskUserOther(answers, question) {
+  return answers[`${askUserKey(question)}__other`];
+}
+function isAskUserQuestion(value) {
+  if (typeof value !== "object" || value === null) return false;
+  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 && !Array.isArray(v);
+}
+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);
+}
+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);
+}
+
+// src/extensions/session-manager/marker.ts
+var SESSION_MANAGER_MARKER = "\0TAIJI_SESSION_MANAGER";
+var SESSION_MANAGER_ACTIONS = ["create", "send", "history", "status", "list", "abort"];
+
+// src/extensions/subagent-inflight/marker.ts
+var SUBAGENT_INFLIGHT_MARKER = "\0TAIJI_SUBAGENT_INFLIGHT";
+
+// src/extensions/subagent-inflight/types.ts
+var INFLIGHT_REPORT_ACK = '{"ack":true}';
+function isRecord2(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isSubagentInFlightReport(v) {
+  if (!isRecord2(v)) return false;
+  if (typeof v.inFlight !== "number" || !Number.isInteger(v.inFlight) || v.inFlight < 0) return false;
+  if (typeof v.emittedAt !== "number") return false;
+  if (v.sessionId !== void 0 && typeof v.sessionId !== "string") return false;
+  return true;
+}
+function isInFlightReportAck(v) {
+  return v === INFLIGHT_REPORT_ACK;
+}
+
+// src/extensions/plugin-bridge/marker.ts
+var BRIDGE_MARKER = "\0TAIJI_BRIDGE";
+var BRIDGE_METHODS = ["bridge:sync", "bridge:tool_execute", "bridge:event", "bridge:intercept"];
+
+// src/extensions/plugin-bridge/guards.ts
+function isRecord3(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isBridgeErrorResponse(v) {
+  return isChannelErrorResult(v);
+}
+function isBridgeToolExecuteResponse(v) {
+  return isRecord3(v) && typeof v.content === "string" && (v.isError === void 0 || typeof v.isError === "boolean");
+}
+function isBridgeSyncPayload(v) {
+  return isRecord3(v) && v.success === true && Array.isArray(v.tools);
+}
+function isBridgeInterceptResponse(v) {
+  return isRecord3(v) && Array.isArray(v.injectedMessages);
+}
+function isSyncedTool(v) {
+  return isRecord3(v) && typeof v.name === "string" && typeof v.description === "string" && isRecord3(v.parameters) && v.parameters.type === "object";
+}
+
+// src/extensions/subagent-engine/contract.ts
+var SUBAGENTS_ENGINES_FILENAME = "engines.json";
+
+// src/pending-entries.ts
+var PENDING_REGISTER_ENTRY_TYPE = "pending:register";
+var PENDING_UNREGISTER_ENTRY_TYPE = "pending:unregister";
+function scanPendingEntries(entries) {
+  const scan = { registerEntries: [], unregisteredIds: /* @__PURE__ */ new Set() };
+  for (const raw of entries) {
+    if (!raw || typeof raw !== "object") continue;
+    const entry = raw;
+    if (entry.customType === PENDING_REGISTER_ENTRY_TYPE) {
+      scan.registerEntries.push({ data: entry.data ?? {} });
+    } else if (entry.customType === PENDING_UNREGISTER_ENTRY_TYPE) {
+      const data = entry.data ?? {};
+      if (typeof data.id === "string") scan.unregisteredIds.add(data.id);
+    }
+  }
+  return scan;
+}
+function applyPendingDiff(scan) {
+  const active = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const { data } of scan.registerEntries) {
+    if (typeof data.id !== "string" || scan.unregisteredIds.has(data.id) || seen.has(data.id)) continue;
+    seen.add(data.id);
+    active.push({ data });
+  }
+  return active;
+}
+function collectActivePendingIds(entries, opts) {
+  const active = applyPendingDiff(scanPendingEntries(entries));
+  const prefix = opts?.idPrefix;
+  const ids = /* @__PURE__ */ new Set();
+  for (const { data } of active) {
+    const id = data.id;
+    if (typeof id !== "string") continue;
+    if (prefix !== void 0 && !id.startsWith(prefix)) continue;
+    ids.add(id);
+  }
+  return ids;
+}
+function mapReasonToStatus(reason) {
+  switch (reason) {
+    case "completed":
+      return "completed";
+    case "failed":
+      return "failed";
+    case "cancelled":
+      return "cancelled";
+    case "expired":
+      return "expired";
+    case "time_limited":
+      return "time_limited";
+    case "budget_limited":
+      return "failed";
+    case "aborted":
+      return "aborted";
+    case "interrupted":
+    case "interrupted-by-restart":
+    case "interrupted-by-parent":
+      return "aborted";
+    case "reopened":
+      return "completed";
+    default:
+      return "completed";
+  }
+}
+export {
+  ASK_USER_MARKER,
+  BACKGROUND_TASK_ID_PREFIX,
+  BACKGROUND_TASK_REGISTRY_FILENAME,
+  BACKGROUND_TASK_REGISTRY_VERSION,
+  BASE_TOOL_ENHANCE_DIRNAME,
+  BRIDGE_MARKER,
+  BRIDGE_METHODS,
+  GUI_WIDGET_MARKER,
+  INFLIGHT_REPORT_ACK,
+  MAX_TERMINAL_REGISTRY_ENTRIES,
+  PENDING_REGISTER_ENTRY_TYPE,
+  PENDING_UNREGISTER_ENTRY_TYPE,
+  PROTOCOL_VERSION,
+  SESSION_MANAGER_ACTIONS,
+  SESSION_MANAGER_MARKER,
+  SUBAGENTS_ENGINES_FILENAME,
+  SUBAGENT_INFLIGHT_MARKER,
+  applyPendingDiff,
+  askUserInteract,
+  callMarkerRpc,
+  collectActivePendingIds,
+  extractGui,
+  firstContentText,
+  formatChannelErrorText,
+  getAskUserAnswer,
+  getAskUserOther,
+  guiComponent,
+  guiResult,
+  guiSetWidget,
+  isActiveBackgroundTaskState,
+  isAskUserQuestion,
+  isBackgroundTaskRegistryEntry,
+  isBridgeErrorResponse,
+  isBridgeInterceptResponse,
+  isBridgeSyncPayload,
+  isBridgeToolExecuteResponse,
+  isChannelErrorResult,
+  isGuiCapable,
+  isGuiComponent,
+  isGuiRenderResult,
+  isInFlightReportAck,
+  isSessionManagerAbortParams,
+  isSessionManagerCreateParams,
+  isSessionManagerHistoryParams,
+  isSessionManagerListParams,
+  isSessionManagerSendParams,
+  isSessionManagerStatusParams,
+  isSubagentInFlightReport,
+  isSyncedTool,
+  isTerminalBackgroundTaskState,
+  mapReasonToStatus,
+  scanPendingEntries,
+  setWidgetDual
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@zhushanwen/extension-protocol",
+  "version": "0.11.0",
+  "description": "Cross-layer pi extension contract package: dual-mode (TUI/GUI) rendering helpers, session/background-task/pending-entries protocols, and shared behavior primitives",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./background-task": {
+      "types": "./dist/background-task-entry.d.ts",
+      "import": "./dist/background-task-entry.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}