@zhin.js/host-http 1.2.2 → 1.4.0

package/lib/access-control.d.ts

@@ -1,4 +1,4 @@
-import { type ConsoleGrant, type ConsolePermission, type ConsolePluginPermissionInfo, type ConsolePluginPermissionLevelResolver, type ConsoleRpcPermissionRule, type ConsoleScopeTarget } from '@zhin.js/console-protocol';
+import { CONSOLE_UNKNOWN_RPC_CODE, type ConsoleDenialReason, type ConsoleGrant, type ConsolePermission, type ConsolePluginPermissionInfo, type ConsolePluginPermissionLevelResolver, type ConsoleRpcPermissionRule, type ConsoleScopeTarget } from '@zhin.js/console-protocol';
 /**
  * Console principals (ADR 0049 §1):
  * - `bootstrap`: the `http.token` before the first owner exists (`open: false`), or a Host
@@ -58,6 +58,16 @@ export interface ConsoleAccessProvider {
     audit?(entry: ConsoleAuditEntry): void;
 }
 export declare function isUserPrincipal(principal: ConsolePrincipal | undefined): principal is ConsoleUserPrincipal;
+/** User id and credential id of the gateway control-socket principal (ADR 0054 §6). */
+export declare const LOCAL_SOCKET_USER_ID = "local";
+export declare const LOCAL_SOCKET_CREDENTIAL_ID = "local-socket";
+/**
+ * The principal of a request from the project owner's CLI over `.zhin/gateway.sock` (no token).
+ * Sessions and API tokens never carry this credential id (theirs are token hashes / token ids).
+ */
+export declare function isLocalSocketPrincipal(principal: ConsolePrincipal | undefined): boolean;
+/** A user principal with a global `owner` binding (the local socket principal is one). */
+export declare function isGlobalOwnerPrincipal(principal: ConsolePrincipal | undefined): boolean;
 /**
  * Whether the request carried an explicit credential: a user session / API token, or the
  * still-valid bootstrap token (`{ kind: 'bootstrap', open: false }`). An open Host is not explicit.
@@ -93,12 +103,36 @@ export type ConsoleRpcDecision = Readonly<{
     delegated?: true;
 }> | Readonly<{
     allowed: false;
-    code: 'setup_required' | 'unmapped' | 'forbidden';
+    /**
+     * `unknown_rpc`: the Host has no handler and no permission entry for the type (zhinjs/zhin#1250).
+     * Nothing runs; it is not a security refusal and callers do not audit it (see
+     * {@link isAuditedRpcDenial}). Every other code is a refusal that is audited.
+     */
+    code: 'setup_required' | 'unmapped' | 'forbidden' | typeof CONSOLE_UNKNOWN_RPC_CODE;
     error: string;
     permission: ConsolePermission | null;
+    /** Audit `detail.reason`; absent for `unknown_rpc`. */
+    reason?: ConsoleDenialReason;
 }>;
+export interface AuthorizeConsoleRpcOptions {
+    /**
+     * Whether this Host has a handler for an RPC type that is missing from the permission map. True
+     * (or no predicate) keeps the audited `unmapped` refusal — a handler without a permission entry
+     * is a development error; false answers `unknown_rpc`. Mapped types never consult it.
+     */
+    readonly registered?: (type: string) => boolean;
+}
+/** Whether a refused RPC is written to the audit log (`unknown_rpc` is not). */
+export declare function isAuditedRpcDenial(decision: ConsoleRpcDecision): boolean;
+/** Error text of an unknown RPC: the (truncated) type and nothing else. */
+export declare function unknownConsoleRpcError(type: unknown): string;
 /** RPC authorization for one principal and message (deny by default). */
