@tiphareth/dsh-hardssh 0.1.2 → 0.2.3

package/src/tools.ts

@@ -1,221 +1,217 @@
-/**
- * Agent tools: the remote-workspace counterpart of the local fs tools. Every
- * tool is bound to the SSH workspace OF THE CALLING SESSION: the tool's
- * `exec` carries `agent.session.header.cwd` (the session's workspace), which
- * the ledger resolves to a bound SSH workspace (alias + remote root). A
- * session in a local workspace gets a clear "this workspace is not SSH-bound"
- * error; sessions in SSH-bound workspaces operate on the remote host.
- *
- * Plain file operations (read / write / edit / mkdir / rm / rename) are NOT
- * duplicated here: the fs seam routes them automatically by the session cwd
- * (SFTP on the remote host). This surface keeps only the tools the seam does
- * not cover: status (self-description), directory listing, and search.
- *
- * @module dsh-hardssh/tools
- */
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import type { ToolRunContext } from '@deepseek-ai/dsh-tools'
-import type { SshEngine } from './ssh/engine.ts'
-import { isInside } from './backend.ts'
-import { RemoteSearchService } from './remote-search.ts'
-import type { SshWorkspaceLedger } from './ledger.ts'
-import type { SshWorkspaceRecord } from './protocol.ts'
-
-/** One text content block (the only render shape these tools emit). */
-function text(value: string): ContentBlock[] {
-  return [{ type: 'text', text: value }]
-}
-
-/** Tool-set dependencies. */
-export interface WorkspaceToolsDeps {
-  engine: SshEngine
-  ledger: SshWorkspaceLedger
-  search: RemoteSearchService
-}
-
-/** Failure envelope shared by every tool. */
-interface ToolFailure {
-  ok: false
-  error: string
-}
-
-/** The SSH bound workspace for the calling session's cwd. */
-function boundWorkspace(ledger: SshWorkspaceLedger, exec: ToolRunContext): Promise<SshWorkspaceRecord | undefined> {
-  const cwd = exec.agent?.session?.header?.cwd
-  if (cwd === undefined || cwd === '') return Promise.resolve(undefined)
-  return ledger.findByAnchor(cwd)
-}
-
-/** True when `abs` is inside (or equals) the remote root. */
-function insideRoot(root: string, abs: string): boolean {
-  return isInside(root, abs)
-}
-
-/** Build every remote_* tool (registered by the host half). */
-export function makeWorkspaceTools(deps: WorkspaceToolsDeps) {
-  const { engine, ledger, search } = deps
-
-  /** The bound workspace for this call, or a failure when the session's
-   *  workspace is not SSH-bound. */
-  const bound = async (exec: ToolRunContext): Promise<{ workspace: SshWorkspaceRecord } | ToolFailure> => {
-    const workspace = await boundWorkspace(ledger, exec)
-    if (workspace === undefined) {
-      return { ok: false, error: 'this session\'s workspace is not SSH-bound — create an SSH workspace and open a session in it first' }
-    }
-    return { workspace }
-  }
-
-  /** Gate one absolute remote path to the workspace's remote root. */
-  const gatePath = (workspace: SshWorkspaceRecord, abs: string): string | undefined => {
-    if (!insideRoot(workspace.remoteRoot, abs)) {
-      return `path '${abs}' is outside the remote root '${workspace.remoteRoot}' of workspace '${workspace.title}'`
-    }
-    return undefined
-  }
-
-  /** Run one remote op, catching errors into the failure envelope. */
-  const run = async <T>(operation: () => Promise<T>): Promise<T | ToolFailure> => {
-    try {
-      return await operation()
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error)
-      return { ok: false, error: message }
-    }
-  }
-
-  return [
-    defineTool({
-      name: 'remote_status',
-      description: 'List the SSH-bound workspaces and report whether the CALLING SESSION\'s workspace is SSH-bound (and to which host/root). Call this before any remote_* tool. Triggers: SSH mode, remote workspace, where am I working, which servers are bound.',
-      parameters: {},
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: false,
-          properties: {
-            ok: { type: 'boolean', required: true },
-            bound: { type: 'boolean', required: true },
-            workspaceTitle: { type: 'string' },
-            alias: { type: 'string' },
-            remoteRoot: { type: 'string' },
-            anchorPath: { type: 'string' },
-            workspaces: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
-              id: { type: 'string', required: true }, title: { type: 'string', required: true }, alias: { type: 'string', required: true }, remoteRoot: { type: 'string', required: true }, anchorPath: { type: 'string', required: true },
-            } } },
-            error: { type: 'string' },
-          },
-        },
-        render: (_args, value) => {
-          if (value.ok !== true) return text(`remote_status failed: ${value.error ?? 'unknown error'}`)
-          const list = (value.workspaces ?? []).map((w: { title: string; alias: string; remoteRoot: string; anchorPath: string }) =>
-            `- ${w.title}  (${w.alias} @ ${w.remoteRoot}, anchor ${w.anchorPath})`)
-          const bound = value.bound === true
-            ? `current session: BOUND -> ${value.workspaceTitle ?? ''} (${value.alias ?? ''} @ ${value.remoteRoot ?? ''})`
-            : 'current session: NOT bound (this workspace is local)'
-          return text([bound, '', 'SSH workspaces:', ...(list.length > 0 ? list : ['(none)'])].join('\n'))
-        },
-      },
-      async execute(_args, exec) {
-        const workspaces = await ledger.list()
-        const workspace = await boundWorkspace(ledger, exec)
-        return {
-          ok: true,
-          bound: workspace !== undefined,
-          workspaceTitle: workspace?.title,
-          alias: workspace?.alias,
-          remoteRoot: workspace?.remoteRoot,
-          anchorPath: workspace?.anchorPath,
-          workspaces: workspaces.map((w) => ({ id: w.id, title: w.title, alias: w.alias, remoteRoot: w.remoteRoot, anchorPath: w.anchorPath })),
-        }
-      },
-    }),
-
-    defineTool({
-      name: 'remote_ls',
-      description: 'List a directory on the SSH host bound to the CALLING SESSION\'s workspace (the path must be inside that workspace\'s remote root). Triggers: list remote directory, remote files, ls on the server.',
-      parameters: {
-        path: { type: 'string', required: true, description: 'Absolute remote directory path inside the workspace\'s remote root (e.g. /home/user/project/src).' },
-      },
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: false,
-          properties: {
-            ok: { type: 'boolean', required: true },
-            path: { type: 'string' },
-            entries: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
-              name: { type: 'string', required: true }, type: { type: 'string', required: true }, size: { type: 'integer', required: true }, mtimeMs: { type: 'integer', required: true },
-            } } },
-            error: { type: 'string' },
-          },
-        },
-        render: (_args, value) => {
-          if (value.ok !== true) return text(`remote_ls failed: ${value.error ?? 'unknown error'}`)
-          const rows = (value.entries ?? []).map((entry: { name: string; type: string; size: number }) =>
-            `${entry.type === 'dir' ? 'dir ' : 'file'} ${entry.name}${entry.type === 'file' ? ` (${entry.size} bytes)` : ''}`)
-          return text([`${value.path}`, ...(rows.length > 0 ? rows : ['(empty)'])].join('\n'))
-        },
-      },
-      async execute(args, exec) {
-        const check = await bound(exec)
-        if ('error' in check) return check
-        const gate = gatePath(check.workspace, args.path)
-        if (gate !== undefined) return { ok: false, error: gate }
-        return run(async () => {
-          const entries = await engine.ls(check.workspace.alias, args.path)
-          return { ok: true, path: args.path, entries: entries.map((entry) => ({ name: entry.name, type: entry.type, size: entry.size, mtimeMs: entry.mtimeMs })) }
-        })
-      },
-    }),
-
-    defineTool({
-      name: 'remote_search',
-      description: 'Search the SSH workspace bound to the CALLING SESSION. mode="glob" matches FILE NAMES by pattern (root-relative, e.g. src/**/*.ts or *.log; max depth 6, capped at 200 hits); mode="grep" searches file CONTENTS for a FIXED STRING (not a regex; skips .git and node_modules; capped at 200 matches per file and 200KB of output). Triggers: find remote files by pattern, glob on the server, grep remote code, search remote contents.',
-      parameters: {
-        mode: { type: 'string', enum: ['glob', 'grep'], required: true, description: 'glob = match file names by pattern; grep = search file contents for a fixed string.' },
-        pattern: { type: 'string', required: true, description: 'glob: root-relative pattern like src/**/*.ts or *.log; grep: the literal text to find (not a regular expression).' },
-      },
-      output: {
-        schema: {
-          type: 'object',
-          additionalProperties: false,
-          properties: {
-            ok: { type: 'boolean', required: true },
-            mode: { type: 'string' },
-            hits: { type: 'array', items: { type: 'string' } },
-            lines: { type: 'array', items: { type: 'string' } },
-            truncated: { type: 'boolean' },
-            error: { type: 'string' },
-          },
-        },
-        render: (_args, value) => {
-          if (value.ok !== true) return text(`remote_search failed: ${value.error ?? 'unknown error'}`)
-          const tail = value.truncated === true
-            ? value.mode === 'grep' ? '\n[output truncated at 200KB]' : '\n[truncated at 200 hits]'
-            : ''
-          const body = value.mode === 'grep' ? (value.lines ?? []) : (value.hits ?? [])
-          return text(body.length > 0 ? body.join('\n') + tail : '(no matches)')
-        },
-      },
-      async execute(args, exec) {
-        const check = await bound(exec)
-        if ('error' in check) return check
-        return run(async () => {
-          if (args.mode === 'grep') {
-            const found = await search.grepFixed(
-              { alias: check.workspace.alias, root: check.workspace.remoteRoot },
-              args.pattern,
-            )
-            return { ok: true, mode: 'grep', lines: found.lines, hits: [], truncated: found.truncated }
-          }
-          const found = await search.glob(
-            { alias: check.workspace.alias, root: check.workspace.remoteRoot },
-            args.pattern,
-          )
-          return { ok: true, mode: 'glob', hits: found.hits, lines: [], truncated: found.truncated }
-        })
-      },
-    }),
-  ]
-}
+/**
+ * Agent tools: the remote-workspace counterpart of the local fs tools. Every
+ * tool is bound to the SSH workspace OF THE CALLING SESSION: the tool's
+ * `exec` carries `agent.session.header.cwd` (the session's workspace), which
+ * the SSH-workspace record source resolves to a bound SSH workspace (alias +
+ * remote root). A session in a local workspace gets a clear "this workspace is
+ * not SSH-bound" error; sessions in SSH-bound workspaces operate on the remote
+ * host.
+ *
+ * Plain file operations (read / write / edit / mkdir / rm / rename) are NOT
+ * duplicated here: the fs seam routes them automatically by the session cwd
+ * (SFTP on the remote host). This surface keeps only the tools the seam does
+ * not cover: status (self-description), directory listing, and search.
+ *
+ * The bound-workspace operations (listing / glob / grep) come from the
+ * `ops` resolver supplied at mount: it opens the logical connection via
+ * `WorkspaceCore` and uses its `workspace.fs` / `workspace.search`
+ * capabilities (provider-neutral). The tools never branch on `provider.id`.
+ *
+ * @module dsh-hardssh/tools
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools'
+import { isInside, type WorkspaceStoreView } from './backend.ts'
+import type { SshWorkspaceRecord } from './protocol.ts'
+import type { ToolOpsResolver } from './workspace-tool-ops.ts'
+
+/** One text content block (the only render shape these tools emit). */
+function text(value: string): ContentBlock[] {
+  return [{ type: 'text', text: value }]
+}
+
+/** Tool-set dependencies. */
+export interface WorkspaceToolsDeps {
+  /** SSH-workspace record source (the generic projection store). */
+  workspaces: WorkspaceStoreView
+  /** Bound-workspace operations provider (generic capability seam). Resolves
+   *  the calling session's cwd to its ops. */
+  ops: ToolOpsResolver
+}
+
+/** Failure envelope shared by every tool. */
+interface ToolFailure {
+  ok: false
+  error: string
+}
+
+/** The bound workspace record for the calling session's cwd, if any. */
+async function boundWorkspace(workspaces: WorkspaceStoreView, exec: ToolRunContext): Promise<SshWorkspaceRecord | undefined> {
+  const cwd = exec.agent?.session?.header?.cwd
+  if (cwd === undefined || cwd === '') return undefined
+  return workspaces.findByAnchor(cwd)
+}
+
+/** Build every remote_* tool (registered by the host half). */
+export function makeWorkspaceTools(deps: WorkspaceToolsDeps) {
+  const { workspaces, ops } = deps
+
+  /** The bound workspace + ops for this call, or a failure when the session's
+   *  workspace is not SSH-bound. */
+  const bound = async (exec: ToolRunContext): Promise<{ record: SshWorkspaceRecord; ops: import('./workspace-tool-ops.ts').WorkspaceToolOps; resolve: (abs: string) => string | undefined } | ToolFailure> => {
+    const cwd = exec.agent?.session?.header?.cwd
+    const outcome = await ops(cwd)
+    if (outcome === null) {
+      return { ok: false, error: 'this session\'s workspace is not SSH-bound — create an SSH workspace and open a session in it first' }
+    }
+    const root = outcome.record.remoteRoot
+    return {
+      record: outcome.record,
+      ops: outcome.ops,
+      // Return undefined when the absolute path escapes the workspace root.
+      resolve: (abs: string): string | undefined => (isInside(root, abs) ? abs : undefined),
+    }
+  }
+
+  /** Run one remote op, catching errors into the failure envelope. */
+  const run = async <T>(operation: () => Promise<T>): Promise<T | ToolFailure> => {
+    try {
+      return await operation()
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      return { ok: false, error: message }
+    }
+  }
+
+  return [
+    defineTool({
+      name: 'remote_status',
+      description: 'List the SSH-bound workspaces and report whether the CALLING SESSION\'s workspace is SSH-bound (and to which host/root). Call this before any remote_* tool. Triggers: SSH mode, remote workspace, where am I working, which servers are bound.',
+      parameters: {},
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            bound: { type: 'boolean', required: true },
+            workspaceTitle: { type: 'string' },
+            alias: { type: 'string' },
+            remoteRoot: { type: 'string' },
+            anchorPath: { type: 'string' },
+            workspaces: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
+              id: { type: 'string', required: true }, title: { type: 'string', required: true }, alias: { type: 'string', required: true }, remoteRoot: { type: 'string', required: true }, anchorPath: { type: 'string', required: true },
+            } } },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (value.ok !== true) return text(`remote_status failed: ${value.error ?? 'unknown error'}`)
+          const list = (value.workspaces ?? []).map((w: { title: string; alias: string; remoteRoot: string; anchorPath: string }) =>
+            `- ${w.title}  (${w.alias} @ ${w.remoteRoot}, anchor ${w.anchorPath})`)
+          const boundText = value.bound === true
+            ? `current session: BOUND -> ${value.workspaceTitle ?? ''} (${value.alias ?? ''} @ ${value.remoteRoot ?? ''})`
+            : 'current session: NOT bound (this workspace is local)'
+          return text([boundText, '', 'SSH workspaces:', ...(list.length > 0 ? list : ['(none)'])].join('\n'))
+        },
+      },
+      async execute(_args, exec) {
+        const records = await workspaces.list()
+        const workspace = await boundWorkspace(workspaces, exec)
+        return {
+          ok: true,
+          bound: workspace !== undefined,
+          workspaceTitle: workspace?.title,
+          alias: workspace?.alias,
+          remoteRoot: workspace?.remoteRoot,
+          anchorPath: workspace?.anchorPath,
+          workspaces: records.map((w) => ({ id: w.id, title: w.title, alias: w.alias, remoteRoot: w.remoteRoot, anchorPath: w.anchorPath })),
+        }
+      },
+    }),
+
+    defineTool({
+      name: 'remote_ls',
+      description: 'List a directory on the SSH host bound to the CALLING SESSION\'s workspace (the path must be inside that workspace\'s remote root). Triggers: list remote directory, remote files, ls on the server.',
+      parameters: {
+        path: { type: 'string', required: true, description: 'Absolute remote directory path inside the workspace\'s remote root (e.g. /home/user/project/src).' },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            path: { type: 'string' },
+            entries: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
+              name: { type: 'string', required: true }, type: { type: 'string', required: true }, size: { type: 'integer', required: true }, mtimeMs: { type: 'integer', required: true },
+            } } },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (value.ok !== true) return text(`remote_ls failed: ${value.error ?? 'unknown error'}`)
+          const rows = (value.entries ?? []).map((entry: { name: string; type: string; size: number }) =>
+            `${entry.type === 'dir' ? 'dir ' : 'file'} ${entry.name}${entry.type === 'file' ? ` (${entry.size} bytes)` : ''}`)
+          return text([`${value.path}`, ...(rows.length > 0 ? rows : ['(empty)'])].join('\n'))
+        },
+      },
+      async execute(args, exec) {
+        const check = await bound(exec)
+        if ('error' in check) return check
+        const abs = check.resolve(args.path)
+        if (abs === undefined) {
+          return { ok: false, error: `path '${args.path}' is outside the remote root '${check.record.remoteRoot}' of workspace '${check.record.title}'` }
+        }
+        return run(async () => {
+          const entries = await check.ops.listDir(abs)
+          return { ok: true, path: abs, entries }
+        })
+      },
+    }),
+
+    defineTool({
+      name: 'remote_search',
+      description: 'Search the SSH workspace bound to the CALLING SESSION. mode="glob" matches FILE NAMES by pattern (root-relative, e.g. src/**/*.ts or *.log; capped at 200 hits); mode="grep" searches file CONTENTS for a FIXED STRING (not a regex; skips .git and node_modules) and returns matched `path:line:content` records. Triggers: find remote files by pattern, glob on the server, grep remote code, search remote contents.',
+      parameters: {
+        mode: { type: 'string', enum: ['glob', 'grep'], required: true, description: 'glob = match file names by pattern; grep = search file contents for a fixed string.' },
+        pattern: { type: 'string', required: true, description: 'glob: root-relative pattern like src/**/*.ts or *.log; grep: the literal text to find (not a regular expression).' },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            mode: { type: 'string' },
+            hits: { type: 'array', items: { type: 'string' } },
+            lines: { type: 'array', items: { type: 'string' } },
+            truncated: { type: 'boolean' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (value.ok !== true) return text(`remote_search failed: ${value.error ?? 'unknown error'}`)
+          const tail = value.truncated === true
+            ? value.mode === 'grep' ? '\n[output truncated]' : '\n[truncated at 200 hits]'
+            : ''
+          const body = value.mode === 'grep' ? (value.lines ?? []) : (value.hits ?? [])
+          return text(body.length > 0 ? body.join('\n') + tail : '(no matches)')
+        },
+      },
+      async execute(args, exec) {
+        const check = await bound(exec)
+        if ('error' in check) return check
+        return run(async () => {
+          if (args.mode === 'grep') {
+            const found = await check.ops.grep(args.pattern)
+            return { ok: true, mode: 'grep', lines: found.lines, hits: [], truncated: found.truncated }
+          }
+          const found = await check.ops.glob(args.pattern)
+          return { ok: true, mode: 'glob', hits: found.hits, lines: [], truncated: found.truncated }
+        })
+      },
+    }),
+  ]
+}

