@agentshouse/kit 0.2.1-ccf188e02985d → 0.2.1-cd423aab3dbcc

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 +35 -42
  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 +60 -0
  7. package/dist/bridge.js +100 -45
  8. package/dist/building.js +50 -0
  9. package/dist/calls.js +88 -0
  10. package/dist/chunks.js +54 -0
  11. package/dist/clis.js +62 -50
  12. package/dist/connect.js +121 -0
  13. package/dist/connection.js +120 -0
  14. package/dist/content.js +106 -0
  15. package/dist/conversations.js +617 -240
  16. package/dist/copies.js +1277 -623
  17. package/dist/earlier.js +273 -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.js +2 -72
  22. package/dist/grok.js +39 -0
  23. package/dist/home.js +86 -29
  24. package/dist/house-cli.js +180 -189
  25. package/dist/house-main.js +3 -3
  26. package/dist/instructions.js +29 -11
  27. package/dist/keys.js +238 -0
  28. package/dist/kit-cli.js +18 -8
  29. package/dist/kit-main.js +3 -3
  30. package/dist/login.js +36 -22
  31. package/dist/logout.js +2 -2
  32. package/dist/manifest.js +75 -0
  33. package/dist/mcp.js +47 -7
  34. package/dist/owner.js +46 -0
  35. package/dist/placement.js +15 -20
  36. package/dist/refusals.js +50 -23
  37. package/dist/relay.js +21 -0
  38. package/dist/resident.js +141 -90
  39. package/dist/scope.js +15 -4
  40. package/dist/scripts.js +319 -0
  41. package/dist/secret-input.js +1 -1
  42. package/dist/settings.js +247 -0
  43. package/dist/sign-in.js +67 -21
  44. package/dist/silence.js +28 -0
  45. package/dist/skills.js +42 -97
  46. package/dist/supervisor.js +163 -0
  47. package/dist/transcription.js +88 -45
  48. package/dist/update.js +118 -120
  49. package/dist/wire.js +30 -4
  50. package/dist/work.js +27 -2
  51. package/dist/workspace.js +113 -0
  52. package/package.json +25 -22
  53. package/dist/authority-main.js +0 -22
  54. package/dist/bootstrap.json +0 -24
  55. package/dist/chatgpt.js +0 -32
  56. package/dist/clis-main.js +0 -23
  57. package/dist/configure-main.js +0 -6
  58. package/dist/enrol-main.js +0 -10
  59. package/dist/git-main.js +0 -153
  60. package/dist/inputs.js +0 -37
  61. package/dist/parts.js +0 -82
  62. package/dist/service-main.js +0 -9
  63. package/dist/service.js +0 -55
  64. package/dist/stream.js +0 -123
  65. package/dist/translate.js +0 -51
  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/house-cli.js CHANGED
@@ -1,108 +1,61 @@
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';
6
- import { HOUSE_REF } from './git.js';
7
- import { ownerSocket, readOwnAgent } from './home.js';
8
- import { callHouse, rpc, UNREACHABLE } from './mcp.js';
1
+ import { request } from 'node:http';
2
+ import { resolve } from 'node:path';
3
+ import { text as textOf } from 'node:stream/consumers';
4
+ import { downloaded, fileInfo, fileRange, mediaTypeOf, opened, sentPart, storeRefusal, uploaded, } from './files.js';
5
+ import { DEFAULT_MAX_SIZE, UPLOAD_NEEDS_OWNER } from './copies.js';
6
+ import { ownerSocket } from './home.js';
7
+ import { fileDigest } from './manifest.js';
8
+ import { ownAgentCall, rpc, unconfirmed, UNREACHABLE } from './mcp.js';
9
9
  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>']";
