@zhin.js/host-http 1.2.2 → 1.4.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,7 +1,15 @@
-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.

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, endpointTransportLabel, } 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;
+                }
+                // 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.writeEnvFile) {
+                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) {
@@ -510,7 +595,7 @@ export async function dispatchHostResourceConsoleRpc(type, message, ctx, request
         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({
@@ -538,7 +623,7 @@ export async function dispatchHostResourceConsoleRpc(type, message, ctx, request
                     emit({ requestId, error: 'endpoint not found' });
                     return true;
                 }
-                emit({ requestId, data: endpoint });
+                emit({ requestId, data: withTransportLabel(endpoint) });
             }
             catch (error) {
                 emit({
@@ -628,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;
@@ -741,3 +828,12 @@ export function configurationSaveMessage(result) {
     }
     return result.restartRequired ? '配置已保存，需重启进程才能生效' : '配置已保存';
 }
+/** Adds the readable `transportLabel` next to the raw `transportState` of an Endpoint row (#1250). */
+function withTransportLabel(endpoint) {
+    if (!endpoint || typeof endpoint !== 'object')
+        return endpoint;
+    const state = endpoint.transportState;
+    if (typeof state !== 'string')
+        return endpoint;
+    return { ...endpoint, transportLabel: endpointTransportLabel(state) };
+}

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, grantsAllow, } from '@zhin.js/console-protocol';
+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';
@@ -34,9 +35,9 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
     let canOperateEndpoint;
     if (ctx.principal) {
         const principal = ctx.principal;
-        const decision = authorizeConsoleRpc(principal, message);
+        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);
@@ -282,7 +283,11 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
                 return payloads;
             }
             const projectPatch = message.type === CONFIG_RPC.PATCH_PROJECT;
-            const { instanceKey, expectedRevision, patches } = message;
+            const { instanceKey, expectedRevision, patches, secretStorage } = message;
+            if (secretStorage !== undefined && secretStorage !== 'env' && secretStorage !== 'plain') {
+                emit({ requestId, error: 'secretStorage 只能是 env 或 plain' });
+                return payloads;
+            }
             if (projectPatch && instanceKey !== undefined) {
                 emit({ requestId, error: 'Project patches must not specify instanceKey' });
                 return payloads;
@@ -317,6 +322,7 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
                     ...(instanceKey === undefined ? {} : { instanceKey }),
                     expectedRevision,
                     patches,
+                    ...(secretStorage === undefined ? {} : { secretStorage }),
                 });
             }
             catch (error) {
@@ -381,9 +387,11 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
                 });
             }
             catch (error) {
+                const code = error instanceof Error && 'code' in error && error.code === 'env-write-required' ? { code: 'env-write-required' } : {};
                 emit({
                     requestId,
                     error: `Failed to set config: ${error instanceof Error ? error.message : String(error)}`,
+                    ...code,
                 });
             }
             return payloads;
@@ -399,7 +407,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;
         }
     }

package/lib/host-installer.js

@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises';
 import { isAbsolute, resolve } from 'node:path';
 import { httpHostToken } from './http-host.js';
 import { parseTrustProxy } from './trust-proxy.js';
+import { parseHttpPort } from './port.js';
 export async function resolveHttpConfig(config, envOverlay, projectRoot = process.cwd()) {
     const document = await readConfigDocument(config);
     if (!document || typeof document !== 'object')
@@ -11,18 +12,20 @@ export async function resolveHttpConfig(config, envOverlay, projectRoot = proces
     if (!http || typeof http !== 'object')
         return {};
     const value = expandEnvironmentValue(http, (key) => envOverlay?.[key] ?? process.env[key]);
+    const stored = http;
     if (value.tokens !== undefined && value.tokens !== null)
         throw new Error(HTTP_TOKENS_REMOVED_MESSAGE);
     const primary = Object.freeze({
         host: typeof value.host === 'string' ? value.host : undefined,
-        port: typeof value.port === 'number' ? value.port : undefined,
+        // An invalid port is an error, never a silent fallback to the default (#1250).
+        port: parseHttpPort(value.port, 'http.port', stored.port),
         token: typeof value.token === 'string' ? value.token : undefined,
         corsOrigins: injectDesktopWebviewOrigins(parseStringList(value.corsOrigins), envOverlay),
         apiBase: typeof value.base === 'string' ? value.base : undefined,
         tls: await parseTlsConfig(value.tls, projectRoot),
         trustProxy: parseTrustProxy(value.trustProxy),
     });
-    const configuredListeners = await parseAdditionalListeners(value.listeners, primary, projectRoot);
+    const configuredListeners = await parseAdditionalListeners(value.listeners, primary, projectRoot, stored.listeners);
     const listeners = await injectDesktopDeviceListener(configuredListeners, primary, envOverlay, projectRoot);
     return Object.freeze({ ...primary, ...(listeners.length > 0 ? { listeners } : {}) });
 }
@@ -71,7 +74,7 @@ async function injectDesktopDeviceListener(configured, primary, envOverlay, proj
     }, projectRoot);
     return Object.freeze([...configured, Object.freeze({ ...primary, host, port, tls })]);
 }
