dsh-kingdom 0.8.0 → 2.0.0

package/lib/types/gui/local-control.d.ts

@@ -0,0 +1,120 @@
+import type { Principal } from '../core/task-service.js';
+import { GuiControlAuthorizeResult, GuiControlBroker, GuiControlInspectResult, GuiControlRedeemResult, GuiControlRequestMeta } from './control-contract.js';
+export declare const LOCAL_CONTROL_REDIRECT_PATH = "/console";
+export declare const LOCAL_CONTROL_LAUNCH_PATH = "/console";
+export declare const LOCAL_CONTROL_SESSION_COOKIE = "dsh_kingdom_control";
+export declare const LOCAL_CONTROL_CSRF_HEADER = "x-kingdom-csrf";
+export declare const LOCAL_CONTROL_REQUEST_ID_HEADER = "x-kingdom-request-id";
+type Clock = () => number;
+type TokenFactory = () => string;
+export interface LocalControlOptions {
+    /** HTTP Host must resolve to this exact IPv4 loopback address. */
+    host?: string;
+    /** Browser Origin must equal this exact value; `*` is never accepted. */
+    expectedOrigin: string | (() => string);
+    ticketTtlMs?: number;
+    sessionTtlMs?: number;
+    maxRequestIds?: number;
+    now?: Clock;
+    tokenFactory?: TokenFactory;
+}
+export interface LocalControlActivation {
+    /** One-time secret for the GUI launch route; never log or persist it. */
+    readonly launchTicket: string;
+    readonly launchPath: typeof LOCAL_CONTROL_LAUNCH_PATH;
+    readonly activationId: string;
+    readonly expiresAt: string;
+    readonly ttlMs: number;
+}
+export interface LocalControlRedeemRequest {
+    host: string;
+    /** Navigation requests may omit Origin; if present it is checked exactly. */
+    origin?: string | null;
+}
+export interface LocalControlCookie {
+    readonly name: typeof LOCAL_CONTROL_SESSION_COOKIE;
+    readonly value: string;
+    readonly httpOnly: true;
+    readonly sameSite: 'Strict';
+    readonly path: '/';
+    readonly maxAgeSeconds: number;
+}
+export interface LocalControlRedemption {
+    readonly ok: true;
+    readonly status: 303;
+    readonly location: typeof LOCAL_CONTROL_REDIRECT_PATH;
+    readonly cookie: LocalControlCookie;
+    /** Returned to the GUI page through the redemption response, not a cookie. */
+    readonly csrfToken: string;
+    readonly expiresAt: string;
+}
+export type LocalControlRejectionCode = 'LOCAL_CONTROL_CLOSED' | 'LOOPBACK_REQUIRED' | 'ORIGIN_MISMATCH' | 'ORIGIN_NOT_CONFIGURED' | 'LAUNCH_TICKET_REQUIRED' | 'LAUNCH_TICKET_INVALID' | 'LAUNCH_TICKET_EXPIRED' | 'SESSION_COOKIE_REQUIRED' | 'SESSION_INVALID' | 'SESSION_EXPIRED' | 'SESSION_REVOKED' | 'CSRF_REQUIRED' | 'CSRF_INVALID' | 'REQUEST_ID_REQUIRED' | 'REQUEST_ID_INVALID' | 'REQUEST_REPLAY' | 'REQUEST_WINDOW_EXHAUSTED' | 'MUTATION_IN_FLIGHT';
+export interface LocalControlRejection {
+    readonly ok: false;
+    readonly code: LocalControlRejectionCode;
+    readonly message: string;
+}
+export interface LocalControlAuthority {
+    /** Captured exact DSH Agent object; never accepted from the HTTP payload. */
+    readonly agent: unknown;
+    /** Captured at activation time and re-used for session-bound Role checks. */
+    readonly principal: Principal;
+    /** Aborted on TTL expiry, revoke, replacement, or plugin unload. */
+    readonly signal: AbortSignal;
+}
+export interface LocalControlAdmission {
+    readonly ok: true;
+    readonly authority: LocalControlAuthority;
+    readonly expiresAt: string;
+    /** Must be called exactly once after the command handler settles. */
+    readonly release: () => void;
+}
+export type LocalControlRedemptionResult = LocalControlRedemption | LocalControlRejection;
+export type LocalControlAdmissionResult = LocalControlAdmission | LocalControlRejection;
+/** Accept `127.0.0.1` and `127.0.0.1:port`; reject localhost/IPv6/other hosts. */
+export declare function isExactLoopbackHost(value: string, expectedHost?: string): boolean;
+/** The server is IPv4-loopback only; do not widen this to localhost or ::1. */
+export declare function isExactLoopbackRemoteAddress(value: string | null): boolean;
+/**
+ * In-process Local GUI Control Session manager.
+ *
+ * `activate()` is intended to be called only from the direct Slash handler.
+ * `redeem()` and `admit()` are transport seams; neither one mints authority.
+ */
+export declare class LocalControlManager implements GuiControlBroker {
+    private readonly host;
+    private readonly expectedOriginSource;
+    private readonly ticketTtlMs;
+    private readonly sessionTtlMs;
+    private readonly maxRequestIds;
+    private readonly now;
+    private readonly tokenFactory;
+    private readonly tickets;
+    private readonly sessions;
+    private closed;
+    constructor(options: LocalControlOptions);
+    private expectedOrigin;
+    private validateTransport;
+    private publicView;
+    private sessionFor;
+    activate(agent: unknown): LocalControlActivation;
+    redeem(launchTicket: string, meta: GuiControlRequestMeta): GuiControlRedeemResult;
+    inspect(cookieValue: string | null, meta: GuiControlRequestMeta): GuiControlInspectResult;
+    authorize(cookieValue: string | null, csrfToken: string | null, requestId: string | null, meta: GuiControlRequestMeta): GuiControlAuthorizeResult;
+    admit(request: {
+        host: string;
+        origin?: string | null;
+        cookie?: string | null;
+        csrfToken?: string | null;
+        requestId?: string | null;
+        mutation?: boolean;
+    }): LocalControlAdmissionResult;
+    revoke(cookieHeaderOrValue: string | null): void;
+    revokeAllSessions(): void;
+    close(): void;
+    dispose(): void;
+    private revokeAll;
+    private revokeRecord;
+}
+export declare function createLocalControl(options: LocalControlOptions): LocalControlManager;
+export {};