13
- const PUSH_USAGE = 'usage: house push [commit] [--owner]';
14
- const PUSH = "push [commit]: sends the Local copy's committed changes to House";
15
- const FETCH_USAGE = 'usage: house fetch';
16
- const FETCH = `fetch: records House's changes on each Local copy's ${HOUSE_REF}`;
17
- const DOWNLOAD_USAGE = `usage: house download '{"path":"/rooms/<handle>/<path>","file":"<local file>"}', adding "ref" for a revision`;
18
- 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 CLOSED = "this conversation's House connection is closed; nothing to do from here";
10
+ import { parse } from 'yaml';
11
+ const USAGE = "usage: house <tool> ['<arguments as JSON>'], or house <tool> - to read them from stdin; house help <tool>: its arguments";
12
+ const HELP = 'help [tool]';
13
+ const UPLOAD_USAGE = `usage: house upload [--owner], or house upload '{"file":"<local file>","path":"/rooms/<handle>/<path>"}', adding "base", the revision it replaces`;
14
+ const UPLOAD = "upload: in a Room's Local copy, sends every file changed, added or deleted there since it last matched House, each .md file as document text and every other file as an attachment, with --owner outside an Agent conversation; with JSON, sends one local file to the Room path it names";
15
+ const DOWNLOAD_USAGE = `usage: house download [--with-attachments] [--max-size <MB>], or house download '{"path":"/rooms/<handle>/<path>","file":"<local file>"}', adding "ref" for a revision`;
16
+ const DOWNLOAD = `download: brings House's changes into every Local copy, leaving each file changed here for the next house upload, and with --with-attachments each attachment it lacks up to --max-size megabytes, ${DEFAULT_MAX_SIZE} by default; with JSON, writes one attachment of a Room to the local file named by file`;
17
+ const MAX_SIZE = `--max-size takes a number of megabytes; ${DOWNLOAD_USAGE}`;
18
+ const MEGABYTES = /^\d+(?:\.\d+)?$/;
19
+ const ARGUMENTS = `the arguments are one JSON object, in single quotes or on stdin after -, like house search '{"query":"invoice"}'`;
20
+ const CLOSED = 'this House connection is closed; nothing to do from here';
21
21
  const SANDBOXED = "your CLI's sandbox kept house from House; run house directly, not through another program";
22
22
  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
23
  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) {
24
+ const WAY = {
25
+ ...(socketPath === undefined ? {} : { socketPath }),
26
+ unreached: (error) => new Error(socketPath === undefined ? UNREACHABLE : error.code === 'EPERM' || error.code === 'EACCES' ? SANDBOXED : CLOSED),
27
+ refused: (status) => storeRefusal('upload', status),
28
+ };
29
+ function refused(path, status, text, local) {
55
30
  const refusal = refusalOf(text);
56
31
  if (refusal !== null)
57
32
  return refusal.text;
58
33
  if (status === 401)
59
34
  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
35
  if (status === 502 && local)
64
36
  return text;
65
37
  return path === '/' ? unconfirmed(status) : `${path} answered ${status}`;
66
38
  }
67
- function unconfirmed(status) {
68
- return `House answered ${status} ${UNCONFIRMED}`;
69
- }
70
- function exchanged(path, method, body, headers = { 'content-type': 'application/json' }, to = socketPath) {
39
+ function bridged(path, body, to = socketPath) {
71
40
  return new Promise((resolve, reject) => {
72
- const sent = request({ socketPath: to, path, method, headers }, (answer) => {
41
+ const sent = request({ socketPath: to, path, method: 'POST', headers: { 'content-type': 'application/json' } }, (answer) => {
73
42
  const chunks = [];
74
43
  answer.on('data', (chunk) => chunks.push(chunk));
75
44
  answer.on('end', () => {
76
- const bytes = Buffer.concat(chunks);
45
+ const text = Buffer.concat(chunks).toString('utf8');
77
46
  if (answer.statusCode === 200)
78
- resolve(bytes);
47
+ resolve(text);
79
48
  else
80
- reject(new Error(refused(path, method, answer.statusCode, bytes.toString('utf8'), answer.headers['content-type'] === undefined)));
49
+ reject(new Error(refused(path, answer.statusCode, text, answer.headers['content-type'] === undefined)));
81
50
  });
82
51
  });
83
52
  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));
85
- });
86
- }
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);
53
+ sent.end(JSON.stringify(body));
98
54
  });
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
55
  }
