hermesdesk-agent 0.0.0-stage → 0.1.0-alpha.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nash Kocur
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,82 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # HermesDesk Agent
2
+
3
+ [![CI](https://github.com/NKocur/hermesdesk-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/NKocur/hermesdesk-agent/actions/workflows/ci.yml)
4
+
5
+ **Windows alpha: 0.1.0-alpha.1.** Community client built on Pi; not affiliated with or endorsed by Earendil Works or Nous Research.
6
+
7
+ A running HermesDesk inference gateway is required. This client does not include a hosted model service, server access, or API keys.
8
+
9
+ An initial Windows-first coding CLI built on the pinned Pi 1.5.0 SDK. The model runs on your HermesDesk/Strata server; coding tools run on the computer where you start this client.
10
+
11
+ ## Install on a Windows computer
12
+
13
+ Install Node.js 22.19 or newer (Node 24 recommended). Download and extract a Windows alpha bundle from [Releases](https://github.com/NKocur/hermesdesk-agent/releases), then run `Install Agent.cmd`, or install the supplied package:
14
+
15
+ ```powershell
16
+ npm.cmd install -g --ignore-scripts "C:\path\to\hermesdesk-agent-0.1.0-alpha.1.tgz"
17
+ hermesdesk.cmd connect
18
+ hermesdesk.cmd doctor
19
+ ```
20
+
21
+ There is no default server address. `connect` asks for your HTTPS inference endpoint ending in `/v1`; for a server on this computer, loopback HTTP is also accepted. Enter a per-computer inference API key created in HermesDesk Settings > Connect coding tools. Use the Hermes/OpenAI-compatible key option; all current inference keys work with this client. The model is discovered automatically if the configured ID is unavailable. No keys are included in the package.
22
+
23
+ On Windows, saved keys are encrypted using DPAPI for the signed-in Windows user and bound to the configured endpoint. Configuration and sessions are stored under `%LOCALAPPDATA%\HermesDeskAgent`. The key is not written to Pi's auth JSON or passed on a command line. `HERMESDESK_API_KEY` supports session-only authentication; the client removes it from its environment before coding tools run. `hermesdesk logout` deletes the saved credential, but does not revoke it on the server.
24
+
25
+ ## Work on a project
26
+
27
+ ```powershell
28
+ cd C:\Projects\MyProject
29
+ hermesdesk.cmd chat
30
+ hermesdesk.cmd chat --continue
31
+ hermesdesk.cmd sessions
32
+ hermesdesk.cmd chat --session SESSION_ID
33
+ hermesdesk.cmd chat --read-only
34
+ ```
35
+
36
+ The interactive terminal uses Pi's UI, streaming, diffs, tool displays, session history and compaction. Escape interrupts work. `/quit` exits; `/new` starts a new conversation and `/resume` opens Pi's session selector. The first interactive startup may download Pi's `fd` helper to this client's own Pi cache. Windows Terminal is recommended. Pi's inherited help and exit hints may still mention `pi`; resume this client with `hermesdesk chat --continue` or `--session ID`.
37
+
38
+ File tools are restricted to the chosen project and reject outside links and protected paths such as `.env`, `.git`, credential files and agent configurations. Each edit and shell command asks for approval. Shell commands execute as your user and are **not OS-sandboxed**; after approval they can access anything your account can access. Direct `!` shell shortcuts are disabled so commands use the managed approval path. Project JavaScript extensions, MCP servers and packages are not automatically loaded.
39
+
40
+ The root project's `AGENTS.md` is included as instructions when it is an ordinary allowed file under 64 KiB. Existing global Pi/Claude settings are not imported. This first version does not synchronize HermesDesk chats, workspace memory or Hermes's skill-learning loop.
41
+
42
+ ## One-shot requests
43
+
44
+ ```powershell
45
+ hermesdesk.cmd run "Explain this repository" --read-only
46
+ hermesdesk.cmd run "Create a small example file" --approve-writes
47
+ hermesdesk.cmd run "Summarize README.md" --json
48
+ ```
49
+
50
+ One-shot operation denies writes unless `--approve-writes` is explicitly provided. It never approves shell commands without interactive confirmation. JSON mode streams `text`, `tool` and `done` records to stdout; diagnostics go to stderr.
51
+
52
+ ## Settings
53
+
54
+ ```powershell
55
+ hermesdesk.cmd config
56
+ hermesdesk.cmd config set thinking true
57
+ hermesdesk.cmd config set context 131072
58
+ hermesdesk.cmd config set maxTokens 4096
59
+ hermesdesk.cmd config set temperature 0.7
60
+ hermesdesk.cmd config set topP 0.95
61
+ hermesdesk.cmd config set topK 20
62
+ hermesdesk.cmd config set maxRequests 64
63
+ ```
64
+
65
+ Changes apply to the next launch. Context is client metadata, not a request to allocate more server context: keep it at or below the server's configured capacity. Output is capped at 8192 by the gateway. The default request budget is 64 per message and can be set from 1 to 512. Pi's in-chat settings are session-only in this version. Change the server using `hermesdesk connect --url https://your-server/v1`. HTTP is accepted only on loopback addresses.
66
+
67
+ Windows uses its built-in `curl.exe` for model HTTP requests because the retained Cloudflare bot filter challenged Node fetch and a native Node follow-up request during testing. TLS verification stays enabled, redirects are not followed, credentials are sent through stdin rather than command-line arguments, and disconnects cancel the request. `doctor` checks the connection without loading the model. Cold Strata startup can still take minutes; the client cannot remove server warm-up costs. A Cloudflare 403 is a connection failure, not a model error.
68
+
69
+ ## Develop
70
+
71
+ ```powershell
72
+ npm.cmd ci --ignore-scripts
73
+ npm.cmd test
74
+ node bin/hermesdesk.js --help
75
+ npm.cmd pack --ignore-scripts
76
+ ```
77
+
78
+ The client is a standalone project. Use the GitHub alpha release assets for the Windows installer or tarball. The `.tgz` contains no local credentials, test transcripts or model files. Pi's MIT license is retained in `THIRD_PARTY_NOTICES.md`; dependency licenses remain in the installed packages.
79
+
80
+ ## License and contributing
81
+
82
+ MIT. Pi is also MIT-licensed; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). See [CONTRIBUTING.md](CONTRIBUTING.md) for development and [SECURITY.md](SECURITY.md) for reporting security issues.
@@ -0,0 +1,26 @@
1
+ # Third-party notices
2
+
3
+ This client uses Pi 1.5.0 by Mario Zechner / Earendil Works, from https://github.com/earendil-works/pi, under the MIT license.
4
+
5
+ MIT License
6
+
7
+ Copyright (c) 2025 Mario Zechner
8
+
9
+ Permission is hereby granted, free of charge, to any person obtaining a copy
10
+ of this software and associated documentation files (the "Software"), to deal
11
+ in the Software without restriction, including without limitation the rights
12
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13
+ copies of the Software, and to permit persons to whom the Software is
14
+ furnished to do so, subject to the following conditions:
15
+
16
+ The above copyright notice and this permission notice shall be included in all
17
+ copies or substantial portions of the Software.
18
+
19
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25
+ SOFTWARE.
26
+ Other dependency licenses are supplied with their npm packages.
@@ -0,0 +1,226 @@
1
+ #!/usr/bin/env node
2
+ import fs from "node:fs";
3
+ import path from "node:path";
4
+ import readline from "node:readline/promises";
5
+ import { parseArgs } from "node:util";
6
+ import {
7
+ VERSION,
8
+ configHome,
9
+ loadConfig,
10
+ saveConfig,
11
+ validateConfig,
12
+ projectSessionDir,
13
+ } from "../src/config.js";
14
+ import {
15
+ getCredential,
16
+ saveCredential,
17
+ hiddenInput,
18
+ logout,
19
+ } from "../src/credentials.js";
20
+ import { discover } from "../src/transport.js";
21
+ const help = `HermesDesk Agent ${VERSION} (Pi-based, Windows first)
22
+
23
+ hermesdesk connect [--url https://your-server.example/v1]
24
+ hermesdesk doctor
25
+ hermesdesk chat [--cwd PATH] [--continue | --session ID] [--read-only]
26
+ hermesdesk run "REQUEST" [--cwd PATH] [--json] [--read-only]
27
+ hermesdesk sessions [--cwd PATH]
28
+ hermesdesk config [set KEY VALUE]
29
+ hermesdesk logout
30
+
31
+ Edits and shell commands ask for approval in interactive chat.
32
+ One-shot runs deny changes by default; --approve-writes permits workspace file edits.
33
+ Shell commands always require interactive approval. This is not an OS sandbox.
34
+ Settings: model, context, maxTokens, thinking, temperature, topP, topK, maxRequests.
35
+ `;
36
+ async function main() {
37
+ const { values: v, positionals: p } = parseArgs({
38
+ allowPositionals: true,
39
+ options: {
40
+ url: { type: "string" },
41
+ cwd: { type: "string" },
42
+ session: { type: "string" },
43
+ continue: { type: "boolean" },
44
+ "read-only": { type: "boolean" },
45
+ "approve-writes": { type: "boolean" },
46
+ json: { type: "boolean" },
47
+ help: { type: "boolean", short: "h" },
48
+ version: { type: "boolean" },
49
+ },
50
+ });
51
+ if (v.help) {
52
+ console.log(help);
53
+ return;
54
+ }
55
+ if (v.version) {
56
+ console.log(VERSION);
57
+ return;
58
+ }
59
+ const command = p.shift() || "chat",
60
+ home = configHome();
61
+ process.env.PI_CODING_AGENT_DIR = path.join(home, "pi");
62
+ let config = loadConfig(home);
63
+ if (command === "connect") {
64
+ if (v.url) config = validateConfig({ ...config, baseUrl: v.url });
65
+ const rl = readline.createInterface({
66
+ input: process.stdin,
67
+ output: process.stdout,
68
+ });
69
+ if (!v.url && process.stdin.isTTY) {
70
+ const answer = await rl.question(
71
+ config.baseUrl
72
+ ? "Server [" + config.baseUrl + "]: "
73
+ : "HermesDesk server URL (https://.../v1): ",
74
+ );
75
+ if (answer.trim())
76
+ config = validateConfig({ ...config, baseUrl: answer.trim() });
77
+ }
78
+ rl.close();
79
+ if (!config.baseUrl)
80
+ throw Error(
81
+ "Enter your server URL, or use hermesdesk connect --url https://your-server.example/v1.",
82
+ );
83
+ const token =
84
+ process.env.HERMESDESK_API_KEY ||
85
+ (await hiddenInput("HermesDesk API key (hidden): "));
86
+ const models = await discover(config, token);
87
+ if (!models.length) throw Error("No models are available.");
88
+ if (!models.includes(config.model)) config.model = models[0];
89
+ await saveCredential(home, config.baseUrl, token);
90
+ saveConfig(config, home);
91
+ console.log(
92
+ "Connected. Credential protected for your Windows account.\nModel: " +
93
+ config.model +
94
+ "\nRun hermesdesk chat from your project directory.",
95
+ );
96
+ return;
97
+ }
98
+ if (command === "logout") {
99
+ logout(home);
100
+ console.log(
101
+ "Saved credential removed. Any HERMESDESK_API_KEY environment variable still applies until cleared.",
102
+ );
103
+ return;
104
+ }
105
+ if (command === "config") {
106
+ if (p[0] === "set") {
107
+ const key = p[1];
108
+ if (!Object.hasOwn(config, key) || key === "baseUrl")
109
+ throw Error(
110
+ "Choose a supported setting; use connect --url to change servers.",
111
+ );
112
+ const raw = p.slice(2).join(" ");
113
+ if (!raw) throw Error("Provide a setting value.");
114
+ let value = raw;
115
+ if (key !== "model") {
116
+ try {
117
+ value = JSON.parse(raw);
118
+ } catch {
119
+ throw Error("Use a number or true/false for this setting.");
120
+ }
121
+ }
122
+ config = saveConfig({ ...config, [key]: value }, home);
123
+ }
124
+ console.log(JSON.stringify(config, null, 2));
125
+ return;
126
+ }
127
+ if (command === "sessions") {
128
+ const { SessionManager } = await import("@earendil-works/pi-coding-agent");
129
+ const cwd = fs.realpathSync.native(v.cwd || process.cwd());
130
+ const rows = await SessionManager.list(cwd, projectSessionDir(home, cwd));
131
+ const selected = rows.filter(
132
+ (r) => r.cwd.toLowerCase() === cwd.toLowerCase(),
133
+ );
134
+ console.log(
135
+ selected.length
136
+ ? selected
137
+ .map(
138
+ (r) =>
139
+ r.id +
140
+ " " +
141
+ (r.name || r.firstMessage || "Untitled")
142
+ .replace(/\s+/g, " ")
143
+ .slice(0, 90),
144
+ )
145
+ .join("\n")
146
+ : "No saved sessions for this project.",
147
+ );
148
+ return;
149
+ }
150
+ if (!["doctor", "chat", "run"].includes(command))
151
+ throw Error("Unknown command. Use hermesdesk --help.");
152
+ if (!config.baseUrl || !config.model)
153
+ throw Error("Not connected. Run hermesdesk connect first.");
154
+ const token = await getCredential(home, config.baseUrl);
155
+ delete process.env.HERMESDESK_API_KEY;
156
+ if (command === "doctor") {
157
+ const models = await discover(config, token);
158
+ console.log(
159
+ JSON.stringify(
160
+ {
161
+ connected: true,
162
+ endpoint: config.baseUrl,
163
+ model: config.model,
164
+ available: models.includes(config.model),
165
+ models,
166
+ settingsDirectory: home,
167
+ node: process.version,
168
+ platform: process.platform,
169
+ },
170
+ null,
171
+ 2,
172
+ ),
173
+ );
174
+ if (!models.includes(config.model)) process.exitCode = 1;
175
+ return;
176
+ }
177
+ const cwd = fs.realpathSync.native(v.cwd || process.cwd());
178
+ if (command === "chat" && (!process.stdin.isTTY || !process.stdout.isTTY))
179
+ throw Error(
180
+ 'Interactive chat needs a terminal. Use hermesdesk run "request" for one-shot operation.',
181
+ );
182
+ if (command === "run" && !p.length)
183
+ throw Error('Provide a request: hermesdesk run "Inspect this project".');
184
+ const { createRuntime, runPrompt } = await import("../src/agent.js");
185
+ const runtime = await createRuntime({
186
+ config,
187
+ home,
188
+ token,
189
+ cwd,
190
+ readOnly: !!v["read-only"],
191
+ approveWrites: !!v["approve-writes"],
192
+ continueSession: !!v.continue,
193
+ sessionId: v.session,
194
+ });
195
+ const cancel = () => {
196
+ void runtime.session.abort();
197
+ };
198
+ process.on("SIGINT", cancel);
199
+ try {
200
+ if (command === "run") {
201
+ await runPrompt(runtime, p.join(" "), { json: !!v.json });
202
+ } else {
203
+ const { InteractiveMode } = await import(
204
+ "@earendil-works/pi-coding-agent"
205
+ );
206
+ const ui = new InteractiveMode(runtime, {
207
+ verbose: false,
208
+ initialMessage: p.length ? p.join(" ") : undefined,
209
+ });
210
+ await ui.run();
211
+ }
212
+ } finally {
213
+ process.off("SIGINT", cancel);
214
+ await runtime.dispose();
215
+ }
216
+ }
217
+ main().catch((e) => {
218
+ let message = e.message || "Operation failed.";
219
+ for (const secret of [process.env.HERMESDESK_API_KEY])
220
+ if (secret) message = message.split(secret).join("[redacted]");
221
+ if (/<!doctype|<html/i.test(message))
222
+ message =
223
+ "Cloudflare rejected the API request. Run hermesdesk doctor to check the connection.";
224
+ console.error("HermesDesk: " + message.slice(0, 1200));
225
+ process.exitCode = 1;
226
+ });