-export declare function authorizeConsoleRpc(principal: ConsolePrincipal, message: Readonly<Record<string, unknown>>): ConsoleRpcDecision;
+export declare function authorizeConsoleRpc(principal: ConsolePrincipal, message: Readonly<Record<string, unknown>>, options?: AuthorizeConsoleRpcOptions): ConsoleRpcDecision;
+/**
+ * Why grants refuse `permission` at a target: `scope_denied` when some binding holds it at another
+ * adapter / endpoint, else `insufficient_permission`.
+ */
+export declare function grantsDenialReason(grants: readonly ConsoleGrant[], permission: string): ConsoleDenialReason;
 /**
  * For plugin RPC: whether the principal holds the rule's write permission (`feature.configure`,
  * or `endpoint.manage` for adapter account methods) at its target. The plugin RPC dispatcher
@@ -114,6 +148,8 @@ export type ConsoleHttpDecision = Readonly<{
     code: 'unauthorized' | 'forbidden' | 'setup_required';
     error: string;
     permission: string | null;
+    /** Audit `detail.reason`. */
+    reason: ConsoleDenialReason;
 }>;
 /**
  * HTTP authorization of a route under the API base. `principal` is undefined when no valid
@@ -121,6 +157,8 @@ export type ConsoleHttpDecision = Readonly<{
  */
 export declare function authorizeConsoleHttp(principal: ConsolePrincipal | undefined, method: string, relativePath: string): ConsoleHttpDecision;
 /** WebSocket upgrade authorization for non-bootstrap principals. */
+/** Audit `detail.reason` of a WebSocket {@link authorizeConsoleWebSocket} refused. */
+export declare function webSocketDenialReason(principal: ConsolePrincipal, pathname: string): ConsoleDenialReason;
 export declare function authorizeConsoleWebSocket(principal: ConsolePrincipal, pathname: string): boolean;
 /**
  * JSON length of the detail of one audit entry. The gateway stores at most 4096 characters of

package/lib/access-control.js

@@ -1,8 +1,24 @@
-import { CONSOLE_PERMISSION_LIST, CONSOLE_WRITE_PERMISSIONS, expandPluginPermissions, grantsAllow, isPluginConsoleRpcType, resolveConsoleHttpPermission, resolveConsoleRpcPermission, resolveConsoleWsPermission, } from '@zhin.js/console-protocol';
+import { CONSOLE_DENIAL_REASONS, CONSOLE_PERMISSION_LIST, CONSOLE_UNKNOWN_RPC_CODE, CONSOLE_WRITE_PERMISSIONS, expandPluginPermissions, grantsAllow, grantsAllowAlsoRequired, isPluginConsoleRpcType, resolveConsoleHttpPermission, resolveConsoleRpcPermission, resolveConsoleWsPermission, } from '@zhin.js/console-protocol';
 import { hasForwardingHeaders } from './trust-proxy.js';
 export function isUserPrincipal(principal) {
     return principal?.kind === 'user' || principal?.kind === 'api-token';
 }
+/** User id and credential id of the gateway control-socket principal (ADR 0054 §6). */
+export const LOCAL_SOCKET_USER_ID = 'local';
+export const LOCAL_SOCKET_CREDENTIAL_ID = 'local-socket';
+/**
+ * The principal of a request from the project owner's CLI over `.zhin/gateway.sock` (no token).
+ * Sessions and API tokens never carry this credential id (theirs are token hashes / token ids).
+ */
+export function isLocalSocketPrincipal(principal) {
+    return principal?.kind === 'user' && principal.userId === LOCAL_SOCKET_USER_ID
+        && principal.credentialId === LOCAL_SOCKET_CREDENTIAL_ID;
+}
+/** A user principal with a global `owner` binding (the local socket principal is one). */
+export function isGlobalOwnerPrincipal(principal) {
+    return isUserPrincipal(principal)
+        && principal.grants.some((grant) => grant.role === 'owner' && grant.scope.kind === 'global');
+}
 /**
  * Whether the request carried an explicit credential: a user session / API token, or the
  * still-valid bootstrap token (`{ kind: 'bootstrap', open: false }`). An open Host is not explicit.
@@ -55,27 +71,67 @@ export function globalPermissions(principal, pluginPermissions = []) {
     }
     return expandPluginPermissions([...held], pluginPermissions);
 }
+/** Whether a refused RPC is written to the audit log (`unknown_rpc` is not). */
+export function isAuditedRpcDenial(decision) {
+    return !decision.allowed && decision.code !== CONSOLE_UNKNOWN_RPC_CODE;
+}
+/** Error text of an unknown RPC: the (truncated) type and nothing else. */
+export function unknownConsoleRpcError(type) {
+    return `RPC "${String(type ?? '').slice(0, 64)}" 不存在`;
+}
 /** RPC authorization for one principal and message (deny by default). */
