@sparkelf/dsh-dataops-managed 0.3.20 → 0.3.22

package/lib/types/client/review-types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Shared vocabulary for the review, permission and notification surfaces.
+ *
+ * The backend contract is landing in parallel; every field that a legacy row cannot carry
+ * yet is optional here and normalized to the product default (approved/global) rather than
+ * guessed per component. Keeping the rules in one place is what lets the skill plaza, the
+ * permission centre and the notification bell agree on what "pending" means.
+ */
+/** Review state of a shared skill or workflow. */
+export type ReviewStatus = 'pending' | 'approved' | 'rejected';
+/** Who may see a shared resource outside its owner. */
+export type ResourceVisibility = 'global' | 'department' | 'private';
+/** The skill-plaza filter tabs, in display order. */
+export type ReviewTab = 'approved' | 'pending' | 'all';
+/** The four DataOps roles the permission centre knows. */
+export type PortalRole = 'SUPER_ADMIN' | 'ADMIN' | 'DEPT_ADMIN' | 'APP_USER';
+/** One node of a department ancestry path. */
+export interface DepartmentPathEntry {
+    code: string;
+    name: string;
+}
+/** A department as a card tag needs it: code, label, and the ancestry for the tooltip. */
+export interface DepartmentSummary {
+    code: string;
+    name: string;
+    /** Root-first path, in either the legacy string form or the backend object form. */
+    path?: readonly (string | DepartmentPathEntry)[];
+}
+/** One AI risk finding. */
+export interface RiskFinding {
+    category: string;
+    severity: 'low' | 'medium' | 'high';
+    evidence?: string;
+    recommendation?: string;
+}
+/** The AI report attached to a pending resource. */
+export interface RiskReport {
+    score?: number;
+    /** Overall severity, which is wider than a single finding's severity. */
+    severity?: 'low' | 'medium' | 'high' | 'critical';
+    summary?: string;
+    findings: readonly RiskFinding[];
+    scannedAt?: string;
+}
+/** The caller's review permissions, as the Host reports them. */
+export interface ReviewContext {
+    userId?: string;
+    role: PortalRole;
+    departmentCode?: string;
+    departmentPath?: readonly string[];
+    canReview: boolean;
+    canManagePermissions: boolean;
+}
+/** One notification row. */
+export interface ReviewNotification {
+    id: string;
+    type: string;
+    title: string;
+    body?: string;
+    resourceKind?: string;
+    resourceId?: string | number;
+    read: boolean;
+    createdAt: string;
+}
+/** A reviewable row as the cards read it. */
+export interface ReviewableSummary {
+    reviewStatus?: ReviewStatus;
+    visibility?: ResourceVisibility;
+    departmentCode?: string | null;
+    departmentName?: string;
+    departmentPath?: readonly (string | DepartmentPathEntry)[];
+    riskReport?: RiskReport | null;
+    reviewNote?: string | null;
+    submittedAt?: string;
+}
+/** Treat a missing status as approved: rows written before the review state existed were live. */
+export declare function normalizeReviewStatus(value: unknown): ReviewStatus;
+/** Treat a missing visibility as global: a shared row with no scope was visible to everyone. */
+export declare function normalizeVisibility(value: unknown): ResourceVisibility;
+/** Whether the caller may see and act on the review queue. */
+export declare function canReview(context: ReviewContext | null | undefined): boolean;
+/** Whether the caller may open the permission centre's write controls. */
+export declare function canManagePermissions(context: ReviewContext | null | undefined): boolean;
+/**
+ * The tabs this caller may see.
+ *
+ * A department administrator sees the queue too, but the Host narrows it to their subtree;
+ * an ordinary user gets only the approved list, and no tab strip at all when there is one tab.
+ */
+export declare function reviewTabsFor(context: ReviewContext | null | undefined): readonly ReviewTab[];
+/** Filter rows by the selected review tab. */
+export declare function filterByReview<T extends ReviewableSummary>(rows: readonly T[], tab: ReviewTab): readonly T[];
+/** Counts for the tab labels. */
+export declare function reviewCounts(rows: readonly ReviewableSummary[]): Record<ReviewTab, number>;
+/** The status badge shown on a local skill card. */
+export declare function reviewStatusLabel(status: ReviewStatus): string;
+/**
+ * The visibility tag in a card's top-right corner.
+ *
+ * A department tag names the department and keeps the full path in the tooltip; a global tag
+ * is one word because it is the default and should not compete with the skill name.
+ */
+/** Read a department path from either the legacy string form or the backend object form. */
+export declare function departmentPathNames(path: ReviewableSummary['departmentPath']): string[];
+export declare function visibilityTag(row: ReviewableSummary): {
+    label: string;
+    detail: string;
+};
+/** Unread count for a bell badge. */
+export declare function unreadCount(items: readonly ReviewNotification[]): number;
+/** Newest first. Read state never reorders rows, so marking one read cannot move it to another page. */
+export declare function sortNotifications(items: readonly ReviewNotification[]): readonly ReviewNotification[];
+/** The tab a notification should open, when its resource has one. */
+export declare function notificationTab(item: ReviewNotification): ReviewTab | undefined;