package/lib/types/gui/owner-control.d.ts

@@ -0,0 +1,45 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { OwnerControlCapability } from '../core/owner-control.js';
+import type { OwnerDecisionController, OwnerDecisionInput } from '../core/owner-window.js';
+import { type GuiControlRequestMeta } from './control-contract.js';
+export declare const OWNER_CONTROL_COOKIE = "dsh_kingdom_owner";
+export declare class OwnerTransportError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status?: number);
+}
+export interface OwnerLocalControlOptions {
+    controller: OwnerDecisionController;
+    expectedOrigin: string | (() => string);
+    now?: () => number;
+}
+/** Transport references existing direct-human decisions; it never accepts an HTTP identity. */
+export declare class OwnerLocalControlManager {
+    private readonly options;
+    private readonly tickets;
+    private readonly windows;
+    private readonly now;
+    private closed;
+    constructor(options: OwnerLocalControlOptions);
+    private origin;
+    checkTransport(meta: GuiControlRequestMeta, mutation?: boolean, navigation?: boolean): void;
+    activate(capability: OwnerControlCapability, input: OwnerDecisionInput): {
+        launchTicket: string;
+        launchPath: '/owner';
+        decisionId: string;
+        expiresAt: string;
+        ttlMs: number;
+    };
+    redeem(ticket: string, meta: GuiControlRequestMeta): {
+        cookie: string;
+        maxAgeSeconds: number;
+    };
+    private window;
+    inspect(cookie: string | null, meta: GuiControlRequestMeta): Promise<unknown>;
+    receipt(cookie: string | null, meta: GuiControlRequestMeta, operationId: string, decisionId: string | null): unknown;
+    mutate(cookie: string | null, csrf: string | null, requestId: string | null, meta: GuiControlRequestMeta, action: 'prepare' | 'commit' | 'revoke', payload: Record<string, unknown>): Promise<unknown>;
+    private invalidate;
+    dispose(): void;
+}
+/** Runs before the Role Plane bearer/admission routes. Neither cookie upgrades the other. */
+export declare function handleOwnerRequest(req: IncomingMessage, res: ServerResponse, url: URL, manager: OwnerLocalControlManager | undefined): Promise<boolean>;

package/lib/types/gui/owner-ui.d.ts

@@ -0,0 +1,2 @@
+/** Self-contained management surface; all business values are rendered as text. */
+export declare function renderOwnerApp(nonce: string): string;

package/lib/types/gui/server.d.ts

@@ -1,24 +1,38 @@
 import type { CommandResultView, SnapshotView, TaskDetailView } from './contract.js';
 import type { EventView } from './contract.js';
