@sparkelf/dsh-dataops-managed 0.3.20 → 0.3.22

package/lib/types/tools.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Model tools for the skill centre, the shared review queues, and the DataOps API reference.
+ *
+ * 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)
+ * exposes disabled entries. Installation, sharing and deletion are deliberately three different
+ * actions: uninstall removes only the caller's installation, unshare unpublishes the shared entry
+ * (with an unpublished notification), and delete permanently removes the entry after a second
+ * confirmation, with its own deleted notification and audit trail.
+ *
+ * @module tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { ReviewApi } from './review-api.ts';
+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/lib/types/workspace-upgrade-state.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Persistent hand-off record for one workspace image upgrade.
+ *
+ * The DSH companion and the workspace container share the same named volume at
+ * `/workspace`; a JSON file there survives the container recreate that applies a new
+ * image. The record is deliberately small: only sessions that were running when the
+ * user confirmed the upgrade, so recovery cannot send "继续" to unrelated history.
+ *
+ * @module workspace-upgrade-state
+ */
+/** Format version of the persisted hand-off record. */
+export declare const WORKSPACE_UPGRADE_STATE_VERSION = 1;
+/** One DSH session that was running when the upgrade was confirmed. */
+export interface WorkspaceUpgradeSession {
+    /** DSH session id, the id `agents.get` and `agents.resume` accept. */
+    sessionId: string;
+    /** Optional human-readable title captured for diagnostics. */
+    title?: string;
+    /** Optional workspace directory captured for diagnostics. */
+    cwd?: string;
+}
+/** The JSON document written before the container is recreated. */
+export interface WorkspaceUpgradeState {
+    version: typeof WORKSPACE_UPGRADE_STATE_VERSION;
+    upgradeId: string;
+    targetImage: string;
+    sessions: WorkspaceUpgradeSession[];
+    createdAt: string;
+}
+/** Directory used by this plugin below the DSH home. */
+export declare const WORKSPACE_UPGRADE_STATE_DIR = "dataops-managed";
+/** Name of the hand-off file. */
+export declare const WORKSPACE_UPGRADE_STATE_FILE = "workspace-upgrade.json";
+/**
+ * Resolve the persistent DSH home used by this workspace.
+ *
+ * The companion currently starts with `DSH_HOME=/workspace/.dataops/dsh`; the fallback
+ * keeps tests and a manually launched host deterministic without reaching outside the
+ * mounted workspace.
+ * @param dshHome - override for tests.
+ * @returns the state directory path.
+ */
+export declare function workspaceUpgradeStatePath(dshHome?: string): string;
+/** Validate a parsed state document. */
+export declare function asWorkspaceUpgradeState(value: unknown): WorkspaceUpgradeState | null;
+/**
+ * Read the pending hand-off record.
+ * @param file - state file path.
+ * @returns the record, or null when none exists or it cannot be parsed.
+ */
+export declare function readWorkspaceUpgradeState(file?: string): Promise<WorkspaceUpgradeState | null>;
+/**
+ * Persist the hand-off record atomically.
+ *
+ * A partially written JSON file would be indistinguishable from "no upgrade pending",
+ * which would silently skip recovery. The temporary file is renamed into place only
+ * after the content is complete.
+ * @param state - record to persist.
+ * @param file - state file path.
+ */
+export declare function writeWorkspaceUpgradeState(state: WorkspaceUpgradeState, file?: string): Promise<void>;
+/**
+ * Remove the hand-off record after recovery has been attempted.
+ * @param file - state file path.
+ */
+export declare function clearWorkspaceUpgradeState(file?: string): Promise<void>;

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

@@ -0,0 +1,83 @@
+/**
+ * Workspace image upgrade orchestration.
+ *
+ * DataOps owns the Docker image comparison and the container restart. This plugin owns
+ * the two facts DSH alone can know: which sessions are running right now, and how to
+ * bring those sessions back after the container has been recreated. A small JSON file
+ * on the shared workspace volume carries that hand-off across the restart.
+ *
+ * @module workspace-upgrade
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type WorkspaceUpgradeSession, type WorkspaceUpgradeState } from './workspace-upgrade-state.ts';
+/** Configuration needed to talk to DataOps. */
+export interface WorkspaceUpgradeConfig {
+    /** DataOps API origin reachable from the DSH Host. */
+    baseUrl: string;
+    /** Credential reference holding the current DataOps JWT. */
+    credentialRef: string;
+}
+/** The subset of the DataOps restart-preview response this plugin uses. */
+export interface WorkspaceUpgradePreview {
+    imageStatus: 'CURRENT' | 'UPDATE_AVAILABLE' | 'NOT_RUNNING' | 'UNKNOWN';
+    configuredImage: string;
+    activeSessions: WorkspaceUpgradeSession[];
+}
+/** A refusal or transport failure from the DataOps API. */
+export declare class WorkspaceUpgradeError extends Error {
+    /** HTTP status, or 502 when DataOps could not be reached. */
+    readonly status: number;
+    constructor(
+    /** HTTP status, or 502 when DataOps could not be reached. */
+    status: number, message: string);
+}
+/** Owns DataOps preview/restart calls and the DSH session hand-off. */
+export declare class WorkspaceUpgrade {
+    private readonly ctx;
+    private readonly config;
+    readonly statePath: string;
+    constructor(ctx: Context, config: WorkspaceUpgradeConfig, statePath?: string);
+    /** Resolve the injected DSH agents service, if the profile provides one. */
+    private agents;
+    /** Read the current DataOps credential. */
+    private token;
+    /** DataOps origin used by this workspace. */
+    private apiBase;
+    /** Call one DataOps API path with the workspace JWT. */
+    private request;
+    /** Read the DataOps restart preview plus this host's running-session snapshot. */
+    preview(): Promise<WorkspaceUpgradePreview>;
+    /** Snapshot sessions that are executing a turn right now. */
+    private runningSessions;
+    /** Restart DataOps' workspace container; force is required when sessions are snapshot. */
+    private restart;
+    /**
+     * Persist the running-session snapshot and ask DataOps to recreate the container.
+     * @returns the accepted hand-off record.
+     */
+    upgrade(): Promise<WorkspaceUpgradeState>;
+    /**
+     * Resume every snapshotted session and send one "继续".
+     *
+     * The method deliberately does not wait for an answer: the user's workspace should
+     * become usable immediately, and an in-flight tool call cannot be replayed safely.
+     * `recoverWorkspaceUpgradeAfterBoot` removes the hand-off file after this attempt.
+     */
+    recover(): Promise<{
+        recovered: number;
+        skipped: number;
+    }>;
+    /** Remove the hand-off record once recovery has been attempted. */
+    clearRecoveryState(): Promise<void>;
+    /** Find a live session or resume it from persisted state. */
+    private ensureAgent;
+}
+/**
+ * Run recovery after the DSH host and its session persistence have had time to boot.
+ *
+ * `apply()` runs before a persisted session necessarily has its live agent; resuming
+ * eagerly can race that boot. A short bounded retry is enough, and a failed attempt
+ * still removes the hand-off file so the next page load cannot send "继续" forever.
+ * @param upgrade - upgrade service.
+ */
+export declare function recoverWorkspaceUpgradeAfterBoot(upgrade: WorkspaceUpgrade): Promise<void>;

package/package.json

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