package/lib/types/client/settings-gate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Whether the managed DataOps settings section may be registered at all.
+ *
+ * Registration is the gate, not a CSS class: an ordinary user's profile should not contain a
+ * section whose controls they may not use. The identity record is presentation-only and arrives
+ * from the portal after the iframe loads, so the registration follows it instead of reading it
+ * once at startup. Authorization still lives in DataOps; this only keeps a forbidden panel out of
+ * the interface.
+ */
+/** Read the current role label without trusting any other field. */
+export declare function currentManagedSettingsRole(): string | null;
+/** Whether the current identity may see the managed DataOps settings section. */
+export declare function canSeeManagedSettings(): boolean;
+/**
+ * Observe identity changes.
+ *
+ * The account plugin keeps one store on `window`; subscribing to its listener set catches the
+ * in-page update even before the portal's DOM event. The event is kept as a second signal because
+ * a future portal may publish the event without touching the store this plugin reads.
+ */
+export declare function subscribeManagedSettingsVisibility(listener: () => void): () => void;

package/lib/types/client/skill-plaza-client.d.ts

@@ -1,4 +1,5 @@
 /** Same-origin skill plaza calls from the DataOps skill center section. */
+import type { ReviewStatus, ResourceVisibility } from './review-types.ts';
 /** Route the plugin's Host half serves for the plaza. */
 export declare const SKILL_PLAZA_PATH = "/integrations/dataops/skill-plaza";
 /** One plaza entry as the section reads it. */
@@ -10,11 +11,29 @@ export interface PlazaSkill {
     tags: string[];
     sharedByMe: boolean;
     updatedAt: string;
+    reviewStatus: ReviewStatus;
+    visibility: ResourceVisibility;
+    departmentCode?: string | null;
+    departmentName?: string;
+    departmentPath?: readonly {
+        code: string;
+        name: string;
+    }[];
+    ownerName?: string;
+    riskReport?: import('./review-types.ts').RiskReport | null;
+    reviewNote?: string | null;
+    submittedAt?: string;
 }
 /** The plaza listing and the tags in use. */
 export interface PlazaListing {
     skills: PlazaSkill[];
     tags: string[];
+    counts?: {
+        pending: number;
+        approved: number;
+        rejected: number;
+        total: number;
+    };
 }
 /**
  * Read the plaza.
@@ -24,6 +43,8 @@ export interface PlazaListing {
 export declare function fetchPlaza(filter?: {
     tag?: string;
     query?: string;
+    status?: string;
+    scope?: string;
 }): Promise<PlazaListing | null>;
 /**
  * Change the plaza.

package/lib/types/client/workspace-upgrade-client.d.ts

@@ -0,0 +1,29 @@
+/** Same-origin calls for the workspace image upgrade banner. */
+/** Route the plugin's Host half serves for upgrade detection and start. */
+export declare const WORKSPACE_UPGRADE_PATH = "/integrations/dataops/workspace-upgrade";
+/** A DSH session that will receive "继续" after the restart. */
+export interface WorkspaceUpgradeSession {
+    sessionId: string;
+    title?: string;
+    cwd?: string;
+}
+/** The status the DSH page reads before offering an upgrade. */
+export interface WorkspaceUpgradeStatus {
+    imageStatus: 'CURRENT' | 'UPDATE_AVAILABLE' | 'NOT_RUNNING' | 'UNKNOWN';
+    configuredImage: string;
+    activeSessions: WorkspaceUpgradeSession[];
+}
+/**
+ * Read the workspace upgrade preview.
+ * @returns the status, or null when the Host route is not ready or not connected.
+ */
+export declare function fetchWorkspaceUpgrade(): Promise<WorkspaceUpgradeStatus | null>;
+/**
+ * Ask the Host to snapshot sessions and recreate the workspace container.
+ * @returns the accepted hand-off summary.
+ */
+export declare function requestWorkspaceUpgrade(): Promise<{
+    accepted: boolean;
+    upgradeId: string;
+    sessions: number;
+}>;