-export function authorizeConsoleRpc(principal, message) {
+export function authorizeConsoleRpc(principal, message, options = {}) {
     const rule = resolveConsoleRpcPermission(message.type, message);
     const permission = rule ? (rule.kind === 'exact' ? rule.permission : rule.read) : null;
     if (principal.kind === 'bootstrap') {
         if (principal.open) {
             return Object.freeze({ allowed: true, rule, permission, write: rule ? isWriteRule(rule) : true });
         }
-        return Object.freeze({ allowed: false, code: 'setup_required', error: '请先完成初始化：创建第一个所有者', permission });
+        return Object.freeze({
+            allowed: false, code: 'setup_required', error: '请先完成初始化：创建第一个所有者', permission,
+            reason: CONSOLE_DENIAL_REASONS.SETUP_REQUIRED,
+        });
     }
     if (!rule) {
-        return Object.freeze({ allowed: false, code: 'unmapped', error: `RPC "${String(message.type ?? '')}" 未登记权限`, permission: null });
+        const type = typeof message.type === 'string' ? message.type : '';
+        if (options.registered && !options.registered(type)) {
+            return Object.freeze({ allowed: false, code: CONSOLE_UNKNOWN_RPC_CODE, error: unknownConsoleRpcError(message.type), permission: null });
+        }
+        return Object.freeze({
+            allowed: false, code: 'unmapped', error: `RPC "${String(message.type ?? '')}" 未登记权限`, permission: null,
+            reason: CONSOLE_DENIAL_REASONS.UNMAPPED_PERMISSION,
+        });
     }
     if (isPluginConsoleRpcType(message.type)) {
         return Object.freeze({ allowed: true, rule, permission, write: isWriteRule(rule), delegated: true });
     }
     if (!grantsAllow(principal.grants, permission, rule.target)) {
-        return Object.freeze({ allowed: false, code: 'forbidden', error: `缺少权限 ${permission}`, permission });
+        return Object.freeze({
+            allowed: false, code: 'forbidden', error: `缺少权限 ${permission}`, permission,
+            reason: grantsDenialReason(principal.grants, permission),
+        });
+    }
+    // `alsoRequires` is held globally (same semantics as grantsAllowAlsoRequired): find the first missing one for the denial reason.
+    const missing = rule.kind === 'exact' && !grantsAllowAlsoRequired(principal.grants, rule)
+        ? rule.alsoRequires?.find(extra => !grantsAllowAlsoRequired(principal.grants, { ...rule, alsoRequires: [extra] }))
+        : undefined;
+    if (missing) {
+        return Object.freeze({
+            allowed: false, code: 'forbidden', error: `缺少权限 ${missing}`, permission,
+            reason: grantsDenialReason(principal.grants, missing),
+        });
     }
     return Object.freeze({ allowed: true, rule, permission, write: isWriteRule(rule) });
 }
+/**
+ * Why grants refuse `permission` at a target: `scope_denied` when some binding holds it at another
+ * adapter / endpoint, else `insufficient_permission`.
+ */
+export function grantsDenialReason(grants, permission) {
+    return grants.some(grant => grant.scope.kind !== 'global' && grant.permissions.includes(permission))
+        ? CONSOLE_DENIAL_REASONS.SCOPE_DENIED
+        : CONSOLE_DENIAL_REASONS.INSUFFICIENT_PERMISSION;
+}
 function isWriteRule(rule) {
     return rule.kind === 'exact' ? CONSOLE_WRITE_PERMISSIONS.has(rule.permission) : false;
 }
@@ -90,7 +146,7 @@ export function pluginRpcWriteAllowed(principal, rule) {
     if (!rule)
         return false;
     const permission = rule.kind === 'exact' ? rule.permission : rule.write;
-    return grantsAllow(principal.grants, permission, rule.target);
+    return grantsAllow(principal.grants, permission, rule.target) && grantsAllowAlsoRequired(principal.grants, rule);
 }
 /**
  * HTTP authorization of a route under the API base. `principal` is undefined when no valid
@@ -102,15 +158,15 @@ export function authorizeConsoleHttp(principal, method, relativePath) {
     if (rule?.permission === 'public')
         return Object.freeze({ allowed: true, permission });
     if (!principal) {
-        return Object.freeze({ allowed: false, status: 401, code: 'unauthorized', error: 'Invalid or missing token', permission });
+        return Object.freeze({ allowed: false, status: 401, code: 'unauthorized', error: 'Invalid or missing token', permission, reason: CONSOLE_DENIAL_REASONS.NOT_AUTHENTICATED });
     }
     if (principal.kind === 'bootstrap') {
         if (principal.open || rule?.permission === 'bootstrap')
             return Object.freeze({ allowed: true, permission });
-        return Object.freeze({ allowed: false, status: 403, code: 'setup_required', error: '初始化令牌只能用于创建第一个所有者', permission });
+        return Object.freeze({ allowed: false, status: 403, code: 'setup_required', error: '初始化令牌只能用于创建第一个所有者', permission, reason: CONSOLE_DENIAL_REASONS.SETUP_REQUIRED });
     }
     if (!rule) {
-        return Object.freeze({ allowed: false, status: 403, code: 'forbidden', error: 'Route is not registered with a Console permission', permission: null });
+        return Object.freeze({ allowed: false, status: 403, code: 'forbidden', error: 'Route is not registered with a Console permission', permission: null, reason: CONSOLE_DENIAL_REASONS.UNMAPPED_ROUTE });
     }
     if (rule.permission === 'rpc' || rule.permission === 'authenticated' || rule.permission === 'bootstrap') {
         return Object.freeze({ allowed: true, permission });
@@ -118,9 +174,20 @@ export function authorizeConsoleHttp(principal, method, relativePath) {
     // Scoped permissions over plain HTTP have no knowable target: a global binding is required.
     if (grantsAllow(principal.grants, rule.permission))
         return Object.freeze({ allowed: true, permission });
-    return Object.freeze({ allowed: false, status: 403, code: 'forbidden', error: `缺少权限 ${rule.permission}`, permission });
+    return Object.freeze({
+        allowed: false, status: 403, code: 'forbidden', error: `缺少权限 ${rule.permission}`, permission,
+        reason: CONSOLE_DENIAL_REASONS.INSUFFICIENT_PERMISSION,
+    });
 }
 /** WebSocket upgrade authorization for non-bootstrap principals. */
+/** Audit `detail.reason` of a WebSocket {@link authorizeConsoleWebSocket} refused. */
+export function webSocketDenialReason(principal, pathname) {
+    if (principal.kind === 'bootstrap')
+        return CONSOLE_DENIAL_REASONS.SETUP_REQUIRED;
+    return resolveConsoleWsPermission(pathname) === null
+        ? CONSOLE_DENIAL_REASONS.UNMAPPED_ROUTE
+        : CONSOLE_DENIAL_REASONS.INSUFFICIENT_PERMISSION;
+}
 export function authorizeConsoleWebSocket(principal, pathname) {
     // Only the Console's own sockets are host-authenticated; plugin sockets use `auth: 'protocol'`.
     const permission = resolveConsoleWsPermission(pathname);
@@ -202,8 +269,43 @@ export function rpcAuditDetail(message, reply, options) {
         type: String(message.type ?? '').slice(0, 256),
         keys: Object.freeze([...new Set([...keys, ...data])].slice(0, 64).map(key => key.slice(0, 128))),
         ...databaseStatementDetail(message, reply, options),
+        ...envDetail(message),
     }));
 }
