@agentshouse/kit 0.2.1-ce3d2bb67177c → 0.2.1-ce46b2b55463f

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 (161) hide show
  1. package/README.md +31 -35
  2. package/dist/acp.js +56 -6
  3. package/dist/afk.js +17 -0
  4. package/dist/agents.js +120 -51
  5. package/dist/api.js +11 -6
  6. package/dist/binaries.js +79 -0
  7. package/dist/bridge.js +30 -26
  8. package/dist/building.js +50 -0
  9. package/dist/calls.js +29 -4
  10. package/dist/chunks.js +49 -0
  11. package/dist/clis.js +61 -49
  12. package/dist/connect.js +108 -0
  13. package/dist/connection.js +33 -38
  14. package/dist/content.js +106 -0
  15. package/dist/conversations.js +325 -141
  16. package/dist/copies.js +720 -247
  17. package/dist/earlier.js +263 -0
  18. package/dist/end.js +4 -5
  19. package/dist/events.js +549 -281
  20. package/dist/files.js +110 -28
  21. package/dist/git-main.js +24 -29
  22. package/dist/git.js +89 -14
  23. package/dist/grok.js +39 -0
  24. package/dist/home.js +65 -29
  25. package/dist/house-cli.js +114 -159
  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 +16 -6
  30. package/dist/kit-main.js +3 -3
  31. package/dist/login.js +36 -20
  32. package/dist/logout.js +2 -2
  33. package/dist/mcp.js +38 -1
  34. package/dist/owner.js +46 -0
  35. package/dist/placement.js +9 -23
  36. package/dist/refusals.js +37 -21
  37. package/dist/relay.js +21 -0
  38. package/dist/resident.js +109 -65
  39. package/dist/scope.js +12 -4
  40. package/dist/scripts.js +303 -0
  41. package/dist/secret-input.js +1 -1
  42. package/dist/settings.js +188 -0
  43. package/dist/sign-in.js +49 -3
  44. package/dist/silence.js +28 -0
  45. package/dist/skills.js +41 -96
  46. package/dist/supervisor.js +163 -0
  47. package/dist/transcription.js +37 -25
  48. package/dist/translate.js +18 -9
  49. package/dist/update.js +115 -117
  50. package/dist/wire.js +19 -9
  51. package/dist/work.js +9 -2
  52. package/dist/workspace.js +103 -0
  53. package/package.json +25 -21
  54. package/dist/authority-main.js +0 -22
  55. package/dist/bootstrap.json +0 -24
  56. package/dist/chatgpt.js +0 -32
  57. package/dist/clis-main.js +0 -23
  58. package/dist/configure-main.js +0 -6
  59. package/dist/enrol-main.js +0 -10
  60. package/dist/parts.js +0 -82
  61. package/dist/service-main.js +0 -9
  62. package/dist/service.js +0 -55
  63. package/how-we-work.md +0 -33
  64. package/skills/ask-matt/LICENSE +0 -21
  65. package/skills/ask-matt/PHASE-BOUNDARIES.md +0 -55
  66. package/skills/ask-matt/SKILL.md +0 -97
  67. package/skills/ask-matt/agents/openai.yaml +0 -5
  68. package/skills/code-review/LICENSE +0 -21
  69. package/skills/code-review/SKILL.md +0 -89
  70. package/skills/code-review/agents/openai.yaml +0 -3
  71. package/skills/codebase-design/DEEPENING.md +0 -37
  72. package/skills/codebase-design/DESIGN-IT-TWICE.md +0 -44
  73. package/skills/codebase-design/LICENSE +0 -21
  74. package/skills/codebase-design/SKILL.md +0 -114
  75. package/skills/codebase-design/agents/openai.yaml +0 -3
  76. package/skills/diagnosing-bugs/LICENSE +0 -21
  77. package/skills/diagnosing-bugs/SKILL.md +0 -138
  78. package/skills/diagnosing-bugs/agents/openai.yaml +0 -3
  79. package/skills/diagnosing-bugs/scripts/hitl-loop.template.sh +0 -44
  80. package/skills/domain-modeling/ADR-FORMAT.md +0 -47
  81. package/skills/domain-modeling/GLOSSARY-FORMAT.md +0 -60
  82. package/skills/domain-modeling/LICENSE +0 -21
  83. package/skills/domain-modeling/SKILL.md +0 -74
  84. package/skills/domain-modeling/agents/openai.yaml +0 -3
  85. package/skills/grill-me/LICENSE +0 -21
  86. package/skills/grill-me/SKILL.md +0 -7
  87. package/skills/grill-me/agents/openai.yaml +0 -5
  88. package/skills/grill-with-docs/LICENSE +0 -21
  89. package/skills/grill-with-docs/SKILL.md +0 -7
  90. package/skills/grill-with-docs/agents/openai.yaml +0 -5
  91. package/skills/grilling/LICENSE +0 -21
  92. package/skills/grilling/SKILL.md +0 -30
  93. package/skills/grilling/agents/openai.yaml +0 -3
  94. package/skills/handoff/LICENSE +0 -21
  95. package/skills/handoff/SKILL.md +0 -16
  96. package/skills/handoff/agents/openai.yaml +0 -5
  97. package/skills/implement/LICENSE +0 -21
  98. package/skills/implement/SKILL.md +0 -17
  99. package/skills/implement/agents/openai.yaml +0 -5
  100. package/skills/implement-spec/LICENSE +0 -21
  101. package/skills/implement-spec/SKILL.md +0 -40
  102. package/skills/implement-spec/agents/openai.yaml +0 -5
  103. package/skills/improve-codebase-architecture/HTML-REPORT.md +0 -123
  104. package/skills/improve-codebase-architecture/LICENSE +0 -21
  105. package/skills/improve-codebase-architecture/SKILL.md +0 -71
  106. package/skills/improve-codebase-architecture/agents/openai.yaml +0 -5
  107. package/skills/pr/CREDITS.md +0 -3
  108. package/skills/pr/LICENSE +0 -21
  109. package/skills/pr/SKILL.md +0 -170
  110. package/skills/pr/agents/openai.yaml +0 -3
  111. package/skills/prototype/LICENSE +0 -21
  112. package/skills/prototype/LOGIC.md +0 -67
  113. package/skills/prototype/SKILL.md +0 -26
  114. package/skills/prototype/UI.md +0 -112
  115. package/skills/prototype/agents/openai.yaml +0 -3
  116. package/skills/research/LICENSE +0 -21
  117. package/skills/research/SKILL.md +0 -12
  118. package/skills/research/agents/openai.yaml +0 -3
  119. package/skills/retro/LICENSE +0 -21
  120. package/skills/retro/SKILL.md +0 -44
  121. package/skills/retro/agents/openai.yaml +0 -5
  122. package/skills/tdd/LICENSE +0 -21
  123. package/skills/tdd/SKILL.md +0 -38
  124. package/skills/tdd/agents/openai.yaml +0 -3
  125. package/skills/tdd/mocking.md +0 -59
  126. package/skills/tdd/tests.md +0 -77
  127. package/skills/teach/GLOSSARY-FORMAT.md +0 -35
  128. package/skills/teach/LEARNING-RECORD-FORMAT.md +0 -46
  129. package/skills/teach/LICENSE +0 -21
  130. package/skills/teach/MISSION-FORMAT.md +0 -31
  131. package/skills/teach/RESOURCES-FORMAT.md +0 -32
  132. package/skills/teach/SKILL.md +0 -140
  133. package/skills/teach/agents/openai.yaml +0 -5
  134. package/skills/to-questionnaire/LICENSE +0 -21
  135. package/skills/to-questionnaire/SKILL.md +0 -54
  136. package/skills/to-questionnaire/agents/openai.yaml +0 -5
  137. package/skills/to-spec/LICENSE +0 -21
  138. package/skills/to-spec/SKILL.md +0 -75
  139. package/skills/to-spec/agents/openai.yaml +0 -5
  140. package/skills/to-tickets/LICENSE +0 -21
  141. package/skills/to-tickets/SKILL.md +0 -105
  142. package/skills/to-tickets/agents/openai.yaml +0 -5
  143. package/skills/triage/AGENT-BRIEF.md +0 -207
  144. package/skills/triage/LICENSE +0 -21
  145. package/skills/triage/OUT-OF-SCOPE.md +0 -105
  146. package/skills/triage/SKILL.md +0 -112
  147. package/skills/triage/agents/openai.yaml +0 -5
  148. package/skills/wait-what/LICENSE +0 -21
  149. package/skills/wait-what/SKILL.md +0 -7
  150. package/skills/wait-what/agents/openai.yaml +0 -5
  151. package/skills/wayfinder/LICENSE +0 -21
  152. package/skills/wayfinder/SKILL.md +0 -128
  153. package/skills/wayfinder/agents/openai.yaml +0 -5
  154. package/skills/wizard/LICENSE +0 -21
  155. package/skills/wizard/SKILL.md +0 -44
  156. package/skills/wizard/agents/openai.yaml +0 -3
  157. package/skills/wizard/template.sh +0 -223
  158. package/skills/writing-for-agents/LICENSE +0 -21
  159. package/skills/writing-for-agents/SKILL-MECHANICS.md +0 -22
  160. package/skills/writing-for-agents/SKILL.md +0 -81
  161. package/skills/writing-for-agents/agents/openai.yaml +0 -3