package/lib/types/connector-state.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The DataOps connector's workspace-visible state and skill-center catalogue.
+ *
+ * The skill center is skill-first, with connectors as its fourth tab. DataOps contributes one
+ * connector whose capability rows are derived from the same scope that drives tool disclosure;
+ * a capability the account cannot use is omitted rather than rendered as a disabled placeholder.
+ *
+ * This module owns only state and presentation. It never authorizes a tool call or a DataOps
+ * request: the backend remains the final boundary.
+ *
+ * @module connector-state
+ */
+import { type DataOpsScope } from './tool-scope.ts';
+/** Same-origin route the skill center's connector tab reads and writes. */
+export declare const CONNECTORS_PATH = "/api/dsh-skill-center/connectors";
+/** Connector id shown in the skill center. */
+export declare const DATAOPS_CONNECTOR_ID = "dataops-managed";
+/** Persisted enable state; a missing file means the connector is off. */
+export interface DataOpsConnectorState {
+    enabled: boolean;
+    capabilities: Record<string, boolean>;
+}
+/** One capability row the skill center renders. */
+export interface ConnectorCapabilityView {
+    id: string;
+    name: string;
+    description: string;
+    enabled: boolean;
+    permitted: boolean;
+    unavailableReason?: string;
+}
+/** One connector row the skill center renders. */
+export interface ConnectorView {
+    id: string;
+    name: string;
+    vendor: string;
+    description: string;
+    enabled: boolean;
+    connected: boolean;
+    capabilities: ConnectorCapabilityView[];
+}
+/** Resolve the persisted state file without depending on a global DSH path. */
+export declare const CONNECTOR_STATE_PATH: string;
+/** Read state; a missing or corrupt file is a safe disabled state. */
+export declare function readConnectorState(path?: string): Promise<DataOpsConnectorState>;
+/** Persist state atomically. */
+export declare function writeConnectorState(state: DataOpsConnectorState, path?: string): Promise<void>;
+/** Build the connector row for one current scope. */
+export declare function buildConnectorView(scope: DataOpsScope | undefined, state: DataOpsConnectorState): ConnectorView;
+/** Whether one capability id is in the fixed catalogue. */
+export declare function hasCapability(id: string): boolean;

package/lib/types/index.d.ts

@@ -1,5 +1,7 @@
 /** DataOps-managed JWT intake and credential-backed MCP composition. */
+import type { IncomingMessage } from 'node:http';
 import type { Context } from '@deepseek-ai/cordis';
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
 import z from '@deepseek-ai/schemastery';
 import { ModelSync } from './model-sync.ts';
 import { SettingsSync, type SectionSyncState } from './settings-sync.ts';
@@ -16,10 +18,26 @@ export declare const MANAGED_PLUGIN_ID = "dataops-managed";
 export declare const MODEL_SYNC_PATH = "/integrations/dataops/model-sync";
 /** Same-origin route the skill center uses to read and change plaza sharing. */
 export declare const SKILL_PLAZA_PATH = "/integrations/dataops/skill-plaza";