+import { type OwnerLocalControlManager } from './owner-control.js';
+import { GuiControlBroker, GuiControlExecutionContext, type GuiControlReadContext } from './control-contract.js';
 export interface GuiServerHandlers {
-    snapshot(): SnapshotView;
-    taskDetail(taskId: string): TaskDetailView | null;
+    snapshot(readContext?: GuiControlReadContext): SnapshotView;
+    taskDetail(taskId: string, readContext?: GuiControlReadContext): TaskDetailView | null;
     eventsSince(afterSeq: number, limit: number): {
         revision: number;
         events: EventView[];
     };
-    command(name: string, payload: Record<string, unknown>): Promise<CommandResultView>;
+    command(name: string, payload: Record<string, unknown>, control?: GuiControlExecutionContext): Promise<CommandResultView>;
+}
+export interface GuiServerAddress {
+    host: string;
+    port: number;
+    origin: string;
 }
 export interface GuiServerOptions {
     port: number;
     host?: string;
     token?: string;
     allowOrigins?: string[];
+    control?: GuiControlBroker;
+    /** Independent direct-human decision transport; never upgrades Role cookies. */
+    ownerControl?: OwnerLocalControlManager;
+    onListening?(address: GuiServerAddress): void;
+    onUnavailable?(error: Error): void;
     logger?: {
         info(message: string): void;
         warn(message: string): void;
     };
 }
