@exagone313/dsh-podman 1.6.0 → 1.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,2 @@
1
+ export type FsGuardDecision = "unchanged" | "stale" | "missing";
2
+ export declare function guardDecision(expectedVersion: string | undefined, currentVersion: string | undefined): FsGuardDecision;
@@ -0,0 +1,14 @@
1
+ // SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
2
+ //
3
+ // SPDX-License-Identifier: MIT
4
+ // guardDecision compares an observed version with the target's current one. An
5
+ // absent current version means the target is gone, which the edit guard reports
6
+ // as not found; an unobserved caller (no expected version) is unguarded and may
7
+ // proceed; otherwise the two versions must match exactly.
8
+ export function guardDecision(expectedVersion, currentVersion) {
9
+ if (currentVersion === undefined)
10
+ return "missing";
11
+ if (expectedVersion === undefined)
12
+ return "unchanged";
13
+ return expectedVersion === currentVersion ? "unchanged" : "stale";
14
+ }
@@ -0,0 +1 @@
1
+ export declare function normalizeFsKey(path: string): string;
package/dist/fs-key.js ADDED
@@ -0,0 +1,26 @@
1
+ // SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
2
+ //
3
+ // SPDX-License-Identifier: MIT
4
+ // The target key the observation policy records and the stale guards compare.
5
+ // One file can reach resolve() through different spellings — a doubled slash, a
6
+ // "." segment, a trailing slash, or a ".." left by a relative path — and they
7
+ // must share one record, so the key is collapsed lexically. Symbolic links are
8
+ // deliberately not resolved: the key is the guest path the caller named, not a
9
+ // realpath, and two links to one file stay distinct targets.
10
+ export function normalizeFsKey(path) {
11
+ const absolute = path.startsWith("/");
12
+ const segments = [];
13
+ for (const segment of path.split("/")) {
14
+ if (segment === "" || segment === ".")
15
+ continue;
16
+ if (segment === "..") {
17
+ segments.pop();
18
+ continue;
19
+ }
20
+ segments.push(segment);
21
+ }
22
+ const joined = segments.join("/");
23
+ if (absolute)
24
+ return `/${joined}`;
25
+ return joined === "" ? "." : joined;
26
+ }
@@ -4,7 +4,35 @@
4
4
  import { detectLineEndings, DIFF_BASIS_MAX_BYTES, fsError, guestChunks, guestStat, guestStatResponse, guestTextChunks, guestVersion, normalizeLineEndings, readDiffBasis, readGuestText, resolveGuestPath, restoreLineEndings, throwIfAborted, unaryGuest, writeGuestFile, } from "./guest-rpc.js";
5
5
  import { hostListDir, hostLstat, hostReadByteRange, hostReadBytes, hostReadText, hostRefuse, hostStat, hostTarget, hostTextChunks, isHostTarget, } from "./host-fs.js";
6
6
  import { isProjectSkillPath, isUserSkillPath } from "./skill-roots.js";
7
+ import { guardDecision } from "./fs-guard.js";
8
+ import { normalizeFsKey } from "./fs-key.js";
7
9
  import { isAbsolute, join, resolve as resolvePath } from "node:path";
