@zhin.js/host-http 1.2.1 → 1.3.0

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

@@ -2,7 +2,33 @@ import { parseCron } from '@zhin.js/schedule';
 import { errorMessage } from './rpc-values.js';
 const CRON_NOT_WIRED = '持久化调度未接线：当前 Plugin Runtime ScheduleHost 仅支持插件注册的内存任务（list），' +
     '不支持 add/remove/pause/resume（需要 @zhin.js/agent 持久化调度引擎）';
-export function listSchedule(ctx) {
+/** `titleI18n[locale]` → `titleI18n[language]` → `title`. */
+function localizedTitle(job, locale) {
+    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) {
+    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, d = {}) {
+    const locale = typeof d.locale === 'string' && d.locale.trim() ? d.locale.trim() : undefined;
     const host = ctx.scheduleHost;
     if (!host || typeof host.list !== 'function') {
         return { error: '调度服务未配置（scheduleHost 未挂载）' };
@@ -13,17 +39,26 @@ export function listSchedule(ctx) {
             .filter((job) => !!job && typeof job === 'object'
             && typeof job.id === 'string'
             && typeof job.cron === 'string')
-            .map((job) => ({
-            id: job.id,
-            cron: job.cron,
-            ...(typeof job.description === 'string' ? { description: job.description } : {}),
-            // console cron 页渲染字段（由 schedule host 提供时透传）
-            expression: job.expression ?? job.cron,
-            running: job.running ?? true,
-            ...(job.plugin ? { plugin: job.plugin } : {}),
-            ...(job.nextExecution
-                ? { nextExecution: job.nextExecution } : {}),
-        }));
+            .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.expression ?? job.cron,
+                running: job.running ?? true,
+                ...(job.plugin ? { plugin: job.plugin } : {}),
+                ...(job.nextExecution
+                    ? { nextExecution: job.nextExecution } : {}),
+            };
+        });
         return listPersistentJobs(ctx).then((persistent) => ({ data: { memory, persistent, capabilities: { persistent: !!ctx.resolveScheduleEngine?.() && ctx.fullScope } } })).catch((error) => ({ error: errorMessage(error) }));
     }
     catch (error) {
@@ -44,10 +79,14 @@ async function listPersistentJobs(ctx) {
             prompt: job.action?.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.createdAt,
             nextExecution: job.state?.nextRunAtMs,
             ...(job.notify?.target
                 ? { context: { target: job.notify.target } } : {}),
+            // #1250: the resolved delivery target; `resolved: false` = results cannot be delivered.
+            ...(ctx.describeScheduleTarget ? { target: ctx.describeScheduleTarget(job.notify) } : {}),
             lastExecutedAt: job.state?.lastExecutedAt,
             lastStatus: job.state?.lastStatus,
         }));
@@ -56,6 +95,23 @@ async function listPersistentJobs(ctx) {
         throw new Error(`读取持久化任务失败: ${errorMessage(error)}`);
     }
 }