+/** v0.9 S2：四区只读 Console；数据只来自现有 GET projection seam。 */
+export declare const READONLY_CONSOLE_HTML = "<!doctype html>\n<html lang=\"zh-CN\">\n<head>\n  <meta charset=\"utf-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n  <title>dsh-Kingdom Read-only Projection Console</title>\n  <style>\n    :root { color-scheme: dark; font-family: system-ui, sans-serif; background: #111827; color: #e5e7eb; }\n    * { box-sizing: border-box; }\n    body { margin: 0; min-width: 0; background: #111827; }\n    main { width: min(100% - 24px, 1180px); margin: 0 auto; padding: 16px 0 28px; }\n    h1, h2, p { margin: 0; }\n    h1 { font-size: 1.35rem; margin-bottom: 12px; }\n    h2 { font-size: 1rem; margin-bottom: 8px; }\n    .grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 12px; }\n    section { min-width: 0; background: #1f2937; border: 1px solid #374151; border-radius: 10px; padding: 12px; overflow-wrap: anywhere; }\n    .wide { grid-column: 1 / -1; }\n    .muted { color: #9ca3af; font-size: .88rem; }\n    .row { border-top: 1px solid #374151; padding: 8px 0; }\n    .row:first-child { border-top: 0; padding-top: 0; }\n    .tag { display: inline-block; color: #bfdbfe; font-size: .76rem; margin-right: 6px; }\n    .attention { color: #fbbf24; }\n    .critical { color: #fca5a5; }\n    @media (max-width: 640px) {\n      main { width: min(100% - 16px, 1180px); padding-top: 10px; }\n      .grid { grid-template-columns: minmax(0, 1fr); }\n      .wide { grid-column: auto; }\n      section { padding: 10px; }\n    }\n  </style>\n</head>\n<body>\n  <main>\n    <h1>Read-only Projection Console</h1>\n    <p class=\"muted\">Owner-only actions: DIRECT_SLASH_REQUIRED</p>\n    <p id=\"status\" class=\"muted\">\u6B63\u5728\u8BFB\u53D6\u53EA\u8BFB Projection\u2026</p>\n    <div class=\"grid\">\n      <section id=\"overview\" aria-labelledby=\"overview-title\"><h2 id=\"overview-title\">\u72B6\u6001\u603B\u89C8</h2><div class=\"content\"></div></section>\n      <section id=\"task-detail\" aria-labelledby=\"task-title\"><h2 id=\"task-title\">Task Detail</h2><div class=\"content\"></div></section>\n      <section id=\"timeline\" class=\"wide\" aria-labelledby=\"timeline-title\"><h2 id=\"timeline-title\">Timeline</h2><div class=\"content\"></div></section>\n      <section id=\"attention\" class=\"wide\" aria-labelledby=\"attention-title\"><h2 id=\"attention-title\">Attention</h2><div class=\"content\"></div></section>\n    </div>\n  </main>\n  <script>\n    (() => {\n      const text = value => String(value ?? 'UNKNOWN');\n      const line = (parent, label, value, className = '') => {\n        const item = document.createElement('div');\n        item.className = 'row ' + className;\n        const tag = document.createElement('span');\n        tag.className = 'tag';\n        tag.textContent = label;\n        const body = document.createElement('span');\n        body.textContent = text(value);\n        item.append(tag, body);\n        parent.append(item);\n      };\n      const clear = id => {\n        const content = document.querySelector('#' + id + ' .content');\n        content.replaceChildren();\n        return content;\n      };\n      const renderSnapshot = (snapshot, detail) => {\n        const projection = snapshot.projection || {};\n        const overview = projection.overview?.data || {};\n        const overviewBox = clear('overview');\n        line(overviewBox, 'Health', overview.health, overview.health === 'CRITICAL' ? 'critical' : '');\n        line(overviewBox, 'Tasks', overview.taskCount);\n        line(overviewBox, 'Active Execution', overview.activeExecutionCount);\n        for (const action of overview.ownerActions || []) {\n          line(overviewBox, 'Owner action', text(action.action) + ' \u2014 ' + text(action.disabledReason?.code), 'attention');\n        }\n        const taskBox = clear('task-detail');\n        const task = snapshot.tasks?.[0];\n        if (!task) line(taskBox, 'State', 'UNKNOWN \u2014 no task detail available');\n        else {\n          line(taskBox, 'Task status', text(task.status) + ' [GOVERNANCE_FACT]');\n          line(taskBox, 'Claim', text(task.latestClaim?.claimedOutcome) + ' [WORKER_CLAIM]');\n          line(taskBox, 'Execution', text(task.latestExecution?.state) + ' [RUNTIME_OBSERVATION]');\n          line(taskBox, 'Actions', (detail?.projection?.data?.actionAvailability || []).map(a => text(a.action) + ': ' + text(a.disabledReason?.code || 'EXECUTABLE')).join('; ') || 'NONE');\n        }\n        const timelineBox = clear('timeline');\n        for (const item of projection.timeline?.data || []) line(timelineBox, text(item.kind), item.summary);\n        if (!(projection.timeline?.data || []).length) line(timelineBox, 'Timeline', 'UNKNOWN / NOT_RUN');\n        const attentionBox = clear('attention');\n        for (const item of projection.attention?.data || []) line(attentionBox, text(item.severity), text(item.reason?.code) + ' \u2014 ' + text(item.summary), item.severity.toLowerCase());\n        if (!(projection.attention?.data || []).length) line(attentionBox, 'Attention', 'NONE');\n      };\n      const load = async () => {\n        try {\n          const response = await fetch('/api/snapshot', { headers: { Accept: 'application/json' } });\n          if (!response.ok) throw new Error('snapshot HTTP ' + response.status);\n          const snapshot = await response.json();\n          let detail = null;\n          const task = snapshot.tasks?.[0];\n          if (task?.taskId) {\n            const detailResponse = await fetch('/api/tasks/' + encodeURIComponent(task.taskId), { headers: { Accept: 'application/json' } });\n            if (detailResponse.ok) detail = await detailResponse.json();\n          }\n          renderSnapshot(snapshot, detail);\n          document.querySelector('#status').textContent = '\u53EA\u8BFB Projection \u5DF2\u52A0\u8F7D\uFF1BConsole \u4E0D\u6267\u884C\u5199\u52A8\u4F5C\u3002';\n        } catch (error) {\n          document.querySelector('#status').textContent = 'UNKNOWN \u2014 ' + text(error?.message || error);\n        }\n      };\n      void load();\n    })();\n  </script>\n</body>\n</html>";
 /**
  * 启动本地 GUI 通道。
  * @returns 关闭函数（挂到 ctx.effect，插件卸载/热重载时自动收回端口）。

package/lib/types/gui/snapshot.d.ts

@@ -1,14 +1,9 @@
-/**
- * dsh-kingdom — DB 行 → GUI 视图的投影（Phase 3）。
- *
- * 全部是**纯函数**：给定 (库状态, now) 就唯一确定输出。
- * 因此 GUI 轮询即可拿到正确的表演状态，服务端不需要任何定时器或推送状态机。
- *
- * 再次强调边界：本文件只产出 `{ role, state, activity }` 这类语义，
- * 绝不产出贴图、clip、场景文件名——那些是 GUI 的 visual-map 的事。
- */
-import type { AllowedAction, BindingView, ClaimView, EventView, ExecutionView, RuntimeGovernanceView, StageActorView, TaskDetailView, TaskView, TerritoryView, SnapshotView, AuthView } from './contract.js';
+import type { AllowedAction, ActionAvailability, AttentionItem, BindingView, ClaimView, EventView, ExecutionView, ProjectionEnvelope, ProjectionSecurityContext, ReadonlySnapshotProjection, RuntimeGovernanceView, SourceRef, StageActorView, TaskProjectionData, TaskDetailView, TaskView, TerritoryView, SnapshotView, TimelineItem, AuthView, WorkbenchCostRuntime } from './contract.js';
 import { type EventRow, type ExecutionRow, type KingdomStore, type RoleBindingRow, type TaskRow, type TerritoryRow, type WorkerResultRow } from '../core/db.js';
+/** 对外暴露前统一限制数量与标识格式；不接受 session/raw payload/path 作为引用。 */
+export declare function boundedSourceRefs(refs: SourceRef[]): SourceRef[];
+/** 只返回生命周期候选的可执行性，不执行 action，也不改变任何状态。 */
+export declare function buildActionAvailability(store: KingdomStore, task: TaskRow, execution: ExecutionRow | null, security?: ProjectionSecurityContext): ActionAvailability[];
 export declare function toEventView(row: EventRow): EventView;
 export declare function toBindingView(row: RoleBindingRow): BindingView;
 export declare function toTerritoryView(row: TerritoryRow): TerritoryView;