10
+ // Overlapping mutations of one target must not both observe the same version
11
+ // and then both write: each guarded mutation holds a per-target lock across
12
+ // stat → check → write, so a second one sees the version the first left behind.
13
+ // Different targets never wait on each other. The entry is dropped when its
14
+ // chain settles, so the map does not grow with every path the session touched.
15
+ const targetLocks = new Map();
16
+ async function withTargetLock(key, run) {
17
+ const previous = targetLocks.get(key) ?? Promise.resolve();
18
+ let release;
19
+ const gate = new Promise((resolve) => {
20
+ release = resolve;
21
+ });
22
+ // Queued, not the gate itself: the next caller awaits a promise that settles
23
+ // only when this mutation has finished, whatever its outcome.
24
+ const queued = previous.then(() => gate);
25
+ targetLocks.set(key, queued);
26
+ await previous;
27
+ try {
28
+ return await run();
29
+ }
30
+ finally {
31
+ release();
32
+ if (targetLocks.get(key) === queued)
33
+ targetLocks.delete(key);
34
+ }
35
+ }
8
36
  export function createFilesystemProvider(resolver, options = {}) {
9
37
  const projectsRoot = options.projectsRoot ?? "";
10
38
  const userRoots = {
@@ -23,7 +51,10 @@ export function createFilesystemProvider(resolver, options = {}) {
23
51
  return {
24
52
  resolve: async (path, opts) => {
25
53
  throwIfAborted(opts?.signal, "resolve");
26
- const resolved = resolveGuestPath(path, opts?.cwd);
54
+ // Collapse the aliases one path can arrive under (a doubled slash, a "."
55
+ // segment, a trailing slash) before anything keys on it, so a read
56
+ // through one spelling satisfies the read-before-write guard for another.
57
+ const resolved = normalizeFsKey(resolveGuestPath(path, opts?.cwd));
27
58
  // An explicit container targets that container's guest; the harness's own
28
59
  // tools never pass one and keep the session workspace's default.
29
60
  const container = typeof opts?.container === "string"
@@ -109,42 +140,52 @@ export function createFilesystemProvider(resolver, options = {}) {
109
140
  if (isHostTarget(target))
110
141
  hostRefuse("write", target);
111
142
  throwIfAborted(signal, "write");
112
- const current = await guestStatResponse(target, signal);
113
- if (current.exists && current.isDir) {
114
- throw fsError("FS_NOT_REGULAR_FILE", `cannot write "${target.displayPath}": not a regular file`);
115
- }
116
- const currentVersion = current.exists ? guestVersion(current) : undefined;
117
- if (expected?.kind === "replaceIfVersion") {
118
- // A file that is gone is a new file: creating it destroys nothing, so
119
- // this backend creates it. (The harness's fs-local reports
120
- // FS_STALE_VERSION here; a path the session read and something else
121
- // removed must stay writable, so the container tools create it.)
122
- if (current.exists && currentVersion !== expected.version) {
123
- throw fsError("FS_STALE_VERSION", `cannot write "${target.displayPath}": file changed since it was read`);
143
+ // The stat, the guard, and the write are one critical section: a second
144
+ // mutation of this path waits here instead of observing the same version
145
+ // and overwriting this one. Different paths never share the lock.
146
+ return await withTargetLock(target.targetKey, async () => {
147
+ const current = await guestStatResponse(target, signal);
148
+ if (current.exists && current.isDir) {
149
+ throw fsError("FS_NOT_REGULAR_FILE", `cannot write "${target.displayPath}": not a regular file`);
124
150
  }
125
- }
126
- else if (expected?.kind === "createIfAbsent" && current.exists) {
127
- throw fsError("FS_NOT_OBSERVED", `cannot overwrite existing "${target.displayPath}" without reading it first`);
128
- }
129
- // The basis is gated on both sides: an incoming or existing file at or
130
- // above the limit yields `before: null` and the consumer falls back to a
131
- // whole-file diff, so writing one byte into a huge file does not read the
132
- // whole file back just for presentation. Both sides are LF-normalized so
133
- // a CRLF overwrite does not read as every line changed.
134
- const rawBasis = current.exists &&
135
- Buffer.byteLength(content, "utf8") < DIFF_BASIS_MAX_BYTES &&
136
- Number(current.size ?? 0) < DIFF_BASIS_MAX_BYTES
137
- ? await readDiffBasis(target, signal)
138
- : null;
139
- const before = rawBasis === null ? null : normalizeLineEndings(rawBasis);
140
- await writeGuestFile(target.binding, target.targetKey, content, { create: true, truncate: true }, signal);
141
- const after = await guestStatResponse(target, signal);
142
- return {
143
- operation: current.exists ? "update" : "create",
144
- version: guestVersion(after),
145
- before,
146
- after: normalizeLineEndings(content),
147
- };
151
+ const currentVersion = current.exists
152
+ ? guestVersion(current)
153
+ : undefined;
154
+ if (expected?.kind === "replaceIfVersion") {
155
+ // A file that is gone is a new file: creating it destroys nothing, so
156
+ // this backend creates it (the decision reports that as missing).
157
+ // (The harness's fs-local reports FS_STALE_VERSION here; a path the
158
+ // session read and something else removed must stay writable, so the
159
+ // container tools create it.)
160
+ if (guardDecision(expected.version, currentVersion) === "stale") {
161
+ throw fsError("FS_STALE_VERSION", `cannot write "${target.displayPath}": file changed since it was read`);
162
+ }
163
+ }
164
+ else if (expected?.kind === "createIfAbsent" && current.exists) {
165
+ throw fsError("FS_NOT_OBSERVED", `cannot overwrite existing "${target.displayPath}" without reading it first`);
166
+ }
167
+ // The basis is gated on both sides: an incoming or existing file at or
168
+ // above the limit yields `before: null` and the consumer falls back to a
169
+ // whole-file diff, so writing one byte into a huge file does not read the
170
+ // whole file back just for presentation. Both sides are LF-normalized so
171
+ // a CRLF overwrite does not read as every line changed.
172
+ const rawBasis = current.exists &&
173
+ Buffer.byteLength(content, "utf8") < DIFF_BASIS_MAX_BYTES &&
174
+ Number(current.size ?? 0) < DIFF_BASIS_MAX_BYTES
175
+ ? await readDiffBasis(target, signal)
176
+ : null;
177
+ const before = rawBasis === null
178
+ ? null
179
+ : normalizeLineEndings(rawBasis);
180
+ await writeGuestFile(target.binding, target.targetKey, content, { create: true, truncate: true }, signal);
181
+ const after = await guestStatResponse(target, signal);
182
+ return {
183
+ operation: current.exists ? "update" : "create",
184
+ version: guestVersion(after),
185
+ before,
186
+ after: normalizeLineEndings(content),
187
+ };
188
+ });
148
189
  },
149
190
  stat: (target, signal) => isHostTarget(target)
150
191
  ? hostStat(target, signal)
@@ -203,40 +244,50 @@ export function createFilesystemProvider(resolver, options = {}) {
203
244
  if (isHostTarget(target))
204
245
  hostRefuse("edit", target);
205
246
  throwIfAborted(signal, "edit");
206
- const current = await guestStatResponse(target, signal);
207
- if (!current.exists) {
208
- throw fsError("FS_STALE_VERSION", `cannot edit "${target.displayPath}": file changed since it was read`);
209
- }
210
- if (current.isDir) {
211
- throw fsError("FS_NOT_REGULAR_FILE", `cannot edit "${target.displayPath}": not a regular file`);
212
- }
213
- if (expected !== undefined &&
214
- guestVersion(current) !== expected.version) {
215
- throw fsError("FS_STALE_VERSION", `cannot edit "${target.displayPath}": file changed since it was read`);
216
- }
217
- const raw = await readGuestText(target, signal);
218
- const before = normalizeLineEndings(raw);
219
- const lineEndings = detectLineEndings(raw);
220
- const oldNorm = normalizeLineEndings(typeof edit.oldString === "string" ? edit.oldString : "");
221
- if (oldNorm.length === 0) {
222
- throw fsError("FS_EDIT_NOT_FOUND", "old_string must be a non-empty string");
223
- }
224
- const newNorm = normalizeLineEndings(typeof edit.newString === "string" ? edit.newString : "");
225
- const occurrences = before.split(oldNorm).length - 1;
226
- if (occurrences === 0) {
227
- throw fsError("FS_EDIT_NOT_FOUND", `old_string was not found in "${target.displayPath}"`);
228
- }
229
- if (!edit.replaceAll && occurrences > 1) {
230
- throw fsError("FS_AMBIGUOUS_EDIT", `old_string matched ${occurrences} times in "${target.displayPath}"; provide a more specific old_string or set replace_all to true`);
231
- }
232
- const after = before.split(oldNorm).join(newNorm);
233
- await writeGuestFile(target.binding, target.targetKey, restoreLineEndings(after, lineEndings), { create: true, truncate: true }, signal);
234
- const afterInfo = await guestStatResponse(target, signal);
235
- return {
236
- version: guestVersion(afterInfo),
237
- before,
238
- after,
239
- };
247
+ // stat → check → read → write is one critical section, like writeText:
248
+ // overlapping edits of this path queue here rather than both matching
249
+ // against the same version.
250
+ return await withTargetLock(target.targetKey, async () => {
251
+ const current = await guestStatResponse(target, signal);
252
+ const currentVersion = current.exists
253
+ ? guestVersion(current)
254
+ : undefined;
255
+ const decision = guardDecision(expected?.version, currentVersion);
256
+ if (decision === "missing") {
257
+ // A file removed after it was read is gone rather than stale; report
258
+ // the harness's not-found code, the one its read tool also uses.
259
+ throw fsError("FS_NOT_FOUND", `cannot edit "${target.displayPath}": not found`);
260
+ }
261
+ if (current.isDir) {
262
+ throw fsError("FS_NOT_REGULAR_FILE", `cannot edit "${target.displayPath}": not a regular file`);
263
+ }
264
+ if (decision === "stale") {
265
+ throw fsError("FS_STALE_VERSION", `cannot edit "${target.displayPath}": file changed since it was read`);
266
+ }
267
+ const raw = await readGuestText(target, signal);
268
+ const before = normalizeLineEndings(raw);
269
+ const lineEndings = detectLineEndings(raw);
270
+ const oldNorm = normalizeLineEndings(typeof edit.oldString === "string" ? edit.oldString : "");
271
+ if (oldNorm.length === 0) {
272
+ throw fsError("FS_EDIT_NOT_FOUND", "old_string must be a non-empty string");
273
+ }
274
+ const newNorm = normalizeLineEndings(typeof edit.newString === "string" ? edit.newString : "");
275
+ const occurrences = before.split(oldNorm).length - 1;
276
+ if (occurrences === 0) {
277
+ throw fsError("FS_EDIT_NOT_FOUND", `old_string was not found in "${target.displayPath}"`);
278
+ }
279
+ if (!edit.replaceAll && occurrences > 1) {
280
+ throw fsError("FS_AMBIGUOUS_EDIT", `old_string matched ${occurrences} times in "${target.displayPath}"; provide a more specific old_string or set replace_all to true`);
281
+ }
282
+ const after = before.split(oldNorm).join(newNorm);
283
+ await writeGuestFile(target.binding, target.targetKey, restoreLineEndings(after, lineEndings), { create: true, truncate: true }, signal);
284
+ const afterInfo = await guestStatResponse(target, signal);
285
+ return {
286
+ version: guestVersion(afterInfo),
287
+ before,
288
+ after,
289
+ };
290
+ });
240
291
  },
241
292
  // Watching would need a watcher inside each workspace's container (inotify
242
293
  // in the guest, or host-side polling of every open tree node), and every
@@ -1,2 +1,2 @@
1
- export declare const VERSION = "1.6.0";
2
- export declare const GIT_COMMIT = "a1a5ab0";
1
+ export declare const VERSION = "1.6.1";
2
+ export declare const GIT_COMMIT = "50e2fb6";
@@ -2,5 +2,5 @@
2
2
  //
3
3
  // SPDX-License-Identifier: MIT
4
4
  // Generated by scripts/generate-version.mjs; do not edit.
5
- export const VERSION = "1.6.0";
6
- export const GIT_COMMIT = "a1a5ab0";
5
+ export const VERSION = "1.6.1";
6
+ export const GIT_COMMIT = "50e2fb6";
@@ -1,3 +1,4 @@
1
+ import { FsError, type FsErrorCode } from "@deepseek-ai/dsh-fs";
1
2
  import { type WorkspaceBinding, WorkspaceResolver } from "./workspace-binding.js";
2
3
  export declare function resolveGuestPath(path: string, sessionCwd: unknown): string;
3
4
  export declare function resolveGuestCwd(cwd: unknown, sessionCwd: unknown): string | undefined;
@@ -9,7 +10,7 @@ export declare const DIFF_BASIS_MAX_BYTES: number;
9
10
  export declare function normalizeLineEndings(content: string): string;
10
11
  export declare function detectLineEndings(raw: string): "CRLF" | "LF";
11
12
  export declare function restoreLineEndings(content: string, endings: "CRLF" | "LF"): string;
12
- export declare function fsError(code: string, message: string): Error;
13
+ export declare function fsError(code: FsErrorCode, message: string): FsError;
13
14
  export declare function throwIfAborted(signal: AbortSignal | undefined, verb: string): void;
14
15
  export declare function withGuestAuth<T>(binding: WorkspaceBinding, run: (guest: any, token: string) => Promise<T>): Promise<T>;
15
16
  export declare function guestChunks(target: any, range: {
package/dist/guest-rpc.js CHANGED
@@ -1,6 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
2
2
  //
3
3
  // SPDX-License-Identifier: MIT
4
+ import { FsError } from "@deepseek-ai/dsh-fs";
4
5
  import { metadata, workspaceSlug, } from "./workspace-binding.js";
5
6
  import { grpc } from "./grpc/runtime-client.js";
6
7
  import { discardUnneededSpill, outputReader, SPILL_ROOT, } from "./output-reader.js";
@@ -85,10 +86,12 @@ export function restoreLineEndings(content, endings) {
85
86
  ? content
86
87
  : normalizeLineEndings(content).split("\n").join("\r\n");
87
88
  }
89
+ // fsError builds the harness's typed filesystem failure, so the tool layer can
90
+ // route on the code and append its own remedy (`remediateFsError` appends the
91
+ // re-read step to FS_STALE_VERSION). A plain Error carrying a code string would
92
+ // be indistinguishable from a transport failure there.
88
93
  export function fsError(code, message) {
89
- const error = new Error(message);
90
- error.code = code;
91
- return error;
94
+ return new FsError(message, code);
92
95
  }
93
96
  // The harness's FS_ABORTED: a caller that already cancelled must fail before
94
97
  // any I/O.
@@ -213,8 +216,12 @@ export async function* guestTextChunks(target, signal) {
213
216
  yield tail;
214
217
  }
215
218
  catch (error) {
216
- // A fatal TextDecoder failure is a TypeError; anything else (our own
217
- // FS_NOT_TEXT/FS_ABORTED, or a transport error) keeps its identity.
219
+ // An already-typed failure — our own FS_NOT_TEXT/FS_ABORTED, or one a
220
+ // caller raised — keeps its identity. A fatal TextDecoder failure is a
221
+ // TypeError, which is the only thing wrapped here (as FS_NOT_TEXT); any
222
+ // other transport error passes through unchanged, as before.
223
+ if (error instanceof FsError)
224
+ throw error;
218
225
  if (error instanceof TypeError) {
219
226
  throw fsError("FS_NOT_TEXT", `cannot read "${target.displayPath}": invalid UTF-8 text`);
220
227
  }
@@ -234,7 +241,7 @@ export async function readDiffBasis(target, signal) {
234
241
  return await readGuestText(target, signal);
235
242
  }
236
243
  catch (error) {
237
- if (error.code === "FS_NOT_TEXT")
244
+ if (error instanceof FsError && error.code === "FS_NOT_TEXT")
238
245
  return null;
239
246
  throw error;
240
247
  }
@@ -17,6 +17,8 @@ The goal of this guide is to install:
17
17
  - the dsh-podman plugin in dsh, which replaces host filesystem and shell access
18
18
  - the dsh-podman orchestrator, a separate Podman container that integrates with
19
19
  Podman
20
+ - the dsh-podman gateway, a container used for publishing container ports on
21
+ localhost
20
22
 
21
23
  Note that if there is existing installation data at `~/.dsh`, it will be reused.
22
24
 
@@ -50,7 +52,7 @@ could be added in the future.
50
52
  dsh-podman plugin, has access to the Podman socket and manages containers and
51
53
  other resources; it runs in a container; referred to later as _orchestrator_
52
54
  - **dsh-podman gateway**: the host-network container that publishes guest pod
53
- ports on the host's loopback; referred to later as _gateway_
55
+ ports on the host's loopback (localhost); referred to later as _gateway_
54
56
  - **Podman socket**: while the Podman client can be used without a daemon, it is
55
57
  still possible to enable management through a socket, which is required by the
56
58
  orchestrator to work as if it were running on the host system
@@ -16,6 +16,7 @@ SPDX-License-Identifier: MIT
16
16
  Podman 容器中运行
17
17
  - dsh 中的 dsh-podman 插件,它取代了宿主的文件系统和 shell 访问
18
18
  - dsh-podman 编排器,一个与 Podman 集成的独立 Podman 容器
19
+ - dsh-podman gateway,一个用于在 localhost 上发布容器端口的容器
19
20
 
20
21
  请注意,如果 `~/.dsh` 中已有安装数据,它将被复用。
21
22
 
@@ -40,7 +41,7 @@ SPDX-License-Identifier: MIT
40
41
  - **dsh-podman 编排器**:接收来自 dsh-podman 插件连接的守护进程,可访问 Podman
41
42
  套接字并管理容器和其他资源;它在容器中运行;下文简称 _orchestrator_
42
43
  - **dsh-podman gateway**:运行在主机网络上的容器,把 guest pod
43
- 端口发布到主机回环地址;下文简称 _gateway_
44
+ 端口发布到主机回环地址(localhost);下文简称 _gateway_
44
45
  - **Podman 套接字**:虽然 Podman
45
46
  客户端可以在没有守护进程的情况下使用,但仍然可以通过套接字启用管理,这是编排器以仿佛在主机系统上运行的方式工作所必需的
46
47
  - **guest 容器**:由 dsh-podman 编排器创建的容器,与 dsh 工作区相关联
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@exagone313/dsh-podman",
3
- "version": "1.6.0",
3
+ "version": "1.6.1",
4
4
  "description": "Podman-backed execution for DeepSeek Harness (dsh).",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -79,6 +79,7 @@
79
79
  "@deepseek-ai/dsh-client-ui-sidebar-right": "0.2.1-rc.2",
80
80
  "@deepseek-ai/dsh-client-ui-slots": "0.2.1-rc.2",
81
81
  "@deepseek-ai/dsh-client-ui-tool": "0.2.1-rc.2",
82
+ "@deepseek-ai/dsh-fs": "0.2.1-rc.2",
82
83
  "@deepseek-ai/dsh-subprocess": "0.2.1-rc.2",
83
84
  "@deepseek-ai/schemastery": "3.18.5",
84
85
  "@types/node": "^26.6.5",
@@ -108,6 +109,7 @@
108
109
  "@deepseek-ai/dsh-client-ui-sidebar-right": "0.2.1-rc.2",
109
110
  "@deepseek-ai/dsh-client-ui-slots": "0.2.1-rc.2",
110
111
  "@deepseek-ai/dsh-client-ui-tool": "0.2.1-rc.2",
112
+ "@deepseek-ai/dsh-fs": "0.2.1-rc.2",
111
113
  "@deepseek-ai/dsh-subprocess": "0.2.1-rc.2",
112
114
  "@deepseek-ai/schemastery": "3.18.5",
113
115
  "react": "^18.2.0"
@@ -146,6 +148,9 @@
146
148
  "@deepseek-ai/dsh-client-ui-tool": {
147
149
  "optional": true
148
150
  },
151
+ "@deepseek-ai/dsh-fs": {
152
+ "optional": true
153
+ },
149
154
  "@deepseek-ai/dsh-subprocess": {
150
155
  "optional": true
151
156
  },