package/src/workspace-tool-ops.ts

@@ -0,0 +1,101 @@
+/**
+ * Bound-workspace operations for the `remote_*` agent tools.
+ *
+ * The tools resolve the CALLING SESSION's bound workspace from its cwd, then
+ * run a small set of operations (directory listing, glob / content-grep)
+ * against it. The resolver opens the bound record through WorkspaceCore and
+ * uses its `workspace.fs` / `workspace.search` capabilities. It fails closed
+ * when the provider omits a required capability rather than falling back to a
+ * second engine-backed implementation.
+ */
+
+import type { FileSystem } from '@deepseek-ai/dsh-fs'
+import type { WorkspaceSearchService } from './base/capability.ts'
+import { isInside, type WorkspaceStoreView } from './backend.ts'
+import type { SshWorkspaceRecord, WorkspaceEntry } from './protocol.ts'
+import type { WorkspaceCore } from './runtime/workspace-core.ts'
+import type { RemoteGlobResult, RemoteGrepResult } from './remote-search.ts'
+
+/** Operations one bound workspace exposes to the remote_* tools. */
+export interface WorkspaceToolOps {
+  /** List one absolute directory path inside the workspace remote root. */
+  listDir(abs: string): Promise<WorkspaceEntry[]>
+  /** glob filename search (pattern keeps glob semantics). */
+  glob(pattern: string): Promise<RemoteGlobResult>
+  /** fixed-string content grep (returns matched `path:line:content` records). */
+  grep(fixedPhrase: string): Promise<RemoteGrepResult>
+}
+
+/** The bound record + its ops for one session cwd. */
+export interface BoundToolOps {
+  record: SshWorkspaceRecord
+  ops: WorkspaceToolOps
+}
+
+/** Resolve the calling session cwd to a bound workspace, or null when local. */
+export type ToolOpsResolver = (cwd: string | undefined) => Promise<BoundToolOps | null>
+
+/** workspace-relative path for an absolute path known to be inside the root. */
+function relOf(root: string, abs: string): string {
+  const normalized = root.endsWith('/') ? root : `${root}/`
+  if (abs === root) return ''
+  if (!abs.startsWith(normalized)) throw new Error(`path '${abs}' is outside remote root '${root}'`)
+  return abs.slice(normalized.length)
+}
+
+/** map a DSH directory entry to the tool DTO shape (mtime is opaque on capabilities). */
+function toEntry(name: string, type: 'directory' | 'file' | 'other'): WorkspaceEntry {
+  return { name, type: type === 'directory' ? 'dir' : type, size: 0, mtimeMs: 0 }
+}
+
+function outsideError(root: string, abs: string): Error {
+  return new Error(`path '${abs}' is outside remote root '${root}'`)
+}
+
+/**
+ * Capability-backed ops over one open connection. `root` confines every
+ * operation; search operations fail closed when the provider offers no
+ * `workspace.search` capability (a limited silent fallback would hide the gap).
+ */
+function capabilityOps(root: string, fs: FileSystem, search: WorkspaceSearchService | undefined): WorkspaceToolOps {
+  return {
+    async listDir(abs) {
+      if (!isInside(root, abs)) throw outsideError(root, abs)
+      const target = await fs.resolve(relOf(root, abs) === '' ? '.' : relOf(root, abs))
+      const info = await fs.stat(target)
+      if (info === undefined) throw new Error(`remote_ls: '${abs}' not found`)
+      if (info.type !== 'directory') throw new Error(`remote_ls: '${abs}' is not a directory`)
+      const entries = await fs.listDir(target)
+      return entries.map(entry => toEntry(entry.name, entry.type))
+    },
+    async glob(pattern) {
+      if (search === undefined) throw new Error('remote_search (glob): this workspace provider exposes no workspace.search capability')
+      const found = await search.glob(pattern)
+      return { hits: found.hits.map(hit => hit.path), truncated: found.truncated }
+    },
+    async grep(fixedPhrase) {
+      if (search === undefined) throw new Error('remote_search (grep): this workspace provider exposes no workspace.search capability')
+      const found = await search.grep(fixedPhrase)
+      return { lines: found.hits.map(hit => hit.match ?? hit.path), truncated: found.truncated }
+    },
+  }
+}
+
+/** Resolver that opens each bound record through the generic WorkspaceCore. */
+export function capabilityToolOpsResolver(store: WorkspaceStoreView, core: WorkspaceCore): ToolOpsResolver {
+  return async (cwd) => {
+    if (cwd === undefined || cwd === '') return null
+    const record = await store.findByAnchor(cwd)
+    if (record === undefined) return null
+    const connection = await core.openById(record.id)
+    if (connection === undefined) {
+      throw new Error(`remote workspace '${record.id}' is not open (failed closed)`)
+    }
+    const fs = connection.get('workspace.fs') as FileSystem | undefined
+    if (fs === undefined) {
+      throw new Error(`remote workspace '${record.id}' provides no workspace.fs capability`)
+    }
+    const search = connection.get('workspace.search') as WorkspaceSearchService | undefined
+    return { record, ops: capabilityOps(record.remoteRoot, fs, search) }
+  }
+}