+const auditName = (value, max) => typeof value === 'string' && value ? value.slice(0, max) : undefined;
+/**
+ * Which dotenv file and variable names an `env:reveal` / `env:save` touched (issue #1250). Never a
+ * value: `changes[].value` and `content` are not read.
+ */
+function envDetail(message) {
+    if (message.type !== 'env:reveal' && message.type !== 'env:save')
+        return {};
+    const data = message.data && typeof message.data === 'object' && !Array.isArray(message.data) ? message.data : {};
+    const pick = (key) => message[key] ?? data[key];
+    const file = auditName(pick('filename'), 64);
+    if (message.type === 'env:reveal') {
+        const key = auditName(pick('key'), 128);
+        return { ...(file ? { file } : {}), ...(key ? { key } : {}) };
+    }
+    const changes = Array.isArray(pick('changes')) ? pick('changes') : undefined;
+    if (!changes)
+        return { ...(file ? { file } : {}), ...(pick('content') !== undefined ? { mode: 'replace' } : {}) };
+    const set = [];
+    const deleted = [];
+    for (const change of changes.slice(0, 64)) {
+        if (!change || typeof change !== 'object')
+            continue;
+        const key = auditName(change.key, 128);
+        if (key)
+            (change.delete === true ? deleted : set).push(key);
+    }
+    return {
+        ...(file ? { file } : {}),
+        set: Object.freeze(set),
+        deleted: Object.freeze(deleted),
+        ...(changes.length > 64 ? { truncated: true } : {}),
+    };
+}
 export function rpcAuditTarget(rule) {
     if (!rule)
         return undefined;

package/lib/console-rest-pages-helpers.js

@@ -15,7 +15,13 @@ const INTROSPECTION_PAGE_SIZES = {
     endpoints: 30,
     bindings: 30,
     mcp: 30,
+    'recent-turns': 20,
 };
+/** Owning plugin of a capability row (`ConsoleIntrospectionOwner`, #1250): searchable by `q`. */
+const OWNER_FIELDS = [
+    (item) => stringProp(item, 'pluginInstance'),
+    (item) => stringProp(item, 'pluginPackage'),
+];
 // ---------------------------------------------------------------------------
 // Runtime snapshot introspection
 // ---------------------------------------------------------------------------
@@ -28,6 +34,7 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
                 (c) => stringProp(c, 'pattern'),
                 (c) => stringProp(c, 'desc'),
                 (c) => stringProp(c, 'plugin'),
+                ...OWNER_FIELDS,
             ],
         },
         {
@@ -39,6 +46,7 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
                 (m) => stringProp(m, 'phase'),
                 (m) => stringProp(m, 'target'),
                 (m) => stringProp(m, 'source'),
+                ...OWNER_FIELDS,
             ],
         },
         {
@@ -48,6 +56,7 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
                 (c) => stringProp(c, 'name'),
                 (c) => stringProp(c, 'owner'),
                 (c) => stringProp(c, 'source'),
+                ...OWNER_FIELDS,
             ],
         },
         {
@@ -64,11 +73,22 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
         },
         {
             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'),
             ],
         },
         {
@@ -78,6 +98,7 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
                 (t) => stringProp(t, 'name'),
                 (t) => stringProp(t, 'source'),
                 (t) => stringProp(t, 'description'),
+                ...OWNER_FIELDS,
             ],
         },
         {
@@ -91,6 +112,7 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
                 (section) => stringProp(section, 'layer'),
                 (section) => stringProp(section, 'retention'),
                 (section) => stringProp(section, 'source'),
+                ...OWNER_FIELDS,
             ],
         },
         {
@@ -113,7 +135,7 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
             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/lib/console-rest-pages.d.ts

@@ -35,7 +35,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?(): {

package/lib/console-rest-pages.js

@@ -11,6 +11,7 @@ import { join } from 'node:path';
 import { readJsonBody } from './json-body.js';
 import { jsonResponse } from '@zhin.js/host-http-contract';
 import { MarketplaceDetailCache, MarketplaceRegistry, isValidNpmPackageName, } from './marketplace-registry.js';
+import { informativeKeywords, isLocale, normalizePluginCategory, packageAuthorName, pickLocalizedText, readPluginMarketplaceMetadata, } from '@zhin.js/plugin-runtime';
 import { clampPositiveInt, decodePathParam, logInternalError, normalizeBase, parsePositiveInt, registerAgentSessionRoutes, registerIntrospectionRoutes, requireWriteScope, trimTrailingSlashes, } from './console-rest-pages-helpers.js';
 const PLUGINS_CACHE_TTL = 5 * 60 * 1000;
 const PACKAGE_DETAIL_CACHE_TTL = 5 * 60 * 1000;
@@ -202,6 +203,10 @@ function registerLogsRoutes(route, base, ctx) {
         });
     }, { summary: 'Cleanup old system logs', tags: ['console', 'logs'] });
 }
