@exagone313/dsh-podman 1.1.1 → 1.2.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.
- package/dist/card-route.js +11 -5
- package/dist/client/ContainerCard.js +2 -2
- package/dist/client/card-protocol.d.ts +1 -0
- package/dist/client/container-card-controller.d.ts +1 -0
- package/dist/client/container-card-controller.js +2 -0
- package/dist/client/index.js +5 -2
- package/dist/fs-provider.d.ts +6 -1
- package/dist/fs-provider.js +60 -6
- package/dist/generated/version.d.ts +2 -2
- package/dist/generated/version.js +2 -2
- package/dist/host-fs.d.ts +16 -0
- package/dist/host-fs.js +181 -0
- package/dist/index.js +14 -1
- package/dist/skill-roots.d.ts +6 -0
- package/dist/skill-roots.js +55 -0
- package/docs/architecture.md +15 -0
- package/docs/architecture.zh.md +12 -0
- package/docs/configuration.md +20 -0
- package/docs/configuration.zh.md +18 -0
- package/docs/development-prompt.md +2 -0
- package/docs/development-prompt.zh.md +2 -0
- package/docs/development.md +5 -2
- package/docs/development.zh.md +5 -2
- package/docs/install-dsh-and-dsh-podman.md +2 -0
- package/docs/install-dsh-and-dsh-podman.zh.md +2 -0
- package/docs/uninstall.md +2 -0
- package/docs/uninstall.zh.md +2 -0
- package/docs/update.md +35 -0
- package/docs/update.zh.md +36 -0
- package/docs/usage.md +23 -0
- package/docs/usage.zh.md +22 -0
- package/package.json +4 -4
- package/quadlet/dsh-podman-orchestrator.container +4 -1
- package/quadlet/dsh.container +4 -1
package/dist/card-route.js
CHANGED
|
@@ -16,15 +16,19 @@ import { workspaceSlug } from "./workspace-binding.js";
|
|
|
16
16
|
import { GIT_COMMIT, VERSION } from "./generated/version.js";
|
|
17
17
|
import { versionState as pluginVersionState } from "./version-compat.js";
|
|
18
18
|
import { dshVersion } from "./dsh-version.js";
|
|
19
|
-
// readOrchestratorVersion asks the orchestrator for its version, or
|
|
20
|
-
// when the call fails (an orchestrator predating the
|
|
19
|
+
// readOrchestratorVersion asks the orchestrator for its version and commit, or
|
|
20
|
+
// returns empty strings when the call fails (an orchestrator predating the
|
|
21
|
+
// handshake).
|
|
21
22
|
async function readOrchestratorVersion(resolver) {
|
|
22
23
|
try {
|
|
23
24
|
const response = await resolver.control("getVersion", {});
|
|
24
|
-
return
|
|
25
|
+
return {
|
|
26
|
+
version: String(response?.version ?? ""),
|
|
27
|
+
commit: String(response?.commit ?? ""),
|
|
28
|
+
};
|
|
25
29
|
}
|
|
26
30
|
catch {
|
|
27
|
-
return "";
|
|
31
|
+
return { version: "", commit: "" };
|
|
28
32
|
}
|
|
29
33
|
}
|
|
30
34
|
// The gateway states the control plane reports, mapped to the card's
|
|
@@ -177,7 +181,7 @@ export async function cardSnapshot(resolver, workspaceRegistry, harnessVersion =
|
|
|
177
181
|
// The handshake RPC is exempt from the orchestrator's version check, so it
|
|
178
182
|
// succeeds even when the rest is refused; an older orchestrator that has no
|
|
179
183
|
// GetVersion yet leaves the version unknown.
|
|
180
|
-
const orchestratorVersion = await readOrchestratorVersion(resolver);
|
|
184
|
+
const { version: orchestratorVersion, commit: orchestratorCommit } = await readOrchestratorVersion(resolver);
|
|
181
185
|
const gateway = await readGatewayStatus(resolver);
|
|
182
186
|
let listings;
|
|
183
187
|
try {
|
|
@@ -201,6 +205,7 @@ export async function cardSnapshot(resolver, workspaceRegistry, harnessVersion =
|
|
|
201
205
|
commit: GIT_COMMIT,
|
|
202
206
|
dshVersion: harnessVersion,
|
|
203
207
|
orchestratorVersion,
|
|
208
|
+
orchestratorCommit,
|
|
204
209
|
versionState: "major-mismatch",
|
|
205
210
|
...gateway,
|
|
206
211
|
gatewayVersionState: "ok",
|
|
@@ -219,6 +224,7 @@ export async function cardSnapshot(resolver, workspaceRegistry, harnessVersion =
|
|
|
219
224
|
commit: GIT_COMMIT,
|
|
220
225
|
dshVersion: harnessVersion,
|
|
221
226
|
orchestratorVersion,
|
|
227
|
+
orchestratorCommit,
|
|
222
228
|
versionState: pluginVersionState(VERSION, orchestratorVersion),
|
|
223
229
|
...gateway,
|
|
224
230
|
// Absent or unreadable is not a mismatch: the gateway is optional.
|
|
@@ -31,7 +31,7 @@ export function ContainerCard(props) {
|
|
|
31
31
|
const lines = [
|
|
32
32
|
`${t("dsh")} ${state.dshVersion || t("versionUnknown")}`,
|
|
33
33
|
`${t("cardTitle")} ${state.version}${state.commit ? ` · ${state.commit}` : ""}`,
|
|
34
|
-
`${t("orchestrator")} ${state.orchestratorVersion || t("versionUnknown")}`,
|
|
34
|
+
`${t("orchestrator")} ${state.orchestratorVersion || t("versionUnknown")}${state.orchestratorCommit ? ` · ${state.orchestratorCommit}` : ""}`,
|
|
35
35
|
`${t("gateway")} ${state.gatewayState === "running"
|
|
36
36
|
? `${state.gatewayVersion}${state.gatewayCommit ? ` · ${state.gatewayCommit}` : ""}`
|
|
37
37
|
: state.gatewayState === "incompatible"
|
|
@@ -123,7 +123,7 @@ export function ContainerCard(props) {
|
|
|
123
123
|
? (` ${state.dshVersion}`)
|
|
124
124
|
: (_jsxs(_Fragment, { children: [" ", _jsx("span", { style: { color: "var(--dsw-alias-state-error-primary)" }, children: t("versionUnknown") })] }))] }), _jsxs("span", { children: [_jsx("span", { style: versionLabel, children: t("cardTitle") }), state.version ? ` ${state.version}` : "", state.commit ? ` · ${state.commit}` : ""] }), _jsxs("span", { children: [_jsx("span", { style: versionLabel, children: t("orchestrator") }), state.orchestratorVersion
|
|
125
125
|
? (` ${state.orchestratorVersion}`)
|
|
126
|
-
: (_jsxs(_Fragment, { children: [" ", _jsx("span", { style: { color: "var(--dsw-alias-state-error-primary)" }, children: t("versionUnknown") })] }))] }), _jsxs("span", { children: [_jsx("span", { style: versionLabel, children: t("gateway") }), state.gatewayState === "running"
|
|
126
|
+
: (_jsxs(_Fragment, { children: [" ", _jsx("span", { style: { color: "var(--dsw-alias-state-error-primary)" }, children: t("versionUnknown") })] })), state.orchestratorCommit ? ` · ${state.orchestratorCommit}` : ""] }), _jsxs("span", { children: [_jsx("span", { style: versionLabel, children: t("gateway") }), state.gatewayState === "running"
|
|
127
127
|
? ` ${state.gatewayVersion}${state.gatewayCommit ? ` · ${state.gatewayCommit}` : ""}`
|
|
128
128
|
: (_jsxs(_Fragment, { children: [" ", _jsx("span", { style: state.gatewayState === "incompatible"
|
|
129
129
|
? { color: "var(--dsw-alias-state-error-primary)" }
|
|
@@ -98,6 +98,7 @@ export interface CardSnapshot {
|
|
|
98
98
|
commit: string;
|
|
99
99
|
dshVersion: string;
|
|
100
100
|
orchestratorVersion: string;
|
|
101
|
+
orchestratorCommit: string;
|
|
101
102
|
versionState: "ok" | "minor-mismatch" | "major-mismatch";
|
|
102
103
|
gatewayState: "unknown" | "running" | "absent" | "incompatible";
|
|
103
104
|
gatewayVersion: string;
|
|
@@ -34,6 +34,7 @@ export interface CardState {
|
|
|
34
34
|
commit: string;
|
|
35
35
|
dshVersion: string;
|
|
36
36
|
orchestratorVersion: string;
|
|
37
|
+
orchestratorCommit: string;
|
|
37
38
|
versionState: "ok" | "minor-mismatch" | "major-mismatch";
|
|
38
39
|
gatewayState: "unknown" | "running" | "absent" | "incompatible";
|
|
39
40
|
gatewayVersion: string;
|
|
@@ -9,6 +9,7 @@ const EMPTY_SNAPSHOT = {
|
|
|
9
9
|
commit: "",
|
|
10
10
|
dshVersion: "",
|
|
11
11
|
orchestratorVersion: "",
|
|
12
|
+
orchestratorCommit: "",
|
|
12
13
|
versionState: "ok",
|
|
13
14
|
gatewayState: "unknown",
|
|
14
15
|
gatewayVersion: "",
|
|
@@ -61,6 +62,7 @@ export class ContainerCardController {
|
|
|
61
62
|
commit: this.snapshot.commit,
|
|
62
63
|
dshVersion: this.snapshot.dshVersion,
|
|
63
64
|
orchestratorVersion: this.snapshot.orchestratorVersion,
|
|
65
|
+
orchestratorCommit: this.snapshot.orchestratorCommit,
|
|
64
66
|
versionState: this.snapshot.versionState,
|
|
65
67
|
gatewayState: this.snapshot.gatewayState,
|
|
66
68
|
gatewayVersion: this.snapshot.gatewayVersion,
|
package/dist/client/index.js
CHANGED
|
@@ -3516,7 +3516,7 @@ function ContainerCard(props) {
|
|
|
3516
3516
|
const lines = [
|
|
3517
3517
|
`${t("dsh")} ${state.dshVersion || t("versionUnknown")}`,
|
|
3518
3518
|
`${t("cardTitle")} ${state.version}${state.commit ? ` \xB7 ${state.commit}` : ""}`,
|
|
3519
|
-
`${t("orchestrator")} ${state.orchestratorVersion || t("versionUnknown")}`,
|
|
3519
|
+
`${t("orchestrator")} ${state.orchestratorVersion || t("versionUnknown")}${state.orchestratorCommit ? ` \xB7 ${state.orchestratorCommit}` : ""}`,
|
|
3520
3520
|
`${t("gateway")} ${state.gatewayState === "running" ? `${state.gatewayVersion}${state.gatewayCommit ? ` \xB7 ${state.gatewayCommit}` : ""}` : state.gatewayState === "incompatible" ? t("gatewayIncompatible") : t("gatewayNotRunning")}`
|
|
3521
3521
|
];
|
|
3522
3522
|
setCopyState(
|
|
@@ -3873,7 +3873,8 @@ function ContainerCard(props) {
|
|
|
3873
3873
|
children: t("versionUnknown")
|
|
3874
3874
|
}
|
|
3875
3875
|
)
|
|
3876
|
-
] })
|
|
3876
|
+
] }),
|
|
3877
|
+
state.orchestratorCommit ? ` \xB7 ${state.orchestratorCommit}` : ""
|
|
3877
3878
|
] }),
|
|
3878
3879
|
/* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("span", { children: [
|
|
3879
3880
|
/* @__PURE__ */ (0, import_jsx_runtime14.jsx)("span", { style: versionLabel, children: t("gateway") }),
|
|
@@ -14895,6 +14896,7 @@ var EMPTY_SNAPSHOT = {
|
|
|
14895
14896
|
commit: "",
|
|
14896
14897
|
dshVersion: "",
|
|
14897
14898
|
orchestratorVersion: "",
|
|
14899
|
+
orchestratorCommit: "",
|
|
14898
14900
|
versionState: "ok",
|
|
14899
14901
|
gatewayState: "unknown",
|
|
14900
14902
|
gatewayVersion: "",
|
|
@@ -14943,6 +14945,7 @@ var ContainerCardController = class {
|
|
|
14943
14945
|
commit: this.snapshot.commit,
|
|
14944
14946
|
dshVersion: this.snapshot.dshVersion,
|
|
14945
14947
|
orchestratorVersion: this.snapshot.orchestratorVersion,
|
|
14948
|
+
orchestratorCommit: this.snapshot.orchestratorCommit,
|
|
14946
14949
|
versionState: this.snapshot.versionState,
|
|
14947
14950
|
gatewayState: this.snapshot.gatewayState,
|
|
14948
14951
|
gatewayVersion: this.snapshot.gatewayVersion,
|
package/dist/fs-provider.d.ts
CHANGED
|
@@ -21,4 +21,9 @@ export interface FilesystemProvider {
|
|
|
21
21
|
editText(target: any, edit: any, expected?: any, signal?: AbortSignal): Promise<any>;
|
|
22
22
|
watch(target: any, changed: (error?: Error) => void, signal?: AbortSignal): Promise<() => Promise<void>>;
|
|
23
23
|
}
|
|
24
|
-
export
|
|
24
|
+
export interface FilesystemProviderOptions {
|
|
25
|
+
readonly projectsRoot?: string;
|
|
26
|
+
readonly dshHome?: string;
|
|
27
|
+
readonly agentsHome?: string;
|
|
28
|
+
}
|
|
29
|
+
export declare function createFilesystemProvider(resolver: WorkspaceResolver, options?: FilesystemProviderOptions): FilesystemProvider;
|
package/dist/fs-provider.js
CHANGED
|
@@ -2,8 +2,24 @@
|
|
|
2
2
|
//
|
|
3
3
|
// SPDX-License-Identifier: MIT
|
|
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
|
+
import { hostListDir, hostLstat, hostReadByteRange, hostReadBytes, hostReadText, hostRefuse, hostStat, hostTarget, hostTextChunks, isHostTarget, } from "./host-fs.js";
|
|
6
|
+
import { isProjectSkillPath, isUserSkillPath } from "./skill-roots.js";
|
|
5
7
|
import { isAbsolute, join, resolve as resolvePath } from "node:path";
|
|
6
|
-
export function createFilesystemProvider(resolver) {
|
|
8
|
+
export function createFilesystemProvider(resolver, options = {}) {
|
|
9
|
+
const projectsRoot = options.projectsRoot ?? "";
|
|
10
|
+
const userRoots = {
|
|
11
|
+
dshHome: options.dshHome ?? "",
|
|
12
|
+
agentsHome: options.agentsHome ?? "",
|
|
13
|
+
};
|
|
14
|
+
// Host reads serve exactly one shape: a skill root resolved without a session
|
|
15
|
+
// cwd, which is how the harness's local skill provider probes it — a project's
|
|
16
|
+
// `<project>/.dsh/skills` or `<project>/.agents/skills`, or the user roots
|
|
17
|
+
// `<dshHome>/skills` and `<agentsHome>/skills`. Those are the same paths the
|
|
18
|
+
// dsh container sees as read-only host trees. Any call carrying a cwd keeps the
|
|
19
|
+
// container route, as does every other path.
|
|
20
|
+
const hostRead = (path, opts) => (opts?.cwd === undefined || opts?.cwd === "") &&
|
|
21
|
+
(isProjectSkillPath(path, projectsRoot) ||
|
|
22
|
+
isUserSkillPath(path, userRoots));
|
|
7
23
|
return {
|
|
8
24
|
resolve: async (path, opts) => {
|
|
9
25
|
throwIfAborted(opts?.signal, "resolve");
|
|
@@ -13,6 +29,10 @@ export function createFilesystemProvider(resolver) {
|
|
|
13
29
|
const container = typeof opts?.container === "string"
|
|
14
30
|
? opts.container
|
|
15
31
|
: "";
|
|
32
|
+
if ((container === "" || container === "default") &&
|
|
33
|
+
hostRead(resolved, opts)) {
|
|
34
|
+
return hostTarget(resolved);
|
|
35
|
+
}
|
|
16
36
|
const binding = container !== "" && container !== "default"
|
|
17
37
|
? await resolver.containerBinding(opts?.cwd, container, opts?.signal)
|
|
18
38
|
: await resolver.resolveForPath(resolved, opts?.cwd, opts?.signal);
|
|
@@ -29,9 +49,16 @@ export function createFilesystemProvider(resolver) {
|
|
|
29
49
|
fileUrl: (target) => `file://${target.targetKey}`,
|
|
30
50
|
contains: (parent, child) => child.targetKey === parent.targetKey ||
|
|
31
51
|
child.targetKey.startsWith(`${parent.targetKey}/`),
|
|
32
|
-
readText: (target, signal) =>
|
|
33
|
-
|
|
52
|
+
readText: (target, signal) => isHostTarget(target)
|
|
53
|
+
? hostReadText(target, signal)
|
|
54
|
+
: readGuestText(target, signal),
|
|
55
|
+
streamText: (target, signal) => Promise.resolve(isHostTarget(target)
|
|
56
|
+
? hostTextChunks(target, signal)
|
|
57
|
+
: guestTextChunks(target, signal)),
|
|
34
58
|
readBytes: async (target, signal, maxBytes) => {
|
|
59
|
+
if (isHostTarget(target)) {
|
|
60
|
+
return await hostReadBytes(target, signal, maxBytes);
|
|
61
|
+
}
|
|
35
62
|
const chunks = [];
|
|
36
63
|
let total = 0;
|
|
37
64
|
for await (const buffer of guestChunks(target, { length: maxBytes + 1 }, signal)) {
|
|
@@ -44,6 +71,9 @@ export function createFilesystemProvider(resolver) {
|
|
|
44
71
|
return Buffer.concat(chunks, total);
|
|
45
72
|
},
|
|
46
73
|
readByteRange: async (target, range, signal) => {
|
|
74
|
+
if (isHostTarget(target)) {
|
|
75
|
+
return await hostReadByteRange(target, range, signal);
|
|
76
|
+
}
|
|
47
77
|
if (range.length === 0)
|
|
48
78
|
return new Uint8Array(0);
|
|
49
79
|
const chunks = [];
|
|
@@ -57,6 +87,8 @@ export function createFilesystemProvider(resolver) {
|
|
|
57
87
|
lstat: async (path, opts, signal) => {
|
|
58
88
|
throwIfAborted(signal, "lstat");
|
|
59
89
|
const resolved = resolveGuestPath(path, opts?.cwd);
|
|
90
|
+
if (hostRead(resolved, opts))
|
|
91
|
+
return await hostLstat(resolved, signal);
|
|
60
92
|
const binding = await resolver.resolveForPath(resolved, opts?.cwd, signal);
|
|
61
93
|
const result = await unaryGuest({ binding }, "stat", { path: resolved, noFollow: true }, signal);
|
|
62
94
|
if (!result?.exists)
|
|
@@ -74,6 +106,8 @@ export function createFilesystemProvider(resolver) {
|
|
|
74
106
|
};
|
|
75
107
|
},
|
|
76
108
|
writeText: async (target, content, expected, signal) => {
|
|
109
|
+
if (isHostTarget(target))
|
|
110
|
+
hostRefuse("write", target);
|
|
77
111
|
throwIfAborted(signal, "write");
|
|
78
112
|
const current = await guestStatResponse(target, signal);
|
|
79
113
|
if (current.exists && current.isDir) {
|
|
@@ -112,8 +146,12 @@ export function createFilesystemProvider(resolver) {
|
|
|
112
146
|
after: normalizeLineEndings(content),
|
|
113
147
|
};
|
|
114
148
|
},
|
|
115
|
-
stat: (target, signal) =>
|
|
149
|
+
stat: (target, signal) => isHostTarget(target)
|
|
150
|
+
? hostStat(target, signal)
|
|
151
|
+
: guestStat(target, signal),
|
|
116
152
|
listDir: async (target, signal) => {
|
|
153
|
+
if (isHostTarget(target))
|
|
154
|
+
return await hostListDir(target, signal);
|
|
117
155
|
const response = await unaryGuest(target, "readDir", { path: target.targetKey }, signal);
|
|
118
156
|
const entries = Array.isArray(response?.entries)
|
|
119
157
|
? response.entries
|
|
@@ -145,9 +183,25 @@ export function createFilesystemProvider(resolver) {
|
|
|
145
183
|
};
|
|
146
184
|
});
|
|
147
185
|
},
|
|
148
|
-
mkdir: async (target, parents = true) =>
|
|
149
|
-
|
|
186
|
+
mkdir: async (target, parents = true) => {
|
|
187
|
+
if (isHostTarget(target))
|
|
188
|
+
hostRefuse("create", target);
|
|
189
|
+
return await unaryGuest(target, "mkdir", {
|
|
190
|
+
path: target.targetKey,
|
|
191
|
+
parents,
|
|
192
|
+
});
|
|
193
|
+
},
|
|
194
|
+
remove: async (target, recursive = false) => {
|
|
195
|
+
if (isHostTarget(target))
|
|
196
|
+
hostRefuse("remove", target);
|
|
197
|
+
return await unaryGuest(target, "delete", {
|
|
198
|
+
path: target.targetKey,
|
|
199
|
+
recursive,
|
|
200
|
+
});
|
|
201
|
+
},
|
|
150
202
|
editText: async (target, edit, expected, signal) => {
|
|
203
|
+
if (isHostTarget(target))
|
|
204
|
+
hostRefuse("edit", target);
|
|
151
205
|
throwIfAborted(signal, "edit");
|
|
152
206
|
const current = await guestStatResponse(target, signal);
|
|
153
207
|
if (!current.exists) {
|
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export declare const VERSION = "1.
|
|
2
|
-
export declare const GIT_COMMIT = "
|
|
1
|
+
export declare const VERSION = "1.2.1";
|
|
2
|
+
export declare const GIT_COMMIT = "d06afd6";
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
export declare const HOST_BINDING: {
|
|
2
|
+
readonly host: true;
|
|
3
|
+
};
|
|
4
|
+
export declare function hostTarget(path: string): any;
|
|
5
|
+
export declare function isHostTarget(target: any): boolean;
|
|
6
|
+
export declare function hostLstat(path: string, signal?: AbortSignal): Promise<any | undefined>;
|
|
7
|
+
export declare function hostStat(target: any, signal?: AbortSignal): Promise<any | undefined>;
|
|
8
|
+
export declare function hostListDir(target: any, signal?: AbortSignal): Promise<any[]>;
|
|
9
|
+
export declare function hostReadText(target: any, signal?: AbortSignal): Promise<string>;
|
|
10
|
+
export declare function hostTextChunks(target: any, signal?: AbortSignal): AsyncIterable<string>;
|
|
11
|
+
export declare function hostReadBytes(target: any, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>;
|
|
12
|
+
export declare function hostReadByteRange(target: any, range: {
|
|
13
|
+
offset: number;
|
|
14
|
+
length: number;
|
|
15
|
+
}, signal?: AbortSignal): Promise<Uint8Array>;
|
|
16
|
+
export declare function hostRefuse(operation: string, target: any): never;
|
package/dist/host-fs.js
ADDED
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
|
|
2
|
+
//
|
|
3
|
+
// SPDX-License-Identifier: MIT
|
|
4
|
+
import { createReadStream } from "node:fs";
|
|
5
|
+
import { lstat, open, readdir, readFile, stat } from "node:fs/promises";
|
|
6
|
+
import { join } from "node:path";
|
|
7
|
+
import { fsError, throwIfAborted } from "./guest-rpc.js";
|
|
8
|
+
// The host half of the filesystem provider: a read-only view of a project's
|
|
9
|
+
// skill roots. The plugin serves them here rather than through a container
|
|
10
|
+
// because the skill provider resolves each root without a session cwd, and a
|
|
11
|
+
// container-backed provider cannot pick a workspace for such a path. The dsh
|
|
12
|
+
// container mounts the projects root read-only, so these are the same files, at
|
|
13
|
+
// the same paths, that the workspace's container sees.
|
|
14
|
+
//
|
|
15
|
+
// Every mutation is refused: a skill is an instruction the model follows, and
|
|
16
|
+
// the container route (which every tool call uses, by passing the session cwd)
|
|
17
|
+
// stays the only writer.
|
|
18
|
+
export const HOST_BINDING = { host: true };
|
|
19
|
+
// hostTarget builds the target shape the rest of the provider passes around.
|
|
20
|
+
export function hostTarget(path) {
|
|
21
|
+
return {
|
|
22
|
+
targetKey: path,
|
|
23
|
+
displayPath: path,
|
|
24
|
+
binding: HOST_BINDING,
|
|
25
|
+
host: true,
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
// isHostTarget reports whether a target came from this host view.
|
|
29
|
+
export function isHostTarget(target) {
|
|
30
|
+
return target?.host === true;
|
|
31
|
+
}
|
|
32
|
+
// hostVersion keeps host reads in their own version namespace, so a version
|
|
33
|
+
// taken from one world can never be mistaken for the other's.
|
|
34
|
+
function hostVersion(info) {
|
|
35
|
+
return `host:${Math.trunc(info.mtimeMs)}:${info.size}:${info.mode}`;
|
|
36
|
+
}
|
|
37
|
+
// entryType names a directory entry the way the guest does.
|
|
38
|
+
function entryType(info) {
|
|
39
|
+
if (info.isDirectory())
|
|
40
|
+
return "directory";
|
|
41
|
+
if (info.isFile())
|
|
42
|
+
return "file";
|
|
43
|
+
return "other";
|
|
44
|
+
}
|
|
45
|
+
// isMissing reports the codes that mean "this path is not here", which the
|
|
46
|
+
// harness's callers treat as an absent entry rather than a failure.
|
|
47
|
+
function isMissing(error) {
|
|
48
|
+
const code = error?.code;
|
|
49
|
+
return code === "ENOENT" || code === "ENOTDIR";
|
|
50
|
+
}
|
|
51
|
+
// hostLstat stats a path without following a final symbolic link.
|
|
52
|
+
export async function hostLstat(path, signal) {
|
|
53
|
+
throwIfAborted(signal, "lstat");
|
|
54
|
+
let info;
|
|
55
|
+
try {
|
|
56
|
+
info = await lstat(path);
|
|
57
|
+
}
|
|
58
|
+
catch (error) {
|
|
59
|
+
if (isMissing(error))
|
|
60
|
+
return undefined;
|
|
61
|
+
throw error;
|
|
62
|
+
}
|
|
63
|
+
return {
|
|
64
|
+
version: hostVersion(info),
|
|
65
|
+
type: info.isSymbolicLink() ? "symlink" : entryType(info),
|
|
66
|
+
...(info.isSymbolicLink() ? {} : { size: info.size }),
|
|
67
|
+
};
|
|
68
|
+
}
|
|
69
|
+
// hostStat stats a path, following symbolic links.
|
|
70
|
+
export async function hostStat(target, signal) {
|
|
71
|
+
throwIfAborted(signal, "stat");
|
|
72
|
+
let info;
|
|
73
|
+
try {
|
|
74
|
+
info = await stat(target.targetKey);
|
|
75
|
+
}
|
|
76
|
+
catch (error) {
|
|
77
|
+
if (isMissing(error))
|
|
78
|
+
return undefined;
|
|
79
|
+
throw error;
|
|
80
|
+
}
|
|
81
|
+
return {
|
|
82
|
+
version: hostVersion(info),
|
|
83
|
+
type: info.isDirectory() ? "directory" : "file",
|
|
84
|
+
...(info.isDirectory() ? {} : { size: info.size }),
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
// hostListDir lists a directory, following entry links so a bundle reached
|
|
88
|
+
// through a symbolic link is still a directory entry.
|
|
89
|
+
export async function hostListDir(target, signal) {
|
|
90
|
+
throwIfAborted(signal, "readDir");
|
|
91
|
+
const entries = await readdir(target.targetKey, { withFileTypes: true });
|
|
92
|
+
const listed = [];
|
|
93
|
+
for (const entry of entries) {
|
|
94
|
+
throwIfAborted(signal, "readDir");
|
|
95
|
+
const childKey = join(target.targetKey, entry.name);
|
|
96
|
+
let info;
|
|
97
|
+
try {
|
|
98
|
+
info = await stat(childKey);
|
|
99
|
+
}
|
|
100
|
+
catch (error) {
|
|
101
|
+
if (!isMissing(error))
|
|
102
|
+
throw error;
|
|
103
|
+
info = entry;
|
|
104
|
+
}
|
|
105
|
+
listed.push({
|
|
106
|
+
name: entry.name,
|
|
107
|
+
type: entryType(info),
|
|
108
|
+
target: hostTarget(childKey),
|
|
109
|
+
...(info.isFile() ? { size: info.size } : {}),
|
|
110
|
+
});
|
|
111
|
+
}
|
|
112
|
+
return listed;
|
|
113
|
+
}
|
|
114
|
+
// hostReadText reads a file as UTF-8.
|
|
115
|
+
export async function hostReadText(target, signal) {
|
|
116
|
+
throwIfAborted(signal, "read");
|
|
117
|
+
return await readFile(target.targetKey, { encoding: "utf8", signal });
|
|
118
|
+
}
|
|
119
|
+
// hostTextChunks streams a file as UTF-8 chunks.
|
|
120
|
+
export async function* hostTextChunks(target, signal) {
|
|
121
|
+
throwIfAborted(signal, "read");
|
|
122
|
+
const stream = createReadStream(target.targetKey, {
|
|
123
|
+
encoding: "utf8",
|
|
124
|
+
signal,
|
|
125
|
+
});
|
|
126
|
+
for await (const chunk of stream)
|
|
127
|
+
yield String(chunk);
|
|
128
|
+
}
|
|
129
|
+
// hostByteChunks reads at most range.length bytes from range.offset.
|
|
130
|
+
async function* hostByteChunks(target, range, signal) {
|
|
131
|
+
const handle = await open(target.targetKey, "r");
|
|
132
|
+
try {
|
|
133
|
+
const bufferSize = 64 * 1024;
|
|
134
|
+
let position = range.offset;
|
|
135
|
+
let remaining = range.length;
|
|
136
|
+
while (remaining > 0) {
|
|
137
|
+
throwIfAborted(signal, "read");
|
|
138
|
+
const length = Math.min(bufferSize, remaining);
|
|
139
|
+
const buffer = Buffer.allocUnsafe(length);
|
|
140
|
+
const { bytesRead } = await handle.read(buffer, 0, length, position);
|
|
141
|
+
if (bytesRead === 0)
|
|
142
|
+
break;
|
|
143
|
+
position += bytesRead;
|
|
144
|
+
remaining -= bytesRead;
|
|
145
|
+
yield buffer.subarray(0, bytesRead);
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
finally {
|
|
149
|
+
await handle.close();
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
// hostReadBytes reads a whole file, refusing content above maxBytes.
|
|
153
|
+
export async function hostReadBytes(target, signal, maxBytes) {
|
|
154
|
+
const chunks = [];
|
|
155
|
+
let total = 0;
|
|
156
|
+
for await (const buffer of hostByteChunks(target, { offset: 0, length: maxBytes + 1 }, signal)) {
|
|
157
|
+
total += buffer.length;
|
|
158
|
+
if (total > maxBytes) {
|
|
159
|
+
throw fsError("FS_TOO_LARGE", `cannot read "${target.displayPath}": content exceeds the ${maxBytes}-byte limit`);
|
|
160
|
+
}
|
|
161
|
+
chunks.push(buffer);
|
|
162
|
+
}
|
|
163
|
+
return Buffer.concat(chunks, total);
|
|
164
|
+
}
|
|
165
|
+
// hostReadByteRange reads one byte range of a file.
|
|
166
|
+
export async function hostReadByteRange(target, range, signal) {
|
|
167
|
+
if (range.length === 0)
|
|
168
|
+
return new Uint8Array(0);
|
|
169
|
+
const chunks = [];
|
|
170
|
+
let total = 0;
|
|
171
|
+
for await (const buffer of hostByteChunks(target, range, signal)) {
|
|
172
|
+
total += buffer.length;
|
|
173
|
+
chunks.push(buffer);
|
|
174
|
+
}
|
|
175
|
+
return Buffer.concat(chunks, total);
|
|
176
|
+
}
|
|
177
|
+
// hostRefuse rejects a mutation of a read-only skill root with the harness's
|
|
178
|
+
// permission code.
|
|
179
|
+
export function hostRefuse(operation, target) {
|
|
180
|
+
throw fsError("FS_PERMISSION_DENIED", `cannot ${operation} "${target.displayPath}": skill roots are read-only`);
|
|
181
|
+
}
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
|
|
2
2
|
//
|
|
3
3
|
// SPDX-License-Identifier: MIT
|
|
4
|
+
import { homedir } from "node:os";
|
|
5
|
+
import { join } from "node:path";
|
|
4
6
|
import { isSandboxEscalation, preExecutePolicy, } from "./approval.js";
|
|
5
7
|
import { resolveReasonLocale } from "./approval-reasons.js";
|
|
6
8
|
import { createFilesystemProvider } from "./fs-provider.js";
|
|
@@ -89,7 +91,18 @@ export function apply(ctx, config) {
|
|
|
89
91
|
const subprocess = createSubprocessProvider(resolver);
|
|
90
92
|
ctx.provide("subprocess", subprocess);
|
|
91
93
|
ctx.effect(() => () => subprocess.dispose(), "podman: subprocess cleanup");
|
|
92
|
-
|
|
94
|
+
// The projects root is what the harness builds a project's skill roots under,
|
|
95
|
+
// and the two user homes are what it builds the user-level skill roots under
|
|
96
|
+
// (`$DSH_HOME` or `~/.dsh`, `$DSH_AGENTS_HOME` or `~/.agents`). The provider
|
|
97
|
+
// reads those roots from the host filesystem when a caller passes no session
|
|
98
|
+
// cwd, which is the shape the local skill provider probes with; every other
|
|
99
|
+
// call keeps the container route.
|
|
100
|
+
const home = homedir();
|
|
101
|
+
ctx.provide("fs", createFilesystemProvider(resolver, {
|
|
102
|
+
projectsRoot: process.env.DSH_PODMAN_PROJECTS_ROOT ?? "/projects",
|
|
103
|
+
dshHome: process.env.DSH_HOME ?? join(home, ".dsh"),
|
|
104
|
+
agentsHome: process.env.DSH_AGENTS_HOME ?? join(home, ".agents"),
|
|
105
|
+
}));
|
|
93
106
|
// Oversized tool results spill inside the session's container, so the agent
|
|
94
107
|
// can read them back with the container file tools; the harness's local
|
|
95
108
|
// (host-filesystem) spill backend is disabled by the bundle patch.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export declare function isProjectSkillPath(path: string, projectsRoot: string): boolean;
|
|
2
|
+
export interface UserSkillRoots {
|
|
3
|
+
readonly dshHome: string;
|
|
4
|
+
readonly agentsHome: string;
|
|
5
|
+
}
|
|
6
|
+
export declare function isUserSkillPath(path: string, roots: UserSkillRoots): boolean;
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
|
|
2
|
+
//
|
|
3
|
+
// SPDX-License-Identifier: MIT
|
|
4
|
+
import { isAbsolute, join, relative } from "node:path";
|
|
5
|
+
// The local skill roots the harness scans: for one project root its `.dsh/skills`
|
|
6
|
+
// and `.agents/skills` directories, plus the two user roots `<dshHome>/skills` and
|
|
7
|
+
// `<agentsHome>/skills`. A project root itself is the nearest ancestor of the
|
|
8
|
+
// session cwd containing `.git`, else the cwd, so a session running in a
|
|
9
|
+
// subdirectory with its own `.git` scans that level.
|
|
10
|
+
//
|
|
11
|
+
// The local provider resolves each root with `fs.resolve(root)` and no session
|
|
12
|
+
// cwd, which a container-backed filesystem can only answer by containment, so
|
|
13
|
+
// this plugin reads those roots from the host filesystem instead. Each matcher is
|
|
14
|
+
// anchored at a root boundary, so no unrelated path can match.
|
|
15
|
+
// isProjectSkillPath reports whether path is a project skill root, or lies
|
|
16
|
+
// inside one, for a project under projectsRoot.
|
|
17
|
+
export function isProjectSkillPath(path, projectsRoot) {
|
|
18
|
+
if (!isAbsolute(path) || projectsRoot === "" || !isAbsolute(projectsRoot)) {
|
|
19
|
+
return false;
|
|
20
|
+
}
|
|
21
|
+
const relativePath = relative(projectsRoot, path);
|
|
22
|
+
if (relativePath === "" ||
|
|
23
|
+
relativePath.startsWith("..") ||
|
|
24
|
+
isAbsolute(relativePath)) {
|
|
25
|
+
return false;
|
|
26
|
+
}
|
|
27
|
+
const segments = relativePath.split("/");
|
|
28
|
+
for (let index = 0; index < segments.length - 1; index += 1) {
|
|
29
|
+
const parent = segments[index];
|
|
30
|
+
if ((parent === ".dsh" || parent === ".agents") &&
|
|
31
|
+
segments[index + 1] === "skills") {
|
|
32
|
+
return true;
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
return false;
|
|
36
|
+
}
|
|
37
|
+
// isUserSkillPath reports whether path is one of the user skill roots, or lies
|
|
38
|
+
// inside one.
|
|
39
|
+
export function isUserSkillPath(path, roots) {
|
|
40
|
+
if (!isAbsolute(path))
|
|
41
|
+
return false;
|
|
42
|
+
return (isUnderSkillDir(path, roots.dshHome) ||
|
|
43
|
+
isUnderSkillDir(path, roots.agentsHome));
|
|
44
|
+
}
|
|
45
|
+
// skillDirFor resolves one user home to its skill directory, or "" when the home
|
|
46
|
+
// is unusable, so a missing environment variable cannot widen the matcher.
|
|
47
|
+
function skillDirFor(home) {
|
|
48
|
+
return home === "" || !isAbsolute(home) ? "" : join(home, "skills");
|
|
49
|
+
}
|
|
50
|
+
function isUnderSkillDir(path, home) {
|
|
51
|
+
const root = skillDirFor(home);
|
|
52
|
+
if (root === "")
|
|
53
|
+
return false;
|
|
54
|
+
return path === root || path.startsWith(`${root}/`);
|
|
55
|
+
}
|
package/docs/architecture.md
CHANGED
|
@@ -6,6 +6,8 @@ SPDX-License-Identifier: MIT
|
|
|
6
6
|
|
|
7
7
|
# Architecture
|
|
8
8
|
|
|
9
|
+
English | [中文](architecture.zh.md)
|
|
10
|
+
|
|
9
11
|
dsh-podman has four components:
|
|
10
12
|
|
|
11
13
|
| Component | Runs | What it does |
|
|
@@ -115,6 +117,19 @@ to a symlink before podman resolves it, on a create or on any later restart. A
|
|
|
115
117
|
container being replaced is stopped before its mounts are resolved again, so its
|
|
116
118
|
own processes cannot race the create either.
|
|
117
119
|
|
|
120
|
+
Skills are read from the host filesystem rather than through a container: the
|
|
121
|
+
local skill provider probes `<project>/.dsh/skills`, `<project>/.agents/skills`,
|
|
122
|
+
and the user roots `<dshHome>/skills` and `<agentsHome>/skills` with no session
|
|
123
|
+
cwd, which a container-backed filesystem cannot answer. The plugin serves
|
|
124
|
+
exactly those paths read-only and refuses mutations, and every call carrying a
|
|
125
|
+
cwd keeps the container route. The dsh container mounts `~/.agents` read-only,
|
|
126
|
+
and the orchestrator adds the configured host skill directory — one read-only
|
|
127
|
+
bind whose source and destination are the same path, listed in the guest file
|
|
128
|
+
API — to every guest container. A directory under the DSH root is never mounted
|
|
129
|
+
into a container: the dsh container mounts `~/.dsh` read-write itself, so a
|
|
130
|
+
symlink swapped in there would be followed by podman, the hazard the
|
|
131
|
+
project-mount rule above already prevents.
|
|
132
|
+
|
|
118
133
|
## Guest agent and daemons
|
|
119
134
|
|
|
120
135
|
The orchestrator starts the guest agent inside each container over the
|
package/docs/architecture.zh.md
CHANGED
|
@@ -6,6 +6,8 @@ SPDX-License-Identifier: MIT
|
|
|
6
6
|
|
|
7
7
|
# 架构
|
|
8
8
|
|
|
9
|
+
[English](architecture.md) | 中文
|
|
10
|
+
|
|
9
11
|
dsh-podman 由四个组件组成:
|
|
10
12
|
|
|
11
13
|
| 组件 | 运行位置 | 功能 |
|
|
@@ -90,6 +92,16 @@ orchestrator 校验的路径与 podman
|
|
|
90
92
|
agent 就能在 podman
|
|
91
93
|
解析之前(创建时或之后任何一次重启时)把内层路径的某个组件改名为符号链接。被替换的容器会先停止,再重新解析其挂载,因此它自己的进程也无法与创建过程竞争。
|
|
92
94
|
|
|
95
|
+
skill 从宿主机文件系统读取,而不是通过容器:本地 skill provider 会在没有会话 cwd
|
|
96
|
+
的情况下探测 `<project>/.dsh/skills`、`<project>/.agents/skills`,以及用户根目录
|
|
97
|
+
`<dshHome>/skills` 与
|
|
98
|
+
`<agentsHome>/skills`,而由容器支撑的文件系统无法回答这类请求。插件只以只读方式提供这些路径并拒绝写入,任何携带
|
|
99
|
+
cwd 的调用仍走容器路径。dsh 容器以只读方式挂载 `~/.agents`,orchestrator
|
|
100
|
+
则把配置的宿主机 skill 目录——一个源路径与目标路径相同的只读绑定挂载,并在 guest
|
|
101
|
+
文件 API 中登记——加到每个 guest 容器中。DSH 根目录下的目录绝不会挂载进容器:dsh
|
|
102
|
+
容器本身就以读写方式挂载了 `~/.dsh`,因此被替换其中的符号链接会被 podman
|
|
103
|
+
跟随,这正是上面项目挂载规则所防范的风险。
|
|
104
|
+
|
|
93
105
|
## Guest agent 与守护进程
|
|
94
106
|
|
|
95
107
|
orchestrator 通过容器的套接字目录在每个容器内启动 guest agent(来宾代理)。guest
|
package/docs/configuration.md
CHANGED
|
@@ -6,6 +6,8 @@ SPDX-License-Identifier: MIT
|
|
|
6
6
|
|
|
7
7
|
# Configuration
|
|
8
8
|
|
|
9
|
+
English | [中文](configuration.zh.md)
|
|
10
|
+
|
|
9
11
|
Environment variables use the `DSH_PODMAN_` prefix and are listed under the
|
|
10
12
|
component that reads them (a variable read by several components appears in each
|
|
11
13
|
of their sections). The plugin also exposes a few **UI settings** on its
|
|
@@ -71,6 +73,7 @@ for secrets (see [Secrets](usage.md#secrets)).
|
|
|
71
73
|
| `DSH_PODMAN_HOST_GUEST_AGENT_BIN` | — | Host-side guest agent binary path; bind-mounted when set; see [Variable details](#variable-details) |
|
|
72
74
|
| `DSH_PODMAN_HOST_PACMAN_CACHE` | — | Host-absolute directory mounted at `/var/cache/pacman/pkg` to persist downloaded packages across pacman builds; unset disables caching |
|
|
73
75
|
| `DSH_PODMAN_HOST_PROJECTS_ROOT` | `DSH_PODMAN_PROJECTS_ROOT` | Host-side projects root used as the source of bind mounts |
|
|
76
|
+
| `DSH_PODMAN_HOST_SKILL_DIR` | — | Host-absolute directory of user-level skills, mounted read-only at the same path in every guest container; unset disables it; see [Variable details](#variable-details) |
|
|
74
77
|
| `DSH_PODMAN_GATEWAY_TOKEN` | — | Optional shared secret for gateway calls (`orchestrator` → gateway); see [Variable details](#variable-details) |
|
|
75
78
|
| `DSH_PODMAN_HOST_SOCKETS_ROOT` | required | Host-side sockets root for guest socket bind mounts; see [Variable details](#variable-details) |
|
|
76
79
|
| `DSH_PODMAN_IMAGE_PREFIX` | `localhost/dsh-podman/` | Prefix prepended to built workspace image references |
|
|
@@ -226,3 +229,20 @@ both processes create them under a `0077` umask so the socket is never briefly
|
|
|
226
229
|
reachable between `bind` and `chmod`. The guest agent then restores the
|
|
227
230
|
conventional `0022` mask, so the commands it runs create files `0644` and
|
|
228
231
|
directories `0755`.
|
|
232
|
+
|
|
233
|
+
### `DSH_PODMAN_HOST_SKILL_DIR`
|
|
234
|
+
|
|
235
|
+
The directory of user-level skills (`~/.agents/skills` in the shipped Quadlet),
|
|
236
|
+
bind-mounted read-only at the same path into every guest container, so a skill's
|
|
237
|
+
scripts run where the agent works. Unset it to mount nothing.
|
|
238
|
+
|
|
239
|
+
The value must be an absolute, cleaned path that does not overlap a reserved
|
|
240
|
+
container path (`DSH_PODMAN_PROJECTS_ROOT`, `DSH_PODMAN_SOCKETS_ROOT`,
|
|
241
|
+
`DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT`, the spill root, `/tmp`, `/var/tmp`, `/`);
|
|
242
|
+
the orchestrator refuses to start otherwise.
|
|
243
|
+
|
|
244
|
+
It must never point inside the DSH root (`~/.dsh`). That tree is mounted
|
|
245
|
+
read-write into the dsh container, and podman follows symlinks on a bind source,
|
|
246
|
+
so a plugin could replace the directory with a link and have its target mounted
|
|
247
|
+
into a guest. `~/.dsh/skills` is therefore read by dsh but never mounted into a
|
|
248
|
+
container.
|
package/docs/configuration.zh.md
CHANGED
|
@@ -6,6 +6,8 @@ SPDX-License-Identifier: MIT
|
|
|
6
6
|
|
|
7
7
|
# 配置
|
|
8
8
|
|
|
9
|
+
[English](configuration.md) | 中文
|
|
10
|
+
|
|
9
11
|
环境变量使用 `DSH_PODMAN_`
|
|
10
12
|
前缀,并按读取它们的组件分组列出(被多个组件读取的变量会出现在每个组件的对应章节中)。插件还在
|
|
11
13
|
侧边栏 **插件** 面板 → **已安装** 中的 **dsh-podman** 页面中暴露了一些 **UI
|
|
@@ -65,6 +67,7 @@ Podman
|
|
|
65
67
|
| `DSH_PODMAN_HOST_GUEST_AGENT_BIN` | — | 主机侧的 guest agent 二进制路径;设置后会绑定挂载;见[变量详解](#变量详解) |
|
|
66
68
|
| `DSH_PODMAN_HOST_PACMAN_CACHE` | — | 挂载在 `/var/cache/pacman/pkg` 的主机绝对路径目录,用于在 pacman 构建之间持久化已下载的软件包;未设置时禁用缓存 |
|
|
67
69
|
| `DSH_PODMAN_HOST_PROJECTS_ROOT` | `DSH_PODMAN_PROJECTS_ROOT` | 用作绑定挂载源的主机侧项目根目录 |
|
|
70
|
+
| `DSH_PODMAN_HOST_SKILL_DIR` | — | 用户级 skill 的主机绝对路径目录,以只读方式按相同路径挂载进每个 guest 容器;未设置则不挂载;见[变量详解](#变量详解) |
|
|
68
71
|
| `DSH_PODMAN_GATEWAY_TOKEN` | — | gateway 调用(`orchestrator` → gateway)的可选共享机密;见[变量详解](#变量详解) |
|
|
69
72
|
| `DSH_PODMAN_HOST_SOCKETS_ROOT` | required | 用于 guest 套接字绑定挂载的主机侧套接字根目录;见[变量详解](#变量详解) |
|
|
70
73
|
| `DSH_PODMAN_IMAGE_PREFIX` | `localhost/dsh-podman/` | 前置到已构建的工作区镜像引用上的前缀 |
|
|
@@ -204,3 +207,18 @@ Quadlet 会挂载 `%h/.dsh/dsh-podman/state`。orchestrator
|
|
|
204
207
|
下创建它们,这样套接字在 `bind` 和 `chmod` 之间永远不会被短暂访问。随后 guest
|
|
205
208
|
agent 会恢复常规的 `0022` umask,因此它运行的命令创建的文件为 `0644`、目录为
|
|
206
209
|
`0755`。
|
|
210
|
+
|
|
211
|
+
### `DSH_PODMAN_HOST_SKILL_DIR`
|
|
212
|
+
|
|
213
|
+
用户级 skill 所在目录(随附的 Quadlet 中为
|
|
214
|
+
`~/.agents/skills`),以只读方式按相同路径挂载进 每个 guest 容器,使 skill
|
|
215
|
+
的脚本能在 agent 工作的地方运行。不设置则不挂载。
|
|
216
|
+
|
|
217
|
+
该值必须是绝对且已规范化的路径,且不得与保留的容器路径重叠(`DSH_PODMAN_PROJECTS_ROOT`、
|
|
218
|
+
`DSH_PODMAN_SOCKETS_ROOT`、`DSH_PODMAN_GUEST_AGENT_IMAGE_MOUNT`、溢出目录、`/tmp`、
|
|
219
|
+
`/var/tmp`、`/`);否则 orchestrator 会拒绝启动。
|
|
220
|
+
|
|
221
|
+
它绝不能指向 DSH 根目录(`~/.dsh`)内的路径。该目录树以读写方式挂载进 dsh
|
|
222
|
+
容器,而 podman
|
|
223
|
+
会跟随绑定挂载源上的符号链接,因此插件可以把该目录替换为链接,让其目标被挂载进
|
|
224
|
+
guest。正因如此,`~/.dsh/skills` 会被 dsh 读取,但绝不会挂载进任何容器。
|
|
@@ -6,6 +6,8 @@ SPDX-License-Identifier: MIT
|
|
|
6
6
|
|
|
7
7
|
# Development container setup prompt
|
|
8
8
|
|
|
9
|
+
English | [中文](development-prompt.zh.md)
|
|
10
|
+
|
|
9
11
|
This page carries the prompt that builds a development image, creates the
|
|
10
12
|
toolchain volume and wires the workspace container to it, as described in
|
|
11
13
|
[Development](development.md#development-container-toolchain). Nothing it needs
|
package/docs/development.md
CHANGED
|
@@ -6,6 +6,8 @@ SPDX-License-Identifier: MIT
|
|
|
6
6
|
|
|
7
7
|
# Development
|
|
8
8
|
|
|
9
|
+
English | [中文](development.zh.md)
|
|
10
|
+
|
|
9
11
|
This page is for **contributors** building the plugin from this repository.
|
|
10
12
|
|
|
11
13
|
## Repository layout
|
|
@@ -34,7 +36,7 @@ host C headers; `make` applies the same tags automatically.
|
|
|
34
36
|
The `Makefile` wraps the common workflows:
|
|
35
37
|
|
|
36
38
|
```sh
|
|
37
|
-
make build-go # build
|
|
39
|
+
make build-go # build the Go binaries into bin/<os>-<arch>/
|
|
38
40
|
make build # build-go + pnpm-build
|
|
39
41
|
make vet # gofmt -s check + go vet with the build tags
|
|
40
42
|
make test-go # go test with the build tags
|
|
@@ -44,7 +46,8 @@ make fmt-check # verify the formatting without rewriting anything
|
|
|
44
46
|
make proto # regenerate the protobuf Go bindings with buf
|
|
45
47
|
make proto-check # buf lint + buf breaking + check the committed bindings are current
|
|
46
48
|
make download-licenses # generate third-party-licenses.pkg from the project and third-party Go licenses
|
|
47
|
-
make image
|
|
49
|
+
make image-go # build the Go container images (orchestrator, guest-agent, gateway)
|
|
50
|
+
make image # image-go + the dsh container image
|
|
48
51
|
```
|
|
49
52
|
|
|
50
53
|
`make image` depends on `third-party-licenses.pkg`: the `download-licenses`
|
package/docs/development.zh.md
CHANGED
|
@@ -6,6 +6,8 @@ SPDX-License-Identifier: MIT
|
|
|
6
6
|
|
|
7
7
|
# 开发
|
|
8
8
|
|
|
9
|
+
[English](development.md) | 中文
|
|
10
|
+
|
|
9
11
|
本页面向从本仓库构建插件的**贡献者**。
|
|
10
12
|
|
|
11
13
|
## 仓库结构
|
|
@@ -34,7 +36,7 @@ Go 构建标签会跳过 btrfs 和 devicemapper 存储驱动,它们需要宿
|
|
|
34
36
|
`Makefile` 封装了常见的工作流:
|
|
35
37
|
|
|
36
38
|
```sh
|
|
37
|
-
make build-go # build
|
|
39
|
+
make build-go # build the Go binaries into bin/<os>-<arch>/
|
|
38
40
|
make build # build-go + pnpm-build
|
|
39
41
|
make vet # gofmt -s check + go vet with the build tags
|
|
40
42
|
make test-go # go test with the build tags
|
|
@@ -44,7 +46,8 @@ make fmt-check # verify the formatting without rewriting anything
|
|
|
44
46
|
make proto # regenerate the protobuf Go bindings with buf
|
|
45
47
|
make proto-check # buf lint + buf breaking + check the committed bindings are current
|
|
46
48
|
make download-licenses # generate third-party-licenses.pkg from the project and third-party Go licenses
|
|
47
|
-
make image
|
|
49
|
+
make image-go # build the Go container images (orchestrator, guest-agent, gateway)
|
|
50
|
+
make image # image-go + the dsh container image
|
|
48
51
|
```
|
|
49
52
|
|
|
50
53
|
`make image` 依赖 `third-party-licenses.pkg`:`download-licenses` 目标会运行
|
package/docs/uninstall.md
CHANGED
|
@@ -6,6 +6,8 @@ SPDX-License-Identifier: MIT
|
|
|
6
6
|
|
|
7
7
|
# Uninstall
|
|
8
8
|
|
|
9
|
+
English | [中文](uninstall.zh.md)
|
|
10
|
+
|
|
9
11
|
This page undoes the [installation guide](install-dsh-and-dsh-podman.md): it
|
|
10
12
|
assumes dsh runs from the dsh-podman image with the orchestrator and the
|
|
11
13
|
gateway, all started from Quadlet units.
|
package/docs/uninstall.zh.md
CHANGED
package/docs/update.md
CHANGED
|
@@ -6,6 +6,8 @@ SPDX-License-Identifier: MIT
|
|
|
6
6
|
|
|
7
7
|
# Update
|
|
8
8
|
|
|
9
|
+
English | [中文](update.zh.md)
|
|
10
|
+
|
|
9
11
|
You should run updates only when no agents are running.
|
|
10
12
|
|
|
11
13
|
Existing guest containers will be recreated afterwards, so running processes and
|
|
@@ -17,6 +19,39 @@ startup.
|
|
|
17
19
|
When enabling auto-updates, it is possible to skip updates while an agent is
|
|
18
20
|
running. Read further to set this up.
|
|
19
21
|
|
|
22
|
+
## Update from before 1.2.0
|
|
23
|
+
|
|
24
|
+
When you update from a version before 1.2.0, copy the updated
|
|
25
|
+
[dsh.container](../quadlet/dsh.container) and
|
|
26
|
+
[dsh-podman-orchestrator.container](../quadlet/dsh-podman-orchestrator.container)
|
|
27
|
+
to `~/.config/containers/systemd/`, then reload systemd configuration and
|
|
28
|
+
restart both services, before the steps below:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
cp quadlet/dsh.container quadlet/dsh-podman-orchestrator.container ~/.config/containers/systemd/
|
|
32
|
+
systemctl --user daemon-reload
|
|
33
|
+
systemctl --user restart dsh-podman-orchestrator dsh
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
If you have customised those files, add the lines instead:
|
|
37
|
+
|
|
38
|
+
- [dsh.container](../quadlet/dsh.container): the `%h/.agents` volume
|
|
39
|
+
(`Volume=%h/.agents:%h/.agents:ro`), `Environment=DSH_AGENTS_HOME=%h/.agents`,
|
|
40
|
+
and `mkdir -p -m 0700 %h/.agents/skills` in the existing `ExecStartPre`;
|
|
41
|
+
- [dsh-podman-orchestrator.container](../quadlet/dsh-podman-orchestrator.container):
|
|
42
|
+
`Environment=DSH_PODMAN_HOST_SKILL_DIR=%h/.agents/skills` and the same `mkdir`
|
|
43
|
+
in the existing `ExecStartPre`.
|
|
44
|
+
|
|
45
|
+
This version adds support for skills (see [Usage](usage.md#skills)). dsh now
|
|
46
|
+
reads them in several locations:
|
|
47
|
+
|
|
48
|
+
- user skills in `~/.dsh/skills` and `~/.agents/skills`;
|
|
49
|
+
- per-project skills in `.dsh/skills` and `.agents/skills` inside a workspace.
|
|
50
|
+
|
|
51
|
+
To let an agent run the code a user skill brings, `~/.agents/skills` is mounted
|
|
52
|
+
read-only into every guest container. `~/.dsh/skills` is read but never mounted
|
|
53
|
+
into a guest container, for security reasons.
|
|
54
|
+
|
|
20
55
|
## Update from before 1.1.0
|
|
21
56
|
|
|
22
57
|
The `dsh-podman-gateway` container is new in 1.1.0: earlier versions did not
|
package/docs/update.zh.md
CHANGED
|
@@ -6,6 +6,8 @@ SPDX-License-Identifier: MIT
|
|
|
6
6
|
|
|
7
7
|
# 更新
|
|
8
8
|
|
|
9
|
+
[English](update.md) | 中文
|
|
10
|
+
|
|
9
11
|
只应在没有 agent 运行时进行更新。
|
|
10
12
|
|
|
11
13
|
现有的 guest 容器随后会被重建,因此运行中的进程和守护进程会被终止。
|
|
@@ -14,6 +16,40 @@ SPDX-License-Identifier: MIT
|
|
|
14
16
|
|
|
15
17
|
启用自动更新后,也可以在 agent 运行时跳过更新。请继续阅读以了解如何设置。
|
|
16
18
|
|
|
19
|
+
## 从 1.2.0 之前的版本更新
|
|
20
|
+
|
|
21
|
+
从 1.2.0 之前的版本更新时,请先把更新后的
|
|
22
|
+
[dsh.container](../quadlet/dsh.container) 与
|
|
23
|
+
[dsh-podman-orchestrator.container](../quadlet/dsh-podman-orchestrator.container)
|
|
24
|
+
复制到 `~/.config/containers/systemd/`,然后重新加载 systemd
|
|
25
|
+
配置并重启这两个服务,再执行后续步骤:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
cp quadlet/dsh.container quadlet/dsh-podman-orchestrator.container ~/.config/containers/systemd/
|
|
29
|
+
systemctl --user daemon-reload
|
|
30
|
+
systemctl --user restart dsh-podman-orchestrator dsh
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
如果你自定义过这些文件,请改为添加以下内容:
|
|
34
|
+
|
|
35
|
+
- [dsh.container](../quadlet/dsh.container):`%h/.agents` 卷
|
|
36
|
+
(`Volume=%h/.agents:%h/.agents:ro`)、
|
|
37
|
+
`Environment=DSH_AGENTS_HOME=%h/.agents`,以及在现有 `ExecStartPre` 中加入
|
|
38
|
+
`mkdir -p -m 0700 %h/.agents/skills`;
|
|
39
|
+
- [dsh-podman-orchestrator.container](../quadlet/dsh-podman-orchestrator.container):
|
|
40
|
+
`Environment=DSH_PODMAN_HOST_SKILL_DIR=%h/.agents/skills`,以及在现有
|
|
41
|
+
`ExecStartPre` 中加入同样的 `mkdir`。
|
|
42
|
+
|
|
43
|
+
本版本新增了对 skill 的支持(见[用法](usage.zh.md#技能))。dsh
|
|
44
|
+
现在会从多个位置读取它们:
|
|
45
|
+
|
|
46
|
+
- 用户 skill:`~/.dsh/skills` 与 `~/.agents/skills`;
|
|
47
|
+
- 项目 skill:工作区内的 `.dsh/skills` 与 `.agents/skills`。
|
|
48
|
+
|
|
49
|
+
为了让 agent 能运行用户 skill 附带的代码,`~/.agents/skills`
|
|
50
|
+
会以只读方式挂载进每个 guest 容器。`~/.dsh/skills` 会被读取,但绝不会挂载进任何
|
|
51
|
+
guest 容器,出于安全原因。
|
|
52
|
+
|
|
17
53
|
## 从 1.1.0 之前的版本更新
|
|
18
54
|
|
|
19
55
|
`dsh-podman-gateway` 容器是 1.1.0 新增的:更早的版本不会提供它的
|
package/docs/usage.md
CHANGED
|
@@ -6,6 +6,8 @@ SPDX-License-Identifier: MIT
|
|
|
6
6
|
|
|
7
7
|
# Usage
|
|
8
8
|
|
|
9
|
+
English | [中文](usage.zh.md)
|
|
10
|
+
|
|
9
11
|
This page documents the model-facing tools, the Podman page, and the image
|
|
10
12
|
model. See [Architecture](architecture.md) for how the pieces fit together.
|
|
11
13
|
|
|
@@ -24,6 +26,27 @@ building a custom image with `image_build` (then `container_start` or
|
|
|
24
26
|
`container_recreate`) for software installs, and toward named volumes rather
|
|
25
27
|
than `tmpfs` for data that must survive a container recreate.
|
|
26
28
|
|
|
29
|
+
## Skills
|
|
30
|
+
|
|
31
|
+
Skills are files, not an API: dsh reads them from the usual locations, and where
|
|
32
|
+
they live decides whether a container can see them.
|
|
33
|
+
|
|
34
|
+
- Project skills live in `.dsh/skills` or `.agents/skills` inside a workspace.
|
|
35
|
+
Workspaces are mounted read-write in their containers, so those skills and
|
|
36
|
+
their scripts work everywhere.
|
|
37
|
+
- User skills live in `~/.agents/skills` (`DSH_AGENTS_HOME`). The dsh container
|
|
38
|
+
mounts that directory read-only, and every guest container mounts it read-only
|
|
39
|
+
too, so a user skill and its scripts work everywhere.
|
|
40
|
+
- User skills in `~/.dsh/skills` (`DSH_HOME`) are read and loaded, but are
|
|
41
|
+
intentionally **not** mounted into containers: the dsh container mounts
|
|
42
|
+
`~/.dsh` read-write itself, and mounting a directory a plugin can rewrite is
|
|
43
|
+
unsafe, because podman follows a symlink left in its place. Their scripts
|
|
44
|
+
therefore cannot run inside a container.
|
|
45
|
+
|
|
46
|
+
The `skill` tool and the `/` menu list the loaded skills. The harness caches the
|
|
47
|
+
menu for an open page, so reload it (or open a new session) after adding or
|
|
48
|
+
editing a skill on the host.
|
|
49
|
+
|
|
27
50
|
## Image model
|
|
28
51
|
|
|
29
52
|
dsh-podman organizes the images its containers run into three tiers:
|
package/docs/usage.zh.md
CHANGED
|
@@ -6,6 +6,8 @@ SPDX-License-Identifier: MIT
|
|
|
6
6
|
|
|
7
7
|
# 使用
|
|
8
8
|
|
|
9
|
+
[English](usage.md) | 中文
|
|
10
|
+
|
|
9
11
|
本页面记录了面向模型的工具、Podman
|
|
10
12
|
页面以及镜像模型。参见[架构](architecture.zh.md)了解各部分如何组合在一起。
|
|
11
13
|
|
|
@@ -21,6 +23,26 @@ dsh-podman 还会添加自己的提示词区段,说明内置的 shell
|
|
|
21
23
|
构建自定义镜像(再用 `container_start` 或 `container_recreate`
|
|
22
24
|
启动),需要跨容器重建保留的数据应使用命名卷而非 `tmpfs`。
|
|
23
25
|
|
|
26
|
+
## 技能
|
|
27
|
+
|
|
28
|
+
skill 就是文件,不是 API:dsh
|
|
29
|
+
从固定位置读取它们,而它们所在的位置决定了容器能否看到。
|
|
30
|
+
|
|
31
|
+
- 项目 skill 位于工作区内的 `.dsh/skills` 或
|
|
32
|
+
`.agents/skills`。工作区以读写方式挂载进其容器, 因此这些 skill
|
|
33
|
+
及其脚本在任何地方都能使用。
|
|
34
|
+
- 用户 skill 位于 `~/.agents/skills`(`DSH_AGENTS_HOME`)。dsh
|
|
35
|
+
容器以只读方式挂载该目录, 每个 guest 容器也以只读方式挂载它,因此用户 skill
|
|
36
|
+
及其脚本在任何地方都能使用。
|
|
37
|
+
- `~/.dsh/skills`(`DSH_HOME`)中的用户 skill
|
|
38
|
+
会被读取和加载,但有意**不**挂载进容器:dsh 容器本身就以读写方式挂载了
|
|
39
|
+
`~/.dsh`,而挂载一个插件可以改写的目录并不安全,因为 podman
|
|
40
|
+
会跟随被替换到该位置的符号链接。因此其中的脚本无法在容器内运行。
|
|
41
|
+
|
|
42
|
+
`skill` 工具与 `/` 菜单会列出已加载的 skill。harness
|
|
43
|
+
会缓存已打开页面的菜单,因此在宿主机上新增 或修改 skill
|
|
44
|
+
后,请重新加载页面(或新建会话)。
|
|
45
|
+
|
|
24
46
|
## 镜像模型
|
|
25
47
|
|
|
26
48
|
dsh-podman 将容器运行的镜像组织为三个层级:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@exagone313/dsh-podman",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.1",
|
|
4
4
|
"description": "Podman-backed execution for DeepSeek Harness (dsh).",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -54,7 +54,7 @@
|
|
|
54
54
|
"bump-version": "node scripts/bump-version.mjs"
|
|
55
55
|
},
|
|
56
56
|
"dependencies": {
|
|
57
|
-
"@grpc/grpc-js": "^1.14.
|
|
57
|
+
"@grpc/grpc-js": "^1.14.6",
|
|
58
58
|
"@grpc/proto-loader": "^0.8.1",
|
|
59
59
|
"@xterm/addon-fit": "^0.11.0",
|
|
60
60
|
"@xterm/addon-serialize": "^0.14.0",
|
|
@@ -79,7 +79,7 @@
|
|
|
79
79
|
"@deepseek-ai/dsh-client-ui-tool": "0.2.0-rc.2",
|
|
80
80
|
"@deepseek-ai/dsh-subprocess": "0.2.0-rc.2",
|
|
81
81
|
"@deepseek-ai/schemastery": "3.18.4",
|
|
82
|
-
"@types/node": "^
|
|
82
|
+
"@types/node": "^26.6.5",
|
|
83
83
|
"@types/react": "^18.3.31",
|
|
84
84
|
"esbuild": "^0.28.2",
|
|
85
85
|
"typescript": "^7.0.2"
|
|
@@ -87,7 +87,7 @@
|
|
|
87
87
|
"engines": {
|
|
88
88
|
"node": ">=22"
|
|
89
89
|
},
|
|
90
|
-
"packageManager": "pnpm@12.
|
|
90
|
+
"packageManager": "pnpm@12.11.2",
|
|
91
91
|
"publishConfig": {
|
|
92
92
|
"access": "public",
|
|
93
93
|
"provenance": true
|
|
@@ -36,8 +36,11 @@ Environment=DSH_PODMAN_SOCKETS_ROOT=/run/dsh-podman
|
|
|
36
36
|
Environment=DSH_PODMAN_GUEST_AGENT_IMAGE=ghcr.io/exagone313/dsh-podman/guest-agent
|
|
37
37
|
Environment=DSH_PODMAN_GUEST_AGENT_IMAGE_USE_VERSION_TAG=true
|
|
38
38
|
|
|
39
|
+
# Must never point to a directory in the DSH root (~/.dsh) for security reasons
|
|
40
|
+
Environment=DSH_PODMAN_HOST_SKILL_DIR=%h/.agents/skills
|
|
41
|
+
|
|
39
42
|
[Service]
|
|
40
|
-
ExecStartPre=/usr/bin/env mkdir -p -m 0700 %h/project ; /usr/bin/env mkdir -p -m 0700 %t/dsh-podman ; /usr/bin/env chmod 0700 %t/dsh-podman ; /usr/bin/env mkdir -p -m 0700 %h/.dsh/dsh-podman/state ; /usr/bin/env mkdir -p -m 0755 %h/.dsh/dsh-podman/apk-cache ; /usr/bin/env mkdir -p -m 0755 %h/.dsh/dsh-podman/apt-cache ; /usr/bin/env mkdir -p -m 0755 %h/.dsh/dsh-podman/pacman-cache
|
|
43
|
+
ExecStartPre=/usr/bin/env mkdir -p -m 0700 %h/project ; /usr/bin/env mkdir -p -m 0700 %t/dsh-podman ; /usr/bin/env chmod 0700 %t/dsh-podman ; /usr/bin/env mkdir -p -m 0700 %h/.dsh/dsh-podman/state ; /usr/bin/env mkdir -p -m 0755 %h/.dsh/dsh-podman/apk-cache ; /usr/bin/env mkdir -p -m 0755 %h/.dsh/dsh-podman/apt-cache ; /usr/bin/env mkdir -p -m 0755 %h/.dsh/dsh-podman/pacman-cache ; /usr/bin/env mkdir -p -m 0700 %h/.agents/skills
|
|
41
44
|
Restart=on-failure
|
|
42
45
|
RestartSec=3
|
|
43
46
|
SuccessExitStatus=0 143
|
package/quadlet/dsh.container
CHANGED
|
@@ -19,6 +19,9 @@ WorkingDir=$HOME
|
|
|
19
19
|
Volume=%h/.dsh:%h/.dsh
|
|
20
20
|
Environment=DSH_HOME=%h/.dsh
|
|
21
21
|
|
|
22
|
+
Volume=%h/.agents:%h/.agents:ro
|
|
23
|
+
Environment=DSH_AGENTS_HOME=%h/.agents
|
|
24
|
+
|
|
22
25
|
Volume=%h/project:%h/project:ro
|
|
23
26
|
Environment=DSH_PODMAN_PROJECTS_ROOT=%h/project
|
|
24
27
|
|
|
@@ -26,7 +29,7 @@ Volume=%t/dsh-podman:/run/dsh-podman
|
|
|
26
29
|
Environment=DSH_PODMAN_SOCKETS_ROOT=/run/dsh-podman
|
|
27
30
|
|
|
28
31
|
[Service]
|
|
29
|
-
ExecStartPre=/usr/bin/env mkdir -p -m 0700 %h/project ; /usr/bin/env mkdir -p -m 0700 %t/dsh-podman ; /usr/bin/env chmod 0700 %t/dsh-podman ; /usr/bin/env mkdir -p -m 0700 %h/.dsh
|
|
32
|
+
ExecStartPre=/usr/bin/env mkdir -p -m 0700 %h/project ; /usr/bin/env mkdir -p -m 0700 %t/dsh-podman ; /usr/bin/env chmod 0700 %t/dsh-podman ; /usr/bin/env mkdir -p -m 0700 %h/.dsh ; /usr/bin/env mkdir -p -m 0700 %h/.agents/skills
|
|
30
33
|
Restart=on-failure
|
|
31
34
|
RestartSec=3
|
|
32
35
|
SuccessExitStatus=0 143
|