@sparkelf/dsh-dataops-managed 0.3.21 → 0.3.22

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

@@ -0,0 +1,80 @@
+/**
+ * Compact search over the DataOps OpenAPI document.
+ *
+ * The document can be tens of thousands of lines; a model needs the operation that answers its
+ * question, not the whole contract. This module reads `paths` and returns only the fields that
+ * identify and parametrize a matching operation: method, path, operationId, summary, tags,
+ * parameters, request-body shape and security. It never executes anything and never accepts a
+ * URL: the caller names the fixed `/api/openapi.json` document, and the search stays inside it.
+ *
+ * @module api-docs
+ */
+/** JSON-safe content a tool may return. */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** One compact parameter row. */
+export interface ApiDocParameter {
+    name: string;
+    in: string;
+    required: boolean;
+    type: string;
+}
+/** A compact request-body description. */
+export interface ApiDocRequestBody {
+    required: boolean;
+    contentTypes: string[];
+    schema: ApiDocSchemaSummary | null;
+}
+/** A compact schema projection: enough to see the fields a call needs. */
+export interface ApiDocSchemaSummary {
+    type?: string;
+    ref?: string;
+    required?: string[];
+    properties?: Array<{
+        name: string;
+        type: string;
+        required: boolean;
+    }>;
+}
+/** One operation as the tool returns it. */
+export interface ApiDocOperation {
+    method: string;
+    path: string;
+    operationId: string | null;
+    summary: string | null;
+    tags: string[];
+    parameters: ApiDocParameter[];
+    requestBody: ApiDocRequestBody | null;
+    security: Json[];
+}
+/** Everything the tool needs to report one search. */
+export interface ApiDocsSearchResult {
+    title: string | null;
+    version: string | null;
+    openapi: string | null;
+    total: number;
+    returned: number;
+    truncated: boolean;
+    results: ApiDocOperation[];
+}
+/** Filters accepted by {@link searchOpenApiDocument}. */
+export interface ApiDocsFilters {
+    query?: string;
+    tag?: string;
+    path?: string;
+    operation_id?: string;
+    method?: string;
+}
+/** Raised when the upstream body is not an OpenAPI document this module can search. */
+export declare class ApiDocsUnavailableError extends Error {
+}
+/**
+ * Search one parsed OpenAPI document.
+ * @param document - Parsed `/api/openapi.json` body.
+ * @param filters - Keyword, tag, path, operationId and method filters.
+ * @returns Matching operations, bounded and ordered by relevance.
+ * @throws ApiDocsUnavailableError when the document has no searchable `paths` object.
+ */
+export declare function searchOpenApiDocument(document: unknown, filters?: ApiDocsFilters): ApiDocsSearchResult;
+export {};

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

@@ -16,6 +16,19 @@
  */
 /** What the last DataOps answer said about the stored credential. */
 export type AuthState = 'unknown' | 'valid' | 'expired';
+/** One observer of the recorded credential observation. */
+export type AuthStateListener = (state: AuthState) => void;
+/**
+ * Observe every recorded transition.
+ *
+ * The tool manager uses this to drop its disclosure as soon as any DataOps call reports a 401:
+ * the scope that produced the tool list can no longer be trusted, and waiting for another
+ * explicit sync would leave tools offered against an ended session. Listener failures are
+ * contained so a broken observer cannot turn a credential observation into a failed call.
+ * @param listener - Called with the new state after it is recorded.
+ * @returns The exact unsubscriber.
+ */
+export declare const onAuthStateChange: (listener: AuthStateListener) => (() => void);
 /**
  * Record that a DataOps call was accepted.
  *

package/lib/types/client/ReloginPrompt.d.ts

@@ -7,11 +7,9 @@
  * signed in any more. This prompt names that state once, with the one action that clears it.
  *
  * It reports and nothing more. It does not retry, expire, or re-authenticate — the portal owns
- * the login form and is the only thing that can issue a session. It also cannot navigate the
- * operator there: the portal is a different origin, so this frame cannot read or drive its
- * window, and the gateway does not forward the browser's origin to the workspace. Guessing a
- * URL from inside here would open the wrong page on some deployments, so the dialog tells the
- * operator which window to switch to instead of pretending it can take them.
+ * the login form and is the only thing that can issue a session. Its action navigates the parent
+ * portal when the frame's ancestor origin is known, and opens the portal separately when the
+ * browser blocks top-level navigation from the frame.
  *
  * @module ReloginPrompt
  */

package/lib/types/client/locales.d.ts