+/** Caller role and review capability. */
+export declare const REVIEW_CONTEXT_PATH = "/integrations/dataops/review-context";
+/** Notification inbox and read receipts. */
+export declare const REVIEW_NOTIFICATIONS_PATH = "/integrations/dataops/review-notifications";
+/** AI scan and the administrator's decision. */
+export declare const REVIEW_ACTION_PATH = "/integrations/dataops/review";
+/** Permission-centre reads and writes. */
+export declare const RBAC_PATH = "/integrations/dataops/rbac";
+/** The three plaza-review switches. */
+export declare const REVIEW_SETTINGS_PATH = "/integrations/dataops/review-settings";
+/** Department CRUD bridge (task-67). */
+export declare const DEPARTMENTS_PATH = "/integrations/dataops/departments";
 /** Same-origin route the Settings panel uses to read and change this workspace's limits. */
 export declare const WORKSPACE_LIMITS_PATH = "/integrations/dataops/workspace-limits";
 /** Same-origin route the Settings panel uses to read and change the tool-call timeout. */
 export declare const TOOL_TIMEOUT_PATH = "/integrations/dataops/tool-timeout";
+/** Same-origin route reporting what the last DataOps answer said about the credential. */
+export declare const AUTH_STATE_PATH = "/integrations/dataops/auth-state";
+/** Same-origin route the DSH page uses to detect and start a workspace image upgrade. */
+export declare const WORKSPACE_UPGRADE_PATH = "/integrations/dataops/workspace-upgrade";
 /** The ends a tool-call timeout may take, in whole seconds. */
 export declare const TOOL_TIMEOUT_MIN_SECONDS = 1;
 export declare const TOOL_TIMEOUT_MAX_SECONDS = 3600;
