@epoch-agent/server 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Lang, WireSkillImportFailure, WireSkillImportForm, WireSkillRemoveFailure, WireCapabilitiesResponse, WireSkillBodyResponse, EpochUserContent, AgentEvent, WireEnvelope, CustomCommandDef, ExpandedCommand, ModelRef, SetSelectionResult, WireCommandExpansion, WireCustomCommand, WireGoalPhase, WireGoalRefusal, WireTurnState, WireSessionFinish, ApprovalOutcome, QuestionAnswer, SessionSurfaceView, WireSessionReference, WireFileReference, ProviderType, ModelSelectionOrigin, WireModelCaveat, WireModelRejection, ContextBreakdown, PermissionLevel, WirePermissionRememberFailure, WirePluginSourceType, WirePluginRefuseReason, WirePluginEntry, WireModelSource, WireModelProbeStatus, ScheduleDefinition, ScheduleRun, ScheduleBackendKind, OperationType, ScheduleTrigger, WireScheduleIssue, ScheduleRunStatus, TrustLevel, WireSandboxReason, WireAuditOutcome, WireAuditCode, WireCachedApproval, WireCachedDecision, WireToolVerdict, WireToolGateAxis, WireSecurityResponse, WireRewindScope, WireRewindRequest, WireCheckpointSummary, WireRewindPreview, WireRewindResponse, ActiveAgentRole, WireSettingValue, WireSettingLayer, WireSettingWriteLayer, WireSettingFutile, WireSettingApply, WireSettingValueKind, WireSettingsResponse, EpochConfig, WireCompressionLine, WireProviderSummary, WireToolSummary, Diagnostic, WireReplayMessage, WireFileChange, WireAuthGuard, WireWorkspaceDiffResponse, BackgroundTaskInfo, WireTasksResponse, WireBackgroundTask, WireScheduleRow } from '@epoch-agent/protocol';
+import { Lang, WireSkillImportFailure, WireSkillImportForm, WireSkillRemoveFailure, WireCapabilitiesResponse, WireSkillBodyResponse, EpochUserContent, AgentEvent, WireEnvelope, CustomCommandDef, ExpandedCommand, ModelRef, SetSelectionResult, WireCommandExpansion, WireCustomCommand, WireGoalPhase, WireGoalRefusal, WireTurnState, WireSessionFinish, ApprovalOutcome, QuestionAnswer, SessionSurfaceView, WireSessionReference, WireFileReference, ProviderType, ModelSelectionOrigin, WireModelCaveat, WireModelRejection, ContextBreakdown, PermissionLevel, WirePermissionRememberFailure, WirePluginSourceType, WirePluginRefuseReason, WirePluginEntry, WireModelSource, WireModelProbeStatus, ScheduleDefinition, ScheduleRun, ScheduleBackendKind, OperationType, ScheduleTrigger, WireScheduleIssue, ScheduleRunStatus, TrustLevel, WireSandboxReason, WireAuditOutcome, WireAuditCode, WireCachedApproval, WireCachedDecision, WireToolVerdict, WireToolGateAxis, WireSecurityResponse, WireRewindScope, WireRewindRequest, WireCheckpointSummary, WireRewindPreview, WireRewindResponse, ActiveAgentRole, WireSettingValue, WireSettingLayer, WireSettingWriteLayer, WireSettingFutile, WireSettingApply, WireSettingValueKind, WireSettingsResponse, EpochConfig, TokenUsage, WireCompressionLine, WireProviderSummary, WireToolSummary, Diagnostic, WireReplayMessage, WireFileChange, WireAuthGuard, WireWorkspaceDiffResponse, BackgroundTaskInfo, WireTasksResponse, WireBackgroundTask, WireScheduleRow } from '@epoch-agent/protocol';
 import { SerializableApprovalRequest, SerializableQuestionRequest, ApprovalRevokeResult, LevelChangeResult, WorkspaceFilesView } from '@epoch-agent/runtime';
 import { ServerResponse } from 'node:http';
 