@@ -1,9 +1,9 @@
 /** English managed DataOps Settings copy. */
 export declare const en: {
-    readonly nav: "DataOps";
-    readonly title: "DataOps";
-    readonly managed: "Connected to DataOps";
-    readonly unavailable: "DataOps is not connected.";
+    readonly nav: "万相AI中台";
+    readonly title: "万相AI中台";
+    readonly managed: "Connected to 万相AI中台";
+    readonly unavailable: "万相AI中台 is not connected.";
     readonly loadFailed: "Loading failed. Try again.";
     readonly brandingTitle: "Wanxiang branding";
     readonly brandingToggle: "Wanxiang branding";
@@ -13,7 +13,7 @@ export declare const en: {
     readonly limitsInvalid: "Enter a size in MiB.";
     readonly limitsSave: "Save";
     readonly limitsSaving: "Saving…";
-    readonly timeoutTitle: "DataOps query timeout";
+    readonly timeoutTitle: "万相AI中台 query timeout";
     readonly timeoutLabel: "Longest single query (seconds)";
     readonly timeoutInvalid: "Enter 1 to 3600 seconds.";
     readonly defaultsTitle: "Default configuration";
@@ -34,7 +34,7 @@ export declare const en: {
     readonly plazaUnshare: "Stop sharing";
     readonly plazaUnshared: "Removed from the plaza. Users who installed it keep their copy.";
     readonly plazaEmpty: "No skills have been shared yet.";
-    readonly plazaUnavailable: "The skill plaza is available once this workspace is connected to DataOps.";
+    readonly plazaUnavailable: "The skill plaza is available once this workspace is connected to 万相AI中台.";
     readonly plazaLoadFailed: "The skill plaza could not be loaded. Try again.";
     readonly plazaActionFailed: "The action could not be completed. Try again.";
     readonly plazaRetry: "Try again";
@@ -123,9 +123,9 @@ export declare const en: {
     readonly permStatusApproved: "Approved";
     readonly permStatusRejected: "Rejected";
     readonly permDemo: "Demo data";
-    readonly reloginTitle: "Sign in to DataOps again";
-    readonly reloginBody: "This workspace can no longer reach DataOps: the sign-in for this session has ended, so settings, shared models and the skill plaza cannot load. Sign in again in the DataOps window, then reload this page.";
-    readonly reloginAction: "Reload";
+    readonly reloginTitle: "Sign in to 万相AI中台 again";
+    readonly reloginBody: "Please sign in again.";
+    readonly reloginAction: "Sign in again";
     readonly reloginDismiss: "Later";
     readonly upgradeAvailableTitle: "A new workspace version is available";
     readonly upgradeAvailableBody: "Restart the workspace to apply it.";

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/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;

package/lib/types/tools.d.ts

@@ -1,10 +1,12 @@
 /**
- * Model tools for the skill centre and the shared review queues.
+ * Model tools for the skill centre, the shared review queues, and the DataOps API reference.
  *
- * Every tool reads the caller's DataOps role from `/api/ai/review/context` and asks DataOps on
- * every call; the Host never caches an authorization decision. Mutations require user approval
- * and write an audit line. Secret material is never a parameter and never a return value: the
- * API only sees the workspace JWT that the credential service already holds.
+ * Registration is disclosure, not authorization. `AiToolManager` computes the workspace's
+ * current DataOps scope once per credential/role sync and registers only the tools that scope
+ * can use; these definitions assume they were registered for a principal that may call them.
+ * Every `execute` therefore validates parameters, asks for user approval where a mutation needs
+ * it, writes its audit line, and lets DataOps answer — no per-call role read, no local permission
+ * tree, and no replacement for the backend's AuthGuard/PermissionGuard.
  *
  * The skill plaza is the catalogue. `scope=mine` exposes the caller's pending/rejected rows,
  * the public list exposes what the caller may install, and the admin list (administrators only)
@@ -16,6 +18,24 @@
  * @module tools
  */
 import type { Context } from '@deepseek-ai/cordis';
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
 import type { ReviewApi } from './review-api.ts';
-/** Register the skill-centre and review tools. */
-export declare function registerAiManagementTools(ctx: Context, reviewApi: ReviewApi): () => void;
+import { type AiToolName, type DataOpsScope } from './tool-scope.ts';
+/** One managed tool together with the name the disclosure map uses. */
+export interface AiManagedTool {
+    name: AiToolName;
+    definition: ToolDefinition;
+}
+/**
+ * Build every managed tool definition.
+ *
+ * The definitions are built once; `readScope` is a live getter so a tool that survives a role
+ * change reports the scope the manager currently holds instead of the one it was registered
+ * with. An undefined scope can only be observed by an in-flight call during disposal, where the
+ * safe behavior is to show only the public catalogue.
+ * @param ctx - Host context used for local skills, approval and audit.
+ * @param reviewApi - Same-origin bridge holding the workspace JWT.
+ * @param readScope - Live accessor for the manager's current scope.
+ * @returns One definition per managed tool name.
+ */
+export declare function buildAiManagementTools(ctx: Context, reviewApi: ReviewApi, readScope: () => DataOpsScope | undefined): AiManagedTool[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkelf/dsh-dataops-managed",
-  "version": "0.3.21",
+  "version": "0.3.22",
   "description": "DataOps JWT intake and credential-backed MCP tools for managed DeepSeek Harness workspaces.",
   "type": "module",
   "main": "./lib/index.js",