@@ -103,6 +121,24 @@ export interface ModelSyncState {
 export declare const DEFAULT_TOOL_CALL_TIMEOUT_MS = 300000;
 /** Schemastery parser for managed DataOps configuration. */
 export declare const Config: z<Config>;
+/**
+ * Adopt the JWT the browser gateway attached to one request.
+ *
+ * Every browser request reaches this workspace through the DataOps gateway, which resolves the
+ * caller's session and forwards a fresh `authorization: Bearer <jwt>` — so the current credential
+ * arrives continuously, without any push, handshake or refresh protocol. The routes below are
+ * the only place this plugin can see that header, and reading it here is what keeps the stored
+ * credential from going stale: the value in it was captured once, while the caller's session is
+ * renewed by DataOps for as long as they stay signed in.
+ *
+ * A request without the header is normal rather than an error (same-origin fetches from inside
+ * the workspace do carry it, but a probe or a health check may not), so this only ever improves
+ * the stored value and never rejects the request.
+ *
+ * @param request - the incoming request, whose headers the gateway filled in.
+ * @returns once the credential has been updated, or immediately when there is nothing to adopt.
+ */
+export declare function adoptRequestJwt(ctx: Context, accessRef: ReturnType<typeof credentialRef>, request: IncomingMessage): Promise<void>;
 /**
  * Accept the current DataOps JWT and expose DataOps MCP tools through its credential.
  * @param ctx - DSH Host context with credentials, Web routes, and tools.

package/lib/types/review-api.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The DataOps review, notification, permission and settings API.
+ *
+ * One transport for the four new surfaces keeps the JWT handling, 401 observation and error
+ * mapping identical; the browser routes only translate same-origin actions into these calls.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Configuration shared with the skill plaza: where DataOps is and which credential holds its JWT. */
+export interface ReviewApiConfig {
+    baseUrl: string;
+    credentialRef: string;
+}
+/** One upstream answer, status included so a 404/503 can reach the browser unchanged. */
+export interface ReviewApiResult {
+    status: number;
+    body: unknown;
+}
+/** Cookie-free same-origin bridge to the review endpoints. */
+export declare class ReviewApi {
+    private readonly ctx;
+    private readonly config;
+    constructor(ctx: Context, config: ReviewApiConfig);
+    private apiBase;
+    private token;
+    /**
+     * Call one DataOps endpoint with the workspace JWT.
+     * @param path - API path below the DataOps origin.
+     * @param init - Method, body and extra headers.
+     * @returns The upstream status and parsed body; 503 when this workspace has no session.
+     */
+    request(path: string, init?: RequestInit): Promise<ReviewApiResult>;
+}

package/lib/types/skill-plaza.d.ts

@@ -11,6 +11,18 @@ export interface PlazaSkill {
     /** Whether the current user shared this entry. */
     sharedByMe: boolean;
     updatedAt: string;
+    reviewStatus: 'pending' | 'approved' | 'rejected';
+    visibility: 'global' | 'department' | 'private';
+    departmentCode?: string | null;
+    departmentName?: string;
+    departmentPath?: {
+        code: string;
+        name: string;
+    }[];
+    ownerName?: string;
+    riskReport?: unknown;
+    reviewNote?: string | null;
+    submittedAt?: string;
 }
 /** A skill the local workspace holds, offered by name for sharing. */
 export interface LocalSkillCandidate {
@@ -74,7 +86,26 @@ export declare class SkillPlaza {
     list(options?: {
         tag?: string;
         query?: string;
+        status?: string;
+        scope?: string;
+        departmentCode?: string;
     }): Promise<PlazaSkill[]>;
+    /** List with the server's tab counts, which the plaza shows without re-counting a page. */
+    listPage(options?: {
+        tag?: string;
+        query?: string;
+        status?: string;
+        scope?: string;
+        departmentCode?: string;
+    }): Promise<{
+        skills: PlazaSkill[];
+        counts?: {
+            pending: number;
+            approved: number;
+            rejected: number;
+            total: number;
+        };
+    }>;
     /**
      * Every tag in use, so the browser offers existing labels.
      * @returns Distinct tags.

package/lib/types/tool-manager.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Owns the managed tool set for the workspace's current DataOps principal.
+ *
+ * A DSH workspace belongs to exactly one DataOps user, so the model's tool list can be derived
+ * from that user's current scope. The manager is the only writer of that list: it reads
+ * `/api/ai/review/context` when the credential changes (the `credentials/reference-updated`
+ * event, which is also what JWT adoption and `managed-auth` produce), on the first connect, and
+ * when the review-context route observes a different role set. It then reconciles the registry:
+ * newly allowed tools are registered, tools the role lost are disposed, and tools that remain
+ * allowed keep their registration.
+ *
+ * The manager never runs inside a tool call. Execution-time authorization belongs to DataOps;
+ * this is disclosure, so a scope sync that fails transiently keeps the current set rather than
+ * flapping, while a definitive 401/403/404/503 clears it.
+ *
+ * @module tool-manager
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ReviewApi, ReviewApiResult } from './review-api.ts';
+import { type AiToolName, type DataOpsScope } from './tool-scope.ts';
+/**
+ * Reconcile the managed tools with the current DataOps scope.
+ *
+ * Construct once per plugin activation. `refresh` is idempotent and coalesces concurrent calls;
+ * the constructor also subscribes to the credential observation so an expired session removes
+ * the tools without waiting for another explicit sync.
+ */
+export declare class AiToolManager {
+    private readonly ctx;
+    private readonly reviewApi;
+    private readonly definitions;
+    private readonly registrations;
+    private readonly unsubscribeExpiry;
+    private disposeViewer;
+    private scope;
+    private revision;
+    private inflight;
+    private disposed;
+    constructor(ctx: Context, reviewApi: ReviewApi);
+    /** The scope the current registration set was derived from, when one has been read. */
+    currentScope(): DataOpsScope | undefined;
+    /** The tool names currently registered, for diagnostics and tests. */
+    registeredToolNames(): AiToolName[];
+    /**
+     * Re-read the workspace's DataOps scope and reconcile the tool list.
+     *
+     * Definitive denials clear the list; transient failures (network, 5xx) keep what the last good
+     * observation produced. The method never throws: sync happens in the background of a browser
+     * request and must not fail that request.
+     * @param force - Start a new read even when one is already in flight. Credential adoption uses
+     *   this because an older read may have captured the previous token; its answer must not win
+     *   over the scope the new token produces.
+     */
+    refresh(force?: boolean): Promise<void>;
+    /**
+     * Apply a context answer already fetched by a same-origin route.
+     *
+     * The review-context route is how the UI learns about a role change, so its answer is also the
+     * freshest scope this plugin will see. Reusing it avoids a second fetch on a page that polls.
+     * @param result - The upstream status and parsed body.
+     */
+    observeContext(result: ReviewApiResult): void;
+    /**
+     * Apply one parsed context body without contacting DataOps.
+     * @param body - Parsed `/api/ai/review/context` body.
+     */
+    applyContext(body: unknown): void;
+    /** Drop every managed tool because no usable DataOps scope is known. */
+    clear(): void;
+    /** Dispose every tool this manager registered and stop observing auth state. */
+    dispose(): void;
+    private loadScope;
+    /** Store the scope and make the registry match it. */
+    private applyScope;
+    /** Map one DataOps scope to the skill registry's audience filter. */
+    private applyViewer;
+    /** Dispose one registration, tolerating a disposer that has already run. */
+    private disposeRegistration;
+    /** Dispose the whole current set. */
+    private disposeRegistrations;
+}

package/lib/types/tool-output.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The canonical output contract shared by this plugin's model tools.
+ *
+ * Every managed tool returns one JSON value and renders it as pretty-printed text. Keeping the
+ * schema and renderer in one place means a new tool cannot accidentally return a shape the tool
+ * registry rejects.
+ *
+ * @module tool-output
+ */
+/** JSON-safe content a tool may return. */
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** One text block as the tool registry accepts it. */
+export type ToolContent = {
+    type: 'text';
+    text: string;
+};
+/** An open object schema: tools declare their canonical shape in code and docs. */
+export declare const OPEN_OBJECT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: true;
+};
+/** Render one canonical value as pretty JSON text. */
+export declare const renderJson: (_args: unknown, value: unknown) => ToolContent[];

package/lib/types/tool-scope.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Which DataOps tools this workspace's model may see.
+ *
+ * This module is disclosure, not authorization. DataOps remains the only authority for every
+ * API call: its AuthGuard and PermissionGuard resolve the caller's current roles and grants,
+ * and every managed tool call still crosses that boundary. What happens here is narrower — a
+ * DSH workspace belongs to one DataOps principal, so the tool schemas offered to the model can
+ * follow that principal's current scope instead of advertising operations the role cannot use.
+ *
+ * The scope is the answer `/api/ai/review/context` gives for the stored JWT. It is read when the
+ * credential changes, on the first connect, and when the review-context route observes a new
+ * role set — never inside a tool `execute`. A tool that is already registered and whose role
+ * loses the capability is disposed by the manager.
+ *
+ * @module tool-scope
+ */
+/** The subset of `/api/ai/review/context` that tool disclosure needs. */
+export interface DataOpsScope {
+    /** Stable DataOps user id. */
+    userId?: string;
+    /** Login name, used only for diagnostics. */
+    username?: string;
+    /** Role display codes such as 超级管理员/管理员/部门管理员/应用人员. */
+    roleCodes?: string[];
+    /** The primary role code; DataOps normalizes it to one of the four portal roles. */
+    primaryRole?: string;
+    /** Stable role keys such as SUPER_ADMIN, when the context carries them. */
+    systemKeys?: string[];
+    /** The caller's department, when one is assigned. */
+    departmentCode?: string | null;
+    /**
+     * Effective permission keys from every role the caller holds.
+     *
+     * `permissions` is the current backend field; `permissionKeys` is accepted while a deployment
+     * still serves the older shape. A present but empty array is a denial, not a reason to fall
+     * back to role names.
+     */
+    permissions?: string[];
+    /** Older spelling of {@link permissions}. */
+    permissionKeys?: string[];
+    /** Data scope DataOps resolved for the caller. */
+    dataScope?: {
+        all?: boolean;
+        self?: boolean;
+        departmentCodes?: string[];
+    };
+    /** Review capability as the current context reports it (older nested shape). */
+    review?: {
+        canReview?: boolean;
+        canReviewGlobal?: boolean;
+        canManagePermissions?: boolean;
+    };
+    /** Review capability as the current context reports it (top-level shape). */
+    canReview?: boolean;
+    /** Whether the caller may review global (department-less) resources. */
+    canReviewGlobal?: boolean;
+}
+/** The permission each managed tool needs before it is offered to the model. */
+export interface ToolAccessPolicy {
+    /** One `skill:*` capability; checked against the context's effective permission list. */
+    readonly permission?: string;
+    /** Review capability from the context, independent of a permission key. */
+    readonly reviewer?: boolean;
+    /** Only the DataOps 超级管理员 role sees this tool. */
+    readonly superAdminOnly?: boolean;
+}
+/**
+ * Tool-to-capability disclosure map.
+ *
+ * `review_notifications_list/read` intentionally carry no policy: every authenticated principal
+ * owns their own notification inbox. `dataops_api_docs` is gated by the role itself because the
+ * backend grants the OpenAPI reader to 超级管理员 by default; an administrator who happens to hold
+ * `developer:openapi:read` is still outside that role and does not receive the tool.
+ */
+export declare const AI_TOOL_ACCESS: {
+    readonly skill_list: {
+        readonly permission: "skill:read";
+    };
+    readonly skill_get: {
+        readonly permission: "skill:read";
+    };
+    readonly skill_submit: {
+        readonly permission: "skill:submit";
+    };
+    readonly skill_install: {
+        readonly permission: "skill:install";
+    };
+    readonly skill_uninstall: {
+        readonly permission: "skill:install";
+    };
+    readonly skill_enable: {
+        readonly permission: "skill:manage";
+    };
+    readonly skill_disable: {
+        readonly permission: "skill:manage";
+    };
+    readonly skill_unshare: {
+        readonly permission: "skill:manage";
+    };
+    readonly skill_delete: {
+        readonly permission: "skill:manage";
+    };
+    readonly review_scan: {
+        readonly permission: "skill:read";
+        readonly reviewer: true;
+    };
+    readonly review_decide: {
+        readonly permission: "skill:review:decide";
+        readonly reviewer: true;
+    };
+    readonly review_notifications_list: {};
+    readonly review_notifications_read: {};
+    readonly dataops_api_docs: {
+        readonly superAdminOnly: true;
+    };
+};
+/** Every managed tool name, in the order the manager considers them. */
+export declare const AI_TOOL_NAMES: AiToolName[];
+/** One managed tool name. */
+export type AiToolName = keyof typeof AI_TOOL_ACCESS;
+/** Whether the context carries the stable super-administrator role. */
+export declare const isSuperAdmin: (scope: DataOpsScope) => boolean;
+/** Whether the context carries an administrator or super-administrator role. */
+export declare const isAdmin: (scope: DataOpsScope) => boolean;
+/** Whether the context carries a department-administrator role. */
+export declare const isDepartmentAdmin: (scope: DataOpsScope) => boolean;
+/**
+ * Whether the caller may run review operations.
+ *
+ * The current backend returns `canReview` at the top level; the nested `review` shape is
+ * accepted for older contexts. Role membership is a fallback, not an override.
+ */
+export declare const canReview: (scope: DataOpsScope) => boolean;
+/**
+ * Whether the caller holds one capability.
+ *
+ * A context that carries a permission list is authoritative. Before the list existed, the
+ * four-role fallback kept the old behavior; it is only used when neither spelling is present.
+ */
+export declare const hasPermission: (scope: DataOpsScope, key: string) => boolean;
+/**
+ * Whether one tool should be registered for this scope.
+ *
+ * Every check is disclosure metadata, not an execution gate: a visible tool still lets DataOps
+ * answer with 403 when the underlying grant changed between a scope sync and the call.
+ */
+export declare function isToolVisible(name: AiToolName, scope: DataOpsScope): boolean;
+/**
+ * Validate one `/api/ai/review/context` body.
+ *
+ * A body without `roleCodes` is not a usable scope: treating it as "no roles" would let the
+ * role-name fallback hand an ordinary capability set to an answer this plugin cannot interpret.
+ * @param body - Parsed JSON from the context endpoint.
+ * @returns The normalized scope, or undefined when the answer is not a context document.
+ */
+export declare function normalizeScope(body: unknown): DataOpsScope | undefined;