package/dist/house-cli.js CHANGED
@@ -1,60 +1,33 @@
1
1
  import { createHash } from 'node:crypto';
2
2
  import { createReadStream } from 'node:fs';
3
- import { readFile } from 'node:fs/promises';
4
- import { request, setGlobalProxyFromEnv } from 'node:http';
5
- import { request as httpsRequest } from 'node:https';
6
- import { basename, extname, join, resolve } from 'node:path';
7
- import { Readable } from 'node:stream';
8
- import { pipeline } from 'node:stream/promises';
9
- import { downloaded, inspectedFile, storeRefusal, uploaded } from './files.js';
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';
10
7
  import { HOUSE_REF } from './git.js';
11
- import { ownerSocket, readOwnAgent } from './home.js';
12
- import { callHouse, rpc, UNREACHABLE, Unsettled } from './mcp.js';
13
- import { refusalOf, retryable } from './refusals.js';
14
- import { relayed, selectRelay } from './relay.js';
8
+ import { ownerSocket } from './home.js';
9
+ import { ownAgentCall, rpc, unconfirmed, UNREACHABLE } from './mcp.js';
10
+ import { refusalOf } from './refusals.js';
15
11
  import { parse } from 'yaml';
16
- const USAGE = "usage: house <tool> ['<arguments as JSON>']";
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]';
17
14
  const PUSH_USAGE = 'usage: house push [commit] [--owner]';