@@ -28,6 +23,7 @@ export declare function allowedActionsFor(task: TaskRow, execution: ExecutionRow
 export declare function toTaskView(store: KingdomStore, task: TaskRow): TaskView;
 interface StageInput {
     bindings: RoleBindingRow[];
+    territories: TerritoryRow[];
     tasks: TaskRow[];
     executions: ExecutionRow[];
     events: EventRow[];
@@ -36,13 +32,39 @@ interface StageInput {
 }
 /** 计算全部角色此刻的表演语义。 */
 export declare function projectStage(input: StageInput): StageActorView[];
+/** 固定 reason code 的 Attention 派生；只读，不修复、不重试、不推进状态。 */
+export declare function buildAttention(store: KingdomStore, kingdomId: string): AttentionItem[];
+/** 从现有 row/event/observation 重建 timeline；不是新 Ledger。 */
+export declare function buildTimeline(store: KingdomStore, kingdomId: string, options?: {
+    eventLimit?: number;
+    security?: ProjectionSecurityContext;
+}): TimelineItem[];
+/** Task Detail 的只读派生 Envelope；保留旧 TaskDetailView 字段，不复刻状态机。 */
+export declare function buildTaskProjection(store: KingdomStore, kingdomId: string, task: TaskRow, options?: {
+    nowMs?: number;
+    security?: ProjectionSecurityContext;
+}): ProjectionEnvelope<TaskProjectionData>;
+export interface ReadonlyProjectionOptions {
+    eventLimit?: number;
+    nowMs?: number;
+    security?: ProjectionSecurityContext;
+    costRuntime?: WorkbenchCostRuntime;
+}
+/** S1 顶层只读 Projection；没有 kingdom 时显式返回 UNKNOWN/空数据。 */
+export declare function buildReadonlySnapshotProjection(store: KingdomStore, kingdomId: string | null, options?: ReadonlyProjectionOptions): ReadonlySnapshotProjection;
 export interface SnapshotOptions {
     auth: AuthView;
     eventLimit?: number;
     transientWindowMs?: number;
     /** 注入的"现在"，仅供测试确定性使用。 */
     nowMs?: number;
+    /** 缺少完整主体/scope/Host context 时 action 保持 fail-closed。 */
+    security?: ProjectionSecurityContext;
+    costRuntime?: WorkbenchCostRuntime;
 }
 export declare function buildSnapshot(store: KingdomStore, options: SnapshotOptions): SnapshotView;
-export declare function buildTaskDetail(store: KingdomStore, kingdomId: string, taskId: string): TaskDetailView | null;
+export declare function buildTaskDetail(store: KingdomStore, kingdomId: string, taskId: string, options?: {
+    nowMs?: number;
+    security?: ProjectionSecurityContext;
+}): TaskDetailView | null;
 export {};

package/lib/types/gui/visual-assets.d.ts

@@ -0,0 +1,27 @@
+/** Decorative icons must be paired with visible text or an accessible control name. */
+export declare const GUI_ICONS: Readonly<{
+    map: string;
+    management: string;
+    ledger: string;
+    refresh: string;
+    chancellor: string;
+    supervisor: string;
+    worker: string;
+    plan: string;
+    assign: string;
+    next: string;
+    run: string;
+    review: string;
+    accept: string;
+    lock: string;
+    error: string;
+    idle: string;
+    unknown: string;
+    empty: string;
+}>;
+/** Original gate-and-organization brand mark; the adjacent wordmark supplies its name. */
+export declare const KINGDOM_BRAND_SVG = "<svg class=\"kingdom-brand-mark\" xmlns=\"http://www.w3.org/2000/svg\" width=\"48\" height=\"48\" viewBox=\"0 0 48 48\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\" focusable=\"false\">\n  <path d=\"M9 31V12h6v5h6v-5h6v5h6v-5h6v19H9Z\" />\n  <path d=\"M19 31v-7a5 5 0 0 1 10 0v7M24 31v5M12 36h24M12 36v3M36 36v3\" />\n  <circle cx=\"12\" cy=\"41\" r=\"2\" /><circle cx=\"24\" cy=\"38\" r=\"2\" /><circle cx=\"36\" cy=\"41\" r=\"2\" />\n</svg>";
+/** Original decorative empty state. It deliberately contains no role or binding claims. */
+export declare const EMPTY_STATE_SVG = "<svg class=\"empty-state-art\" xmlns=\"http://www.w3.org/2000/svg\" width=\"240\" height=\"128\" viewBox=\"0 0 240 128\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\" focusable=\"false\">\n  <path d=\"M84 67V27h12v9h16v-9h16v9h16v-9h12v40H84Z\" />\n  <path d=\"M109 67V53a11 11 0 0 1 22 0v14M76 67h88\" />\n  <path d=\"M120 74v10M62 84h116M62 84v12M120 84v12M178 84v12\" stroke-dasharray=\"4 5\" opacity=\".55\" />\n  <rect x=\"43\" y=\"96\" width=\"38\" height=\"20\" rx=\"6\" stroke-dasharray=\"4 5\" opacity=\".65\" />\n  <rect x=\"101\" y=\"96\" width=\"38\" height=\"20\" rx=\"6\" stroke-dasharray=\"4 5\" opacity=\".65\" />\n  <rect x=\"159\" y=\"96\" width=\"38\" height=\"20\" rx=\"6\" stroke-dasharray=\"4 5\" opacity=\".65\" />\n</svg>";
+/** Static governance guidance, never a projection of current task progress. */
+export declare const GOVERNANCE_FLOW_HTML: string;

package/lib/types/gui/visual-system.d.ts

@@ -0,0 +1,2 @@
+/** Final presentation layer; the existing console owns all state and behavior. */
+export declare const CONSOLE_DESIGN_CSS: string;

package/lib/types/gui/workbench-ui.d.ts

@@ -0,0 +1,5 @@
+/** Personal workbench presentation. No model calls or authority are created here. */
+export declare const WORKBENCH_CSS: string;
+export declare const WORKBENCH_HTML: string;
+/** Injected into the existing console closure; all Host text uses append/textContent. */
+export declare const WORKBENCH_SCRIPT: string;

package/lib/types/gui/workbench.d.ts

@@ -0,0 +1,33 @@
+import type { ActionAvailability, ExecutionView, PersonalWorkbenchData, RuntimeGovernanceView, SupervisorDecisionView, TaskView, WorkbenchUsageSummary, WorkbenchCostSummary, WorkbenchCollaborationView } from './contract.js';
+export declare const WORKBENCH_ITEM_LIMIT = 40;
+/** All inputs are public projections. This module has no Store, command or model access. */
+export interface PersonalWorkbenchInput {
+    kingdomPresent: boolean;
+    bindings: {
+        bindingId: string;
+        roleType: string;
+        roleName: string;
+        status: string;
+        sessionBound: boolean;
+    }[];
+    territories: {
+        territoryId: string;
+        name: string;
+        status: string;
+        supervisorBindingId: string | null;
+    }[];
+    tasks: {
+        task: Pick<TaskView, 'taskId' | 'territoryId' | 'title' | 'status' | 'assignedBindingId' | 'latestClaim' | 'latestExecution' | 'updatedAt'>;
+        actionAvailability: ActionAvailability[];
+        latestReview: SupervisorDecisionView | null;
+        claimExecutionMismatch: boolean;
+    }[];
+    executions: Pick<ExecutionView, 'executionId' | 'taskId' | 'workerBindingId' | 'state'>[];
+    governance: RuntimeGovernanceView;
+    cost?: WorkbenchCostSummary;
+    collaboration?: WorkbenchCollaborationView;
+}
+/** Sum only provider reports whose identity and numeric shape match this Dispatch. */
+export declare function buildWorkbenchUsage(input: Pick<PersonalWorkbenchInput, 'governance' | 'executions'>): WorkbenchUsageSummary;
+/** Derive current work; past DENIED and ordinary in-flight receipts are not current incidents. */
+export declare function buildPersonalWorkbench(input: PersonalWorkbenchInput): PersonalWorkbenchData;

package/lib/types/index.d.ts

@@ -13,9 +13,10 @@
  *   kingdom_list_bindings
  *
  * Phase 2 能力（Worker Claim Bridge → 治理闭环）：
- * - 工具：kingdom_plan_task / kingdom_assign_task / kingdom_start_task /
- *   kingdom_review_task / kingdom_list_tasks
- * - Worker 经 one-shot subagent 执行（裁决 2），结果落 worker_results（裁决 4）。
+ * - 工具：kingdom_plan_task / kingdom_assign_task /
+ *   kingdom_start_task_governed / kingdom_review_task / kingdom_list_tasks
+ * - `kingdom_start_task` 仅保留为显式选择的 LEGACY_COMPAT one-shot 兼容入口；
+ *   正常 headless 执行必须走 governed persistent 路径。
  *
  * 治理底线（Phase 1 保持 + Phase 2 强化）：
  * - **无任何工具能把 Task 直接标 DONE**：DONE 唯一入口是 REVIEW + Supervisor ACCEPT。
@@ -24,9 +25,15 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import { type ToolDisclosureConfig } from './capability/tool-disclosure.js';
+import { type AdminAuth, type ExecutionProfileV1 } from './core/binding.js';
+import type { KingdomStore, RoleBindingRow, TerritoryRow } from './core/db.js';
+import type { CommandResult } from '@deepseek-ai/dsh-commands';
+import { type TargetSessionClassification } from './core/owner-binding-intent.js';
 export declare const name = "dsh-kingdom";
 export declare const inject: string[];
 export interface Config {
+    toolDisclosure?: ToolDisclosureConfig;
     kingdomName: string;
     ownerName: string;
     workerProvider: string;
@@ -37,7 +44,102 @@ export interface Config {
     /** v0.8（M3-S2 v6）：允许对已有 v3 库执行 Schema v4 迁移（Formal DB Migration Gate 用）。 */
     migrateV4: boolean;
 }
+/**
+ * Process-local seams for deterministic integration verification. Normal
+ * Cordis/DSH loading uses the two-argument apply(ctx, config) path. These
+ * functions are not Config, HTTP, GUI payload, or persisted-state inputs.
+ */
+export interface ApplyDependencies {
+    governedPolling?: {
+        intervalMs: number;
+        maxPolls: number;
+    };
+    openLocalConsole?: (url: string) => boolean;
+    loadS4Policy?: () => Promise<{
+        sandboxPolicy: {
+            setSandboxMode(session: unknown, mode: string): void;
+        } | null;
+        approval: {
+            setApprovalPolicy(session: unknown, policy: string): void;
+        } | null;
+    }>;
+}
+/**
+ * The public DSH runtime seam used by the Owner-binding boundary.  Keep this
+ * local duck type instead of importing a concrete registry implementation: the
+ * plugin is loaded against a host-provided bundle, while the identity checks
+ * below intentionally depend only on the documented methods and object
+ * identity.
+ */
+export interface KingdomDshAgentLike {
+    readonly id?: unknown;
+    readonly session?: unknown;
+    readonly status?: unknown;
+}
+export interface KingdomDshAgentRegistryLike {
+    currentInitiator?: () => unknown;
+    get?: (id: string) => unknown;
+    list?: () => readonly unknown[];
+}
+export interface KingdomDshSessionRegistryLike {
+    get?: (id: string) => unknown;
+}
+export interface KingdomDshRegistrySeam {
+    agents?: KingdomDshAgentRegistryLike | null;
+    sessions?: KingdomDshSessionRegistryLike | null;
+}
+export interface KingdomToolExecutionLike {
+    readonly agent?: unknown;
+    readonly signal?: {
+        readonly aborted?: boolean;
+    } | null;
+}
+export type TrustedToolSessionResolution = {
+    readonly classification: 'ACTIVE';
+    readonly sessionId: string;
+    readonly agent: KingdomDshAgentLike;
+    readonly session: {
+        readonly id?: unknown;
+    };
+} | {
+    readonly classification: Exclude<TargetSessionClassification, 'ACTIVE'>;
+    readonly sessionId: string | null;
+    readonly reason: string;
+};
+export type LiveDirectSessionResolution = {
+    readonly ok: true;
+    readonly sessionId: string;
+    readonly agent: KingdomDshAgentLike;
+    readonly session: {
+        readonly id?: unknown;
+    };
+} | {
+    readonly ok: false;
+    readonly classification: Exclude<TargetSessionClassification, 'ACTIVE'>;
+    readonly reason: string;
+};
+/**
+ * Resolve the exact DSH Tool caller.  A non-empty session id is only a target
+ * reference; it becomes an ACTIVE Principal after every public identity/life
+ * check succeeds.  In particular, tool arguments are not accepted here.
+ */
+export declare function resolveTrustedToolSession(execution: KingdomToolExecutionLike | null | undefined, seam: KingdomDshRegistrySeam): TrustedToolSessionResolution;
+/** Validate a direct Owner Slash target without requiring current-initiator scope. */
+export declare function validateLiveDirectSession(sessionId: string, seam: KingdomDshRegistrySeam): LiveDirectSessionResolution;
 export declare const Config: z<Schemastery.ObjectS<{
+    toolDisclosure: z<Schemastery.ObjectS<{
+        mode: z<"off" | "pilot", "off" | "pilot">;
+        residentTools: z<string[], string[]>;
+        phaseTools: z<string[], string[]>;
+        maxResults: z<number, number>;
+        maxResultBytes: z<number, number>;
+    }>, Schemastery.ObjectT<{
+        mode: z<"off" | "pilot", "off" | "pilot">;
+        residentTools: z<string[], string[]>;
+        phaseTools: z<string[], string[]>;
+        maxResults: z<number, number>;
+        maxResultBytes: z<number, number>;
+    }>>;
     kingdomName: z<string, string>;
     ownerName: z<string, string>;
     /** Worker 执行用的 subagent provider（dsh base bundle 默认注册 spawn / fork）。 */
@@ -47,7 +149,7 @@ export declare const Config: z<Schemastery.ObjectS<{
      * 设为非零值即启用，只绑定 127.0.0.1。
      */
     guiPort: z<number, number>;
-    /** 可选 bearer token；设置后 GUI 所有请求都要带 Authorization 头。 */
+    /** Role GUI 可选 bearer；独立 Owner 路由使用其直接激活的短期凭据，不升级 Role 权限。 */
     guiToken: z<string, string>;
     /** CORS 允许的 Origin 列表；默认放开（服务只绑本机回环）。 */
     guiAllowOrigins: z<string[], string[]>;
@@ -65,6 +167,19 @@ export declare const Config: z<Schemastery.ObjectS<{
      */
     migrateV4: z<boolean, boolean>;
 }>, Schemastery.ObjectT<{
+    toolDisclosure: z<Schemastery.ObjectS<{
+        mode: z<"off" | "pilot", "off" | "pilot">;
+        residentTools: z<string[], string[]>;
+        phaseTools: z<string[], string[]>;
+        maxResults: z<number, number>;
+        maxResultBytes: z<number, number>;
+    }>, Schemastery.ObjectT<{
+        mode: z<"off" | "pilot", "off" | "pilot">;
+        residentTools: z<string[], string[]>;
+        phaseTools: z<string[], string[]>;
+        maxResults: z<number, number>;
+        maxResultBytes: z<number, number>;
+    }>>;
     kingdomName: z<string, string>;
     ownerName: z<string, string>;
     /** Worker 执行用的 subagent provider（dsh base bundle 默认注册 spawn / fork）。 */
@@ -74,7 +189,7 @@ export declare const Config: z<Schemastery.ObjectS<{
      * 设为非零值即启用，只绑定 127.0.0.1。
      */
     guiPort: z<number, number>;
-    /** 可选 bearer token；设置后 GUI 所有请求都要带 Authorization 头。 */
+    /** Role GUI 可选 bearer；独立 Owner 路由使用其直接激活的短期凭据，不升级 Role 权限。 */
     guiToken: z<string, string>;
     /** CORS 允许的 Origin 列表；默认放开（服务只绑本机回环）。 */
     guiAllowOrigins: z<string[], string[]>;
@@ -92,4 +207,40 @@ export declare const Config: z<Schemastery.ObjectS<{
      */
     migrateV4: z<boolean, boolean>;
 }>>;
-export declare function apply(ctx: Context, config: Config): void;
+/** Smallest capability fact used by the GUI thin slice's governed path. */
+export declare const MINIMAL_CAPABILITY_JSON = "{\"tool:pwsh\":true}";
+export { connectRunnerContextBroker, createRunnerContextBrokerLaunch, createRunnerContextBrokerProductLifecycle, } from './runner-context-broker.js';
+export type { RunnerContextBrokerClient, RunnerContextBrokerCleanupReceipt, RunnerContextBrokerConnectionBootstrap, RunnerContextBrokerConnectorInput, RunnerContextBrokerDescriptor, RunnerContextBrokerEnvironment, RunnerContextBrokerProductLifecycle, } from './runner-context-broker.js';
+/**
+ * Format the direct GUI activation result without accepting any launch secret
+ * as presentation data.  The ticket is handed only to the local URL opener;
+ * command/done persistence, logger output, and domain events receive this
+ * clean result instead.
+ */
+export declare function formatGuiLaunchCommandResult(origin: string, expiresAt: string, browserOpened: boolean): CommandResult;
+/** Reuse an ACTIVE same-name Territory without changing its topology. */
+export declare function ensureGuiSetupTerritory(store: KingdomStore, input: {
+    kingdomId: string;
+    name: string;
+    workspacePath?: string | null;
+}, auth: AdminAuth): TerritoryRow;
+/** Ensure setup role identity without ever binding a Worker to the activator. */
+export declare function ensureGuiSetupBinding(store: KingdomStore, input: {
+    kingdomId: string;
+    roleType: 'CHANCELLOR' | 'SUPERVISOR' | 'WORKER';
+    roleName: string;
+    sessionId: string | null;
+}, auth: AdminAuth): RoleBindingRow;
+/** Set the requested Worker profile only when its semantic value changes. */
+export declare function ensureGuiSetupExecutionProfile(store: KingdomStore, input: {
+    kingdomId: string;
+    bindingId: string;
+    profile: ExecutionProfileV1;
+}, auth: AdminAuth): string | null;
+/** Set Territory scope only when the target Supervisor binding changes. */
+export declare function ensureGuiSetupTerritorySupervisor(store: KingdomStore, input: {
+    kingdomId: string;
+    territoryId: string;
+    supervisorBindingId: string;
+}, auth: AdminAuth): string | null;
+export declare function apply(ctx: Context, config: Config, dependencies?: ApplyDependencies): void;