@zhin.js/host-http 1.2.2 → 1.4.0

package/src/console-rest-pages-helpers.ts

@@ -25,10 +25,17 @@ const INTROSPECTION_PAGE_SIZES = {
   endpoints: 30,
   bindings: 30,
   mcp: 30,
+  'recent-turns': 20,
 } as const;
 
 type IntrospectionKind = keyof typeof INTROSPECTION_PAGE_SIZES;
 
+/** Owning plugin of a capability row (`ConsoleIntrospectionOwner`, #1250): searchable by `q`. */
+const OWNER_FIELDS: ReadonlyArray<(item: unknown) => string | undefined> = [
+  (item) => stringProp(item, 'pluginInstance'),
+  (item) => stringProp(item, 'pluginPackage'),
+];
+
 // ---------------------------------------------------------------------------
 // Runtime snapshot introspection
 // ---------------------------------------------------------------------------
@@ -41,7 +48,8 @@ export function registerIntrospectionRoutes(
 ): void {
   const collectors: Array<{
     kind: IntrospectionKind;
-    collect: (introspection: ConsoleAgentIntrospection | undefined) => { rows: readonly unknown[]; note?: string };
+    collect: (introspection: ConsoleAgentIntrospection | undefined) =>
+      { rows: readonly unknown[]; note?: string } | Promise<{ rows: readonly unknown[]; note?: string }>;
     fields: Array<(item: unknown) => string | undefined>;
   }> = [
     {
@@ -51,6 +59,7 @@ export function registerIntrospectionRoutes(
         (c) => stringProp(c, 'pattern'),
         (c) => stringProp(c, 'desc'),
         (c) => stringProp(c, 'plugin'),
+        ...OWNER_FIELDS,
       ],
     },
     {
@@ -62,6 +71,7 @@ export function registerIntrospectionRoutes(
         (m) => stringProp(m, 'phase'),
         (m) => stringProp(m, 'target'),
         (m) => stringProp(m, 'source'),
+        ...OWNER_FIELDS,
       ],
     },
     {
@@ -71,6 +81,7 @@ export function registerIntrospectionRoutes(
         (c) => stringProp(c, 'name'),
         (c) => stringProp(c, 'owner'),
         (c) => stringProp(c, 'source'),
+        ...OWNER_FIELDS,
       ],
     },
     {
@@ -87,11 +98,22 @@ export function registerIntrospectionRoutes(
     },
     {
       kind: 'bindings',
-      collect: (value) => ({ rows: value?.bindings?.() ?? [] }),
+      collect: async (value) => ({ rows: await value?.bindings?.() ?? [] }),
       fields: [
         (a) => stringProp(a, 'name'),
         (a) => stringProp(a, 'provider'),
         (a) => stringProp(a, 'model'),
+        (a) => stringProp(a, 'displayName'),
+      ],
+    },
+    {
+      // #1250: the Agent workbench's recent conversations come from the turn trace archive, newest first.
+      kind: 'recent-turns',
+      collect: async (value) => ({ rows: await value?.recentTurns?.() ?? [] }),
+      fields: [
+        (t) => stringProp(t, 'sessionDisplayName'),
+        (t) => stringProp(t, 'sessionKey'),
+        (t) => stringProp(t, 'status'),
       ],
     },
     {
@@ -101,6 +123,7 @@ export function registerIntrospectionRoutes(
         (t) => stringProp(t, 'name'),
         (t) => stringProp(t, 'source'),
         (t) => stringProp(t, 'description'),
+        ...OWNER_FIELDS,
       ],
     },
     {
@@ -114,6 +137,7 @@ export function registerIntrospectionRoutes(
         (section) => stringProp(section, 'layer'),
         (section) => stringProp(section, 'retention'),
         (section) => stringProp(section, 'source'),
+        ...OWNER_FIELDS,
       ],
     },
     {
@@ -136,7 +160,7 @@ export function registerIntrospectionRoutes(
       const lease = kind === 'endpoints' ? null : ctx.acquireAgentRuntime?.() ?? null;
       try {
         const introspection = lease?.value.introspection;
-        const { rows, note } = collect(introspection);
+        const { rows, note } = await collect(introspection);
         const query = url.searchParams;
         const filter = query.get('filter')?.trim() || undefined;
         const filtered = filterByFields([...rows], filter, fields);

package/src/console-rest-pages.ts

@@ -17,6 +17,15 @@ import {
   isValidNpmPackageName,
 } from './marketplace-registry.js';
 import type { ConsoleMessageEventData } from '@zhin.js/console-protocol';
+import {
+  informativeKeywords,
+  isLocale,
+  normalizePluginCategory,
+  packageAuthorName,
+  pickLocalizedText,
+  readPluginMarketplaceMetadata,
+  type PluginLocalizedText,
+} from '@zhin.js/plugin-runtime';
 import {
   clampPositiveInt,
   decodePathParam,
@@ -65,7 +74,10 @@ export interface ConsoleAgentIntrospection {
   commands?(): readonly unknown[];
   middlewares?(): readonly unknown[];
   components?(): readonly unknown[];
-  bindings?(): readonly unknown[];
+  /** Agent bindings with the provider / model they actually run on (may read the provider graph). */
+  bindings?(): readonly unknown[] | Promise<readonly unknown[]>;
+  /** Recent Agent turns from the trace archive, newest first (#1250). */
+  recentTurns?(): readonly unknown[] | Promise<readonly unknown[]>;
   tools?(): readonly unknown[];
   promptSections?(): readonly unknown[];
   mcp?(): { rows: readonly unknown[]; note?: string } | readonly unknown[];
@@ -356,6 +368,11 @@ function registerLogsRoutes(
   }, { summary: 'Cleanup old system logs', tags: ['console', 'logs'] });
 }
 
+/** Locale-keyed texts from an untrusted registry entry (reuses the published-manifest reader). */
+function localizedTextOf(value: unknown): PluginLocalizedText | undefined {
+  return readPluginMarketplaceMetadata({ metadata: { displayNameI18n: value } }).displayNameI18n;
+}
+
 // ---------------------------------------------------------------------------
 // marketplace（legacy marketplace-rest-api.ts；plugins.json + npmmirror）
 // ---------------------------------------------------------------------------
@@ -390,10 +407,17 @@ function registerMarketplaceRoutes(
       const versions = meta.versions as Record<string, Record<string, unknown>> | undefined;
       const latestInfo = latest && versions ? versions[latest] : undefined;
       const time = meta.time as Record<string, string> | undefined;
+      // Marketplace fields come from the published manifest (`zhin.metadata`); the author is the
+      // package's author / maintainers, never the publishing account (`_npmUser`, a release bot).
+      const market = readPluginMarketplaceMetadata(latestInfo?.zhin);
       return {
         name: meta.name,
         version: latest,
-        description: meta.description || '',
+        ...(market.displayName ? { displayName: market.displayName } : {}),
+        ...(market.displayNameI18n ? { displayNameI18n: market.displayNameI18n } : {}),
+        ...(market.descriptionI18n ? { descriptionI18n: market.descriptionI18n } : {}),
+        ...(market.category ? { category: market.category } : {}),
+        description: (latestInfo?.description as string | undefined) || meta.description || '',
         readme: meta.readme || '',
         license: meta.license || latestInfo?.license || '',
         homepage: meta.homepage || latestInfo?.homepage || '',
@@ -401,11 +425,8 @@ function registerMarketplaceRoutes(
           (meta.repository as { url?: string } | undefined)?.url ||
           (latestInfo?.repository as { url?: string } | undefined)?.url ||
           '',
-        author:
-          typeof meta.author === 'string'
-            ? meta.author
-            : (meta.author as { name?: string } | undefined)?.name || '',
-        keywords: (latestInfo?.keywords as string[]) || [],
+        author: packageAuthorName(latestInfo ?? {}) ?? packageAuthorName(meta) ?? '',
+        keywords: informativeKeywords(latestInfo?.keywords),
         engines: latestInfo?.engines || {},
         peerDependencies: latestInfo?.peerDependencies || {},
         versions: Object.keys(versions || {}),
@@ -421,32 +442,48 @@ function registerMarketplaceRoutes(
       100,
       Math.max(1, parseInt(url.searchParams.get('size') ?? url.searchParams.get('limit') ?? '20', 10) || 20),
     );
-    const category = url.searchParams.get('category') ?? undefined;
+    const rawCategory = url.searchParams.get('category') || undefined;
+    const category = rawCategory === undefined ? undefined : normalizePluginCategory(rawCategory) ?? rawCategory;
     const official = url.searchParams.get('official') ?? undefined;
+    const rawLocale = url.searchParams.get('locale');
+    const locale = isLocale(rawLocale) ? rawLocale : undefined;
     const searchKeyword = q.trim().toLowerCase();
 
     try {
       const allPlugins = (await registry.list()) as readonly Record<string, unknown>[];
-      let plugins = allPlugins.map((p) => ({
+      let plugins = allPlugins.map((p) => {
+        const displayNameI18n = localizedTextOf(p.displayNameI18n);
+        const descriptionI18n = localizedTextOf(p.descriptionI18n);
+        const displayName = typeof p.displayName === 'string' ? p.displayName : '';
+        const description = typeof p.description === 'string' ? p.description : '';
+        return {
         name: p.name,
-        displayName: p.displayName || '',
+        // `locale` resolves the display texts for the caller; translations stay available either way.
+        displayName: locale ? pickLocalizedText(displayNameI18n, locale, displayName) ?? '' : displayName,
+        ...(displayNameI18n ? { displayNameI18n } : {}),
         version: p.version || '',
-        description: p.description || '',
+        description: locale ? pickLocalizedText(descriptionI18n, locale, description) ?? '' : description,
+        ...(descriptionI18n ? { descriptionI18n } : {}),
         author: p.author || '',
         isOfficial: typeof p.name === 'string' && /^@zhin\.js\/[a-z0-9][a-z0-9._-]*$/.test(p.name),
         official: typeof p.name === 'string' && /^@zhin\.js\/[a-z0-9][a-z0-9._-]*$/.test(p.name),
-        category: p.category || 'util',
-        keywords: (p.tags as string[]) || [],
+        category: normalizePluginCategory(p.category) ?? 'utility',
+        keywords: informativeKeywords(p.tags),
         npm: p.npm || `https://www.npmjs.com/package/${p.name}`,
         date: p.lastUpdate || '',
         downloads: p.downloads || { weekly: 0, monthly: 0 },
         readme: p.readme || '',
         license: p.license || '',
-      }));
+        };
+      });
 
       if (searchKeyword) {
         plugins = plugins.filter((p) => {
-          const haystack = [p.name, p.displayName, p.description, ...(p.keywords || [])]
+          const haystack = [
+            p.name, p.displayName, p.description,
+            ...Object.values(p.displayNameI18n ?? {}), ...Object.values(p.descriptionI18n ?? {}),
+            ...p.keywords,
+          ]
             .join(' ')
             .toLowerCase();
           return haystack.includes(searchKeyword);

package/src/console-rpc-extended/contracts.ts

@@ -22,6 +22,11 @@ export interface ConsoleRpcExtendedCtx {
   databaseHost?: { models: { get(name: string): unknown } };
   /** Narrow generation-bound persistent-job port; null when Assistant is disabled. */
   resolveScheduleEngine?: () => ConsoleScheduleEngine | null | undefined;
+  /**
+   * Resolves a persistent job's delivery target (#1250): `{ resolved, display?, reason? }`, where
+   * `resolved: false` means the job's results cannot be delivered (no target / unknown account).
+   */
+  describeScheduleTarget?: (notify: unknown) => ConsoleScheduleTarget;
   /** LoginAssist list/submit/cancel（刷新后仍可消费扫码/滑块待办）；ADR 0058 flow methods are optional. */
   loginAssist?: ConsoleLoginAssistPort;
   /** ADR 0058: the Endpoint's login declaration and lease-scoped login control (`null` = unknown Endpoint). */
@@ -160,6 +165,11 @@ export interface ScheduleJobRow {
   id: string;
   cron: string;
   description?: string;
+  /** Host display metadata (`ScheduleJobDisplay` in `@zhin.js/plugin-runtime`). */
+  title?: string;
+  titleI18n?: Readonly<Partial<Record<string, string>>>;
+  kind?: 'plugin-internal' | 'user-task';
+  lastRun?: { startedAt: number; finishedAt: number; status: 'succeeded' | 'failed'; error?: string };
 }
 
 export interface InboxSelection {
@@ -219,3 +229,11 @@ export interface EndpointManagementPort {
   setGroupAdmin?(request: EndpointAdminCommand): Promise<void>;
   deleteFriend?(request: EndpointUserCommand): Promise<void>;
 }
+
+/** `target` of a `schedule:list` persistent row (#1250). */
+export interface ConsoleScheduleTarget {
+  readonly resolved: boolean;
+  readonly display?: string;
+  /** `missing_target` | `incomplete_target` | `endpoint_not_found` */
+  readonly reason?: string;
+}

package/src/console-rpc-extended/dispatcher.ts

@@ -21,7 +21,7 @@ export async function dispatchExtendedConsoleRpc(
   switch (type) {
     case 'schedule:list':
     case 'cron:list':
-      return listSchedule(ctx);
+      return listSchedule(ctx, d);
 
     case 'cron:validate':
       return validateCron(d);

package/src/console-rpc-extended/endpoint-rpc.ts

@@ -1,4 +1,5 @@
 import type { ConsoleRpcExtendedCtx, EndpointManagementPort, ExtendedRpcResult } from './contracts.js';
+import type { EndpointManagementCapability } from '@zhin.js/console-protocol';
 import { boolField, numField, strField, withLiveEndpoint } from './rpc-values.js';
 
 export async function listFriends(
@@ -12,7 +13,7 @@ export async function listFriends(
       const friends = [...await management.listFriends()];
       return { data: { friends, count: friends.length } };
     }
-    return { error: `当前适配器（${endpoint.adapter}）不支持好友列表` };
+    return unsupportedList('friends', 'listFriends', endpoint.adapter, '好友列表');
   });
 }
 
@@ -27,7 +28,7 @@ export async function listGroups(
       const groups = [...await management.listGroups()];
       return { data: { groups, count: groups.length } };
     }
-    return { error: `当前适配器（${endpoint.adapter}）不支持群列表` };
+    return unsupportedList('groups', 'listGroups', endpoint.adapter, '群列表');
   });
 }
 
@@ -42,7 +43,7 @@ export async function listChannels(
       const channels = [...await management.listChannels()];
       return { data: { channels, count: channels.length } };
     }
-    return { error: `当前适配器（${endpoint.adapter}）不支持频道列表` };
+    return unsupportedList('channels', 'listChannels', endpoint.adapter, '频道列表');
   });
 }
 
@@ -59,13 +60,36 @@ export async function listGroupMembers(
   return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
     const method = management.listGroupMembers;
     if (!method) {
-      return { error: `当前适配器（${adapter}）不支持群成员列表` };
+      return unsupportedList('members', 'listGroupMembers', adapter, '群成员列表');
     }
     const members = [...await method.call(management, { groupId })];
     return { data: { members, count: members.length } };
   });
 }
 
+/**
+ * A read the Adapter does not declare is not a failure (#1250): reply with an empty list plus
+ * `status: 'unsupported'` (`ConsoleEndpointCapabilityUnsupported`) instead of `{ error }`, so the
+ * Console can render "该平台不提供" rather than a red read error. Older clients still see an empty
+ * list with `count: 0`.
+ */
+function unsupportedList(
+  key: 'friends' | 'groups' | 'channels' | 'members',
+  capability: EndpointManagementCapability,
+  adapter: string,
+  label: string,
+): ExtendedRpcResult {
+  return {
+    data: {
+      [key]: [],
+      count: 0,
+      status: 'unsupported',
+      capability,
+      message: `当前适配器（${adapter}）不支持${label}`,
+    },
+  };
+}
+
 // ---------------------------------------------------------------- 群管/好友写操作
 
 interface GroupWriteSpec {

package/src/console-rpc-extended/index.ts

@@ -1,6 +1,7 @@
 export type {
   ConsoleRpcExtendedCtx,
   ConsoleScheduleEngine,
+  ConsoleScheduleTarget,
   ConsoleWorkroomKnowledgeControlPort,
   ConsoleWorkroomProfileControlPort,
   ExtendedRpcResult,

package/src/console-rpc-extended/schedule-rpc.ts

@@ -6,7 +6,32 @@ const CRON_NOT_WIRED =
   '持久化调度未接线：当前 Plugin Runtime ScheduleHost 仅支持插件注册的内存任务（list），' +
   '不支持 add/remove/pause/resume（需要 @zhin.js/agent 持久化调度引擎）';
 
-export function listSchedule(ctx: ConsoleScheduleListCtx): Promise<ExtendedRpcResult> | ExtendedRpcResult {
+/** `titleI18n[locale]` → `titleI18n[language]` → `title`. */
+function localizedTitle(job: ScheduleJobRow, locale: string | undefined): string | undefined {
+  const map = job.titleI18n && typeof job.titleI18n === 'object' ? job.titleI18n : undefined;
+  if (locale && map) {
+    const exact = map[locale];
+    if (typeof exact === 'string' && exact.trim()) return exact.trim();
+    const language = locale.split('-')[0]!;
+    const byLanguage = map[language];
+    if (typeof byLanguage === 'string' && byLanguage.trim()) return byLanguage.trim();
+  }
+  return typeof job.title === 'string' && job.title.trim() ? job.title.trim() : undefined;
+}
+
+function lastRunFields(job: ScheduleJobRow): Record<string, unknown> {
+  const run = job.lastRun;
+  if (!run || typeof run !== 'object' || typeof run.startedAt !== 'number') return {};
+  return {
+    lastExecutedAt: run.startedAt,
+    ...(typeof run.finishedAt === 'number' ? { lastFinishedAt: run.finishedAt, lastDurationMs: Math.max(0, run.finishedAt - run.startedAt) } : {}),
+    lastStatus: run.status === 'failed' ? 'failed' : 'succeeded',
+    ...(run.status === 'failed' && typeof run.error === 'string' ? { lastError: run.error } : {}),
+  };
+}
+
+export function listSchedule(ctx: ConsoleScheduleListCtx, d: Record<string, unknown> = {}): Promise<ExtendedRpcResult> | ExtendedRpcResult {
+  const locale = typeof d.locale === 'string' && d.locale.trim() ? d.locale.trim() : undefined;
   const host = ctx.scheduleHost as { list?: () => unknown } | undefined;
   if (!host || typeof host.list !== 'function') {
     return { error: '调度服务未配置（scheduleHost 未挂载）' };
@@ -18,17 +43,26 @@ export function listSchedule(ctx: ConsoleScheduleListCtx): Promise<ExtendedRpcRe
         !!job && typeof job === 'object'
         && typeof (job as ScheduleJobRow).id === 'string'
         && typeof (job as ScheduleJobRow).cron === 'string')
-      .map((job) => ({
+      .map((job) => {
+        const title = localizedTitle(job, locale);
+        return {
         id: job.id,
         cron: job.cron,
         ...(typeof job.description === 'string' ? { description: job.description } : {}),
+        // #1250: plugin polling is not a user reminder; title is localized, displayName never falls back to a bare id when a title exists.
+        kind: job.kind === 'user-task' ? 'user-task' : 'plugin-internal',
+        ...(title ? { title } : {}),
+        ...(job.titleI18n && typeof job.titleI18n === 'object' ? { titleI18n: job.titleI18n } : {}),
+        displayName: title ?? (typeof job.description === 'string' && job.description ? job.description : job.id),
+        ...lastRunFields(job),
         // console cron 页渲染字段（由 schedule host 提供时透传）
         expression: (job as { expression?: string }).expression ?? job.cron,
         running: (job as { running?: boolean }).running ?? true,
         ...((job as { plugin?: string }).plugin ? { plugin: (job as { plugin?: string }).plugin } : {}),
         ...((job as { nextExecution?: number }).nextExecution
           ? { nextExecution: (job as { nextExecution?: number }).nextExecution } : {}),
-      }));
+        };
+      });
     return listPersistentJobs(ctx).then((persistent) => ({ data: { memory, persistent, capabilities: { persistent: !!ctx.resolveScheduleEngine?.() && ctx.fullScope } } })).catch((error) => ({ error: errorMessage(error) }));
   } catch (error) {
     return { error: errorMessage(error) };
@@ -50,10 +84,14 @@ async function listPersistentJobs(ctx: ConsoleRpcExtendedCtx): Promise<Record<st
       prompt: (job.action as { prompt?: string } | undefined)?.prompt ?? '',
       enabled: job.enabled !== false,
       source: job.source ?? 'manual',
+      // Persistent jobs are created by a person or on their behalf by the Agent.
+      kind: 'user-task',
       createdAt: (job as { createdAt?: number }).createdAt,
       nextExecution: (job.state as { nextRunAtMs?: number } | undefined)?.nextRunAtMs,
       ...((job.notify as { target?: unknown } | undefined)?.target
         ? { context: { target: (job.notify as { target?: unknown }).target } } : {}),
+      // #1250: the resolved delivery target; `resolved: false` = results cannot be delivered.
+      ...(ctx.describeScheduleTarget ? { target: ctx.describeScheduleTarget(job.notify) } : {}),
       lastExecutedAt: (job.state as { lastExecutedAt?: number } | undefined)?.lastExecutedAt,
       lastStatus: (job.state as { lastStatus?: string } | undefined)?.lastStatus,
     }));
@@ -62,6 +100,22 @@ async function listPersistentJobs(ctx: ConsoleRpcExtendedCtx): Promise<Record<st
   }
 }
 
+/** The account (`adapter` / `endpoint`) a schedule delivery target sends from, if it names one. */
+function deliveryAccount(target: unknown): { adapter: string; endpoint: string } | undefined {
+  if (typeof target === 'string') {
+    // `<adapter>:<endpoint>:<kind>:<id>`
+    const [adapter, endpoint] = target.split(':');
+    return adapter && endpoint ? { adapter, endpoint } : undefined;
+  }
+  if (!target || typeof target !== 'object') return undefined;
+  const scene = (target as { scene?: unknown }).scene;
+  if (!scene || typeof scene !== 'object') return undefined;
+  const { platform, endpointKey } = scene as { platform?: unknown; endpointKey?: unknown };
+  return typeof platform === 'string' && platform && typeof endpointKey === 'string' && endpointKey
+    ? { adapter: platform, endpoint: endpointKey }
+    : undefined;
+}
+
 export async function addCron(
   d: Record<string, unknown>,
   ctx: ConsoleRpcExtendedCtx,
@@ -80,6 +134,16 @@ export async function addCron(
   const label = typeof d.label === 'string' && d.label.trim() ? d.label.trim() : undefined;
   const context = (d.context ?? {}) as Record<string, unknown>;
   const target = context.target ?? context.channel;
+  // A delivery target sends to that account on every run: `endpoint.operate` there, like
+  // `/message/send`, on top of `ops.schedule.write` (absent check = trusted in-process caller).
+  if (target && ctx.canOperateEndpoint) {
+    const account = deliveryAccount(target);
+    if (!account || !ctx.canOperateEndpoint(account.adapter, account.endpoint)) {
+      return { error: account
+        ? `没有向该账号投递的权限：需要 ${account.adapter} / ${account.endpoint} 上的 endpoint.operate`
+        : '投递目标需要指明账号（scene.platform 与 scene.endpointKey）' };
+    }
+  }
   const job = {
     id: `console-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`,
     ...(label ? { label } : {}),

package/src/console-rpc-handlers.ts

@@ -1,7 +1,12 @@
 import {
   CONFIG_PATCH_LIMITS,
+  CONSOLE_SEND_FAILURE_MESSAGES,
   ENDPOINT_RPC,
+  classifyConsoleSendFailure,
+  endpointTransportLabel,
   type ConsoleConfigApplicationStatus,
+  type ConsoleSendFailure,
+  type ConsoleSendFailureStatus,
 } from '@zhin.js/console-protocol';
 import type {
   ConversationAddress,
@@ -30,6 +35,43 @@ export function wireConversation(
   };
 }
 
+const SEND_FAILURE_STATUSES: ReadonlySet<string> = new Set(['failed', 'rejected', 'unsupported', 'suppressed']);
+
+/**
+ * Structural read of an outbound failure (#1250): Core's `EndpointDeliveryError` carries `code`,
+ * `disposition` and the canonical receipt; host/http must not import Core, so only those fields are
+ * read. `endpoint not found` is the Endpoint directory's plain error. An error counts as a send
+ * failure only when its `code` is a known delivery code or it carries a `disposition` / `receipt`;
+ * anything else (a Node `ENOENT`, a database error, …) is unclassified and keeps its own message.
+ */
+export function consoleSendFailure(error: unknown): ConsoleSendFailure | undefined {
+  if (!(error instanceof Error)) return undefined;
+  const record = error as Error & { code?: unknown; disposition?: unknown; receipt?: unknown };
+  if (typeof record.code !== 'string' || !record.code) {
+    return error.message === 'endpoint not found'
+      ? { code: 'endpoint_not_found', reason: 'endpoint_not_found', status: 'failed' }
+      : undefined;
+  }
+  // Every known delivery code maps to a reason other than the catch-all `failed`.
+  const knownCode = classifyConsoleSendFailure(record.code) !== 'failed';
+  const delivery = typeof record.disposition === 'string' || (!!record.receipt && typeof record.receipt === 'object');
+  if (!knownCode && !delivery) return undefined;
+  const receipt = record.receipt && typeof record.receipt === 'object'
+    ? record.receipt as { status?: unknown; failure?: { retryable?: unknown; deliveryUnknown?: unknown } }
+    : undefined;
+  const status: ConsoleSendFailureStatus = record.disposition === 'unknown' || receipt?.failure?.deliveryUnknown === true
+    ? 'unknown'
+    : typeof receipt?.status === 'string' && SEND_FAILURE_STATUSES.has(receipt.status)
+      ? receipt.status as ConsoleSendFailureStatus
+      : record.disposition === 'rejected' ? 'rejected' : 'failed';
+  return {
+    code: record.code,
+    reason: classifyConsoleSendFailure(record.code, status),
+    status,
+    ...(receipt?.failure?.retryable === true ? { retryable: true } : {}),
+  };
+}
+
 const FORBIDDEN_PATCH_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
 
 /**
@@ -145,12 +187,12 @@ export async function dispatchHostResourceConsoleRpc(
           emit({ requestId, error: 'filename is required' });
           return true;
         }
-        if (!ctx.readEnvFile) {
+        // Masked only (issue #1250): the file as written is never answered here.
+        if (!ctx.readEnvFileView) {
           emit({ requestId, error: 'Env read is not configured' });
           return true;
         }
-        const content = await ctx.readEnvFile(filename);
-        emit({ requestId, data: { content } });
+        emit({ requestId, data: await ctx.readEnvFileView(filename) });
       } catch (error) {
         emit({
           requestId,
@@ -159,23 +201,70 @@ export async function dispatchHostResourceConsoleRpc(
       }
       return true;
     }
+    case 'env:reveal': {
+      try {
+        const filename = String(message.filename ?? '');
+        const key = message.key;
+        if (!filename) {
+          emit({ requestId, error: 'filename is required' });
+          return true;
+        }
+        if (typeof key !== 'string' || !key) {
+          emit({ requestId, error: 'key is required' });
+          return true;
+        }
+        if (!ctx.revealEnvVariable) {
+          emit({ requestId, error: 'Env reveal is not configured' });
+          return true;
+        }
+        emit({ requestId, data: await ctx.revealEnvVariable(filename, key) });
+      } catch (error) {
+        emit({
+          requestId,
+          error: `Failed to reveal env variable: ${error instanceof Error ? error.message : String(error)}`,
+        });
+      }
+      return true;
+    }
     case 'env:save': {
       try {
         const filename = String(message.filename ?? '');
-        const content = message.content;
         if (!filename) {
           emit({ requestId, error: 'filename is required' });
           return true;
         }
-        if (typeof content !== 'string') {
-          emit({ requestId, error: 'content field is required' });
+        const hasChanges = message.changes !== undefined;
+        const hasContent = message.content !== undefined;
+        if (hasChanges && hasContent) {
+          emit({ requestId, error: 'changes 与 content 只能提供一个' });
+          return true;
+        }
+        if (hasChanges) {
+          if (!ctx.updateEnvVariables) {
+            emit({ requestId, error: 'Env write is not configured' });
+            return true;
+          }
+          const { changed } = await ctx.updateEnvVariables(filename, message.changes);
+          emit({ requestId, data: { success: true, message: `环境文件已保存: ${filename}`, changed } });
           return true;
         }
-        if (!ctx.writeEnvFile) {
+        if (typeof message.content !== 'string') {
+          emit({ requestId, error: 'changes field is required' });
+          return true;
+        }
+        // The whole-file form must be asked for: an older Console sends back what `env:get` showed it.
+        if (message.mode !== 'replace') {
+          emit({
+            requestId,
+            error: '此 Host 只接受逐键保存（changes）；整文件保存需显式声明 mode: "replace"。请升级 Console 后重试',
+          });
+          return true;
+        }
+        if (!ctx.replaceEnvFile) {
           emit({ requestId, error: 'Env write is not configured' });
           return true;
         }
-        await ctx.writeEnvFile(filename, content);
+        await ctx.replaceEnvFile(filename, message.content);
         emit({ requestId, data: { success: true, message: `环境文件已保存: ${filename}` } });
       } catch (error) {
         emit({
@@ -441,7 +530,7 @@ export async function dispatchHostResourceConsoleRpc(
     case 'endpoint.list': {
       try {
         const endpoints = ctx.listEndpoints ? await ctx.listEndpoints() : [];
-        emit({ requestId, data: { endpoints } });
+        emit({ requestId, data: { endpoints: endpoints.map(withTransportLabel) } });
       } catch (error) {
         emit({
           requestId,
@@ -468,7 +557,7 @@ export async function dispatchHostResourceConsoleRpc(
           emit({ requestId, error: 'endpoint not found' });
           return true;
         }
-        emit({ requestId, data: endpoint });
+        emit({ requestId, data: withTransportLabel(endpoint) });
       } catch (error) {
         emit({
           requestId,
@@ -555,9 +644,11 @@ export async function dispatchHostResourceConsoleRpc(
         });
         emit({ requestId, data: { messageId: result.messageId } });
       } catch (error) {
+        const failure = consoleSendFailure(error);
         emit({
           requestId,
-          error: error instanceof Error ? error.message : String(error),
+          error: failure ? CONSOLE_SEND_FAILURE_MESSAGES[failure.reason] : error instanceof Error ? error.message : String(error),
+          ...(failure ? { data: failure } : {}),
         });
       }
       return true;
@@ -674,3 +765,11 @@ export function configurationSaveMessage(result: { restartRequired: boolean; rev
   return result.restartRequired ? '配置已保存，需重启进程才能生效' : '配置已保存';
 }
 
+
+/** Adds the readable `transportLabel` next to the raw `transportState` of an Endpoint row (#1250). */
+function withTransportLabel<T>(endpoint: T): T {
+  if (!endpoint || typeof endpoint !== 'object') return endpoint;
+  const state = (endpoint as { transportState?: unknown }).transportState;
+  if (typeof state !== 'string') return endpoint;
+  return { ...endpoint, transportLabel: endpointTransportLabel(state) };
+}