18
- 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; one commit and one push carry text and binary files alike";
19
16
  const FETCH_USAGE = 'usage: house fetch';
20
17
  const FETCH = `fetch: records House's changes on each Local copy's ${HOUSE_REF}`;
21
18
  const DOWNLOAD_USAGE = `usage: house download '{"path":"/rooms/<handle>/<path>","file":"<local file>"}', adding "ref" for a revision`;
22
19
  const DOWNLOAD = 'download: writes a binary file of a Room to the local file named by file';
23
- 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"}'`;
24
22
  const CLOSED = "this conversation's House connection is closed; nothing to do from here";
25
23
  const SANDBOXED = "your CLI's sandbox kept house from House; run house directly, not through another program";
26
24
  const REVOKED = 'this conversation no longer has House access; nothing to do from here';
27
- const UNCONNECTED = "this computer's own agent has no House connection; run kit login, or kit chatgpt --key <key> with a script key";
28
- const DISCONNECTED = "House no longer accepts this computer's own agent; run kit login, or kit chatgpt --key <key> with a script key";
29
- const UNCONFIRMED = 'with no result; a write may or may not have taken effect, so read before you repeat it';
30
25
  const socketPath = process.env.HOUSE_BRIDGE;
31
- const MEDIA_TYPES = new Map([
32
- ['avif', 'image/avif'],
33
- ['csv', 'text/csv'],
34
- ['docx', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
35
- ['gif', 'image/gif'],
36
- ['heic', 'image/heic'],
37
- ['html', 'text/html'],
38
- ['jpeg', 'image/jpeg'],
39
- ['jpg', 'image/jpeg'],
40
- ['json', 'application/json'],
41
- ['m4a', 'audio/mp4'],
42
- ['md', 'text/markdown'],
43
- ['mov', 'video/quicktime'],
44
- ['mp3', 'audio/mpeg'],
45
- ['mp4', 'video/mp4'],
46
- ['ogg', 'audio/ogg'],
47
- ['pdf', 'application/pdf'],
48
- ['png', 'image/png'],
49
- ['pptx', 'application/vnd.openxmlformats-officedocument.presentationml.presentation'],
50
- ['svg', 'image/svg+xml'],
51
- ['txt', 'text/plain'],
52
- ['wav', 'audio/wav'],
53
- ['webm', 'video/webm'],
54
- ['webp', 'image/webp'],
55
- ['xlsx', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
56
- ['zip', 'application/zip'],
57
- ]);
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
+ };
58
31
  function refused(path, status, text, local) {
59
32
  const refusal = refusalOf(text);
60
33
  if (refusal !== null)
@@ -65,9 +38,6 @@ function refused(path, status, text, local) {
65
38
  return text;
66
39
  return path === '/' ? unconfirmed(status) : `${path} answered ${status}`;
67
40
  }
68
- function unconfirmed(status) {
69
- return `House answered ${status} ${UNCONFIRMED}`;
70
- }
71
41
  function bridged(path, body, to = socketPath) {
72
42
  return new Promise((resolve, reject) => {
73
43
  const sent = request({ socketPath: to, path, method: 'POST', headers: { 'content-type': 'application/json' } }, (answer) => {
@@ -85,25 +55,9 @@ function bridged(path, body, to = socketPath) {
85
55
  sent.end(JSON.stringify(body));
86
56
  });
87
57
  }
88
- async function direct(message) {
89
- const ownAgent = await readOwnAgent();
90
- if (ownAgent === null)
91
- throw new Error(UNCONNECTED);
92
- selectRelay(process.env.HOUSE_KIT_RELAY || ownAgent.relay);
93
- setGlobalProxyFromEnv();
94
- const answer = await callHouse(ownAgent.house, ownAgent.credential, message).catch(() => {
95
- throw new Unsettled(UNREACHABLE);
96
- });
97
- if (answer.status === 200)
98
- return answer.text;
99
- if (answer.status === 401)
100
- throw new Error(DISCONNECTED);
101
- const refusal = refusalOf(answer.text)?.text ?? unconfirmed(answer.status);
102
- throw retryable(answer.text) === false ? new Error(refusal) : new Unsettled(refusal);
103
- }
104
58
  async function mcp(method, params) {
105
59
  const message = rpc(method, params);
106
- 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));
107
61
  if (answer.error !== undefined)
108
62
  throw new Error(answer.error.message);
109
63
  return answer.result;
@@ -116,62 +70,21 @@ function unreadable(path, error) {
116
70
  ? `${path} is a folder; upload one file at a time`
117
71
  : `${path} is not a readable file`);
118
72
  }
119
- async function localFile(path) {
120
- try {
121
- return await readFile(path);
122
- }
123
- catch (error) {
124
- throw unreadable(path, error);
125
- }
126
- }
127
- function opened(url, method, headers, body) {
128
- return new Promise((answered, failed) => {
129
- const local = socketPath !== undefined;
130
- const target = local ? null : relayed(url);
131
- if (!local)
132
- setGlobalProxyFromEnv();
133
- const sent = target === null
134
- ? request({ socketPath, path: url, method, headers }, answered)
135
- : (target.protocol === 'https:' ? httpsRequest : request)(target, { method, headers }, answered);
136
- sent.on('error', (error) => failed(new Error(!local ? UNREACHABLE : error.code === 'EPERM' || error.code === 'EACCES' ? SANDBOXED : CLOSED)));
137
- if (body instanceof Readable)
138
- pipeline(body, sent).catch(() => undefined);
139
- else
140
- sent.end(body);
141
- });
142
- }
143
- async function textOf(answer) {
144
- return Buffer.concat(await answer.toArray()).toString('utf8');
145
- }
146
- async function sent(url, bytes, operation) {
147
- const headers = { 'content-type': 'application/octet-stream', 'x-house-byte-operation': operation };
148
- const answer = await opened(url, 'POST', headers, bytes);
149
- const text = await textOf(answer);
150
- if (answer.statusCode === 200)
151
- return text;
152
- throw new Error(refusalOf(text)?.text ?? storeRefusal('upload', answer.statusCode).message);
153
- }
154
- async function sentPart(url, file, start, end) {
155
- const answer = await opened(url, 'PUT', { 'content-length': String(end - start) }, end === start ? undefined : createReadStream(file, { start, end: end - 1 }));
156
- await answer.toArray();
157
- if (answer.statusCode !== 200)
158
- throw storeRefusal('upload', answer.statusCode);
159
- }
160
73
  async function download(args) {
161
74
  const { flags, positionals: [argument] } = accepted(args, ['--help'], 1, DOWNLOAD_USAGE);
162
75
  if (flags.has('--help'))
163
76
  return DOWNLOAD_USAGE;
164
- const { file, ...selected } = argumentsOf(argument);
77
+ const { file, ...selected } = await argumentsOf(argument);
165
78
  if (typeof file !== 'string' || file === '')
166
79
  throw new Error('download needs "file", the local file to write');
167
80
  const written = resolve(file);
168
81
  await downloaded(async () => {
169
- const file = inspectedFile(await called('inspect', selected));
82
+ const file = fileInfo(await called('info', selected));
170
83
  if (file === null)
171
84
  throw new Error(`${String(selected.path)} holds no binary file; shell reads its text`);
172
85
  return file;
173
86
  }, async (url) => {
174
- const answer = await opened(url, 'GET', {});
87
+ const answer = await opened(url, 'GET', {}, WAY);
175
88
  return { status: answer.statusCode, body: answer };
176
89
  }, written, String(selected.path));
177
90
  return written;
@@ -188,13 +101,13 @@ async function described(file) {
188
101
  catch (error) {
189
102
  throw unreadable(file, error);
190
103
  }
191
- const mediaType = MEDIA_TYPES.get(extname(file).slice(1).toLowerCase());
104
+ const mediaType = mediaTypeOf(file);
192
105
  return { bytes, sha256: digest.digest('hex'), ...(mediaType === undefined ? {} : { media_type: mediaType }) };
193
106
  }
194
- async function finished(upload, room) {
195
- const text = await called('upload', { upload, room_ref: room });
107
+ async function finished(upload, room, partSha256) {
108
+ const text = await called('upload', { upload, room_ref: room, part_sha256: partSha256 });
196
109
  const answer = parse(text);
197
- return answer !== null && ('upload' in answer || 'checking' in answer) ? answer : { text };
110
+ return answer !== null && 'upload' in answer ? answer : { text };
198
111
  }
199
112
  async function upload({ file, ...destination }) {
200
113
  if (typeof file !== 'string' || file === '')
@@ -205,33 +118,15 @@ async function upload({ file, ...destination }) {
205
118
  if (declared?.upload === undefined)
206
119
  return answer;
207
120
  const accepted = await uploaded(declared.upload, {
121
+ name: file,
208
122
  bytes: description.bytes,
209
- send: (url, start, end) => sentPart(url, file, start, end),
210
- finish: (id) => finished(id, destination.room_ref),
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),
211
127
  });
212
128
  return accepted.text;
213
129
  }
214
- async function appendRecord(args) {
215
- const held = new Map();
216
- const attachments = Array.isArray(args.attachments)
217
- ? await Promise.all(args.attachments.map(async (attachment) => {
218
- if (typeof attachment !== 'string')
219
- return attachment;
220
- const description = await described(attachment);
221
- held.set(description.sha256, attachment);
222
- return { name: basename(attachment), ...description };
223
- }))
224
- : args.attachments;
225
- const record = { ...args, attachments };
226
- for (;;) {
227
- const answer = await called('append_record', record);
228
- const { upload } = parse(answer);
229
- if (upload === undefined)
230
- return answer;
231
- for (const grant of upload)
232
- await sent(grant.url, await localFile(held.get(grant.sha256)), grant.operation);
233
- }
234
- }
235
130
  function unexpected(argument, usage) {
236
131
  return new Error(`unexpected argument ${argument}; ${usage}`);
237
132
  }
@@ -240,7 +135,7 @@ function accepted(args, flags, positionals, usage) {
240
135
  for (const arg of args) {
241
136
  if (flags.includes(arg))
242
137
  given.flags.add(arg);
243
- else if (!arg.startsWith('-') && given.positionals.length < positionals)
138
+ else if ((arg === '-' || !arg.startsWith('-')) && given.positionals.length < positionals)
244
139
  given.positionals.push(arg);
245
140
  else
246
141
  throw unexpected(arg, usage);
@@ -250,7 +145,7 @@ function accepted(args, flags, positionals, usage) {
250
145
  async function push(args) {
251
146
  const { flags, positionals: [commit = 'HEAD'] } = accepted(args, ['--help', '--owner'], 1, PUSH_USAGE);
252
147
  if (flags.has('--help'))
253
- return PUSH_USAGE;
148
+ return `${PUSH_USAGE}\n${PUSH}`;
254
149
  const owner = flags.has('--owner');
255
150
  if (owner && socketPath !== undefined)
256
151
  throw new Error('--owner is not for Agent conversations; run house push without it');
@@ -269,12 +164,13 @@ async function fetched(args) {
269
164
  throw new Error(answer.text);
270
165
  return answer.text;
271
166
  }
272
- function argumentsOf(argument) {
167
+ async function argumentsOf(argument) {
273
168
  if (argument === undefined)
274
169
  return {};
170
+ const given = argument === '-' ? await textOf(process.stdin) : argument;
275
171
  let parsed;
276
172
  try {
277
- parsed = JSON.parse(argument);
173
+ parsed = JSON.parse(given);
278
174
  }
279
175
  catch {
280
176
  throw new Error(ARGUMENTS);
@@ -283,23 +179,79 @@ function argumentsOf(argument) {
283
179
  throw new Error(ARGUMENTS);
284
180
  return parsed;
285
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
+ }
286
240
  async function house(args) {
287
241
  const { flags, positionals: [verb, argument] } = accepted(args, ['--help'], 2, USAGE);
288
- if (verb === 'help' && argument !== undefined)
289
- throw unexpected(argument, USAGE);
290
242
  if (flags.has('--help') && argument !== undefined)
291
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']);
292
247
  if (verb === undefined || verb === 'help') {
293
- return [USAGE, 'help', PUSH, FETCH, DOWNLOAD, ...(await tools()).map((tool) => (tool.description === undefined ? tool.name : `${tool.name}: ${tool.description}`))].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');
294
250
  }
295
- if (flags.has('--help')) {
296
- const tool = (await tools()).find((listed) => listed.name === verb);
297
- if (tool === undefined)
298
- throw new Error(`${verb} is no Tool; house find_command '{"query":"${verb}"}' finds Commands`);
299
- return [...(tool.description === undefined ? [] : [tool.description]), JSON.stringify(tool.inputSchema)].join('\n');
300
- }
301
- const parsed = argumentsOf(argument);
302
- 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);
303
255
  }
304
256
  async function called(name, args) {
305
257
  const result = await mcp('tools/call', { name, arguments: args });
@@ -308,16 +260,19 @@ async function called(name, args) {
308
260
  throw new Error(text.replace(/\n+$/, ''));
309
261
  return text;
310
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
+ }
311
274
  const argv = process.argv.slice(2);
312
- const named = argv.findIndex((arg) => !arg.startsWith('-'));
313
- const rest = argv.filter((_arg, index) => index !== named);
314
- (argv[named] === 'push'
315
- ? push(rest)
316
- : argv[named] === 'fetch'
317
- ? fetched(rest)
318
- : argv[named] === 'download'
319
- ? download(rest)
320
- : house(argv)).then((text) => {
275
+ run(argv).then((text) => {
321
276
  process.stdout.write(`${text}\n`);
322
277
  if (argv[0] === 'shell')
323
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 {
@@ -1,12 +1,30 @@
1
- import { HOUSE_REF } from './git.js';
2
- import { readHowWeWork } from './skills.js';
3
- const SOURCE_LINE = "From House:";
4
- const HOUSE_LINE = "Work with House through the `house` CLI: run `house --help`, and `house find_command` for House's guides and formats.";
5
- const FILE_LINE = 'To give the User a file, upload it with `house upload` and link it; for an App, a Site or a website, follow `house find_command \'{"query":"app"}\'`. Never start a server.';
6
- const READ_LINE = "Optional per-Room instructions: `/rooms/private/rooms/<handle>/AGENTS.md`.";
7
- const REQUEST_LINE = "For another Agent's help, `send_routine_request`; its mail comes back into this conversation. If an Agent of your User has no Routine to call, write one in the Private Room and `create_routine_access` with your User as its only caller.";
8
- const COPIES_LINE = `House Local copies; before work run \`house fetch\` and rebase onto \`${HOUSE_REF}\`; after it commit, then \`house push\`:`;
9
- export async function instructions(bridge, base, copies) {
10
- const lines = [SOURCE_LINE, HOUSE_LINE, FILE_LINE, READ_LINE, REQUEST_LINE, ...(copies.length === 0 ? [] : [COPIES_LINE, ...copies])];
11
- return [lines.join('\n'), base, (await readHowWeWork(bridge)).replace(/\n$/, '')].filter((part) => part !== '').join('\n\n');
1
+ import { agentInstructions } from '@agentshouse/skills';
2
+ const OWNER_RULES = '/rooms/private/owner-rules.md';
3
+ const UNREADABLE = /^(?:\S+: )?(?:path_not_found|room_not_found|operation_denied)\b/;
4
+ const FAILED = /^exit: [1-9]\d*$/;
5
+ const CUT = /^stderr: shell: output_cut (\d+) of \d+ bytes; continue with: (.+)$/;
6
+ function cutOf(lines) {
7
+ const cut = CUT.exec(lines[0] ?? '');
8
+ return cut !== null && Buffer.byteLength(lines.slice(1).join('\n')) === Number(cut[1]) ? cut : null;
9
+ }
10
+ async function readOwnerRules(bridge) {
11
+ let document = '';
12
+ for (let command = `cat ${OWNER_RULES}`; command !== undefined;) {
13
+ const read = await bridge.tool('shell', { command });
14
+ const text = read.content.map((content) => content.text).join('\n');
15
+ const lines = text.split('\n');
16
+ if (read.isError === true || (FAILED.test(lines[0] ?? '') && lines[1]?.startsWith('stderr: '))) {
17
+ const refusal = read.isError === true ? text : lines.slice(1).join('\n').replace(/^stderr: /gm, '');
18
+ if (UNREADABLE.test(refusal))
19
+ return '';
20
+ throw new Error(refusal);
21
+ }
22
+ const cut = cutOf(lines);
23
+ document += lines.slice(cut === null ? 0 : 1).join('\n');
24
+ command = cut?.[2];
25
+ }
26
+ return document;
27
+ }
28
+ export async function instructions(bridge, base) {
29
+ return [agentInstructions().join('\n'), base, (await readOwnerRules(bridge)).replace(/\n$/, '')].filter((part) => part !== '').join('\n\n');
12
30
  }