103
56
  async function mcp(method, params) {
104
57
  const message = rpc(method, params);
105
- const answer = JSON.parse(socketPath === undefined ? await direct(message) : await bridged('/', message));
58
+ const answer = JSON.parse(socketPath === undefined ? await ownAgentCall(message) : await bridged('/', message));
106
59
  if (answer.error !== undefined)
107
60
  throw new Error(answer.error.message);
108
61
  return answer.result;
@@ -110,91 +63,74 @@ async function mcp(method, params) {
110
63
  async function tools() {
111
64
  return (await mcp('tools/list', {})).tools;
112
65
  }
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');
66
+ function unreadable(path, error) {
67
+ return new Error(error.code === 'EISDIR'
68
+ ? `${path} is a folder; upload one file at a time`
69
+ : `${path} is not a readable file`);
138
70
  }
139
71
  async function download(args) {
140
- const { flags, positionals: [argument] } = accepted(args, ['--help'], 1, DOWNLOAD_USAGE);
72
+ const valued = args.indexOf('--max-size');
73
+ const size = valued === -1 ? undefined : args[valued + 1];
74
+ const rest = valued === -1 ? args : args.filter((_arg, index) => index !== valued && index !== valued + 1);
75
+ const { flags, positionals: [argument] } = accepted(rest, ['--help', '--with-attachments'], 1, DOWNLOAD_USAGE);
141
76
  if (flags.has('--help'))
142
- return DOWNLOAD_USAGE;
143
- const { file, ...selected } = argumentsOf(argument);
77
+ return `${DOWNLOAD_USAGE}\n${DOWNLOAD}`;
78
+ if (argument === undefined) {
79
+ if (valued !== -1 && !MEGABYTES.test(size ?? ''))
80
+ throw new Error(MAX_SIZE);
81
+ const maxSize = size === undefined ? DEFAULT_MAX_SIZE : Number(size);
82
+ return copyVerb('/copy/download', { attachments: flags.has('--with-attachments'), max_size: maxSize });
83
+ }
84
+ if (valued !== -1 || flags.has('--with-attachments'))
85
+ throw unexpected(valued !== -1 ? '--max-size' : '--with-attachments', DOWNLOAD_USAGE);
86
+ const { file, ...selected } = await argumentsOf(argument);
144
87
  if (typeof file !== 'string' || file === '')
145
88
  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
89
  const written = resolve(file);
151
- await mkdir(dirname(written), { recursive: true });
152
- await writeFile(written, bytes);
90
+ await downloaded(async () => {
91
+ const file = fileInfo(await called('info', selected));
92
+ if (file === null)
93
+ throw new Error(`${String(selected.path)} holds no binary file; shell reads its text`);
94
+ return file;
95
+ }, async (url) => {
96
+ const answer = await opened(url, 'GET', {}, WAY);
97
+ return { status: answer.statusCode, body: answer };
98
+ }, written, String(selected.path));
153
99
  return written;
154
100
  }
155
101
  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
- };
102
+ let held;
103
+ try {
104
+ held = await fileDigest(file);
105
+ }
106
+ catch (error) {
107
+ throw unreadable(file, error);
108
+ }
109
+ const mediaType = mediaTypeOf(file);
110
+ return { bytes: held.bytes, sha256: held.sha256, ...(mediaType === undefined ? {} : { media_type: mediaType }) };
111
+ }
112
+ async function finished(upload, path, partSha256) {
113
+ const text = await called('upload', { upload, path, part_sha256: partSha256 });
114
+ const answer = parse(text);
115
+ return answer !== null && 'upload' in answer ? answer : { text };
166
116
  }
167
117
  async function upload({ file, ...destination }) {
168
118
  if (typeof file !== 'string' || file === '')
169
119
  throw new Error('upload needs "file", a local file');
170
- const { bytes, description } = await described(file);
120
+ const description = await described(file);
171
121
  const answer = await called('upload', { ...destination, ...description });
172
122
  const declared = parse(answer);
173
- if (declared.upload === undefined)
123
+ if (declared?.upload === undefined)
174
124
  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
- }
125
+ const accepted = await uploaded(declared.upload, {
126
+ name: file,
127
+ bytes: description.bytes,
128
+ sha256: description.sha256,
129
+ read: (start, end) => fileRange(file, start, end, (error) => unreadable(file, error)),
130
+ send: (url, start, end, headers) => sentPart(url, file, start, end, headers, WAY),
131
+ finish: (id, partSha256) => finished(id, destination.path, partSha256),
132
+ });
133
+ return accepted.text;
198
134
  }
