@agentshouse/kit 0.2.1-ccf188e02985d → 0.2.1-ccffb3f637815

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.
Files changed (164) hide show
  1. package/README.md +37 -41
  2. package/dist/acp.js +66 -12
  3. package/dist/afk.js +17 -0
  4. package/dist/agents.js +122 -53
  5. package/dist/api.js +15 -10
  6. package/dist/binaries.js +89 -0
  7. package/dist/bridge.js +29 -28
  8. package/dist/building.js +50 -0
  9. package/dist/calls.js +88 -0
  10. package/dist/chunks.js +49 -0
  11. package/dist/clis.js +62 -50
  12. package/dist/connect.js +108 -0
  13. package/dist/connection.js +120 -0
  14. package/dist/content.js +106 -0
  15. package/dist/conversations.js +594 -219
  16. package/dist/copies.js +772 -279
  17. package/dist/earlier.js +263 -0
  18. package/dist/end.js +12 -5
  19. package/dist/events.js +549 -281
  20. package/dist/files.js +206 -38
  21. package/dist/git-main.js +24 -29
  22. package/dist/git.js +90 -15
  23. package/dist/grok.js +39 -0
  24. package/dist/home.js +80 -29
  25. package/dist/house-cli.js +155 -164
  26. package/dist/house-main.js +3 -3
  27. package/dist/instructions.js +29 -11
  28. package/dist/keys.js +238 -0
  29. package/dist/kit-cli.js +18 -8
  30. package/dist/kit-main.js +3 -3
  31. package/dist/login.js +36 -22
  32. package/dist/logout.js +2 -2
  33. package/dist/mcp.js +42 -3
  34. package/dist/old-references.js +27 -0
  35. package/dist/owner.js +46 -0
  36. package/dist/placement.js +15 -20
  37. package/dist/refusals.js +37 -21
  38. package/dist/relay.js +21 -0
  39. package/dist/resident.js +128 -82
  40. package/dist/scope.js +15 -4
  41. package/dist/scripts.js +303 -0
  42. package/dist/secret-input.js +1 -1
  43. package/dist/settings.js +188 -0
  44. package/dist/sign-in.js +67 -21
  45. package/dist/silence.js +28 -0
  46. package/dist/skills.js +42 -97
  47. package/dist/supervisor.js +163 -0
  48. package/dist/transcription.js +88 -45
  49. package/dist/translate.js +19 -18
  50. package/dist/update.js +118 -120
  51. package/dist/wire.js +30 -4
  52. package/dist/work.js +27 -2
  53. package/dist/workspace.js +103 -0
  54. package/package.json +26 -22
  55. package/dist/authority-main.js +0 -22
  56. package/dist/bootstrap.json +0 -24
  57. package/dist/chatgpt.js +0 -32
  58. package/dist/clis-main.js +0 -23
  59. package/dist/configure-main.js +0 -6
  60. package/dist/enrol-main.js +0 -10
  61. package/dist/inputs.js +0 -37
  62. package/dist/parts.js +0 -82
  63. package/dist/service-main.js +0 -9
  64. package/dist/service.js +0 -55
  65. package/dist/stream.js +0 -123
  66. package/how-we-work.md +0 -33
  67. package/skills/ask-matt/LICENSE +0 -21
  68. package/skills/ask-matt/PHASE-BOUNDARIES.md +0 -55
  69. package/skills/ask-matt/SKILL.md +0 -97
  70. package/skills/ask-matt/agents/openai.yaml +0 -5
  71. package/skills/code-review/LICENSE +0 -21
  72. package/skills/code-review/SKILL.md +0 -89
  73. package/skills/code-review/agents/openai.yaml +0 -3
  74. package/skills/codebase-design/DEEPENING.md +0 -37
  75. package/skills/codebase-design/DESIGN-IT-TWICE.md +0 -44
  76. package/skills/codebase-design/LICENSE +0 -21
  77. package/skills/codebase-design/SKILL.md +0 -114
  78. package/skills/codebase-design/agents/openai.yaml +0 -3
  79. package/skills/diagnosing-bugs/LICENSE +0 -21
  80. package/skills/diagnosing-bugs/SKILL.md +0 -138
  81. package/skills/diagnosing-bugs/agents/openai.yaml +0 -3
  82. package/skills/diagnosing-bugs/scripts/hitl-loop.template.sh +0 -44
  83. package/skills/domain-modeling/ADR-FORMAT.md +0 -47
  84. package/skills/domain-modeling/GLOSSARY-FORMAT.md +0 -60
  85. package/skills/domain-modeling/LICENSE +0 -21
  86. package/skills/domain-modeling/SKILL.md +0 -74
  87. package/skills/domain-modeling/agents/openai.yaml +0 -3
  88. package/skills/grill-me/LICENSE +0 -21
  89. package/skills/grill-me/SKILL.md +0 -7
  90. package/skills/grill-me/agents/openai.yaml +0 -5
  91. package/skills/grill-with-docs/LICENSE +0 -21
  92. package/skills/grill-with-docs/SKILL.md +0 -7
  93. package/skills/grill-with-docs/agents/openai.yaml +0 -5
  94. package/skills/grilling/LICENSE +0 -21
  95. package/skills/grilling/SKILL.md +0 -30
  96. package/skills/grilling/agents/openai.yaml +0 -3
  97. package/skills/handoff/LICENSE +0 -21
  98. package/skills/handoff/SKILL.md +0 -16
  99. package/skills/handoff/agents/openai.yaml +0 -5
  100. package/skills/implement/LICENSE +0 -21
  101. package/skills/implement/SKILL.md +0 -17
  102. package/skills/implement/agents/openai.yaml +0 -5
  103. package/skills/implement-spec/LICENSE +0 -21
  104. package/skills/implement-spec/SKILL.md +0 -40
  105. package/skills/implement-spec/agents/openai.yaml +0 -5
  106. package/skills/improve-codebase-architecture/HTML-REPORT.md +0 -123
  107. package/skills/improve-codebase-architecture/LICENSE +0 -21
  108. package/skills/improve-codebase-architecture/SKILL.md +0 -71
  109. package/skills/improve-codebase-architecture/agents/openai.yaml +0 -5
  110. package/skills/pr/CREDITS.md +0 -3
  111. package/skills/pr/LICENSE +0 -21
  112. package/skills/pr/SKILL.md +0 -170
  113. package/skills/pr/agents/openai.yaml +0 -3
  114. package/skills/prototype/LICENSE +0 -21
  115. package/skills/prototype/LOGIC.md +0 -67
  116. package/skills/prototype/SKILL.md +0 -26
  117. package/skills/prototype/UI.md +0 -112
  118. package/skills/prototype/agents/openai.yaml +0 -3
  119. package/skills/research/LICENSE +0 -21
  120. package/skills/research/SKILL.md +0 -12
  121. package/skills/research/agents/openai.yaml +0 -3
  122. package/skills/retro/LICENSE +0 -21
  123. package/skills/retro/SKILL.md +0 -44
  124. package/skills/retro/agents/openai.yaml +0 -5
  125. package/skills/tdd/LICENSE +0 -21
  126. package/skills/tdd/SKILL.md +0 -38
  127. package/skills/tdd/agents/openai.yaml +0 -3
  128. package/skills/tdd/mocking.md +0 -59
  129. package/skills/tdd/tests.md +0 -77
  130. package/skills/teach/GLOSSARY-FORMAT.md +0 -35
  131. package/skills/teach/LEARNING-RECORD-FORMAT.md +0 -46
  132. package/skills/teach/LICENSE +0 -21
  133. package/skills/teach/MISSION-FORMAT.md +0 -31
  134. package/skills/teach/RESOURCES-FORMAT.md +0 -32
  135. package/skills/teach/SKILL.md +0 -140
  136. package/skills/teach/agents/openai.yaml +0 -5
  137. package/skills/to-questionnaire/LICENSE +0 -21
  138. package/skills/to-questionnaire/SKILL.md +0 -54
  139. package/skills/to-questionnaire/agents/openai.yaml +0 -5
  140. package/skills/to-spec/LICENSE +0 -21
  141. package/skills/to-spec/SKILL.md +0 -75
  142. package/skills/to-spec/agents/openai.yaml +0 -5
  143. package/skills/to-tickets/LICENSE +0 -21
  144. package/skills/to-tickets/SKILL.md +0 -105
  145. package/skills/to-tickets/agents/openai.yaml +0 -5
  146. package/skills/triage/AGENT-BRIEF.md +0 -207
  147. package/skills/triage/LICENSE +0 -21
  148. package/skills/triage/OUT-OF-SCOPE.md +0 -105
  149. package/skills/triage/SKILL.md +0 -112
  150. package/skills/triage/agents/openai.yaml +0 -5
  151. package/skills/wait-what/LICENSE +0 -21
  152. package/skills/wait-what/SKILL.md +0 -7
  153. package/skills/wait-what/agents/openai.yaml +0 -5
  154. package/skills/wayfinder/LICENSE +0 -21
  155. package/skills/wayfinder/SKILL.md +0 -128
  156. package/skills/wayfinder/agents/openai.yaml +0 -5
  157. package/skills/wizard/LICENSE +0 -21
  158. package/skills/wizard/SKILL.md +0 -44
  159. package/skills/wizard/agents/openai.yaml +0 -3
  160. package/skills/wizard/template.sh +0 -223
  161. package/skills/writing-for-agents/LICENSE +0 -21
  162. package/skills/writing-for-agents/SKILL-MECHANICS.md +0 -22
  163. package/skills/writing-for-agents/SKILL.md +0 -81
  164. package/skills/writing-for-agents/agents/openai.yaml +0 -3