@@ -2263,15 +2263,20 @@ interface RuntimeModel {
 }
 
 /**
- * 插件那一页的六条端点（方案 59 §六 E2，2026-08-21）：
+ * 插件那一页的十条端点（方案 59 §六 E2，2026-08-21；本地源与市场管理 2026-09-04
+ * 补，判据在 protocol 的 `wire-plugin.ts` 文件头第一节那次**翻案**）：
  *
  * ```
- * GET  /api/plugins                    装着的 + 市场里有什么 + pendingRestart
- * POST /api/plugins/install/preview    {ref}          → 将安装什么，一个字节都不写
- * POST /api/plugins/install            {ref, token}   → 真装
- * POST /api/plugins/update/preview     {name}         → 更新会带来什么
- * POST /api/plugins/update             {name, token}  → 真更新
- * POST /api/plugins/uninstall          {name}         → 卸载
+ * GET  /api/plugins                       装着的 + 市场里有什么 + 已加的市场 + pendingRestart
+ * POST /api/plugins/install/preview       {ref}           → 将安装什么，一个字节都不写
+ * POST /api/plugins/install               {ref, token}    → 真装
+ * POST /api/plugins/install/local/preview {path}          → 同上，来源是本机一条目录
+ * POST /api/plugins/install/local         {path, token}   → 真装
+ * POST /api/plugins/update/preview        {name}          → 更新会带来什么
+ * POST /api/plugins/update                {name, token}   → 真更新
+ * POST /api/plugins/uninstall             {name}          → 卸载
+ * POST /api/plugins/marketplaces          {source}        → 加一个市场
+ * POST /api/plugins/marketplaces/remove   {name}          → 移除一个市场
  * ```
  *
  * ## ⚠️ 这一层**一条策略判断都没有**
@@ -2285,10 +2290,10 @@ interface RuntimeModel {
  * 界面上是一条画成可点、点了却被拒的行（判据同 `PluginSearchHit.installable`
  * 为什么不从结果里剔掉远程那条）。
  *
- * ## ⚠️ 那一道闸：**五条 POST 在回环之外一律 403**，这是这个文件的正题
+ * ## ⚠️ 那一道闸：**九条 POST 在回环之外一律 403**，这是这个文件的正题
  *
  * 判据全文在 protocol 的 [wire-plugin.ts](../../protocol/src/wire-plugin.ts) 文件头
- * 第二节，这里记它对这一层的四条直接后果：
+ * 第二节，这里记它对这一层的五条直接后果：
  *
  * 1. **`ctx.lanExposed` 为真时 403 `plugin-write-lan-exposed`，一个字节都不写。**
  *    装一包插件会落下 `hooks.json` 和 `mcp.json`，那两样**起子进程** ——
@@ -2297,8 +2302,12 @@ interface RuntimeModel {
  * 2. **`install/preview` 也吃这道闸，虽然它一个字节都不写**：`allowRemote: true`
  *    的部署上，预览一条远程条目会 spawn `git clone --depth 1` 到 staging。
  *    按「写不写盘」切一刀会漏掉它；
- * 3. **那道闸在读请求体之前**，同 `addRole`：被拒的那一发连正文都不该被解析；
- * 4. **`GET` 刻意不挡。** 那一份里是插件名 / 版本 / 目录路径，和
+ * 3. **本地那两条同样挡**，虽然它们既不拉网也不起子进程。本地路径这一档的
+ *    **全部前提**是「网线另一头就是这台机器」，而 `lanExposed` 为真时那句前提是
+ *    假的 —— 放行的话，LAN 上的人能指着这台机器上任意一个目录说「装它」，
+ *    而那个目录里的 `hooks.json` 是谁写的他知道我们不知道；
+ * 4. **那道闸在读请求体之前**，同 `addRole`：被拒的那一发连正文都不该被解析；
+ * 5. **`GET` 刻意不挡。** 那一份里是插件名 / 版本 / 目录路径，和
  *    `GET /api/sessions/:id/capabilities` 早就在发的那些同一档 —— 而挡掉它的
  *    唯一后果是那一页在 LAN 那一档下一片空白，
  *    偏偏那时用户最想知道的就是「我装了什么、生效了没有」。
@@ -2437,13 +2446,27 @@ type ActionOutcomeView = {
     ok: true;
     detail: string;
 } | RefusalView;
+/** `PluginMarketplaceEntry`（runtime）的镜像 */
+interface MarketplaceView {
+    name: string;
+    source: string;
+    entries: number;
+    addedAt: number;
+    local: boolean;
+}
+/** 加 / 移除一个市场的结局。移除成功那一档没有 `marketplace` —— 它已经不在表里了 */
+type MarketOutcomeView = {
+    ok: true;
+    marketplace?: MarketplaceView;
+} | RefusalView;
 /**
- * `PluginControl`（runtime）在服务端眼里的样子 —— **只有那六个动词加一格布尔**。
+ * `PluginControl`（runtime）在服务端眼里的样子 —— **只有那十一个动词加一格布尔**。
  *
  * 镜像里只有它们，于是这个包**写不出** core 的 `setPluginEnabled`
- * （停用一个插件会静默拿掉别人正依赖的一批命令，正当性和「装 / 卸」不是一回事）、
- * 也写不出「往任意路径装一个插件」——那不是靠 review 盯住的，是编译期的事
- * （同 `SkillImportControlView` 只有两个动作、`RoleWriteControlView` 只有 `add`）。
+ * （停用一个插件会静默拿掉别人正依赖的一批命令，正当性和「装 / 卸」不是一回事）；
+ * 装进来的那两个动词也各自只表达得出一种来源 —— `install(ref)` 表达不出一条路径，
+ * `installLocal(path)` 表达不出一个 `github:`（那不是靠 review 盯住的，是编译期的事，
+ * 同 `SkillImportControlView` 只有两个动作、`RoleWriteControlView` 只有 `add`）。
  *
  * ⚠️ 每个方法都带 `lang?`。**镜像上漏一格不一定会红**（多一个可选参数是宽化，
  * `EpochRuntime` 照样满足这份镜像），而漏了的表现是这一层递不出去、一声不吭
@@ -2455,9 +2478,14 @@ interface PluginControlView {
     search(keyword?: string): readonly PluginHitView[];
     preview(ref: string, lang?: Lang): Promise<PreviewOutcomeView>;
     install(ref: string, token: string, lang?: Lang): Promise<InstallOutcomeView>;
+    previewLocal(path: string, lang?: Lang): Promise<PreviewOutcomeView>;
+    installLocal(path: string, token: string, lang?: Lang): Promise<InstallOutcomeView>;
     previewUpdate(name: string, lang?: Lang): Promise<PreviewOutcomeView>;
     update(name: string, token: string, lang?: Lang): Promise<InstallOutcomeView>;
     uninstall(name: string, lang?: Lang): Promise<ActionOutcomeView>;
+    marketplaces(): readonly MarketplaceView[];
+    addMarketplace(source: string, lang?: Lang): Promise<MarketOutcomeView>;
+    removeMarketplace(name: string, lang?: Lang): Promise<MarketOutcomeView>;
     readonly pendingRestart: boolean;
 }
 /**
@@ -3965,6 +3993,17 @@ interface WebRuntimeView extends RuntimeCapabilities, RuntimeSecurity, RuntimeSe
      */
     artifactsRoot: string;
     usageScope: 'session' | 'run';