-async function parseAdditionalListeners(value, primary, projectRoot) {
+async function parseAdditionalListeners(value, primary, projectRoot, stored) {
     if (value === undefined)
         return Object.freeze([]);
     if (!Array.isArray(value))
@@ -87,13 +90,15 @@ async function parseAdditionalListeners(value, primary, projectRoot) {
         if (typeof listener.host !== 'string' || !listener.host) {
             throw new Error(`http.listeners[${index}].host is required`);
         }
-        if (typeof listener.port !== 'number') {
+        const storedPort = Array.isArray(stored) ? stored[index]?.port : undefined;
+        const port = parseHttpPort(listener.port, `http.listeners[${index}].port`, storedPort);
+        if (port === undefined) {
             throw new Error(`http.listeners[${index}].port is required`);
         }
         listeners.push(Object.freeze({
             ...primary,
             host: listener.host,
-            port: listener.port,
+            port,
             tls: await parseTlsConfig(listener.tls, projectRoot),
         }));
     }

package/lib/http-host.js

@@ -12,7 +12,7 @@ import { createToken, generationAdmissionBinder, } from '@zhin.js/plugin-runtime
 import { HttpBodyError, jsonResponse } from '@zhin.js/host-http-contract';
 import { TokenRegistry, extractBearerToken, } from './token-registry.js';
 import { buildOpenApiDocument, } from './openapi.js';
-import { auditActor, authorizeConsoleHttp, authorizeConsoleWebSocket, requestMeta, } from './access-control.js';
+import { auditActor, authorizeConsoleHttp, authorizeConsoleWebSocket, requestMeta, webSocketDenialReason, } from './access-control.js';
 const logger = getLogger('http');
 export const REMOTE_CONSOLE_ORIGIN = 'https://console.zhin.dev';
 const DEFAULT_CORS_ORIGINS = Object.freeze([REMOTE_CONSOLE_ORIGIN]);
@@ -85,12 +85,12 @@ export function createHttpRouter(options = {}) {
         if (!principal)
             return undefined;
         if (!authorizeConsoleWebSocket(principal, pathname)) {
-            audit(principal, remoteAddress, `ws:${pathname}`, 'denied');
+            audit(principal, remoteAddress, `ws:${pathname}`, 'denied', webSocketDenialReason(principal, pathname));
             return undefined;
         }
         return principal;
     }
-    function audit(principal, remoteAddress, action, outcome) {
+    function audit(principal, remoteAddress, action, outcome, reason) {
         const sink = tokenRegistry.accessProvider?.audit;
         if (!sink)
             return;
@@ -99,6 +99,7 @@ export function createHttpRouter(options = {}) {
                 actor: auditActor(principal),
                 action,
                 outcome,
+                ...(reason ? { detail: { reason } } : {}),
                 ...(remoteAddress ? { ip: remoteAddress } : {}),
             });
         }
@@ -282,7 +283,7 @@ export function createHttpRouter(options = {}) {
         const decision = authorizeConsoleHttp(principal, method, relative);
         if (!decision.allowed) {
             if (principal)
-                audit(principal, remoteAddress, `http:${method} ${relative}`, 'denied');
+                audit(principal, remoteAddress, `http:${method} ${relative}`, 'denied', decision.reason);
             return { ok: false, status: decision.status, code: decision.code, error: decision.error };
         }
         return { ok: true, ...(principal ? { principal } : {}) };

package/lib/index.d.ts

@@ -1,8 +1,9 @@
 export { createHttpRouter, httpHostToken, normalizePath, REMOTE_CONSOLE_ORIGIN, type HttpHandler, type HttpHost, type HttpRequestInfo, type HttpRouter, type HttpRouterOptions, type HttpRouteRegistration, type RouteContext, type WsConnection, type WsHandle, type WsRouteOptions, type WsTransport, type WsUpgradeDecision, type WsUpgradeRequest, type ListedWsRoute, } from './http-host.js';
 export type { HttpHostAddress, HttpHostOptions, HttpHostTlsOptions } from './host-options.js';
 export { listHttpHostAddresses } from './addresses.js';
+export { DEFAULT_HTTP_PORT, ENVIRONMENT_REFERENCE_PATTERN, InvalidHttpPortError, describeInvalidPortValue, parseHttpPort, } from './port.js';
 export { TokenRegistry, extractBearerToken, publicConsoleAccess, unrestrictedConsoleAccess, type AuthenticatedTokenPrincipal, type ConsoleAccess, type AuthScope, type TokenRegistryConfig, } from './token-registry.js';
-export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, isUserPrincipal, isExplicitConsolePrincipal, pluginRpcWriteAllowed, principalAllows, requestMeta, rpcAuditDetail, rpcAuditTarget, type RpcAuditOptions, type ConsoleAccessProvider, type ConsoleAuditEntry, type ConsoleBootstrapPrincipal, type ConsoleHttpDecision, type ConsolePrincipal, type ConsoleRequestMeta, type ConsoleRpcDecision, type ConsoleUserPrincipal, } from './access-control.js';
+export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, grantsDenialReason, isAuditedRpcDenial, unknownConsoleRpcError, webSocketDenialReason, type AuthorizeConsoleRpcOptions, isUserPrincipal, isExplicitConsolePrincipal, isGlobalOwnerPrincipal, isLocalSocketPrincipal, LOCAL_SOCKET_CREDENTIAL_ID, LOCAL_SOCKET_USER_ID, pluginRpcWriteAllowed, principalAllows, requestMeta, rpcAuditDetail, rpcAuditTarget, type RpcAuditOptions, type ConsoleAccessProvider, type ConsoleAuditEntry, type ConsoleBootstrapPrincipal, type ConsoleHttpDecision, type ConsolePrincipal, type ConsoleRequestMeta, type ConsoleRpcDecision, type ConsoleUserPrincipal, } from './access-control.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
 export { isLoopbackAddress, isLoopbackHost, verifyProtocolAccessToken, type ProtocolAuthRequest } from './protocol-auth.js';
 export { compileTrustProxy, hasForwardingHeaders, parseTrustProxy, resolveClientAddress, TrustProxyConfigError, type TrustProxyPredicate, type TrustProxySetting, } from './trust-proxy.js';
@@ -10,9 +11,11 @@ export { createConsoleEventHub, consoleEventHubToken, type ConsoleEventHub, } fr
 export { buildOpenApiDocument, patternToOpenApiPath, routeRequiresBearerAuth, type BuildOpenApiOptions, type ListedRoute, type OpenApiParameter, type RouteMeta, } from './openapi.js';
 export { HttpBodyError, readBodyBytes, readJsonBody, readTextBody, type HttpBodyReadOptions, } from './json-body.js';
 export { createResponseStream, emptyResponse, jsonResponse, SSE_HEADERS, type HttpResponseStream, type HttpResponseStreamOptions, } from '@zhin.js/host-http-contract';
-export { dispatchRuntimeConsoleRpc, pickRpcReply, type RuntimeConsolePage, type RuntimeConsoleRpcContext, type RuntimeConsoleRpcMessage, type RuntimeConsoleRpcReply, type RuntimeEndpointSendInput, type PluginInstallPlan, type PluginUninstallPlan, type PluginUpdatePlan, type PluginManagementPort, type PluginManagementState, type PluginVerificationResult, type PluginVerificationPlan, type PluginConfigValidation, } from './console-rpc.js';
+export { isRuntimeConsoleRpcType, RUNTIME_CONSOLE_RPC_TYPES } from './console-rpc-types.js';
+export { createUnknownRpcLog, unknownRpcLog, type UnknownRpcLog, type UnknownRpcLogEntry } from './unknown-rpc.js';
+export { dispatchRuntimeConsoleRpc, pickRpcReply, type RuntimeConsolePage, type RuntimeConsoleRpcContext, type RuntimeConsoleRpcMessage, type RuntimeConsoleRpcReply, type RuntimeEndpointSendInput, type PluginInstallPlan, type PluginUninstallPlan, type PluginUpdatePlan, type PluginManagementPort, type PluginManagementState, type PluginInspectOptions, type PluginDependencyCheck, type PluginVerificationResult, type PluginVerificationPlan, type PluginConfigValidation, } from './console-rpc.js';
 export { dispatchPluginConsoleRpc, PLUGIN_SWITCH_REQUIRES_GATEWAY } from './console-plugin-rpc.js';
 export { buildProjectFileTree, FILE_MANAGER_ALLOWED, FILE_MANAGER_BLOCKED, isProjectPathAllowed, listEnvFiles, readProjectFile, saveProjectFile, type FileTreeNode, } from './project-files.js';
 export { registerConsoleRestPages, type ConsoleAgentIntrospection, type ConsoleAgentRuntime, type ConsoleAgentSessionTree, type ConsoleRestCtx, type ConsoleRestPagesOptions, } from './console-rest-pages.js';
-export { dispatchExtendedConsoleRpc, type ConsoleRpcExtendedCtx, type ConsoleScheduleEngine, type ConsoleWorkroomProfileControlPort, type ConsoleWorkroomKnowledgeControlPort, type ExtendedRpcResult, type ConsoleLoginAssistPort, type ConsoleEndpointLoginAccess, loginAuditDetail, LOGIN_SUBMIT_WAIT_MS, } from './console-rpc-extended/index.js';
+export { dispatchExtendedConsoleRpc, type ConsoleRpcExtendedCtx, type ConsoleScheduleEngine, type ConsoleScheduleTarget, type ConsoleWorkroomProfileControlPort, type ConsoleWorkroomKnowledgeControlPort, type ExtendedRpcResult, type ConsoleLoginAssistPort, type ConsoleEndpointLoginAccess, loginAuditDetail, LOGIN_SUBMIT_WAIT_MS, } from './console-rpc-extended/index.js';
 export * from './host-installer.js';

package/lib/index.js

@@ -1,7 +1,8 @@
 export { createHttpRouter, httpHostToken, normalizePath, REMOTE_CONSOLE_ORIGIN, } from './http-host.js';
 export { listHttpHostAddresses } from './addresses.js';
+export { DEFAULT_HTTP_PORT, ENVIRONMENT_REFERENCE_PATTERN, InvalidHttpPortError, describeInvalidPortValue, parseHttpPort, } from './port.js';
 export { TokenRegistry, extractBearerToken, publicConsoleAccess, unrestrictedConsoleAccess, } from './token-registry.js';
-export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, isUserPrincipal, isExplicitConsolePrincipal, pluginRpcWriteAllowed, principalAllows, requestMeta, rpcAuditDetail, rpcAuditTarget, } from './access-control.js';
+export { auditActor, authorizeConsoleHttp, authorizeConsoleRpc, authorizeConsoleWebSocket, globalPermissions, grantsDenialReason, isAuditedRpcDenial, unknownConsoleRpcError, webSocketDenialReason, isUserPrincipal, isExplicitConsolePrincipal, isGlobalOwnerPrincipal, isLocalSocketPrincipal, LOCAL_SOCKET_CREDENTIAL_ID, LOCAL_SOCKET_USER_ID, pluginRpcWriteAllowed, principalAllows, requestMeta, rpcAuditDetail, rpcAuditTarget, } from './access-control.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
 export { isLoopbackAddress, isLoopbackHost, verifyProtocolAccessToken } from './protocol-auth.js';
 export { compileTrustProxy, hasForwardingHeaders, parseTrustProxy, resolveClientAddress, TrustProxyConfigError, } from './trust-proxy.js';
@@ -9,6 +10,8 @@ export { createConsoleEventHub, consoleEventHubToken, } from './console-events.j
 export { buildOpenApiDocument, patternToOpenApiPath, routeRequiresBearerAuth, } from './openapi.js';
 export { HttpBodyError, readBodyBytes, readJsonBody, readTextBody, } from './json-body.js';
 export { createResponseStream, emptyResponse, jsonResponse, SSE_HEADERS, } from '@zhin.js/host-http-contract';
+export { isRuntimeConsoleRpcType, RUNTIME_CONSOLE_RPC_TYPES } from './console-rpc-types.js';
+export { createUnknownRpcLog, unknownRpcLog } from './unknown-rpc.js';
 export { dispatchRuntimeConsoleRpc, pickRpcReply, } from './console-rpc.js';
 export { dispatchPluginConsoleRpc, PLUGIN_SWITCH_REQUIRES_GATEWAY } from './console-plugin-rpc.js';
 export { buildProjectFileTree, FILE_MANAGER_ALLOWED, FILE_MANAGER_BLOCKED, isProjectPathAllowed, listEnvFiles, readProjectFile, saveProjectFile, } from './project-files.js';