199
135
  function unexpected(argument, usage) {
200
136
  return new Error(`unexpected argument ${argument}; ${usage}`);
@@ -204,41 +140,40 @@ function accepted(args, flags, positionals, usage) {
204
140
  for (const arg of args) {
205
141
  if (flags.includes(arg))
206
142
  given.flags.add(arg);
207
- else if (!arg.startsWith('-') && given.positionals.length < positionals)
143
+ else if ((arg === '-' || !arg.startsWith('-')) && given.positionals.length < positionals)
208
144
  given.positionals.push(arg);
209
145
  else
210
146
  throw unexpected(arg, usage);
211
147
  }
212
148
  return given;
213
149
  }
214
- async function push(args) {
215
- const { flags, positionals: [commit = 'HEAD'] } = accepted(args, ['--help', '--owner'], 1, PUSH_USAGE);
216
- if (flags.has('--help'))
217
- return PUSH_USAGE;
218
- const owner = flags.has('--owner');
219
- if (owner && socketPath !== undefined)
220
- throw new Error('--owner is not for Agent conversations; run house push without it');
221
- if (!owner && socketPath === undefined)
222
- 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));
224
- if (pushed.refused)
225
- throw new Error(pushed.text);
226
- return pushed.text;
227
- }
228
- async function fetched(args) {
229
- if (accepted(args, ['--help'], 0, FETCH_USAGE).flags.has('--help'))
230
- return FETCH_USAGE;
231
- const answer = JSON.parse(await bridged('/git/fetch', {}, undefined, socketPath ?? ownerSocket()));
150
+ async function copyVerb(path, body) {
151
+ const answer = JSON.parse(await bridged(path, body, socketPath ?? ownerSocket()));
232
152
  if (answer.refused)
233
153
  throw new Error(answer.text);
234
154
  return answer.text;
235
155
  }
236
- function argumentsOf(argument) {
156
+ async function uploadVerb(args) {
157
+ const { flags, positionals: [argument] } = accepted(args, ['--help', '--owner'], 1, UPLOAD_USAGE);
158
+ if (flags.has('--help'))
159
+ return `${UPLOAD_USAGE}\n${UPLOAD}`;
160
+ if (argument !== undefined) {
161
+ if (flags.has('--owner'))
162
+ throw unexpected('--owner', UPLOAD_USAGE);
163
+ return upload(await argumentsOf(argument));
164
+ }
165
+ const owner = flags.has('--owner');
166
+ if (!owner && socketPath === undefined)
167
+ throw new Error(UPLOAD_NEEDS_OWNER);
168
+ return copyVerb('/copy/upload', { cwd: process.cwd(), owner });
169
+ }
170
+ async function argumentsOf(argument) {
237
171
  if (argument === undefined)
238
172
  return {};
173
+ const given = argument === '-' ? await textOf(process.stdin) : argument;
239
174
  let parsed;
240
175
  try {
241
- parsed = JSON.parse(argument);
176
+ parsed = JSON.parse(given);
242
177
  }
243
178
  catch {
244
179
  throw new Error(ARGUMENTS);
@@ -247,23 +182,78 @@ function argumentsOf(argument) {
247
182
  throw new Error(ARGUMENTS);
248
183
  return parsed;
249
184
  }
185
+ // The schema a $ref points to inside the Tool's own inputSchema, or an empty one when it points elsewhere.
186
+ function resolved(schema, root) {
187
+ if (schema.$ref === undefined)
188
+ return schema;
189
+ if (!schema.$ref.startsWith('#'))
190
+ return {};
191
+ let found = root;
192
+ for (const key of schema.$ref.split('/').slice(1)) {
193
+ found = typeof found === 'object' && found !== null ? found[key.replaceAll('~1', '/').replaceAll('~0', '~')] : undefined;
194
+ }
195
+ return typeof found === 'object' && found !== null ? found : {};
196
+ }
197
+ // The schema a $ref resolves to, with that $ref added to the open ones, or null when it is open already,
198
+ // so a schema that holds itself is expanded once.
199
+ function expanded(schema, root, refs) {
200
+ if (schema.$ref === undefined)
201
+ return { schema, refs };
202
+ return refs.has(schema.$ref) ? null : { schema: resolved(schema, root), refs: new Set([...refs, schema.$ref]) };
203
+ }
204
+ // One line per argument: its name, its value when it has one or a few, whether it is required, and its
205
+ // description. When deep, the arguments its value holds follow it.
206
+ function argumentLines(schema, root, indent, deep, refs = new Set()) {
207
+ const required = new Set(schema.required ?? []);
208
+ return Object.entries(schema.properties ?? {}).flatMap(([name, property]) => {
209
+ const value = resolved(property, root);
210
+ const values = value.const !== undefined ? [value.const] : (value.enum ?? []);
211
+ const words = [name, ...(values.length === 0 ? [] : [values.map((one) => JSON.stringify(one)).join(' | ')]), ...(required.has(name) ? ['(required)'] : [])];
212
+ const description = property.description ?? value.description;
213
+ const line = `${indent}${words.join(' ')}${description === undefined ? '' : `: ${description}`}`;
214
+ return deep ? [line, ...held(property, root, `${indent} `, refs)] : [line];
215
+ });
216
+ }
217
+ // The arguments a value holds: its own, its items', and those of each alternative of a oneOf or anyOf,
218
+ // each alternative a "- " entry when more than one has arguments.
219
+ function held(schema, root, indent, refs) {
220
+ const value = expanded(schema, root, refs);
221
+ if (value === null)
222
+ return [];
223
+ const alternatives = (value.schema.oneOf ?? value.schema.anyOf ?? [])
224
+ .map((alternative) => held(alternative, root, indent, value.refs))
225
+ .filter((lines) => lines.length > 0);
226
+ return [
227
+ ...argumentLines(value.schema, root, indent, true, value.refs),
228
+ ...(value.schema.items === undefined ? [] : held(value.schema.items, root, indent, value.refs)),
229
+ ...(alternatives.length === 1
230
+ ? alternatives[0]
231
+ : alternatives.flatMap((lines) => lines.map((line, index) => (index === 0 ? `${indent}- ${line.slice(indent.length)}` : ` ${line}`)))),
232
+ ];
233
+ }
234
+ function listed(tool) {
235
+ return tool.description === undefined ? tool.name : `${tool.name}: ${tool.description}`;
236
+ }
237
+ async function toolHelp(name) {
238
+ const tool = (await tools()).find((one) => one.name === name);
239
+ if (tool === undefined)
240
+ throw new Error(`${name} is no Tool; house find_command '{"query":"${name}"}' finds Commands`);
241
+ return [listed(tool), ...argumentLines(tool.inputSchema, tool.inputSchema, ' ', true)].join('\n');
242
+ }
250
243
  async function house(args) {
251
244
  const { flags, positionals: [verb, argument] } = accepted(args, ['--help'], 2, USAGE);
252
- if (verb === 'help' && argument !== undefined)
253
- throw unexpected(argument, USAGE);
254
245
  if (flags.has('--help') && argument !== undefined)
255
246
  throw unexpected('--help', USAGE);
247
+ // house help <name> runs as house <name> --help, so both forms answer alike.
248
+ if (verb === 'help' && argument !== undefined)
249
+ return run([argument, '--help']);
256
250
  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');
251
+ const listing = (await tools()).flatMap((tool) => tool.description === undefined ? [tool.name, ...argumentLines(tool.inputSchema, tool.inputSchema, ' ', false)] : [listed(tool)]);
252
+ return [USAGE, HELP, UPLOAD, DOWNLOAD, ...listing].join('\n');
264
253
  }
265
- const parsed = argumentsOf(argument);
266
- return verb === 'upload' ? upload(parsed) : verb === 'append_record' ? appendRecord(parsed) : called(verb, parsed);
254
+ if (flags.has('--help'))
255
+ return toolHelp(verb);
256
+ return called(verb, await argumentsOf(argument));
267
257
  }
268
258
  async function called(name, args) {
269
259
  const result = await mcp('tools/call', { name, arguments: args });
@@ -272,16 +262,17 @@ async function called(name, args) {
272
262
  throw new Error(text.replace(/\n+$/, ''));
273
263
  return text;
274
264
  }
265
+ function run(argv) {
266
+ const named = argv.findIndex((arg) => !arg.startsWith('-'));
267
+ const rest = argv.filter((_arg, index) => index !== named);
268
+ if (argv[named] === 'upload')
269
+ return uploadVerb(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 {
@@ -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 WAIT_LINE = 'To get what another Agent will write into a Room, `create_trigger` on where it will land with a `conversation` action, then end your turn: this conversation continues when it lands.';
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, WAIT_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
  }