+/** Locale-keyed texts from an untrusted registry entry (reuses the published-manifest reader). */
+function localizedTextOf(value) {
+    return readPluginMarketplaceMetadata({ metadata: { displayNameI18n: value } }).displayNameI18n;
+}
 // ---------------------------------------------------------------------------
 // marketplace（legacy marketplace-rest-api.ts；plugins.json + npmmirror）
 // ---------------------------------------------------------------------------
@@ -225,20 +230,25 @@ function registerMarketplaceRoutes(route, base, ctx, fetchFn, pluginRegistryUrl,
             const versions = meta.versions;
             const latestInfo = latest && versions ? versions[latest] : undefined;
             const time = meta.time;
+            // 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 || meta.description || '',
                 readme: meta.readme || '',
                 license: meta.license || latestInfo?.license || '',
                 homepage: meta.homepage || latestInfo?.homepage || '',
                 repository: meta.repository?.url ||
                     latestInfo?.repository?.url ||
                     '',
-                author: typeof meta.author === 'string'
-                    ? meta.author
-                    : meta.author?.name || '',
-                keywords: latestInfo?.keywords || [],
+                author: packageAuthorName(latestInfo ?? {}) ?? packageAuthorName(meta) ?? '',
+                keywords: informativeKeywords(latestInfo?.keywords),
                 engines: latestInfo?.engines || {},
                 peerDependencies: latestInfo?.peerDependencies || {},
                 versions: Object.keys(versions || {}),
@@ -250,30 +260,46 @@ function registerMarketplaceRoutes(route, base, ctx, fetchFn, pluginRegistryUrl,
         const q = url.searchParams.get('q') ?? url.searchParams.get('keyword') ?? '';
         const pageNum = Math.max(1, parseInt(url.searchParams.get('page') ?? '1', 10) || 1);
         const pageSize = Math.min(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());
-            let plugins = allPlugins.map((p) => ({
-                name: p.name,
-                displayName: p.displayName || '',
-                version: p.version || '',
-                description: p.description || '',
-                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 || [],
-                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 || '',
-            }));
+            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,
+                    // `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: 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: 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/lib/console-rpc-extended/contracts.d.ts

@@ -21,6 +21,11 @@ export interface ConsoleRpcExtendedCtx {
     };
     /** 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). */
@@ -182,6 +187,16 @@ 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 {
     where(query: Record<string, unknown>): InboxSelection;
@@ -264,4 +279,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;
+}
 export {};

package/lib/console-rpc-extended/dispatcher.js

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

package/lib/console-rpc-extended/endpoint-rpc.js

@@ -8,7 +8,7 @@ export async function listFriends(d, ctx) {
             const friends = [...await management.listFriends()];
             return { data: { friends, count: friends.length } };
         }
-        return { error: `当前适配器（${endpoint.adapter}）不支持好友列表` };
+        return unsupportedList('friends', 'listFriends', endpoint.adapter, '好友列表');
     });
 }
 export async function listGroups(d, ctx) {
@@ -20,7 +20,7 @@ export async function listGroups(d, ctx) {
             const groups = [...await management.listGroups()];
             return { data: { groups, count: groups.length } };
         }
-        return { error: `当前适配器（${endpoint.adapter}）不支持群列表` };
+        return unsupportedList('groups', 'listGroups', endpoint.adapter, '群列表');
     });
 }
 export async function listChannels(d, ctx) {
@@ -32,7 +32,7 @@ export async function listChannels(d, ctx) {
             const channels = [...await management.listChannels()];
             return { data: { channels, count: channels.length } };
         }
-        return { error: `当前适配器（${endpoint.adapter}）不支持频道列表` };
+        return unsupportedList('channels', 'listChannels', endpoint.adapter, '频道列表');
     });
 }
 export async function listGroupMembers(d, ctx) {
@@ -45,12 +45,29 @@ export async function listGroupMembers(d, ctx) {
     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, capability, adapter, label) {
+    return {
+        data: {
+            [key]: [],
+            count: 0,
+            status: 'unsupported',
+            capability,
+            message: `当前适配器（${adapter}）不支持${label}`,
+        },
+    };
+}
 export async function groupWriteOp(d, ctx, spec) {
     const adapter = strField(d, 'adapter');
     const endpointKey = strField(d, 'endpointKey');

package/lib/console-rpc-extended/index.d.ts

@@ -1,3 +1,3 @@
-export type { ConsoleRpcExtendedCtx, ConsoleScheduleEngine, ConsoleWorkroomKnowledgeControlPort, ConsoleWorkroomProfileControlPort, ExtendedRpcResult, ConsoleLoginAssistPort, ConsoleEndpointLoginAccess, } from './contracts.js';
+export type { ConsoleRpcExtendedCtx, ConsoleScheduleEngine, ConsoleScheduleTarget, ConsoleWorkroomKnowledgeControlPort, ConsoleWorkroomProfileControlPort, ExtendedRpcResult, ConsoleLoginAssistPort, ConsoleEndpointLoginAccess, } from './contracts.js';
 export { loginAuditDetail, LOGIN_SUBMIT_WAIT_MS } from './login-rpc.js';
 export { dispatchExtendedConsoleRpc } from './dispatcher.js';

package/lib/console-rpc-extended/schedule-rpc.d.ts

@@ -1,5 +1,5 @@
 import type { ConsoleRpcExtendedCtx, ExtendedRpcResult } from './contracts.js';
-export declare function listSchedule(ctx: ConsoleScheduleListCtx): Promise<ExtendedRpcResult> | ExtendedRpcResult;
+export declare function listSchedule(ctx: ConsoleScheduleListCtx, d?: Record<string, unknown>): Promise<ExtendedRpcResult> | ExtendedRpcResult;
 type ConsoleScheduleListCtx = ConsoleRpcExtendedCtx;
 export declare function addCron(d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): Promise<ExtendedRpcResult>;
 export declare function mutateCron(type: 'cron:remove' | 'cron:pause' | 'cron:resume', d: Record<string, unknown>, ctx: ConsoleRpcExtendedCtx): Promise<ExtendedRpcResult>;