package/src/workspace.ts

@@ -0,0 +1,52 @@
+/**
+ * Public workspace API entry — the stable surface third-party plugins consume.
+ * Exports only platform-neutral record/provider/connection/capability types,
+ * the `WorkspaceCore` consumer interface, and the stable provider API version.
+ *
+ * Deliberately NOT exported from here: `SshEngine`, concrete SSH connection /
+ * provider classes, the ledger/router/registry internals, and migration or
+ * legacy compatibility code — so implementation swaps never leak through this
+ * boundary (migration plan Phase 6, §「稳定导出」).
+ *
+ * @module @tiphareth/dsh-hardssh/workspace
+ */
+
+// Platform-neutral model: records, provider/connection contracts, manifest.
+export type {
+  ConnectionRef,
+  WorkspaceAnchor,
+  WorkspaceCapabilityMap,
+  WorkspaceConnection,
+  WorkspaceCreateInput,
+  WorkspaceId,
+  WorkspaceLocation,
+  WorkspaceProvider,
+  WorkspaceProviderManifest,
+  WorkspaceProviderRef,
+  WorkspaceRecord,
+  WorkspaceUpdate,
+} from './base/model.ts'
+export { WORKSPACE_PROVIDER_API_VERSION } from './base/model.ts'
+
+// The capability resource contracts a provider may serve (path-style fs,
+// search, and DSH FileSystem/SubprocessRuntime live on the runtime map above).
+export type {
+  WorkspaceDirEntry,
+  WorkspaceFileSystem,
+  WorkspaceProcessResult,
+  WorkspaceProcessRuntime,
+  WorkspaceSearchHit,
+  WorkspaceSearchService,
+  WorkspaceStat,
+} from './base/capability.ts'
+
+// The high-level consumer surface (ready/openById/openByAnchor/CRUD/
+// registerProvider/subscribe/closeAll). The concrete workspace-core
+// implementation stays internal; consumers depend on this interface only.
+export type {
+  WorkspaceCore,
+  WorkspaceListener,
+} from './runtime/workspace-core.ts'
+
+// The registry surface used to register third-party providers.
+export type { WorkspaceRegistry } from './base/registry.ts'