+/** The account (`adapter` / `endpoint`) a schedule delivery target sends from, if it names one. */
+function deliveryAccount(target) {
+    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.scene;
+    if (!scene || typeof scene !== 'object')
+        return undefined;
+    const { platform, endpointKey } = scene;
+    return typeof platform === 'string' && platform && typeof endpointKey === 'string' && endpointKey
+        ? { adapter: platform, endpoint: endpointKey }
+        : undefined;
+}
 export async function addCron(d, ctx) {
     const engine = ctx.resolveScheduleEngine?.();
     if (!engine)
@@ -75,6 +131,16 @@ export async function addCron(d, ctx) {
     const label = typeof d.label === 'string' && d.label.trim() ? d.label.trim() : undefined;
     const context = (d.context ?? {});
     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/lib/console-rpc-handlers.d.ts

@@ -1,13 +1,23 @@
-import { type ConsoleConfigApplicationStatus } from '@zhin.js/console-protocol';
+import { type ConsoleConfigApplicationStatus, type ConsoleSendFailure } from '@zhin.js/console-protocol';
 import type { ConversationAddress, RuntimeConsoleRpcContext, RuntimeConsoleRpcMessage, RuntimeConsoleRpcReply } from './console-rpc.js';
 /** Canonical Console wire fields → runtime conversation address. */
 export declare function wireConversation(channelType: string, channelId: string, parent: unknown): ConversationAddress;
+/**
+ * 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 declare function consoleSendFailure(error: unknown): ConsoleSendFailure | undefined;
 /**
  * Structural check for `config:patch-project` operations at the RPC boundary, so no project
  * port implementation receives a malformed request. The store repeats the full validation.
  */
 export declare function invalidProjectPatchOperations(patches: readonly unknown[]): string | undefined;
 export declare function dispatchHostResourceConsoleRpc(type: string, message: RuntimeConsoleRpcMessage, ctx: RuntimeConsoleRpcContext, requestId: number | string | undefined, payloads: RuntimeConsoleRpcReply[]): Promise<boolean>;
+/** Longest statement text the Console SQL editor sends. */
+export declare const MAX_CONSOLE_SQL_LENGTH = 100000;
 export declare function stringField(message: RuntimeConsoleRpcMessage, key: string): string;
 export declare function recordField(value: unknown): Record<string, unknown> | undefined;
 export declare function positiveInteger(value: unknown, fallback: number): number;

package/lib/console-rpc-handlers.js

@@ -1,4 +1,4 @@
-import { CONFIG_PATCH_LIMITS, ENDPOINT_RPC, } from '@zhin.js/console-protocol';
+import { CONFIG_PATCH_LIMITS, CONSOLE_SEND_FAILURE_MESSAGES, ENDPOINT_RPC, classifyConsoleSendFailure, } from '@zhin.js/console-protocol';
 /** Canonical Console wire fields → runtime conversation address. */
 export function wireConversation(channelType, channelId, parent) {
     const kind = channelType === 'group' || channelType === 'channel' ? channelType : 'private';
@@ -13,6 +13,43 @@ export function wireConversation(channelType, channelId, parent) {
         ...(parentKind && parentId ? { parent: { kind: parentKind, id: parentId } } : {}),
     };
 }
+const SEND_FAILURE_STATUSES = 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) {
+    if (!(error instanceof Error))
+        return undefined;
+    const record = error;
+    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
+        : undefined;
+    const status = record.disposition === 'unknown' || receipt?.failure?.deliveryUnknown === true
+        ? 'unknown'
+        : typeof receipt?.status === 'string' && SEND_FAILURE_STATUSES.has(receipt.status)
+            ? receipt.status
+            : 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']);
 /**
  * Structural check for `config:patch-project` operations at the RPC boundary, so no project
@@ -129,12 +166,12 @@ export async function dispatchHostResourceConsoleRpc(type, message, ctx, request
                     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({
@@ -144,23 +181,71 @@ export async function dispatchHostResourceConsoleRpc(type, message, ctx, request
             }
             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 (typeof message.content !== 'string') {
+                    emit({ requestId, error: 'changes field is required' });
                     return true;
                 }
-                if (!ctx.writeEnvFile) {
+                // 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) {
@@ -250,15 +335,100 @@ export async function dispatchHostResourceConsoleRpc(type, message, ctx, request
             const page = positiveInteger(message.page, 1);
             const pageSize = Math.min(positiveInteger(message.pageSize, 50), 500);
             const where = recordField(message.where);
+            const order = recordField(message.orderBy);
+            if (message.orderBy !== undefined && message.orderBy !== null
+                && (!order || typeof order.column !== 'string' || (order.direction !== 'asc' && order.direction !== 'desc'))) {
+                errorReply(payloads, requestId, 'orderBy must be { column, direction: "asc" | "desc" }');
+                return true;
+            }
             if (!ctx.database) {
                 emit({ requestId, data: { rows: [], total: 0, page, pageSize } });
                 return true;
             }
             try {
-                emit({ requestId, data: await ctx.database.select(table, page, pageSize, where) });
+                const orderBy = order ? { column: order.column, direction: order.direction } : undefined;
+                emit({ requestId, data: await ctx.database.select(table, page, pageSize, where, orderBy) });
             }
             catch (error) {
-                emit({ requestId, error: `Failed to select: ${errorMessage(error)}` });
+                emit({ requestId, error: `Failed to select: ${errorMessage(error)}`, ...refusalData(error) });
+            }
+            return true;
+        }
+        case 'db:query': {
+            const sql = sqlField(message);
+            if (!sql) {
+                errorReply(payloads, requestId, `sql is required (at most ${MAX_CONSOLE_SQL_LENGTH} characters)`);
+                return true;
+            }
+            if (!ctx.database?.query) {
+                unsupportedDatabaseFeature(payloads, requestId, 'SQL query');
+                return true;
+            }
+            try {
+                const maxRows = typeof message.maxRows === 'number' ? message.maxRows : undefined;
+                emit({ requestId, data: await ctx.database.query(sql, maxRows ? { maxRows } : undefined) });
+            }
+            catch (error) {
+                emit({ requestId, error: errorMessage(error), ...refusalData(error) });
+            }
+            return true;
+        }
+        case 'db:execute': {
+            const sql = sqlField(message);
+            if (!sql) {
+                errorReply(payloads, requestId, `sql is required (at most ${MAX_CONSOLE_SQL_LENGTH} characters)`);
+                return true;
+            }
+            if (!ctx.database?.execute) {
+                unsupportedDatabaseFeature(payloads, requestId, 'SQL execution');
+                return true;
+            }
+            try {
+                emit({ requestId, data: await ctx.database.execute(sql, { dryRun: message.dryRun === true }) });
+            }
+            catch (error) {
+                emit({ requestId, error: errorMessage(error), ...refusalData(error) });
+            }
+            return true;
+        }
+        case 'db:schema:describe': {
+            const table = stringField(message, 'table');
+            if (!table) {
+                errorReply(payloads, requestId, 'table is required');
+                return true;
+            }
+            if (!ctx.database?.describe) {
+                unsupportedDatabaseFeature(payloads, requestId, 'Schema inspection');
+                return true;
+            }
+            try {
+                emit({ requestId, data: await ctx.database.describe(table) });
+            }
+            catch (error) {
+                emit({ requestId, error: errorMessage(error), ...refusalData(error) });
+            }
+            return true;
+        }
+        case 'db:schema:preview':
+        case 'db:schema:apply': {
+            const change = recordField(message.change);
+            if (!change) {
+                errorReply(payloads, requestId, 'change is required');
+                return true;
+            }
+            const database = ctx.database;
+            if (!database?.previewSchema || !database.applySchema) {
+                unsupportedDatabaseFeature(payloads, requestId, 'Schema editing');
+                return true;
+            }
+            try {
+                const plan = type === 'db:schema:apply'
+                    ? await database.applySchema(change, typeof message.confirm === 'string' ? message.confirm : undefined)
+                    : await database.previewSchema(change);
+                emit({ requestId, data: plan });
+            }
+            catch (error) {
+                emit({ requestId, error: errorMessage(error), ...refusalData(error) });
             }
             return true;
         }
@@ -543,9 +713,11 @@ export async function dispatchHostResourceConsoleRpc(type, message, ctx, request
                 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;
@@ -577,6 +749,43 @@ export async function dispatchHostResourceConsoleRpc(type, message, ctx, request
             return false;
     }
 }
+/** Longest statement text the Console SQL editor sends. */
+export const MAX_CONSOLE_SQL_LENGTH = 100_000;
+function sqlField(message) {
+    const value = message.sql;
+    return typeof value === 'string' && value.trim() && value.length <= MAX_CONSOLE_SQL_LENGTH ? value : '';
+}
+const REFUSAL_NAMES = new Set(['ConsoleSqlRefusal', 'ConsoleSchemaRefusal', 'ConsoleSelectRefusal', 'SqliteQueryTimeoutError']);
+/**
+ * `data.code` of a refusal by the database port (`read_only`, `protected_table`, …), and the DDL a
+ * failed `db:schema:apply` attempted (`data.statements`, for the audit log).
+ */
+/** SQLSTATE of a driver error (PostgreSQL `code`, mysql2 `sqlState`), e.g. `42501` insufficient privilege. */
+function sqlStateOf(error) {
+    const record = error;
+    for (const candidate of [record.sqlState, record.code]) {
+        if (typeof candidate === 'string' && /^[0-9A-Z]{5}$/u.test(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function refusalData(error) {
+    if (!(error instanceof Error))
+        return {};
+    const attempted = error.statements;
+    const statements = Array.isArray(attempted) && attempted.every(entry => typeof entry === 'string') ? { statements: attempted } : {};
+    if (error.name === 'GatewayOwnedTableError')
+        return { data: { code: 'protected_table', ...statements } };
+    const code = error.code;
+    const refused = REFUSAL_NAMES.has(error.name) && typeof code === 'string';
+    // The server's SQLSTATE lets the Console explain e.g. 42501 from the restricted account (ADR 0059 §4).
+    const sqlState = refused ? undefined : sqlStateOf(error);
+    const data = { ...(refused ? { code } : {}), ...(sqlState ? { sqlState } : {}), ...statements };
+    return Object.keys(data).length ? { data } : {};
+}
+function unsupportedDatabaseFeature(payloads, requestId, feature) {
+    payloads.push({ requestId, error: `${feature} is not supported by this database Host`, data: { code: 'unsupported' } });
+}
 export function stringField(message, key) {
     const value = message[key];
     return typeof value === 'string' ? value.trim() : '';

package/lib/console-rpc-types.d.ts

@@ -0,0 +1,2 @@
+export declare const RUNTIME_CONSOLE_RPC_TYPES: ReadonlySet<string>;
+export declare function isRuntimeConsoleRpcType(type: unknown): type is string;

package/lib/console-rpc-types.js

@@ -0,0 +1,43 @@
+/**
+ * RPC types the runtime Console dispatcher of this package answers (`dispatchRuntimeConsoleRpc`:
+ * shell, configuration, plugin management, project files / environment / database, endpoints,
+ * schedules, inbox, login assist, workrooms). Used to tell an RPC this Host has but forgot to map
+ * (audited `unmapped`) from one it does not have at all (`unknown_rpc`, zhinjs/zhin#1250), and to
+ * build the Host's capability list. `console-rpc-types.test.ts` keeps it in step with the
+ * dispatchers' `case` labels.
+ */
+import { CONFIG_RPC, ENDPOINT_RPC, PLUGIN_RPC } from '@zhin.js/console-protocol';
+export const RUNTIME_CONSOLE_RPC_TYPES = new Set([
+    // Shell
+    'ping', 'entries:get', 'pages:list',
+    // Configuration
+    ...Object.values(CONFIG_RPC),
+    'workrooms:get', 'workrooms:set',
+    // Plugin management (the global switch is refused with a pointer to the gateway)
+    ...Object.values(PLUGIN_RPC),
+    // Project files / environment / schemas / database / process
+    'files:tree', 'files:read', 'files:save',
+    'env:list', 'env:get', 'env:reveal', 'env:save',
+    'schema:get', 'schema:get-all',
+    'db:info', 'db:tables', 'db:select', 'db:query', 'db:execute',
+    'db:schema:describe', 'db:schema:preview', 'db:schema:apply',
+    'db:insert', 'db:update', 'db:delete', 'db:drop-table',
+    'db:kv:get', 'db:kv:set', 'db:kv:delete', 'db:kv:entries',
+    'system:restart',
+    // Endpoints
+    ...Object.values(ENDPOINT_RPC),
+    // Schedules
+    'schedule:list', 'cron:list', 'cron:validate', 'cron:add', 'cron:remove', 'cron:pause', 'cron:resume',
+    // Requests / notices / inbox
+    'request.list', 'request.approve', 'request.reject', 'request.consumed', 'notice.consumed',
+    'inbox.requests', 'inbox.notices', 'inbox.messages', 'inbox.recent',
+    // Login assist
+    'login.list', 'login.submit', 'login.cancel', 'login.flow.list', 'login.flow.get', 'login.relogin', 'login.refresh',
+    // Workroom profiles / knowledge
+    'workroom.profile.status', 'workroom.profile.bootstrap', 'workroom.profile.pack.publish',
+    'workroom.profile.publish', 'workroom.profile.rollback', 'workroom.profile.policy.publish',
+    'workroom.knowledge.get', 'workroom.knowledge.publish', 'workroom.knowledge.rollback',
+]);
+export function isRuntimeConsoleRpcType(type) {
+    return typeof type === 'string' && RUNTIME_CONSOLE_RPC_TYPES.has(type);
+}

package/lib/console-rpc.d.ts

@@ -101,9 +101,22 @@ export interface PluginVerificationResult {
     readonly evidence: readonly string[];
     readonly evidenceI18n?: import('@zhin.js/plugin-runtime').PluginVerificationOutcome['evidenceI18n'];
 }
+/** `inspect` options. `dependencies: 'skip'` leaves the project-wide graph check out (`dependencies: 'unchecked'`). */
+export interface PluginInspectOptions {
+    readonly dependencies?: 'check' | 'skip';
+}
+/** Result of the project-wide dependency graph check (the same check `inspect` runs per plugin). */
+export type PluginDependencyCheck = {
+    readonly status: 'passed';
+} | {
+    readonly status: 'failed';
+    readonly error: string;
+};
 export interface PluginManagementPort {
     explainConfiguration?(instanceKey: string, expectedRevision: string): Promise<ConsoleConfigExplanation>;
-    inspect?(packageName: string): Promise<PluginManagementState>;
+    inspect?(packageName: string, options?: PluginInspectOptions): Promise<PluginManagementState>;
+    /** Runs the project-wide dependency graph check once, for callers that inspect many plugins. */
+    checkDependencies?(): Promise<PluginDependencyCheck>;
     apply?(packageName: string, expectedProjectRevision?: string): Promise<{
         readonly requested: boolean;
         readonly state: PluginManagementState;
@@ -193,8 +206,23 @@ export type RuntimeConsoleRpcContext = {
         name: string;
         exists: boolean;
     }[]>;
+    /**
+     * @deprecated Not used any more: `env:get` answers {@link readEnvFileView} only, so the file as
+     * written never reaches the Console (issue #1250).
+     */
     readEnvFile?(filename: string): Promise<string>;
+    /** @deprecated Not used any more: `env:save` writes through {@link updateEnvVariables} / {@link replaceEnvFile}. */
     writeEnvFile?(filename: string, content: string): Promise<void>;
+    /** `env:get`: masked view (key names, masks, lengths; comments and blank lines in place). */
+    readEnvFileView?(filename: string): Promise<import('@zhin.js/console-protocol').ConsoleEnvFileView>;
+    /** `env:reveal`: one variable as written. The route requires `ops.env.write` + `ops.env.read` and audits. */
+    revealEnvVariable?(filename: string, key: string): Promise<import('@zhin.js/console-protocol').ConsoleEnvRevealResult>;
+    /** `env:save { changes }`: validates and writes only the named keys (mask placeholders refused). */
+    updateEnvVariables?(filename: string, changes: unknown): Promise<{
+        readonly changed: readonly string[];
+    }>;
+    /** `env:save { content, mode: 'replace' }`: whole file; refused when it holds mask placeholders. */
+    replaceEnvFile?(filename: string, content: string): Promise<void>;
     /** Optional schema accessors (plugin schema.json / Runtime schema registry). */
     getSchema?(pluginName?: string): Promise<unknown>;
     getAllSchemas?(): Promise<Record<string, unknown>>;

package/lib/console-rpc.js

@@ -1,5 +1,6 @@
-import { CONFIG_PATCH_LIMITS, CONFIG_RPC, } from '@zhin.js/console-protocol';
-import { authorizeConsoleRpc } from './access-control.js';
+import { CONFIG_PATCH_LIMITS, CONFIG_RPC, CONSOLE_UNKNOWN_RPC_CODE, grantsAllow, } from '@zhin.js/console-protocol';
+import { authorizeConsoleRpc, principalAllows } from './access-control.js';
+import { isRuntimeConsoleRpcType } from './console-rpc-types.js';
 import { dispatchExtendedConsoleRpc } from './console-rpc-extended/index.js';
 import { dispatchPluginConsoleRpc } from './console-plugin-rpc.js';
 import { configurationSaveMessage, dispatchHostResourceConsoleRpc, invalidProjectPatchOperations, } from './console-rpc-handlers.js';
@@ -9,6 +10,20 @@ export function pickRpcReply(message, payloads) {
         ?? payloads[payloads.length - 1]
         ?? null);
 }
+/**
+ * The Endpoint a principal was admitted for when only an adapter / endpoint-scoped grant covers the
+ * call (B-1): handlers must then stay inside it. `undefined` when a global grant covers it.
+ */
+function scopedAuthorizedEndpoint(principal, decision) {
+    if (principal.kind === 'bootstrap' || !decision.permission || !decision.rule)
+        return undefined;
+    if (grantsAllow(principal.grants, decision.permission))
+        return undefined;
+    const target = decision.rule.target;
+    if (target.kind !== 'endpoint')
+        return undefined;
+    return Object.freeze({ adapter: target.adapter, endpointKey: target.endpoint });
+}
 export async function dispatchRuntimeConsoleRpc(message, ctx) {
     const payloads = [];
     const emit = (payload) => {
@@ -16,19 +31,30 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
     };
     const type = String(message.type ?? '');
     const requestId = message.requestId;
+    let authorizedEndpoint;
+    let canOperateEndpoint;
     if (ctx.principal) {
-        const decision = authorizeConsoleRpc(ctx.principal, message);
+        const principal = ctx.principal;
+        const decision = authorizeConsoleRpc(principal, message, { registered: isRuntimeConsoleRpcType });
         if (!decision.allowed) {
-            emit({ requestId, error: decision.error, code: decision.code });
+            emit({ requestId, error: decision.error, code: decision.code, ...(decision.reason ? { reason: decision.reason } : {}) });
             return payloads;
         }
+        authorizedEndpoint = scopedAuthorizedEndpoint(principal, decision);
+        // Same grant check the map applies to `login.submit` for that Endpoint (ADR 0058 §8).
+        canOperateEndpoint = (adapter, endpointKey) => principalAllows(principal, 'endpoint.operate', Object.freeze({ kind: 'endpoint', adapter, endpoint: endpointKey }));
     }
     // Extended RPC surface (cron/schedule、endpoint 社交/inbox)
     if (ctx.extended) {
-        const extended = await dispatchExtendedConsoleRpc(type, message, { ...ctx.extended, fullScope: ctx.authScope === 'full' });
+        const extended = await dispatchExtendedConsoleRpc(type, message, {
+            ...ctx.extended,
+            fullScope: ctx.authScope === 'full',
+            ...(authorizedEndpoint ? { authorizedEndpoint } : {}),
+            ...(canOperateEndpoint ? { canOperateEndpoint } : {}),
+        });
         if (extended !== undefined) {
             emit('error' in extended
-                ? { requestId, error: extended.error }
+                ? { requestId, error: extended.error, ...(extended.data !== undefined ? { data: extended.data } : {}) }
                 : { requestId, data: extended.data });
             return payloads;
         }
@@ -374,7 +400,7 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
                 });
                 return payloads;
             }
-            emit({ requestId, error: `Unknown RPC type: ${type || '<empty>'}` });
+            emit({ requestId, error: `Unknown RPC type: ${type.slice(0, 64) || '<empty>'}`, code: CONSOLE_UNKNOWN_RPC_CODE });
             return payloads;
         }
     }