package/dist/home.js CHANGED
@@ -1,24 +1,15 @@
1
1
  import { createHash, randomUUID } from 'node:crypto';
2
- import { accessSync, chmodSync, constants, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync } from 'node:fs';
2
+ import { chmodSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
3
3
  import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
4
- import { homedir, tmpdir } from 'node:os';
4
+ import { homedir } from 'node:os';
5
5
  import { join, resolve } from 'node:path';
6
6
  import { selectRelay } from './relay.js';
7
7
  const ENROLMENT = 'credential.json';
8
8
  const DISCONNECTED = 'disconnected.json';
9
9
  const CONFIGURATION = 'kit.json';
10
10
  const OWN_AGENT = 'own-agent.json';
11
- const RESTART = 'restart';
12
- let defaulted;
13
- function writable(directory) {
14
- try {
15
- accessSync(directory, constants.W_OK | constants.X_OK);
16
- return true;
17
- }
18
- catch {
19
- return false;
20
- }
21
- }
11
+ const PLANNED_RESTART = 'planned-restart';
12
+ const EARLIER_PREFIXES = ['/kit-home/kit', '/opt/house-kit'];
22
13
  function privateDirectory(path) {
23
14
  try {
24
15
  mkdirSync(path, { mode: 0o700 });
@@ -37,15 +28,39 @@ function privateDirectory(path) {
37
28
  chmodSync(path, 0o700);
38
29
  return path;
39
30
  }
40
- function ownTemporaryHome() {
41
- return privateDirectory(join(tmpdir(), `house-kit-${process.getuid()}`));
31
+ export function oneFolder(account = homedir()) {
32
+ return join(account, '.agents', 'house');
33
+ }
34
+ export function desktopPrefix() {
35
+ return join(homedir(), '.local', 'share', 'house-kit');
36
+ }
37
+ export function earlierPrefix() {
38
+ const prefix = process.env.HOUSE_KIT_PREFIX;
39
+ if (prefix === undefined || prefix === '')
40
+ return null;
41
+ return [...EARLIER_PREFIXES, desktopPrefix()].includes(resolve(prefix)) ? resolve(prefix) : null;
42
+ }
43
+ export function awaitsTakeover() {
44
+ const prefix = earlierPrefix();
45
+ return prefix === EARLIER_PREFIXES[0] || (prefix === EARLIER_PREFIXES[1] && process.getuid() !== 0);
46
+ }
47
+ export function earlierHome() {
48
+ return process.env.HOUSE_KIT_HOME || join(homedir(), '.house-kit');
42
49
  }
43
- function defaultHome() {
44
- const home = join(homedir(), '.house-kit');
45
- return existsSync(home) || writable(homedir()) ? home : ownTemporaryHome();
50
+ export function reinstall() {
51
+ if (!awaitsTakeover())
52
+ return undefined;
53
+ try {
54
+ return readFileSync(join(earlierHome(), 'placement'), 'utf8').trim() === 'windows' ? 'windows' : 'linux';
55
+ }
56
+ catch (error) {
57
+ if (error.code === 'ENOENT')
58
+ return 'linux';
59
+ throw error;
60
+ }
46
61
  }
47
62
  export function kitHome() {
48
- return process.env.HOUSE_KIT_HOME || (defaulted ??= defaultHome());
63
+ return earlierPrefix() === null ? oneFolder() : earlierHome();
49
64
  }
50
65
  export function socketDirectory() {
51
66
  const sockets = privateDirectory(join(realpathSync('/tmp'), `hk-${process.geteuid()}`));
@@ -60,20 +75,32 @@ export function ownerLock() {
60
75
  return join(socketDirectory(), 'owner.lock');
61
76
  }
62
77
  export function workspaceRoot() {
63
- return process.env.HOUSE_KIT_WORKSPACE ?? '/agents/house';
78
+ if (earlierPrefix() !== null)
79
+ return process.env.HOUSE_KIT_WORKSPACE ?? '/agents/house';
80
+ return configuredWorkspace() ?? kitHome();
64
81
  }
65
82
  export function agentBase() {
66
83
  return join(workspaceRoot(), 'agents');
67
84
  }
85
+ function parsed(name, text) {
86
+ try {
87
+ return JSON.parse(text);
88
+ }
89
+ catch {
90
+ throw new Error(`${name} in Kit home holds no JSON`);
91
+ }
92
+ }
68
93
  export async function readHome(name) {
94
+ let text;
69
95
  try {
70
- return JSON.parse(await readFile(join(kitHome(), name), 'utf8'));
96
+ text = await readFile(join(kitHome(), name), 'utf8');
71
97
  }
72
98
  catch (error) {
73
99
  if (error.code === 'ENOENT')
74
100
  return null;
75
101
  throw error;
76
102
  }
103
+ return parsed(name, text);
77
104
  }
78
105
  export async function writeHome(name, value) {
79
106
  const home = kitHome();
@@ -117,7 +144,7 @@ export async function forgetRejected(rejected) {
117
144
  return;
118
145
  throw error;
119
146
  }
120
- if (JSON.parse(readFileSync(taken, 'utf8')).credential !== rejected) {
147
+ if (parsed(ENROLMENT, readFileSync(taken, 'utf8')).credential !== rejected) {
121
148
  try {
122
149
  linkSync(taken, enrolment);
123
150
  }
@@ -129,14 +156,22 @@ export async function forgetRejected(rejected) {
129
156
  }
130
157
  rmSync(taken);
131
158
  }
132
- export function enrolled() {
133
- return existsSync(join(kitHome(), ENROLMENT));
159
+ export function recordPlannedRestart() {
160
+ writeFileSync(join(kitHome(), PLANNED_RESTART), '', { mode: 0o600 });
134
161
  }
135
- export function restartAsked() {
136
- return existsSync(join(kitHome(), RESTART));
162
+ export function takePlannedRestart() {
163
+ try {
164
+ unlinkSync(join(kitHome(), PLANNED_RESTART));
165
+ return true;
166
+ }
167
+ catch (error) {
168
+ if (error.code === 'ENOENT')
169
+ return false;
170
+ throw error;
171
+ }
137
172
  }
138
- export function forgetRestart() {
139
- return rm(join(kitHome(), RESTART), { force: true });
173
+ export function enrolled() {
174
+ return existsSync(join(kitHome(), ENROLMENT));
140
175
  }
141
176
  export function readOwnAgent() {
142
177
  return readHome(OWN_AGENT);
@@ -147,8 +182,24 @@ export function writeOwnAgent(ownAgent) {
147
182
  export function forgetOwnAgent() {
148
183
  return rm(join(kitHome(), OWN_AGENT), { force: true });
149
184
  }
185
+ function configuredWorkspace() {
186
+ let text;
187
+ try {
188
+ text = readFileSync(join(kitHome(), CONFIGURATION), 'utf8');
189
+ }
190
+ catch (error) {
191
+ if (error.code === 'ENOENT')
192
+ return undefined;
193
+ throw error;
194
+ }
195
+ return parsed(CONFIGURATION, text).workspace;
196
+ }
150
197
  export async function readConfiguration() {
151
- return { skills: (await readHome(CONFIGURATION))?.skills !== false };
198
+ const stored = await readHome(CONFIGURATION);
199
+ return { skills: stored?.skills !== false, workspace: stored?.workspace ?? kitHome() };
200
+ }
201
+ export async function storedConfiguration() {
202
+ return (await readHome(CONFIGURATION)) ?? {};
152
203
  }
153
204
  export function writeConfiguration(configuration) {
154
205
  return writeHome(CONFIGURATION, configuration);
package/dist/house-cli.js CHANGED
@@ -1,108 +1,63 @@
1
1
  import { createHash } from 'node:crypto';
2
- import { mkdir, readFile, writeFile } from 'node:fs/promises';
3
- import { request, setGlobalProxyFromEnv } from 'node:http';
4
- import { basename, dirname, extname, join, resolve } from 'node:path';
5
- import { verified } from './files.js';
2
+ import { createReadStream } from 'node:fs';
3
+ import { request } from 'node:http';
4
+ import { resolve } from 'node:path';
5
+ import { text as textOf } from 'node:stream/consumers';
6
+ import { downloaded, fileInfo, fileRange, mediaTypeOf, opened, sentPart, storeRefusal, uploaded, } from './files.js';
6
7
  import { HOUSE_REF } from './git.js';
7
- import { ownerSocket, readOwnAgent } from './home.js';
8
- import { callHouse, rpc, UNREACHABLE } from './mcp.js';
8
+ import { ownerSocket } from './home.js';
9
+ import { ownAgentCall, rpc, unconfirmed, UNREACHABLE } from './mcp.js';
9
10
  import { refusalOf } from './refusals.js';
10
- import { relayed, selectRelay } from './relay.js';
11
- import { parse, stringify } from 'yaml';
12
- const USAGE = "usage: house <tool> ['<arguments as JSON>']";
11
+ import { parse } from 'yaml';
12
+ const USAGE = "usage: house <tool> ['<arguments as JSON>'], or house <tool> - to read them from stdin; house help <tool>: its arguments";
13
+ const HELP = 'help [tool]';
13
14
  const PUSH_USAGE = 'usage: house push [commit] [--owner]';
14
- const PUSH = "push [commit]: sends the Local copy's committed changes to House";
15
+ const PUSH = "push [commit]: sends the Local copy's committed changes to House in one push, each .md file as document text and every other file as an attachment";
15
16
  const FETCH_USAGE = 'usage: house fetch';
16
17
  const FETCH = `fetch: records House's changes on each Local copy's ${HOUSE_REF}`;
17
18
  const DOWNLOAD_USAGE = `usage: house download '{"path":"/rooms/<handle>/<path>","file":"<local file>"}', adding "ref" for a revision`;
18
19
  const DOWNLOAD = 'download: writes a binary file of a Room to the local file named by file';
19
- const ARGUMENTS = `the arguments are one JSON object in single quotes, like house search '{"query":"invoice"}'`;
20
+ const UPLOAD_USAGE = `usage: house upload '{"file":"<local file>","room_ref":"r_…","path":"<path in the Room>"}', adding "base", the revision it replaces`;
21
+ const ARGUMENTS = `the arguments are one JSON object, in single quotes or on stdin after -, like house search '{"query":"invoice"}'`;
20
22
  const CLOSED = "this conversation's House connection is closed; nothing to do from here";
21
23
  const SANDBOXED = "your CLI's sandbox kept house from House; run house directly, not through another program";
22
24
  const REVOKED = 'this conversation no longer has House access; nothing to do from here';
23
- const UNCONNECTED = "this computer's own agent has no House connection; run kit login, or kit chatgpt --key <key> with a script key";
24
- const DISCONNECTED = "House no longer accepts this computer's own agent; run kit login, or kit chatgpt --key <key> with a script key";
25
- const UNCONFIRMED = 'with no result; a write may or may not have taken effect, so read before you repeat it';
26
25
  const socketPath = process.env.HOUSE_BRIDGE;
27
- const MEDIA_TYPES = new Map([
28
- ['avif', 'image/avif'],
29
- ['csv', 'text/csv'],
30
- ['docx', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
31
- ['gif', 'image/gif'],
32
- ['heic', 'image/heic'],
33
- ['html', 'text/html'],
34
- ['jpeg', 'image/jpeg'],
35
- ['jpg', 'image/jpeg'],
36
- ['json', 'application/json'],
37
- ['m4a', 'audio/mp4'],
38
- ['md', 'text/markdown'],
39
- ['mov', 'video/quicktime'],
40
- ['mp3', 'audio/mpeg'],
41
- ['mp4', 'video/mp4'],
42
- ['ogg', 'audio/ogg'],
43
- ['pdf', 'application/pdf'],
44
- ['png', 'image/png'],
45
- ['pptx', 'application/vnd.openxmlformats-officedocument.presentationml.presentation'],
46
- ['svg', 'image/svg+xml'],
47
- ['txt', 'text/plain'],
48
- ['wav', 'audio/wav'],
49
- ['webm', 'video/webm'],
50
- ['webp', 'image/webp'],
51
- ['xlsx', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
52
- ['zip', 'application/zip'],
53
- ]);
54
- function refused(path, method, status, text, local) {
26
+ const WAY = {
27
+ ...(socketPath === undefined ? {} : { socketPath }),
28
+ unreached: (error) => new Error(socketPath === undefined ? UNREACHABLE : error.code === 'EPERM' || error.code === 'EACCES' ? SANDBOXED : CLOSED),
29
+ refused: (status) => storeRefusal('upload', status),
30
+ };
31
+ function refused(path, status, text, local) {
55
32
  const refusal = refusalOf(text);
56
33
  if (refusal !== null)
57
34
  return refusal.text;
58
35
  if (status === 401)
59
36
  return REVOKED;
60
- const act = method === 'GET' ? 'download' : 'upload';
61
- if (URL.canParse(path))
62
- return `the ${act} answered ${status}; ${act} the file again`;
63
37
  if (status === 502 && local)
64
38
  return text;
65
39
  return path === '/' ? unconfirmed(status) : `${path} answered ${status}`;
66
40
  }
67
- function unconfirmed(status) {
68
- return `House answered ${status} ${UNCONFIRMED}`;
69
- }
70
- function exchanged(path, method, body, headers = { 'content-type': 'application/json' }, to = socketPath) {
41
+ function bridged(path, body, to = socketPath) {
71
42
  return new Promise((resolve, reject) => {
72
- const sent = request({ socketPath: to, path, method, headers }, (answer) => {
43
+ const sent = request({ socketPath: to, path, method: 'POST', headers: { 'content-type': 'application/json' } }, (answer) => {
73
44
  const chunks = [];
74
45
  answer.on('data', (chunk) => chunks.push(chunk));
75
46
  answer.on('end', () => {
76
- const bytes = Buffer.concat(chunks);
47
+ const text = Buffer.concat(chunks).toString('utf8');
77
48
  if (answer.statusCode === 200)
78
- resolve(bytes);
49
+ resolve(text);
79
50
  else
80
- reject(new Error(refused(path, method, answer.statusCode, bytes.toString('utf8'), answer.headers['content-type'] === undefined)));
51
+ reject(new Error(refused(path, answer.statusCode, text, answer.headers['content-type'] === undefined)));
81
52
  });
82
53
  });
83
54
  sent.on('error', (error) => reject(new Error(error.code === 'EPERM' || error.code === 'EACCES' ? SANDBOXED : CLOSED)));
84
- sent.end(body === undefined ? undefined : body instanceof Buffer ? body : JSON.stringify(body));
55
+ sent.end(JSON.stringify(body));
85
56
  });
86
57
  }
87
- async function bridged(path, body, headers, to = socketPath) {
88
- return (await exchanged(path, 'POST', body, headers, to)).toString('utf8');
89
- }
90
- async function direct(message) {
91
- const ownAgent = await readOwnAgent();
92
- if (ownAgent === null)
93
- throw new Error(UNCONNECTED);
94
- selectRelay(process.env.HOUSE_KIT_RELAY || ownAgent.relay);
95
- setGlobalProxyFromEnv();
96
- const answer = await callHouse(ownAgent.house, ownAgent.credential, message).catch(() => {
97
- throw new Error(UNREACHABLE);
98
- });
99
- if (answer.status === 200)
100
- return answer.text;
101
- throw new Error(answer.status === 401 ? DISCONNECTED : (refusalOf(answer.text)?.text ?? unconfirmed(answer.status)));
102
- }
103
58
  async function mcp(method, params) {
104
59
  const message = rpc(method, params);
105
- const answer = JSON.parse(socketPath === undefined ? await direct(message) : await bridged('/', message));
60
+ const answer = JSON.parse(socketPath === undefined ? await ownAgentCall(message) : await bridged('/', message));
106
61
  if (answer.error !== undefined)
107
62
  throw new Error(answer.error.message);
108
63
  return answer.result;
@@ -110,91 +65,67 @@ async function mcp(method, params) {
110
65
  async function tools() {
111
66
  return (await mcp('tools/list', {})).tools;
112
67
  }
113
- async function localFile(path) {
114
- try {
115
- return await readFile(path);
116
- }
117
- catch (error) {
118
- throw new Error(error.code === 'EISDIR'
119
- ? `${path} is a folder; upload one file at a time`
120
- : `${path} is not a readable file`);
121
- }
122
- }
123
- async function transferred(url, method, bytes, headers) {
124
- if (socketPath !== undefined)
125
- return exchanged(url, method, bytes, headers);
126
- setGlobalProxyFromEnv();
127
- const answer = await fetch(relayed(url), { method, ...(headers === undefined ? {} : { headers }), ...(bytes === undefined ? {} : { body: bytes }) }).catch(() => {
128
- throw new Error(UNREACHABLE);
129
- });
130
- const received = Buffer.from(await answer.arrayBuffer());
131
- if (answer.status === 200)
132
- return received;
133
- throw new Error(refused(url, method, answer.status, received.toString('utf8'), false));
134
- }
135
- async function sent(url, bytes, operation) {
136
- const headers = { 'content-type': 'application/octet-stream', 'x-house-byte-operation': operation };
137
- return (await transferred(url, 'POST', bytes, headers)).toString('utf8');
68
+ function unreadable(path, error) {
69
+ return new Error(error.code === 'EISDIR'
70
+ ? `${path} is a folder; upload one file at a time`
71
+ : `${path} is not a readable file`);
138
72
  }
139
73
  async function download(args) {
140
74
  const { flags, positionals: [argument] } = accepted(args, ['--help'], 1, DOWNLOAD_USAGE);
141
75
  if (flags.has('--help'))
142
76
  return DOWNLOAD_USAGE;
143
- const { file, ...selected } = argumentsOf(argument);
77
+ const { file, ...selected } = await argumentsOf(argument);
144
78
  if (typeof file !== 'string' || file === '')
145
79
  throw new Error('download needs "file", the local file to write');
146
- const inspected = parse(await called('inspect', selected));
147
- if (typeof inspected?.download !== 'string')
148
- throw new Error(`${String(selected.path)} holds no binary file; shell reads its text`);
149
- const bytes = verified(await transferred(inspected.download, 'GET'), String(inspected.sha256), String(selected.path));
150
80
  const written = resolve(file);
151
- await mkdir(dirname(written), { recursive: true });
152
- await writeFile(written, bytes);
81
+ await downloaded(async () => {
82
+ const file = fileInfo(await called('info', selected));
83
+ if (file === null)
84
+ throw new Error(`${String(selected.path)} holds no binary file; shell reads its text`);
85
+ return file;
86
+ }, async (url) => {
87
+ const answer = await opened(url, 'GET', {}, WAY);
88
+ return { status: answer.statusCode, body: answer };
89
+ }, written, String(selected.path));
153
90
  return written;
154
91
  }
155
92
  async function described(file) {
156
- const bytes = await localFile(file);
157
- const mediaType = MEDIA_TYPES.get(extname(file).slice(1).toLowerCase());
158
- return {
159
- bytes,
160
- description: {
161
- bytes: bytes.length,
162
- sha256: createHash('sha256').update(bytes).digest('hex'),
163
- ...(mediaType === undefined ? {} : { media_type: mediaType }),
164
- },
165
- };
93
+ const digest = createHash('sha256');
94
+ let bytes = 0;
95
+ try {
96
+ for await (const chunk of createReadStream(file)) {
97
+ digest.update(chunk);
98
+ bytes += chunk.length;
99
+ }
100
+ }
101
+ catch (error) {
102
+ throw unreadable(file, error);
103
+ }
104
+ const mediaType = mediaTypeOf(file);
105
+ return { bytes, sha256: digest.digest('hex'), ...(mediaType === undefined ? {} : { media_type: mediaType }) };
106
+ }
107
+ async function finished(upload, room, partSha256) {
108
+ const text = await called('upload', { upload, room_ref: room, part_sha256: partSha256 });
109
+ const answer = parse(text);
110
+ return answer !== null && 'upload' in answer ? answer : { text };
166
111
  }
167
112
  async function upload({ file, ...destination }) {
168
113
  if (typeof file !== 'string' || file === '')
169
114
  throw new Error('upload needs "file", a local file');
170
- const { bytes, description } = await described(file);
115
+ const description = await described(file);
171
116
  const answer = await called('upload', { ...destination, ...description });
172
117
  const declared = parse(answer);
173
- if (declared.upload === undefined)
118
+ if (declared?.upload === undefined)
174
119
  return answer;
175
- const written = JSON.parse(await sent(declared.upload.url, bytes, declared.upload.operation));
176
- return stringify(written, { lineWidth: 0 }).trimEnd();
177
- }
178
- async function appendRecord(args) {
179
- const held = new Map();
180
- const attachments = Array.isArray(args.attachments)
181
- ? await Promise.all(args.attachments.map(async (attachment) => {
182
- if (typeof attachment !== 'string')
183
- return attachment;
184
- const { bytes, description } = await described(attachment);
185
- held.set(description.sha256, bytes);
186
- return { name: basename(attachment), ...description };
187
- }))
188
- : args.attachments;
189
- const record = { ...args, attachments };
190
- for (;;) {
191
- const answer = await called('append_record', record);
192
- const { upload } = parse(answer);
193
- if (upload === undefined)
194
- return answer;
195
- for (const grant of upload)
196
- await sent(grant.url, held.get(grant.sha256), grant.operation);
197
- }
120
+ const accepted = await uploaded(declared.upload, {
121
+ name: file,
122
+ bytes: description.bytes,
123
+ sha256: description.sha256,
124
+ read: (start, end) => fileRange(file, start, end, (error) => unreadable(file, error)),
125
+ send: (url, start, end, headers) => sentPart(url, file, start, end, headers, WAY),
126
+ finish: (id, partSha256) => finished(id, destination.room_ref, partSha256),
127
+ });
128
+ return accepted.text;
198
129
  }
199
130
  function unexpected(argument, usage) {
200
131
  return new Error(`unexpected argument ${argument}; ${usage}`);
@@ -204,7 +135,7 @@ function accepted(args, flags, positionals, usage) {
204
135
  for (const arg of args) {
205
136
  if (flags.includes(arg))
206
137
  given.flags.add(arg);
207
- else if (!arg.startsWith('-') && given.positionals.length < positionals)
138
+ else if ((arg === '-' || !arg.startsWith('-')) && given.positionals.length < positionals)
208
139
  given.positionals.push(arg);
209
140
  else
210
141
  throw unexpected(arg, usage);
@@ -214,13 +145,13 @@ function accepted(args, flags, positionals, usage) {
214
145
  async function push(args) {
215
146
  const { flags, positionals: [commit = 'HEAD'] } = accepted(args, ['--help', '--owner'], 1, PUSH_USAGE);
216
147
  if (flags.has('--help'))
217
- return PUSH_USAGE;
148
+ return `${PUSH_USAGE}\n${PUSH}`;
218
149
  const owner = flags.has('--owner');
219
150
  if (owner && socketPath !== undefined)
220
151
  throw new Error('--owner is not for Agent conversations; run house push without it');
221
152
  if (!owner && socketPath === undefined)
222
153
  throw new Error('outside an Agent conversation, house push needs --owner');
223
- const pushed = JSON.parse(await bridged('/git/push', { cwd: process.cwd(), commit }, undefined, owner ? ownerSocket() : socketPath));
154
+ const pushed = JSON.parse(await bridged('/git/push', { cwd: process.cwd(), commit }, owner ? ownerSocket() : socketPath));
224
155
  if (pushed.refused)
225
156
  throw new Error(pushed.text);
226
157
  return pushed.text;
@@ -228,17 +159,18 @@ async function push(args) {
228
159
  async function fetched(args) {
229
160
  if (accepted(args, ['--help'], 0, FETCH_USAGE).flags.has('--help'))
230
161
  return FETCH_USAGE;
231
- const answer = JSON.parse(await bridged('/git/fetch', {}, undefined, socketPath ?? ownerSocket()));
162
+ const answer = JSON.parse(await bridged('/git/fetch', {}, socketPath ?? ownerSocket()));
232
163
  if (answer.refused)
233
164
  throw new Error(answer.text);
234
165
  return answer.text;
235
166
  }
236
- function argumentsOf(argument) {
167
+ async function argumentsOf(argument) {
237
168
  if (argument === undefined)
238
169
  return {};
170
+ const given = argument === '-' ? await textOf(process.stdin) : argument;
239
171
  let parsed;
240
172
  try {
241
- parsed = JSON.parse(argument);
173
+ parsed = JSON.parse(given);
242
174
  }
243
175
  catch {
244
176
  throw new Error(ARGUMENTS);
@@ -247,23 +179,79 @@ function argumentsOf(argument) {
247
179
  throw new Error(ARGUMENTS);
248
180
  return parsed;
249
181
  }
182
+ // The schema a $ref points to inside the Tool's own inputSchema, or an empty one when it points elsewhere.
183
+ function resolved(schema, root) {
184
+ if (schema.$ref === undefined)
185
+ return schema;
186
+ if (!schema.$ref.startsWith('#'))
187
+ return {};
188
+ let found = root;
189
+ for (const key of schema.$ref.split('/').slice(1)) {
190
+ found = typeof found === 'object' && found !== null ? found[key.replaceAll('~1', '/').replaceAll('~0', '~')] : undefined;
191
+ }
192
+ return typeof found === 'object' && found !== null ? found : {};
193
+ }
194
+ // The schema a $ref resolves to, with that $ref added to the open ones, or null when it is open already,
195
+ // so a schema that holds itself is expanded once.
196
+ function expanded(schema, root, refs) {
197
+ if (schema.$ref === undefined)
198
+ return { schema, refs };
199
+ return refs.has(schema.$ref) ? null : { schema: resolved(schema, root), refs: new Set([...refs, schema.$ref]) };
200
+ }
201
+ // One line per argument: its name, its value when it has one or a few, whether it is required, and its
202
+ // description. When deep, the arguments its value holds follow it.
203
+ function argumentLines(schema, root, indent, deep, refs = new Set()) {
204
+ const required = new Set(schema.required ?? []);
205
+ return Object.entries(schema.properties ?? {}).flatMap(([name, property]) => {
206
+ const value = resolved(property, root);
207
+ const values = value.const !== undefined ? [value.const] : (value.enum ?? []);
208
+ const words = [name, ...(values.length === 0 ? [] : [values.map((one) => JSON.stringify(one)).join(' | ')]), ...(required.has(name) ? ['(required)'] : [])];
209
+ const description = property.description ?? value.description;
210
+ const line = `${indent}${words.join(' ')}${description === undefined ? '' : `: ${description}`}`;
211
+ return deep ? [line, ...held(property, root, `${indent} `, refs)] : [line];
212
+ });
213
+ }
214
+ // The arguments a value holds: its own, its items', and those of each alternative of a oneOf or anyOf,
215
+ // each alternative a "- " entry when more than one has arguments.
216
+ function held(schema, root, indent, refs) {
217
+ const value = expanded(schema, root, refs);
218
+ if (value === null)
219
+ return [];
220
+ const alternatives = (value.schema.oneOf ?? value.schema.anyOf ?? [])
221
+ .map((alternative) => held(alternative, root, indent, value.refs))
222
+ .filter((lines) => lines.length > 0);
223
+ return [
224
+ ...argumentLines(value.schema, root, indent, true, value.refs),
225
+ ...(value.schema.items === undefined ? [] : held(value.schema.items, root, indent, value.refs)),
226
+ ...(alternatives.length === 1
227
+ ? alternatives[0]
228
+ : alternatives.flatMap((lines) => lines.map((line, index) => (index === 0 ? `${indent}- ${line.slice(indent.length)}` : ` ${line}`)))),
229
+ ];
230
+ }
231
+ function listed(tool) {
232
+ return tool.description === undefined ? tool.name : `${tool.name}: ${tool.description}`;
233
+ }
234
+ async function toolHelp(name) {
235
+ const tool = (await tools()).find((one) => one.name === name);
236
+ if (tool === undefined)
237
+ throw new Error(`${name} is no Tool; house find_command '{"query":"${name}"}' finds Commands`);
238
+ return [listed(tool), ...argumentLines(tool.inputSchema, tool.inputSchema, ' ', true)].join('\n');
239
+ }
250
240
  async function house(args) {
251
241
  const { flags, positionals: [verb, argument] } = accepted(args, ['--help'], 2, USAGE);
252
- if (verb === 'help' && argument !== undefined)
253
- throw unexpected(argument, USAGE);
254
242
  if (flags.has('--help') && argument !== undefined)
255
243
  throw unexpected('--help', USAGE);
244
+ // house help <name> runs as house <name> --help, so both forms answer alike.
245
+ if (verb === 'help' && argument !== undefined)
246
+ return run([argument, '--help']);
256
247
  if (verb === undefined || verb === 'help') {
257
- return [USAGE, 'help', PUSH, FETCH, DOWNLOAD, ...(await tools()).map((tool) => (tool.description === undefined ? tool.name : `${tool.name}: ${tool.description}`))].join('\n');
258
- }
259
- if (flags.has('--help')) {
260
- const tool = (await tools()).find((listed) => listed.name === verb);
261
- if (tool === undefined)
262
- throw new Error(`${verb} is no Tool; house find_command '{"query":"${verb}"}' finds Commands`);
263
- return [...(tool.description === undefined ? [] : [tool.description]), JSON.stringify(tool.inputSchema)].join('\n');
248
+ const listing = (await tools()).flatMap((tool) => tool.description === undefined ? [tool.name, ...argumentLines(tool.inputSchema, tool.inputSchema, ' ', false)] : [listed(tool)]);
249
+ return [USAGE, HELP, PUSH, FETCH, DOWNLOAD, ...listing].join('\n');
264
250
  }
265
- const parsed = argumentsOf(argument);
266
- return verb === 'upload' ? upload(parsed) : verb === 'append_record' ? appendRecord(parsed) : called(verb, parsed);
251
+ if (flags.has('--help'))
252
+ return verb === 'upload' ? UPLOAD_USAGE : toolHelp(verb);
253
+ const parsed = await argumentsOf(argument);
254
+ return verb === 'upload' ? upload(parsed) : called(verb, parsed);
267
255
  }
268
256
  async function called(name, args) {
269
257
  const result = await mcp('tools/call', { name, arguments: args });
@@ -272,16 +260,19 @@ async function called(name, args) {
272
260
  throw new Error(text.replace(/\n+$/, ''));
273
261
  return text;
274
262
  }
263
+ function run(argv) {
264
+ const named = argv.findIndex((arg) => !arg.startsWith('-'));
265
+ const rest = argv.filter((_arg, index) => index !== named);
266
+ if (argv[named] === 'push')
267
+ return push(rest);
268
+ if (argv[named] === 'fetch')
269
+ return fetched(rest);
270
+ if (argv[named] === 'download')
271
+ return download(rest);
272
+ return house(argv);
273
+ }
275
274
  const argv = process.argv.slice(2);
276
- const named = argv.findIndex((arg) => !arg.startsWith('-'));
277
- const rest = argv.filter((_arg, index) => index !== named);
278
- (argv[named] === 'push'
279
- ? push(rest)
280
- : argv[named] === 'fetch'
281
- ? fetched(rest)
282
- : argv[named] === 'download'
283
- ? download(rest)
284
- : house(argv)).then((text) => {
275
+ run(argv).then((text) => {
285
276
  process.stdout.write(`${text}\n`);
286
277
  if (argv[0] === 'shell')
287
278
  process.exitCode = Number(/^exit: (\d+)(?:\n|$)/.exec(text)?.[1] ?? 0);
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
- const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
3
- if (major < 24 || (major === 24 && minor < 14)) {
4
- process.stderr.write(`house: the Kit needs Node 24.14.0 or newer; this is ${process.versions.node}\n`);
2
+ const [major = 0, minor = 0, patch = 0] = process.versions.node.split('.').map(Number);
3
+ if (major < 24 || (major === 24 && (minor < 22 || (minor === 22 && patch < 1)))) {
4
+ process.stderr.write(`house: the Kit needs Node 24.22.1 or newer; this is ${process.versions.node}\n`);
5
5
  process.exitCode = 1;
6
6
  }
7
7
  else {