+    /**
+     * 一段会话到此刻的**累计**用量（2026-09-04）。`EpochRuntime.sessionUsage`
+     * 结构上正好满足它。
+     *
+     * 收窄成一个函数而不是一份快照，理由和 `tools` 那个 getter 同一条：这本账
+     * 在别的会话 / 别的进程里也会被写，拍一张快照的话第二个会话读到的是第一个的数。
+     *
+     * ⚠️ **它是「刷新之后总账没了」唯一的来路**，判据全文在
+     * `WireMessageListResponse.usage` 上。`undefined` = 不知道，不是 0。
+     */
+    sessionUsage(sessionId: string): TokenUsage | undefined;
     /**
      * 自动压缩那条线（决定 8 的第三个时刻，2026-08-16）。`EpochRuntime.compression`
      * 结构上正好满足它 —— **对不上就是两边长歪了，装配那一行当场编译不过**。

package/dist/index.js

@@ -1449,6 +1449,7 @@ function config(ctx, res, lang) {
     ...runtime.config.budget?.maxCostUsd !== void 0 ? { maxCostUsd: runtime.config.budget.maxCostUsd } : {},
     ...runtime.config.brand !== void 0 ? { brand: runtime.config.brand } : {},
     ...runtime.config.sidebarMenu !== void 0 ? { sidebarMenu: runtime.config.sidebarMenu } : {},
+    ...runtime.config.blankCards !== void 0 ? { blankCards: runtime.config.blankCards } : {},
     provider: runtime.providerInfo,
     tools: runtime.tools,
     diagnostics: (lang && runtime.diagnosticsIn?.(lang)) ?? runtime.diagnosticList,
@@ -1540,7 +1541,11 @@ function listMessages(ctx, res, sessionId, lang) {
     return sendUnknownSession(res, sessionId, lang);
   }
   const messages = ctx.runtime.sessionStore?.loadMessages(sessionId) ?? [];
-  sendJson(res, 200, { messages });
+  const usage = ctx.runtime.sessionUsage(sessionId);
+  sendJson(res, 200, {
+    messages,
+    ...usage ? { usage } : {}
+  });
 }
 async function postMessage(ctx, req, res, sessionId, lang) {
   if (!ctx.hub.has(sessionId)) {
@@ -2453,6 +2458,15 @@ function toWirePluginHit(hit, installedNames) {
     installed: installedNames.has(hit.entry.name)
   };
 }
+function toWireMarketplace(market) {
+  return {
+    name: market.name,
+    source: market.source,
+    entries: market.entries,
+    addedAt: market.addedAt,
+    local: market.local
+  };
+}
 function toWirePreview2(preview) {
   const { manifest, source, inventory } = preview;
   return {
@@ -2505,6 +2519,7 @@ function listPlugins(ctx, res, lang) {
   sendJson(res, 200, {
     installed: installed.map(toWirePluginEntry),
     hits: control.search().map((hit) => toWirePluginHit(hit, installedNames)),
+    marketplaces: control.marketplaces().map(toWireMarketplace),
     pendingRestart: control.pendingRestart
   });
 }
@@ -2534,6 +2549,14 @@ async function previewPluginInstall(ctx, req, res, lang) {
   if (!body.ok) return sendError(res, body.status, "bad-body", body.message);
   sendPreview(res, await control.preview(fieldOf(asRecord(body.value), "ref"), lang));
 }
+async function previewLocalPluginInstall(ctx, req, res, lang) {
+  if (refusedByLan(ctx, res, lang)) return;
+  const control = controlOf(ctx, res, lang);
+  if (!control) return;
+  const body = await readJsonBody(req);
+  if (!body.ok) return sendError(res, body.status, "bad-body", body.message);
+  sendPreview(res, await control.previewLocal(fieldOf(asRecord(body.value), "path"), lang));
+}
 async function previewPluginUpdate(ctx, req, res, lang) {
   if (refusedByLan(ctx, res, lang)) return;
   const control = controlOf(ctx, res, lang);
@@ -2574,6 +2597,19 @@ async function installPluginFromMarket(ctx, req, res, lang) {
     await control.install(fieldOf(payload, "ref"), fieldOf(payload, "token"), lang)
   );
 }
+async function installLocalPlugin(ctx, req, res, lang) {
+  if (refusedByLan(ctx, res, lang)) return;
+  const control = controlOf(ctx, res, lang);
+  if (!control) return;
+  const body = await readJsonBody(req);
+  if (!body.ok) return sendError(res, body.status, "bad-body", body.message);
+  const payload = asRecord(body.value);
+  sendAction(
+    res,
+    control,
+    await control.installLocal(fieldOf(payload, "path"), fieldOf(payload, "token"), lang)
+  );
+}
 async function updateInstalledPlugin(ctx, req, res, lang) {
   if (refusedByLan(ctx, res, lang)) return;
   const control = controlOf(ctx, res, lang);
@@ -2595,6 +2631,30 @@ async function uninstallPluginByName(ctx, req, res, lang) {
   if (!body.ok) return sendError(res, body.status, "bad-body", body.message);
   sendAction(res, control, await control.uninstall(fieldOf(asRecord(body.value), "name"), lang));
 }
+function sendMarket(res, outcome) {
+  sendJson(res, 200, {
+    ok: outcome.ok,
+    marketplace: outcome.ok && outcome.marketplace ? toWireMarketplace(outcome.marketplace) : null,
+    reason: outcome.ok ? null : outcome.reason,
+    detail: outcome.ok ? null : outcome.detail
+  });
+}
+async function addPluginMarketplace(ctx, req, res, lang) {
+  if (refusedByLan(ctx, res, lang)) return;
+  const control = controlOf(ctx, res, lang);
+  if (!control) return;
+  const body = await readJsonBody(req);
+  if (!body.ok) return sendError(res, body.status, "bad-body", body.message);
+  sendMarket(res, await control.addMarketplace(fieldOf(asRecord(body.value), "source"), lang));
+}
+async function removePluginMarketplace(ctx, req, res, lang) {
+  if (refusedByLan(ctx, res, lang)) return;
+  const control = controlOf(ctx, res, lang);
+  if (!control) return;
+  const body = await readJsonBody(req);
+  if (!body.ok) return sendError(res, body.status, "bad-body", body.message);
+  sendMarket(res, await control.removeMarketplace(fieldOf(asRecord(body.value), "name"), lang));
+}
 function toWireProvider(option, lang) {
   return {
     type: option.type,
@@ -4185,6 +4245,12 @@ async function handleApi(opts, req, res, method, segments, lang) {
   if (resource === "plugins" && first === "install" && second === void 0 && method === "POST") {
     return installPluginFromMarket(ctx, req, res, lang);
   }
+  if (resource === "plugins" && first === "install" && second === "local" && detail === "preview" && method === "POST") {
+    return previewLocalPluginInstall(ctx, req, res, lang);
+  }
+  if (resource === "plugins" && first === "install" && second === "local" && detail === void 0 && method === "POST") {
+    return installLocalPlugin(ctx, req, res, lang);
+  }
   if (resource === "plugins" && first === "update" && second === "preview" && method === "POST") {
     return previewPluginUpdate(ctx, req, res, lang);
   }
@@ -4194,6 +4260,12 @@ async function handleApi(opts, req, res, method, segments, lang) {
   if (resource === "plugins" && first === "uninstall" && second === void 0 && method === "POST") {
     return uninstallPluginByName(ctx, req, res, lang);
   }
+  if (resource === "plugins" && first === "marketplaces" && second === "remove" && method === "POST") {
+    return removePluginMarketplace(ctx, req, res, lang);
+  }
+  if (resource === "plugins" && first === "marketplaces" && second === void 0 && method === "POST") {
+    return addPluginMarketplace(ctx, req, res, lang);
+  }
   if (resource === "providers" && first === void 0 && isRead(method)) {
     return listProviders(ctx, res, lang);
   }