@agentshouse/kit 0.2.1-ce8e5419af3f9 → 0.2.1-ce9401bb7d372

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -9,7 +9,7 @@ Run `sh -c 'kit=$(curl -fsSL "$0") || { echo "Kit could not be downloaded; run t
9
9
  or `& { try { $kit = irm agents.house/kit.ps1 } catch { throw 'Kit could not be downloaded; run this command again.' }; & ([scriptblock]::Create($kit)) @args }` on Windows, which run nothing of a failed download, and again to update; options follow `agents.house/kit`.
10
10
  On macOS and Linux it installs Kit natively under your own account, without an admin password, as a service that runs
11
11
  while you are logged in. `kit` and `house` are then on your login shell's `PATH`, and your workspace is `~/AgentsHouse` unless you
12
- pass `--workspace <path>`. Every run places the Kit release your Building serves, with the Node.js and agent adapters it runs on, in a directory of its own beside the one that runs, then starts it; the earlier one stays until the next release. Kit also updates itself: when your Building takes another release, Kit places it the same way and, once no turn is open, ends so its service, or the container's restart policy, starts it. When House refuses the Kit that runs as too old or too new, Kit places your Building's release at once, ending any running turn, and ends the same way; while it cannot, it stays offline, prints why with the command that installs it again, and tries again regularly.
12
+ pass `--workspace <path>`. Every run places the Kit release your Building serves, with the Node.js and agent adapters it runs on, in a directory of its own beside the one that runs, then starts it; the earlier one stays until the next release. Kit also updates itself: when your Building takes another release, Kit places it the same way and, once no turn is open, ends so its service, or the container's restart policy, starts it. When House no longer serves the wire of the Kit that runs, Kit places your Building's release at once, ending any running turn, and ends the same way; while it cannot, it stays offline, prints why with the command that installs it again, and tries again regularly.
13
13
 
14
14
  Add `--container` to run Kit in one Docker container instead, with your workspace mounted at `/agents/house`; your Agents then reach only that
15
15
  workspace. The container's image holds no Kit release and no Node.js: every run places them in Kit home's `kit` folder, which a container created again keeps. On Windows,
@@ -38,7 +38,7 @@ reconnects an Environment you already have; `--rooms <ref>[,<ref>...]` gives it
38
38
  only those Rooms and `--no-private` every Room but your Private Room; `--code <code>` connects immediately without a link.
39
39
  A login also connects your own agent: outside an Agent conversation, `house <tool>` calls
40
40
  House as you and `git` clones and pushes your Apps at `<house>/app/` as you, each through the Kit
41
- home `$HOUSE_KIT_HOME` names where it runs, until you revoke that connection on Connections. `house help` lists the Tools. Codex sessions started after a
41
+ home `$HOUSE_KIT_HOME` names where it runs, until you revoke that connection on Connections. `house help` lists the Tools and `house help <tool>` one Tool's arguments. Codex sessions started after a
42
42
  login run a lone `house` command outside their sandbox. `kit logout` disconnects this
43
43
  computer, stops the Kit process and ends your own agent's connection, so `house` and `git` no
44
44
  longer act as you here; a later `kit login` reconnects the same Environment, or connects
package/dist/agents.js CHANGED
@@ -1,18 +1,19 @@
1
1
  import { client } from '@agentclientprotocol/sdk';
2
+ import { KIT_WIRE } from '@agentshouse/kit-wire';
2
3
  import { readFile } from 'node:fs/promises';
3
4
  import { setTimeout as delay } from 'node:timers/promises';
4
5
  import { signedOut, startAdapter } from './acp.js';
5
6
  import { CLIS, KIT_RELEASE, below, installCli, locate, run, updateCli, versionOf } from './clis.js';
6
7
  import { agentBase, kitHome } from './home.js';
7
8
  import { holdTranscription, transcriptionReport } from './transcription.js';
8
- import { KIT_WIRE } from './wire.js';
9
9
  // Two quiet seconds let a fresh conversation start before background model discovery competes for its CPU.
10
10
  const MODEL_PROBE_QUIET_MS = 2_000;
11
11
  // A CLI's maker can publish several releases a day, so running each chosen CLI's update command hourly brings a new one to the next conversation within the hour for one small check.
12
12
  export const CLI_UPDATE_MS = 60 * 60_000;
13
13
  // A sign-in's model read that has not answered in ten seconds leaves its sign-in to the status check, so a hung CLI never holds the sign-in's result.
14
14
  const SIGNED_IN_READ_MS = 10_000;
15
- const SIGNED_OUT = { signed_in: false, models: [], modes: [] };
15
+ const UNNAMED = { default_model: null, default_effort: null };
16
+ const SIGNED_OUT = { signed_in: false, models: [], ...UNNAMED, modes: [] };
16
17
  const INSTALLING = { release: null, failure: null, installing: true, ...SIGNED_OUT };
17
18
  function select(options, category) {
18
19
  const option = options.find((candidate) => candidate.category === category);
@@ -24,6 +25,22 @@ function choices(options) {
24
25
  function values(options) {
25
26
  return choices(options).map((entry) => entry.value);
26
27
  }
28
+ const CLI_DEFAULT = 'default';
29
+ function effortsOf(option) {
30
+ return option === undefined ? [] : values(option.options).filter((value) => value !== CLI_DEFAULT);
31
+ }
32
+ function named(options) {
33
+ const listed = choices(options).filter((entry) => entry.value !== CLI_DEFAULT);
34
+ return listed.filter((entry, at) => listed.findIndex((first) => first.name === entry.name) === at);
35
+ }
36
+ function starting(model, effort) {
37
+ const current = choices(model.options).find((entry) => entry.value === model.currentValue);
38
+ const name = current?.value === CLI_DEFAULT ? current.description : current?.name;
39
+ return {
40
+ default_model: named(model.options).find((entry) => entry.name === name)?.value ?? null,
41
+ default_effort: effort === undefined || effort.currentValue === CLI_DEFAULT ? null : effort.currentValue,
42
+ };
43
+ }
27
44
  function causeOf(error) {
28
45
  return error instanceof Error ? error.message : String(error);
29
46
  }
@@ -54,23 +71,23 @@ async function models(kind, adapter, known) {
54
71
  const modes = mode === undefined ? [] : choices(mode.options).map(({ value, name }) => ({ mode: value, name }));
55
72
  const model = select(options, 'model');
56
73
  if (model === undefined)
57
- return { models: [], modes };
74
+ return { models: [], ...UNNAMED, modes };
75
+ const started = starting(model, select(options, 'thought_level'));
58
76
  const offered = [];
59
- for (const value of values(model.options)) {
77
+ for (const { value, name } of named(model.options)) {
60
78
  if (select(options, 'model')?.currentValue !== value) {
61
79
  try {
62
80
  options = (await agent.request('session/set_config_option', { sessionId: opened.sessionId, configId: model.id, value })).configOptions;
63
81
  }
64
82
  catch (error) {
65
83
  process.stderr.write(`kit: ${kind} refused its model ${value}: ${causeOf(error)}\n`);
66
- offered.push({ model: value, efforts: known.find((entry) => entry.model === value)?.efforts ?? [] });
84
+ offered.push({ model: value, name, efforts: known.find((entry) => entry.model === value)?.efforts ?? [] });
67
85
  continue;
68
86
  }
69
87
  }
70
- const effort = select(options, 'thought_level');
71
- offered.push({ model: value, efforts: effort === undefined ? [] : values(effort.options) });
88
+ offered.push({ model: value, name, efforts: effortsOf(select(options, 'thought_level')) });
72
89
  }
73
- return { models: offered, modes };
90
+ return { models: offered, ...started, modes };
74
91
  }
75
92
  function ended(signal) {
76
93
  return new Promise((_, reject) => {
@@ -103,6 +120,8 @@ async function offer(kind, cli, known, signal) {
103
120
  return {
104
121
  signed_in: adapter === undefined && 'initializeMeta' in probe ? known.signed_in : true,
105
122
  models: known.models,
123
+ default_model: known.default_model,
124
+ default_effort: known.default_effort,
106
125
  modes: known.modes,
107
126
  };
108
127
  }
@@ -122,6 +141,8 @@ function reported(kind, reading) {
122
141
  models: reading.models,
123
142
  modes: reading.modes,
124
143
  full_access: CLIS[kind].fullAccess,
144
+ ...(reading.default_model === null ? {} : { default_model: reading.default_model }),
145
+ ...(reading.default_effort === null ? {} : { default_effort: reading.default_effort }),
125
146
  };
126
147
  }
127
148
  const NOT_READY = "the Agent's CLI is not ready on this computer";
@@ -186,7 +207,7 @@ export class Agents {
186
207
  this.refreshing++;
187
208
  this.changed();
188
209
  const reading = this.read().then(async () => {
189
- this.desired = await this.house.deliver('/kit/agents/desired/list', {});
210
+ this.desired = await this.house.deliver('agents/desired/list', {});
190
211
  return this.desired;
191
212
  });
192
213
  this.reading = reading;
@@ -225,7 +246,15 @@ export class Agents {
225
246
  const known = this.readings.get(kind);
226
247
  const kept = known?.release === null ? SIGNED_OUT : (known ?? SIGNED_OUT);
227
248
  if (known?.release !== release || this.installs.has(kind)) {
228
- this.update(kind, { release, failure: null, signed_in: kept.signed_in, models: kept.models, modes: kept.modes });
249
+ this.update(kind, {
250
+ release,
251
+ failure: null,
252
+ signed_in: kept.signed_in,
253
+ models: kept.models,
254
+ default_model: kept.default_model,
255
+ default_effort: kept.default_effort,
256
+ modes: kept.modes,
257
+ });
229
258
  }
230
259
  const read = this.nextRead(kind);
231
260
  this.quietOffer(kind, cli, kept)
@@ -391,7 +420,7 @@ export class Agents {
391
420
  const state = JSON.stringify(body);
392
421
  if (state === this.sent)
393
422
  return;
394
- await this.house.deliver('/kit/agents/report', body);
423
+ await this.house.deliver('agents/report', body);
395
424
  this.sent = state;
396
425
  }
397
426
  }
package/dist/api.js CHANGED
@@ -1,9 +1,10 @@
1
+ import { KIT_WIRE, KIT_WIRE_HEADER, } from '@agentshouse/kit-wire';
1
2
  import { setTimeout as delay } from 'node:timers/promises';
2
3
  import { signInAgain } from './end.js';
3
4
  import { readEnrolment } from './home.js';
4
5
  import { retryable } from './refusals.js';
5
6
  import { relayed } from './relay.js';
6
- import { endUnserved, KIT_WIRE, KIT_WIRE_HEADER } from './wire.js';
7
+ import { endUnserved } from './wire.js';
7
8
  export class HouseRefusal extends Error {
8
9
  status;
9
10
  text;
@@ -38,7 +39,7 @@ export async function post(house, path, body, credential, signal) {
38
39
  method: 'POST',
39
40
  headers: {
40
41
  'content-type': 'application/json',
41
- [KIT_WIRE_HEADER]: String(KIT_WIRE),
42
+ [KIT_WIRE_HEADER]: KIT_WIRE,
42
43
  ...(credential === undefined ? {} : { authorization: `Bearer ${credential}` }),
43
44
  },
44
45
  body: JSON.stringify(body),
@@ -51,6 +52,9 @@ export async function post(house, path, body, credential, signal) {
51
52
  throw new HouseRefusal(path, answer.status, text);
52
53
  return JSON.parse(text);
53
54
  }
55
+ export function kitAct(house, act, request, credential, signal) {
56
+ return post(house, `/kit/${act}`, request, credential, signal);
57
+ }
54
58
  async function enrolledPost(path, body, signal) {
55
59
  const { house, credential } = (await readEnrolment());
56
60
  try {
@@ -63,16 +67,17 @@ async function enrolledPost(path, body, signal) {
63
67
  }
64
68
  }
65
69
  export const house = {
66
- post: enrolledPost,
67
- deliver: async (path, body, current = () => true) => {
70
+ act: (act, request, signal) => enrolledPost(`/kit/${act}`, request, signal),
71
+ door: (act, body, signal) => enrolledPost(`/kit/door/${act}`, body, signal),
72
+ deliver: async (act, request, current = () => true) => {
68
73
  for (let attempt = 0;; attempt++) {
69
74
  try {
70
- return await enrolledPost(path, body);
75
+ return await enrolledPost(`/kit/${act}`, request);
71
76
  }
72
77
  catch (error) {
73
78
  if (finalRefusal(error))
74
79
  throw error;
75
- process.stderr.write(`kit: ${path} did not reach House: ${error.message}\n`);
80
+ process.stderr.write(`kit: /kit/${act} did not reach House: ${error.message}\n`);
76
81
  // A delivery House did not take is sent again on the jittered curve for as long as it is still current.
77
82
  await new Promise((resolve) => setTimeout(resolve, retryDelay(attempt)));
78
83
  if (!current())
@@ -1,4 +1,4 @@
1
- import { HouseRefusal, post } from './api.js';
1
+ import { HouseRefusal, kitAct } from './api.js';
2
2
  import { readEnrolment } from './home.js';
3
3
  import { proxyUnlessRelayed } from './relay.js';
4
4
  function unanswered(error) {
@@ -8,7 +8,7 @@ proxyUnlessRelayed();
8
8
  try {
9
9
  const { house, credential } = (await readEnrolment());
10
10
  try {
11
- await post(house, '/kit/agents/desired/list', {}, credential);
11
+ await kitAct(house, 'agents/desired/list', {}, credential);
12
12
  }
13
13
  catch (error) {
14
14
  if (!unanswered(error))
package/dist/bridge.js CHANGED
@@ -81,7 +81,7 @@ function editAnswer(forwarded) {
81
81
  export async function openBridge(house, copies, conversationId, signal) {
82
82
  const path = [join(kitHome(), 'shim'), dirname(process.execPath), await loginPath()].join(delimiter);
83
83
  const origin = (await readEnrolment()).house;
84
- const { credential } = await retrying(() => house.post('/kit/conversations/credentials/issue', { conversation: conversationId }, signal), signal);
84
+ const { credential } = await retrying(() => house.act('conversations/credentials/issue', { conversation: conversationId }, signal), signal);
85
85
  const closed = new AbortController();
86
86
  const sent = (message, operation) => callHouse(origin, credential, message, operation, closed.signal);
87
87
  const send = async (message, operation) => {
package/dist/calls.js CHANGED
@@ -42,7 +42,7 @@ export class Calls {
42
42
  return carried
43
43
  .then(async ({ result, returned, release }) => {
44
44
  try {
45
- await this.house.deliver('/kit/kit-calls/results/return', { call: callId, ...result });
45
+ await this.house.deliver('kit-calls/results/return', { call: callId, ...result });
46
46
  }
47
47
  finally {
48
48
  this.returned.add(callId);
@@ -1,3 +1,4 @@
1
+ import { KIT_CONNECTION_PATH, KIT_CONNECTION_PROTOCOL_PREFIX, KIT_WIRE, } from '@agentshouse/kit-wire';
1
2
  import { subscribe } from 'node:diagnostics_channel';
2
3
  import { setTimeout as delay } from 'node:timers/promises';
3
4
  import { HouseRefusal, retryDelay } from './api.js';
@@ -5,16 +6,15 @@ import { end, REPLACED, signInAgain } from './end.js';
5
6
  import { readEnrolment } from './home.js';
6
7
  import { relayed } from './relay.js';
7
8
  import { Silence } from './silence.js';
8
- import { endUnserved, KIT_WIRE, unserved } from './wire.js';
9
- const PATH = '/kit/stream';
10
- const SUBPROTOCOL = `house.kit.stream.${KIT_WIRE}`;
9
+ import { endUnserved, unserved } from './wire.js';
10
+ const SUBPROTOCOL = `${KIT_CONNECTION_PROTOCOL_PREFIX}${KIT_WIRE}`;
11
11
  const REFUSAL_HEADER = 'x-house-refusal';
12
12
  // House beats each Kit connection every thirty seconds, so two silent beats mean this Kit process cannot hear House.
13
13
  export const CONNECTION_SILENCE_MS = 60_000;
14
14
  // A stopping Kit waits up to two seconds for House to answer its close, so what it sent last reaches House and a House that does not answer holds no stop.
15
15
  const CLOSE_ANSWER_MS = 2_000;
16
16
  function connectionUrl(house) {
17
- const url = new URL(PATH, house);
17
+ const url = new URL(KIT_CONNECTION_PATH, house);
18
18
  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
19
19
  return url;
20
20
  }
@@ -28,9 +28,9 @@ function header(headers, name) {
28
28
  let refused = null;
29
29
  subscribe('undici:request:headers', (message) => {
30
30
  const { request, response } = message;
31
- if (!request.path.endsWith(PATH))
31
+ if (!request.path.endsWith(KIT_CONNECTION_PATH))
32
32
  return;
33
- refused = new HouseRefusal(PATH, response.statusCode, header(response.headers, REFUSAL_HEADER) || response.statusText);
33
+ refused = new HouseRefusal(KIT_CONNECTION_PATH, response.statusCode, header(response.headers, REFUSAL_HEADER) || response.statusText);
34
34
  });
35
35
  export function holdConnection(handlers) {
36
36
  let connection = null;
@@ -73,6 +73,9 @@ function unopened(reason) {
73
73
  }
74
74
  // A start-up step is shown only once it has lasted a second, so a quick start shows none of them.
75
75
  const STARTING_SHOWN_AFTER_MS = 1_000;
76
+ function turnOf(conversation, turn) {
77
+ return { conversation: conversation.id, turn: turn.id };
78
+ }
76
79
  function unbridged(error) {
77
80
  return (finalRefusal(error) ? ENDED[refusalOf(error.text)?.code ?? ''] : undefined) ?? NO_CONNECTION;
78
81
  }
@@ -86,7 +89,6 @@ const GROK_QUESTION = {
86
89
  return value;
87
90
  },
88
91
  };
89
- export const CONVERSATION_METHODS = new Set(['open', 'message', 'take_out', 'interrupt', 'kill', 'done', 'option', 'answer']);
90
92
  function addedTokens(sum, tokens) {
91
93
  if (sum === null)
92
94
  return tokens;
@@ -319,12 +321,12 @@ export class Conversations {
319
321
  return { result: Promise.resolve({}) };
320
322
  }
321
323
  if (call.kind === 'take_out')
322
- return { result: Promise.resolve(this.takeOut(conversation, String(call.message_id))) };
324
+ return { result: Promise.resolve(this.takeOut(conversation, call.message_id)) };
323
325
  await this.launched(conversation);
324
326
  if (call.kind === 'interrupt') {
325
327
  if (--conversation.interrupts === 0)
326
328
  conversation.interrupted = new AbortController();
327
- await this.interrupt(conversation, String(call.turn_id));
329
+ await this.interrupt(conversation, call.turn_id);
328
330
  }
329
331
  if (call.kind === 'kill') {
330
332
  await this.kill(conversation);
@@ -333,9 +335,9 @@ export class Conversations {
333
335
  conversation.killed = new AbortController();
334
336
  }
335
337
  if (call.kind === 'option')
336
- await this.option(conversation, String(call.option), call.value);
338
+ await this.option(conversation, call.option, call.value);
337
339
  if (call.kind === 'answer') {
338
- const question = this.questions.get(String(call.interaction_id));
340
+ const question = this.questions.get(call.interaction_id);
339
341
  if (question === undefined) {
340
342
  const text = answerMessage(call.request, call.response);
341
343
  return this.message(conversation, { ...call, text, first: false, message_id: null });
@@ -402,8 +404,8 @@ export class Conversations {
402
404
  }
403
405
  async message(conversation, call) {
404
406
  const content = [
405
- ...(typeof call.recent === 'string' ? [{ type: 'text', text: call.recent }] : []),
406
- { type: 'text', text: String(call.text) },
407
+ ...(call.recent === undefined ? [] : [{ type: 'text', text: call.recent }]),
408
+ { type: 'text', text: call.text },
407
409
  ];
408
410
  let route;
409
411
  let instructing = null;
@@ -412,7 +414,7 @@ export class Conversations {
412
414
  if (call.first === true)
413
415
  instructing = this.instructed(conversation, route);
414
416
  if (call.message_id !== null)
415
- content.push(...(await this.transcribed(conversation, String(call.message_id), String(call.text))));
417
+ content.push(...(await this.transcribed(conversation, call.message_id, call.text)));
416
418
  if (conversation.kills > 0)
417
419
  throw new Error(KILLED);
418
420
  }
@@ -469,7 +471,7 @@ export class Conversations {
469
471
  for (const turn of conversation.turns)
470
472
  turn.steered ||= turn.prompted;
471
473
  }
472
- this.kit.calls.keepResult(String(waiting.call.input_id), {});
474
+ this.kit.calls.keepResult(waiting.call.input_id, {});
473
475
  waiting.settle({});
474
476
  }
475
477
  else {
@@ -535,7 +537,7 @@ export class Conversations {
535
537
  return;
536
538
  }
537
539
  this.starts(conversation, null);
538
- this.prompt(conversation, [...prompt, ...waiting.content], () => this.kit.calls.keepResult(String(call.input_id), result));
540
+ this.prompt(conversation, [...prompt, ...waiting.content], () => this.kit.calls.keepResult(call.input_id, result));
539
541
  waiting.settle(result);
540
542
  }
541
543
  starts(conversation, step) {
@@ -591,7 +593,7 @@ export class Conversations {
591
593
  throw new Error(`${path} is no longer an audio file`);
592
594
  return address;
593
595
  }, signal);
594
- await step(unbridged, unlessAborted(this.kit.house.deliver('/kit/transcripts/keep', { conversation: conversation.id, message: messageId, path, text: said }, () => !signal.aborted), signal));
596
+ await step(unbridged, unlessAborted(this.kit.house.deliver('transcripts/keep', { conversation: conversation.id, message: messageId, path, text: said }, () => !signal.aborted), signal));
595
597
  blocks.push({ type: 'text', text: `${path}\nTranscript: ${said}` });
596
598
  }
597
599
  }
@@ -656,6 +658,9 @@ export class Conversations {
656
658
  if (running === null)
657
659
  return;
658
660
  try {
661
+ if (conversation.options?.find(({ id }) => id === option)?.category === 'mode') {
662
+ throw new Error(`conversation ${conversation.id} keeps the mode its Agent's launch settings name`);
663
+ }
659
664
  running.reader.requested(option, value);
660
665
  const answered = await running.adapter.connection.agent.request('session/set_config_option', {
661
666
  sessionId: running.sessionId,
@@ -831,16 +836,16 @@ export class Conversations {
831
836
  if (conversation.running === null)
832
837
  return;
833
838
  conversation.options = options;
834
- this.kit.send({ type: 'options', conversation_id: conversation.id, options });
839
+ this.kit.send({ type: 'options', conversation_id: conversation.id, options: options.filter((option) => option.category !== 'mode') });
835
840
  const chosen = (category) => {
836
841
  const value = options.find((option) => option.category === category)?.currentValue;
837
842
  return value === undefined ? null : String(value);
838
843
  };
839
844
  this.stated(conversation, { model: chosen('model'), effort: chosen('thought_level'), mode: chosen('mode') });
840
845
  }
841
- deliver(conversation, turn, act, body, current) {
846
+ deliver(conversation, act, request, current) {
842
847
  this.reporting++;
843
- const delivered = conversation.reports.then(async () => this.kit.house.deliver(`/kit/${act}`, { conversation: conversation.id, turn: turn.id, ...(await body) }, current));
848
+ const delivered = conversation.reports.then(async () => this.kit.house.deliver(act, await request, current));
844
849
  conversation.reports = delivered
845
850
  .catch(() => undefined)
846
851
  .finally(() => {
@@ -862,7 +867,7 @@ export class Conversations {
862
867
  const turn = new Turn((operation) => this.write(conversation, turn, operation));
863
868
  conversation.turns.add(turn);
864
869
  conversation.running?.adapter.turn(true);
865
- void this.deliver(conversation, turn, 'turns/start', {})
870
+ void this.deliver(conversation, 'turns/start', turnOf(conversation, turn))
866
871
  .then((answer) => {
867
872
  if (answer.run === true)
868
873
  turn.quietUntil = Date.now() + ACTIVITY_REPORT_MS;
@@ -873,7 +878,7 @@ export class Conversations {
873
878
  for (const event of conversation.reader?.began() ?? [])
874
879
  this.event(conversation, event);
875
880
  for (const held of conversation.held.splice(0))
876
- this.place(conversation, turn, held);
881
+ this.place(turn, held);
877
882
  this.kit.changed();
878
883
  return turn;
879
884
  }
@@ -898,10 +903,11 @@ export class Conversations {
898
903
  if (tokens !== null)
899
904
  this.stated(conversation, { tokens: addedTokens(conversation.state.tokens, tokens) });
900
905
  const body = Promise.allSettled(turn.uploads).then(() => ({
906
+ ...turnOf(conversation, turn),
901
907
  content: { parts: turn.content.parts, tokens, state: conversation.state },
902
908
  ...(failed === null ? {} : { failed: failed.failure }),
903
909
  }));
904
- void this.deliver(conversation, turn, 'turns/end', body).catch(logged);
910
+ void this.deliver(conversation, 'turns/end', body).catch(logged);
905
911
  this.next(conversation);
906
912
  this.kit.changed();
907
913
  }
@@ -967,7 +973,8 @@ export class Conversations {
967
973
  const answered = new Promise((answer, fail) => {
968
974
  this.questions.set(interactionId, { conversation, answer: (response) => answer(response) });
969
975
  signal.addEventListener('abort', () => answer(null), { once: true });
970
- this.deliver(conversation, turn, 'conversations/interaction/ask', {
976
+ this.deliver(conversation, 'conversations/interaction/ask', {
977
+ ...turnOf(conversation, turn),
971
978
  interaction_id: interactionId,
972
979
  request: { method, params },
973
980
  secret,
@@ -1019,7 +1026,7 @@ export class Conversations {
1019
1026
  if (turn === null || Date.now() < turn.quietUntil)
1020
1027
  return;
1021
1028
  turn.quietUntil = Infinity;
1022
- void this.deliver(conversation, turn, 'turns/activity/report', {}, () => false)
1029
+ void this.deliver(conversation, 'turns/activity/report', turnOf(conversation, turn), () => false)
1023
1030
  .catch(logged)
1024
1031
  .finally(() => {
1025
1032
  turn.quietUntil = Date.now() + ACTIVITY_REPORT_MS;
@@ -1070,7 +1077,7 @@ export class Conversations {
1070
1077
  switch (event.kind) {
1071
1078
  case 'text':
1072
1079
  case 'reasoning': {
1073
- const parent = this.parentIn(conversation, turn, event.parent);
1080
+ const parent = this.parentIn(turn, event.parent);
1074
1081
  if (parent !== undefined)
1075
1082
  turn.content.write(event.kind, event.id, parent, event.text);
1076
1083
  return;
@@ -1081,10 +1088,14 @@ export class Conversations {
1081
1088
  case 'plan':
1082
1089
  turn.content.plan(event.entries);
1083
1090
  return;
1084
- case 'image':
1085
- turn.uploads.push(this.image(conversation, turn, event.parent, event.data, event.mediaType));
1091
+ case 'image': {
1092
+ const parent = this.parentIn(turn, event.parent);
1093
+ if (parent === undefined)
1094
+ return;
1095
+ turn.uploads.push(this.image(conversation, turn, parent, event.data, event.mediaType));
1086
1096
  this.kit.changed();
1087
1097
  return;
1098
+ }
1088
1099
  }
1089
1100
  }
1090
1101
  keyed(conversation, keyed) {
@@ -1101,37 +1112,32 @@ export class Conversations {
1101
1112
  if (turn === null)
1102
1113
  conversation.held.push(keyed);
1103
1114
  else
1104
- this.place(conversation, turn, keyed);
1115
+ this.place(turn, keyed);
1105
1116
  return;
1106
1117
  }
1107
1118
  if (keyed.parent !== null && turn === null)
1108
1119
  return;
1109
- this.place(conversation, this.started(conversation), keyed);
1120
+ this.place(this.started(conversation), keyed);
1110
1121
  }
1111
- place(conversation, turn, keyed) {
1112
- const parent = this.parentIn(conversation, turn, keyed.parent);
1113
- if (parent === undefined && workRuns(keyed.part) === null)
1114
- return;
1115
- turn.content.put(keyed.key, parent ?? null, keyed.part);
1122
+ place(turn, keyed) {
1123
+ const parent = this.parentIn(turn, keyed.parent);
1124
+ if (parent !== undefined)
1125
+ turn.content.put(keyed.key, parent, keyed.part);
1116
1126
  }
1117
- parentIn(conversation, turn, key) {
1127
+ // A sub-agent's card lives only in the turn keyed() placed it in, so its steps, text, images and sub-agents join a turn only under a card that turn holds.
1128
+ parentIn(turn, key) {
1118
1129
  if (key === null)
1119
1130
  return null;
1120
1131
  const index = turn.content.index(key);
1121
- if (index !== undefined)
1122
- return turn.content.parts[index].type === 'subagent' ? index : undefined;
1123
- const running = conversation.work.get(key);
1124
- if (running?.part.type !== 'subagent')
1125
- return undefined;
1126
- const parent = this.parentIn(conversation, turn, running.parent);
1127
- return parent === undefined ? undefined : turn.content.put(key, parent, running.part);
1132
+ return index !== undefined && turn.content.parts[index].type === 'subagent' ? index : undefined;
1128
1133
  }
1129
1134
  async image(conversation, turn, parent, data, mediaType) {
1130
1135
  const bytes = Buffer.from(data, 'base64');
1131
1136
  const name = `image-${++turn.images}.${mediaType.split('/')[1]}`;
1132
1137
  const sha256 = createHash('sha256').update(bytes).digest('hex');
1133
1138
  try {
1134
- const declared = (await this.deliver(conversation, turn, 'turns/images/declare', {
1139
+ const declared = (await this.deliver(conversation, 'turns/images/declare', {
1140
+ ...turnOf(conversation, turn),
1135
1141
  name,
1136
1142
  media_type: mediaType,
1137
1143
  bytes: bytes.length,
@@ -1143,9 +1149,9 @@ export class Conversations {
1143
1149
  sha256,
1144
1150
  read: (start, end) => [bytes.subarray(start, end)],
1145
1151
  send: (url, start, end, headers) => sentPart(url, bytes.subarray(start, end), headers),
1146
- finish: (upload, partSha256) => this.kit.house.deliver('/kit/uploads/finish', { upload, part_sha256: partSha256 }),
1152
+ finish: (upload, partSha256) => this.kit.house.deliver('uploads/finish', { upload, part_sha256: partSha256 }),
1147
1153
  });
1148
- turn.content.arrived(this.parentIn(conversation, turn, parent) ?? null, { type: 'image', file: saved.path, name, media_type: mediaType });
1154
+ turn.content.arrived(parent, { type: 'image', file: saved.path, name, media_type: mediaType });
1149
1155
  }
1150
1156
  catch (error) {
1151
1157
  const cause = error instanceof HouseRefusal ? (refusalOf(error.text)?.text ?? causeOf(error)) : causeOf(error);
package/dist/copies.js CHANGED
@@ -14,7 +14,6 @@ const BRANCH = 'main';
14
14
  const PROVENANCE = '_provenance';
15
15
  const IDENTITY = { GIT_COMMITTER_NAME: 'Kit', GIT_COMMITTER_EMAIL: 'house-kit@localhost' };
16
16
  const ROOMS = 'rooms/';
17
- const ENUMERATE = '/kit/door/changes/enumerate';
18
17
  const NOT_READY = 'not ready yet; Kit copies it once House has built it';
19
18
  const STAGED_CHUNKS = 'house-chunks';
20
19
  const SCHEMA = 'settings/schema.yaml';
@@ -243,7 +242,7 @@ export class LocalCopies {
243
242
  key: 'owner',
244
243
  submit: async (operation, changes) => {
245
244
  try {
246
- const outcome = await retrying(() => house.post('/kit/door/files/batch', { operation_id: operation, changes }));
245
+ const outcome = await retrying(() => house.door('files/batch', { operation_id: operation, changes }));
247
246
  return { accepted: outcome.contents };
248
247
  }
249
248
  catch (error) {
@@ -291,7 +290,7 @@ export class LocalCopies {
291
290
  return answered;
292
291
  }
293
292
  async fetched(refreshing) {
294
- const { local_copy: answer } = await this.house.post('/kit/local-copies/selection/read', {});
293
+ const { local_copy: answer } = await this.house.act('local-copies/selection/read', {});
295
294
  const synced = new Map(answer.rooms.map((room) => [`${ROOMS}${room.room_ref}`, room.room_handle]));
296
295
  return this.holding([...new Set([...this.copies.keys(), ...synced.keys()])].sort(), async () => {
297
296
  const said = [];
@@ -439,7 +438,7 @@ export class LocalCopies {
439
438
  return copy;
440
439
  }
441
440
  async discovered(handles) {
442
- const discover = (group) => this.house.post('/kit/door/rooms/discover', { prefixes: group.map(rootOf) });
441
+ const discover = (group) => this.house.door('rooms/discover', { prefixes: group.map(rootOf) });
443
442
  const [first, ...rest] = handles;
444
443
  const { bounds, authorities } = await discover([first]);
445
444
  for (const group of grouped(rest, bounds.max_prefixes))
@@ -449,7 +448,7 @@ export class LocalCopies {
449
448
  async chunked(root, room, directory) {
450
449
  await mkdir(directory, { recursive: true });
451
450
  for (let renewed = false;; renewed = true) {
452
- const { rooms } = await this.house.post('/kit/door/room-chunks/list', { prefixes: [root] });
451
+ const { rooms } = await this.house.door('room-chunks/list', { prefixes: [root] });
453
452
  const list = rooms.find((entry) => entry.room_ref === room);
454
453
  if (list === undefined)
455
454
  throw new Error('House serves nothing of it to copy');
@@ -508,7 +507,7 @@ export class LocalCopies {
508
507
  let answer = null;
509
508
  try {
510
509
  if (!this.waiting.has(authority.room_ref)) {
511
- answer = await this.house.post(ENUMERATE, {
510
+ answer = await this.house.door('changes/enumerate', {
512
511
  prefixes: [root],
513
512
  positions: [
514
513
  { authority: authority.room_ref, position: '0', log_epoch: authority.log_epoch, page: { through: authority.position, read: 0 } },
@@ -601,7 +600,7 @@ export class LocalCopies {
601
600
  while (asking.length > 0) {
602
601
  let answer;
603
602
  try {
604
- answer = await this.house.post(ENUMERATE, {
603
+ answer = await this.house.door('changes/enumerate', {
605
604
  prefixes: asking.map((copy) => rootOf(copy.room_handle)),
606
605
  positions: asking.map((copy) => ({ authority: copy.room_ref, position: copy.position, log_epoch: copy.log_epoch })),
607
606
  });
@@ -743,7 +742,7 @@ export class LocalCopies {
743
742
  const arrived = new Set(moved.values());
744
743
  const arriving = [...after].filter(([path, entry]) => before.get(path) !== entry);
745
744
  if (arriving.length > 0) {
746
- const { bounds } = await this.house.post('/kit/door/rooms/discover', { prefixes: [root] });
745
+ const { bounds } = await this.house.door('rooms/discover', { prefixes: [root] });
747
746
  const binary = [];
748
747
  for (const [path, entry] of arriving) {
749
748
  if (!(await isText(copy.repository, entry, bounds.max_authored_file_bytes)))
@@ -961,7 +960,7 @@ export class LocalCopies {
961
960
  return true;
962
961
  }
963
962
  async revisionText(path, wanted) {
964
- const page = await this.house.post('/kit/door/files/revisions/list', {
963
+ const page = await this.house.door('files/revisions/list', {
965
964
  path,
966
965
  revision: wanted,
967
966
  });
package/dist/end.js CHANGED
@@ -1,4 +1,3 @@
1
- import { KIT_RELEASE } from './clis.js';
2
1
  import { forgetRejected } from './home.js';
3
2
  import { installCommand } from './placement.js';
4
3
  import { killDescendants } from './scope.js';
@@ -19,13 +18,7 @@ export function updateLine(lead) {
19
18
  return command === null ? `${lead}; install it again.` : `${lead}. Update it: ${command}`;
20
19
  }
21
20
  export function updateRequired() {
22
- end(updateLine('This Kit is too old for House'));
23
- }
24
- export function unknownMethod(kind) {
25
- return updateLine(`This Kit does not know ${kind}`);
26
- }
27
- export function newerThanHouse(release, command) {
28
- end(`Kit ${KIT_RELEASE} is newer than this Building supports (Kit ${release}). Install Kit ${release}: ${command}`);
21
+ end(updateLine("House does not serve this Kit's wire"));
29
22
  }
30
23
  export async function signInAgain(rejected) {
31
24
  await forgetRejected(rejected);
package/dist/house-cli.js CHANGED
@@ -12,7 +12,8 @@ import { callHouse, rpc, UNREACHABLE, Unsettled } from './mcp.js';
12
12
  import { refusalOf, retryable } from './refusals.js';
13
13
  import { proxyUnlessRelayed, relayed, selectRelay } from './relay.js';
14
14
  import { parse } from 'yaml';
15
- const USAGE = "usage: house <tool> ['<arguments as JSON>']";
15
+ const USAGE = "usage: house <tool> ['<arguments as JSON>']; house help <tool>: its arguments";
16
+ const HELP = 'help [tool]';
16
17
  const PUSH_USAGE = 'usage: house push [commit] [--owner]';
17
18
  const PUSH = "push [commit]: sends the Local copy's committed changes to House";
18
19
  const FETCH_USAGE = 'usage: house fetch';
@@ -255,21 +256,77 @@ function argumentsOf(argument) {
255
256
  throw new Error(ARGUMENTS);
256
257
  return parsed;
257
258
  }
259
+ // The schema a $ref points to inside the Tool's own inputSchema, or an empty one when it points elsewhere.
260
+ function resolved(schema, root) {
261
+ if (schema.$ref === undefined)
262
+ return schema;
263
+ if (!schema.$ref.startsWith('#'))
264
+ return {};
265
+ let found = root;
266
+ for (const key of schema.$ref.split('/').slice(1)) {
267
+ found = typeof found === 'object' && found !== null ? found[key.replaceAll('~1', '/').replaceAll('~0', '~')] : undefined;
268
+ }
269
+ return typeof found === 'object' && found !== null ? found : {};
270
+ }
271
+ // The schema a $ref resolves to, with that $ref added to the open ones, or null when it is open already,
272
+ // so a schema that holds itself is expanded once.
273
+ function expanded(schema, root, refs) {
274
+ if (schema.$ref === undefined)
275
+ return { schema, refs };
276
+ return refs.has(schema.$ref) ? null : { schema: resolved(schema, root), refs: new Set([...refs, schema.$ref]) };
277
+ }
278
+ // One line per argument: its name, its value when it has one or a few, whether it is required, and its
279
+ // description. When deep, the arguments its value holds follow it.
280
+ function argumentLines(schema, root, indent, deep, refs = new Set()) {
281
+ const required = new Set(schema.required ?? []);
282
+ return Object.entries(schema.properties ?? {}).flatMap(([name, property]) => {
283
+ const value = resolved(property, root);
284
+ const values = value.const !== undefined ? [value.const] : (value.enum ?? []);
285
+ const words = [name, ...(values.length === 0 ? [] : [values.map((one) => JSON.stringify(one)).join(' | ')]), ...(required.has(name) ? ['(required)'] : [])];
286
+ const description = property.description ?? value.description;
287
+ const line = `${indent}${words.join(' ')}${description === undefined ? '' : `: ${description}`}`;
288
+ return deep ? [line, ...held(property, root, `${indent} `, refs)] : [line];
289
+ });
290
+ }
291
+ // The arguments a value holds: its own, its items', and those of each alternative of a oneOf or anyOf,
292
+ // each alternative a "- " entry when more than one has arguments.
293
+ function held(schema, root, indent, refs) {
294
+ const value = expanded(schema, root, refs);
295
+ if (value === null)
296
+ return [];
297
+ const alternatives = (value.schema.oneOf ?? value.schema.anyOf ?? [])
298
+ .map((alternative) => held(alternative, root, indent, value.refs))
299
+ .filter((lines) => lines.length > 0);
300
+ return [
301
+ ...argumentLines(value.schema, root, indent, true, value.refs),
302
+ ...(value.schema.items === undefined ? [] : held(value.schema.items, root, indent, value.refs)),
303
+ ...(alternatives.length === 1
304
+ ? alternatives[0]
305
+ : alternatives.flatMap((lines) => lines.map((line, index) => (index === 0 ? `${indent}- ${line.slice(indent.length)}` : ` ${line}`)))),
306
+ ];
307
+ }
308
+ function listed(tool) {
309
+ return tool.description === undefined ? tool.name : `${tool.name}: ${tool.description}`;
310
+ }
311
+ async function toolHelp(name) {
312
+ const tool = (await tools()).find((one) => one.name === name);
313
+ if (tool === undefined)
314
+ throw new Error(`${name} is no Tool; house find_command '{"query":"${name}"}' finds Commands`);
315
+ return [listed(tool), ...argumentLines(tool.inputSchema, tool.inputSchema, ' ', true)].join('\n');
316
+ }
258
317
  async function house(args) {
259
318
  const { flags, positionals: [verb, argument] } = accepted(args, ['--help'], 2, USAGE);
260
- if (verb === 'help' && argument !== undefined)
261
- throw unexpected(argument, USAGE);
262
319
  if (flags.has('--help') && argument !== undefined)
263
320
  throw unexpected('--help', USAGE);
321
+ // house help <name> runs as house <name> --help, so both forms answer alike.
322
+ if (verb === 'help' && argument !== undefined)
323
+ return run([argument, '--help']);
264
324
  if (verb === undefined || verb === 'help') {
265
- return [USAGE, 'help', PUSH, FETCH, DOWNLOAD, ...(await tools()).map((tool) => (tool.description === undefined ? tool.name : `${tool.name}: ${tool.description}`))].join('\n');
266
- }
267
- if (flags.has('--help')) {
268
- const tool = (await tools()).find((listed) => listed.name === verb);
269
- if (tool === undefined)
270
- throw new Error(`${verb} is no Tool; house find_command '{"query":"${verb}"}' finds Commands`);
271
- return [...(tool.description === undefined ? [] : [tool.description]), JSON.stringify(tool.inputSchema)].join('\n');
325
+ const listing = (await tools()).flatMap((tool) => tool.description === undefined ? [tool.name, ...argumentLines(tool.inputSchema, tool.inputSchema, ' ', false)] : [listed(tool)]);
326
+ return [USAGE, HELP, PUSH, FETCH, DOWNLOAD, ...listing].join('\n');
272
327
  }
328
+ if (flags.has('--help'))
329
+ return toolHelp(verb);
273
330
  const parsed = argumentsOf(argument);
274
331
  return verb === 'upload' ? upload(parsed) : called(verb, parsed);
275
332
  }
@@ -280,16 +337,19 @@ async function called(name, args) {
280
337
  throw new Error(text.replace(/\n+$/, ''));
281
338
  return text;
282
339
  }
340
+ function run(argv) {
341
+ const named = argv.findIndex((arg) => !arg.startsWith('-'));
342
+ const rest = argv.filter((_arg, index) => index !== named);
343
+ if (argv[named] === 'push')
344
+ return push(rest);
345
+ if (argv[named] === 'fetch')
346
+ return fetched(rest);
347
+ if (argv[named] === 'download')
348
+ return download(rest);
349
+ return house(argv);
350
+ }
283
351
  const argv = process.argv.slice(2);
284
- const named = argv.findIndex((arg) => !arg.startsWith('-'));
285
- const rest = argv.filter((_arg, index) => index !== named);
286
- (argv[named] === 'push'
287
- ? push(rest)
288
- : argv[named] === 'fetch'
289
- ? fetched(rest)
290
- : argv[named] === 'download'
291
- ? download(rest)
292
- : house(argv)).then((text) => {
352
+ run(argv).then((text) => {
293
353
  process.stdout.write(`${text}\n`);
294
354
  if (argv[0] === 'shell')
295
355
  process.exitCode = Number(/^exit: (\d+)(?:\n|$)/.exec(text)?.[1] ?? 0);
package/dist/login.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { KIT_LOGIN_PATHS, } from '@agentshouse/kit-wire';
1
2
  import { spawn } from 'node:child_process';
2
3
  import { createHash, randomBytes } from 'node:crypto';
3
4
  import { parseArgs } from 'node:util';
@@ -15,6 +16,12 @@ const DEFAULT_HOUSE = 'https://agents.house';
15
16
  const OPENER = process.platform === 'darwin' ? 'open' : 'xdg-open';
16
17
  // Polling every two seconds brings the User's confirmation to the waiting Kit moments after they give it.
17
18
  const POLL_INTERVAL_MS = 2000;
19
+ function startLogin(house, request) {
20
+ return post(house, KIT_LOGIN_PATHS.start, request);
21
+ }
22
+ function pollLogin(house, request) {
23
+ return post(house, KIT_LOGIN_PATHS.poll, request);
24
+ }
18
25
  function open(link) {
19
26
  spawn(OPENER, [link], { detached: true, stdio: 'ignore' })
20
27
  .on('error', () => undefined)
@@ -92,12 +99,12 @@ export async function login(argv) {
92
99
  let named = environment;
93
100
  let exchanged;
94
101
  if (values.code !== undefined) {
95
- exchanged = await post(house, '/kit/token', { code: values.code });
102
+ exchanged = await pollLogin(house, { code: values.code });
96
103
  }
97
104
  else {
98
105
  held = ownAgent !== null && ownAgent.house === house && (await accepted(house, ownAgent.credential));
99
106
  const verifier = randomBytes(32).toString('base64url');
100
- const start = () => retrying(() => post(house, '/kit', {
107
+ const start = () => retrying(() => startLogin(house, {
101
108
  ...(named === undefined
102
109
  ? { act: 'new_environment', ...(replaces === undefined ? {} : { replaces }) }
103
110
  : { act: 'existing_environment', environment_id: named }),
@@ -119,7 +126,7 @@ export async function login(argv) {
119
126
  }
120
127
  process.stdout.write(`Open this link and confirm: ${started.start_url}\n`);
121
128
  open(started.start_url);
122
- exchanged = await retrying(() => post(house, '/kit/token', { login: started.login, code_verifier: verifier }), undefined, () => POLL_INTERVAL_MS);
129
+ exchanged = await retrying(() => pollLogin(house, { login: started.login, code_verifier: verifier }), undefined, () => POLL_INTERVAL_MS);
123
130
  }
124
131
  await placeSkillSet(house);
125
132
  await writeCodexRule().catch((error) => process.stderr.write(`kit: ${error.message}\n`));
package/dist/logout.js CHANGED
@@ -1,10 +1,10 @@
1
- import { HouseRefusal, post } from './api.js';
1
+ import { HouseRefusal, kitAct } from './api.js';
2
2
  import { forgetEnrolment, forgetOwnAgent, readEnrolment } from './home.js';
3
3
  export async function logout() {
4
4
  const enrolled = await readEnrolment();
5
5
  if (enrolled !== null) {
6
6
  try {
7
- await post(enrolled.house, '/kit/kits/log-out', {}, enrolled.credential);
7
+ await kitAct(enrolled.house, 'kits/log-out', {}, enrolled.credential);
8
8
  }
9
9
  catch (error) {
10
10
  if (!(error instanceof HouseRefusal && error.status === 401))
package/dist/mcp.js CHANGED
@@ -1,7 +1,7 @@
1
+ import { KIT_WIRE, KIT_WIRE_HEADER } from '@agentshouse/kit-wire';
1
2
  import { randomUUID } from 'node:crypto';
2
3
  import { KIT_RELEASE } from './clis.js';
3
4
  import { relayed } from './relay.js';
4
- import { KIT_WIRE, KIT_WIRE_HEADER } from './wire.js';
5
5
  const MCP_PROTOCOL_VERSION = '2026-07-28';
6
6
  export const UNREACHABLE = 'House is unreachable; call again in a minute';
7
7
  export class Unsettled extends Error {
@@ -34,7 +34,7 @@ export async function callHouse(origin, credential, message, operation = null, s
34
34
  'mcp-protocol-version': MCP_PROTOCOL_VERSION,
35
35
  'mcp-method': message.method,
36
36
  ...(tool === null ? {} : { 'mcp-name': tool }),
37
- [KIT_WIRE_HEADER]: String(KIT_WIRE),
37
+ [KIT_WIRE_HEADER]: KIT_WIRE,
38
38
  },
39
39
  body: mcpBody(message, operation),
40
40
  signal,
package/dist/placement.js CHANGED
@@ -14,12 +14,6 @@ function recorded(name) {
14
14
  export function installCommand() {
15
15
  return recorded('install-command');
16
16
  }
17
- export function machine() {
18
- const placed = recorded('placement');
19
- if (placed === 'container' || placed === 'server' || placed === 'windows')
20
- return placed;
21
- return process.platform === 'darwin' ? 'macos' : 'linux';
22
- }
23
17
  export function placedPrefix() {
24
18
  const prefix = process.env.HOUSE_KIT_PREFIX;
25
19
  if (prefix === undefined || prefix === '')
package/dist/resident.js CHANGED
@@ -8,9 +8,9 @@ import { fileURLToPath } from 'node:url';
8
8
  import { Agents } from './agents.js';
9
9
  import { house } from './api.js';
10
10
  import { received } from './bridge.js';
11
- import { CONVERSATION_METHODS, Conversations } from './conversations.js';
11
+ import { Conversations } from './conversations.js';
12
12
  import { LocalCopies } from './copies.js';
13
- import { restart, unknownMethod } from './end.js';
13
+ import { restart } from './end.js';
14
14
  import { agentBase, enrolled, kitHome, ownerLock, ownerSocket, readEnrolment } from './home.js';
15
15
  import { Calls } from './calls.js';
16
16
  import { killDescendants } from './scope.js';
@@ -145,13 +145,13 @@ export async function resident() {
145
145
  if (!idle()) {
146
146
  reported = false;
147
147
  }
148
- else if (update.placedRelease() !== null && conversations.quiet()) {
148
+ else if (update.placedRelease() !== null && conversations.quiet() && process.env.HOUSE_KIT_SANDBOX !== '1') {
149
149
  const placed = update.placedRelease();
150
150
  void stop(() => restart(`Kit ${placed} is placed; its supervisor starts it`));
151
151
  }
152
152
  else if (!reported) {
153
153
  reported = true;
154
- logged(house.deliver('/kit/kits/report-idle', {}, idle));
154
+ logged(house.deliver('kits/report-idle', {}, idle));
155
155
  }
156
156
  };
157
157
  const calls = new Calls(house, changed);
@@ -165,8 +165,7 @@ export async function resident() {
165
165
  });
166
166
  const signIns = new SignIns(house, agents, calls);
167
167
  const update = new KitUpdate(calls);
168
- if (process.env.HOUSE_KIT_SANDBOX !== '1')
169
- takeUnservedRelease((release) => logged(update.takeRefused(release)));
168
+ takeUnservedRelease((release) => logged(update.takeRefused(release)));
170
169
  removeInputs();
171
170
  const scripts = new Scripts(calls, (oneWayCall) => connection?.send(oneWayCall) ?? false);
172
171
  for (const signal of ['SIGTERM', 'SIGINT']) {
@@ -183,12 +182,13 @@ export async function resident() {
183
182
  };
184
183
  watch(kitHome(), unenrolled);
185
184
  unenrolled();
186
- await house.deliver('/kit/kits/report-restart', {}).catch(report);
185
+ await house.deliver('kits/report-restart', {}).catch(report);
187
186
  logged(agents.refresh());
188
187
  agents.keepCurrent(() => process.env.HOUSE_KIT_SANDBOX === '1' && reported);
189
188
  connection = holdConnection({
190
189
  opened: () => {
191
190
  conversations.opened();
191
+ scripts.connected();
192
192
  changed();
193
193
  logged(copies.connected());
194
194
  },
@@ -200,16 +200,12 @@ export async function resident() {
200
200
  update.take(call);
201
201
  else if (call.kind === 'run_wizard' || call.kind === 'run_function')
202
202
  scripts.start(call);
203
- else if (CONVERSATION_METHODS.has(call.kind))
203
+ else
204
204
  conversations.call(call);
205
- else {
206
- const refused = { refused: unknownMethod(call.kind) };
207
- void calls.carry(call.input_id, async () => ({ result: refused }));
208
- }
209
205
  },
210
206
  oneWayCall: (oneWayCall) => {
211
207
  if (oneWayCall.type === 'watching')
212
- conversations.watching(oneWayCall.watching === true);
208
+ conversations.watching(oneWayCall.watching);
213
209
  if (oneWayCall.type === 'work_available' && oneWayCall.subject === 'agents')
214
210
  logged(agents.refresh());
215
211
  scripts.notified(oneWayCall);
package/dist/scripts.js CHANGED
@@ -15,6 +15,11 @@ const SIGNALLED = 128;
15
15
  const NEWLINE = 0x0a;
16
16
  const NO_BASH = "bash is not on the login shell's PATH";
17
17
  const LOST = { refused: 'the Kit lost its connection to House' };
18
+ const UNSENT_CHARS = 64_000;
19
+ // House holds a Web Wizard's run two minutes for its Kit to connect again, so the script waits as long for a dropped connection to come back.
20
+ const RETURN_MS = 120_000;
21
+ // House takes a run on again with its page's terminal size in the frames right after the Kit connects, so a script it sent nothing for in ten seconds is one House no longer carries.
22
+ const TAKEN_ON_MS = 10_000;
18
23
  function causeOf(error) {
19
24
  return error instanceof Error ? error.message : String(error);
20
25
  }
@@ -44,6 +49,12 @@ async function inputFile(value) {
44
49
  export function removeInputs() {
45
50
  rmSync(inputs(), { recursive: true, force: true });
46
51
  }
52
+ function latest(screen) {
53
+ if (screen.length <= UNSENT_CHARS)
54
+ return screen;
55
+ const line = screen.indexOf('\n', screen.length - UNSENT_CHARS);
56
+ return screen.slice(line < 0 ? screen.length - UNSENT_CHARS : line + 1);
57
+ }
47
58
  function struck(line, typed) {
48
59
  return typed.some((typedLine) => line.includes(typedLine));
49
60
  }
@@ -131,24 +142,53 @@ export class Scripts {
131
142
  void this.calls.carry(call.input_id, () => this.run(call.input_id, planned(call)));
132
143
  }
133
144
  notified(oneWayCall) {
134
- const run = this.runs.get(String(oneWayCall.wizard));
145
+ if (!('wizard' in oneWayCall))
146
+ return;
147
+ const run = this.runs.get(oneWayCall.wizard);
135
148
  if (run === undefined)
136
149
  return;
150
+ this.waited(run, null);
137
151
  if (oneWayCall.type === 'wizard_input')
138
- this.typed(run, String(oneWayCall.data));
152
+ this.typed(run, oneWayCall.data);
139
153
  if (oneWayCall.type === 'wizard_size')
140
- this.resized(run, { cols: Number(oneWayCall.cols), rows: Number(oneWayCall.rows) });
154
+ this.resized(run, { cols: oneWayCall.cols, rows: oneWayCall.rows });
141
155
  if (oneWayCall.type === 'wizard_end' && run.plan.terminal === 'page')
142
156
  this.end(run, {});
143
157
  }
144
158
  disconnected() {
145
- for (const run of this.runs.values())
146
- this.end(run, LOST);
159
+ for (const run of this.runs.values()) {
160
+ if (run.plan.terminal === 'page')
161
+ this.waited(run, RETURN_MS);
162
+ else
163
+ this.end(run, LOST);
164
+ }
165
+ }
166
+ connected() {
167
+ for (const [id, run] of this.runs) {
168
+ if (run.waiting === null)
169
+ continue;
170
+ this.waited(run, TAKEN_ON_MS);
171
+ if (run.unsent !== '' && this.send({ type: 'wizard_output', wizard: id, data: run.unsent }))
172
+ run.unsent = '';
173
+ }
147
174
  }
148
175
  async run(id, plan) {
149
176
  const size = plan.terminal === 'page' ? null : FIRST_SIZE;
150
177
  const output = plan.function === null ? null : new KeptOutput(plan.function.outputCap);
151
- const run = { plan, input: null, output, process: null, pipes: [], terminal: null, size, typed: [], ended: null, sized: Promise.withResolvers() };
178
+ const run = {
179
+ plan,
180
+ input: null,
181
+ output,
182
+ process: null,
183
+ pipes: [],
184
+ terminal: null,
185
+ size,
186
+ typed: [],
187
+ unsent: '',
188
+ waiting: null,
189
+ ended: null,
190
+ sized: Promise.withResolvers(),
191
+ };
152
192
  if (size !== null)
153
193
  run.sized.resolve();
154
194
  this.runs.set(id, run);
@@ -184,7 +224,8 @@ export class Scripts {
184
224
  run.process = terminal;
185
225
  run.terminal = terminal;
186
226
  terminal.onData((data) => {
187
- this.send({ type: 'wizard_output', wizard: id, data });
227
+ if (!this.send({ type: 'wizard_output', wizard: id, data }))
228
+ run.unsent = latest(`${run.unsent}${data}`);
188
229
  output?.add(data);
189
230
  });
190
231
  for (const data of run.typed.splice(0))
@@ -242,10 +283,17 @@ export class Scripts {
242
283
  end(run, result) {
243
284
  if (run.ended !== null)
244
285
  return;
286
+ this.waited(run, null);
245
287
  run.ended = result;
246
288
  run.sized.resolve();
247
289
  this.stop(run);
248
290
  }
291
+ waited(run, ms) {
292
+ if (run.waiting !== null)
293
+ clearTimeout(run.waiting);
294
+ run.waiting = ms === null ? null : setTimeout(() => this.end(run, LOST), ms);
295
+ run.waiting?.unref();
296
+ }
249
297
  stop(run) {
250
298
  if (run.process !== null)
251
299
  killTree(run.process);
@@ -2,7 +2,7 @@ import { finalRefusal, retryDelay } from './api.js';
2
2
  export async function holdSecretInput(house, subject, steps, waiting) {
3
3
  for (let failures = 0; waiting();) {
4
4
  try {
5
- const held = await house.post('/kit/secret-inputs/await', { subject, steps });
5
+ const held = await house.act('secret-inputs/await', { subject, steps });
6
6
  if (held.outcome === 'collected')
7
7
  return held.content;
8
8
  if (held.release !== 'held')
@@ -1,6 +1,7 @@
1
1
  import { chmod, mkdir, mkdtemp, readdir, readFile, rename, rm, stat } from 'node:fs/promises';
2
2
  import { availableParallelism, tmpdir } from 'node:os';
3
3
  import { basename, join } from 'node:path';
4
+ import { isDeepStrictEqual } from 'node:util';
4
5
  import { unlessAborted } from './abort.js';
5
6
  import { downloadServed } from './building.js';
6
7
  import { failureOf, run } from './clis.js';
@@ -34,7 +35,6 @@ const NOT_INSTALLED = "the speech engine is not installed on the Agent's Environ
34
35
  const NOT_DOWNLOADED = 'an audio file this message links could not be downloaded; send the message again';
35
36
  const UNDECODABLE = 'an audio file this message links could not be decoded';
36
37
  const UNTRANSCRIBED = 'an audio file this message links could not be transcribed';
37
- const NO_ENGINE = 'there is no transcription engine for this computer';
38
38
  let held = Promise.resolve();
39
39
  let holding = Promise.resolve();
40
40
  let setting = null;
@@ -79,10 +79,7 @@ function ready() {
79
79
  throw new Error(NOT_INSTALLED);
80
80
  }
81
81
  function pinnedHere() {
82
- const engine = ENGINES[`${process.platform}-${process.arch}`];
83
- if (engine === undefined)
84
- throw new Error(NO_ENGINE);
85
- return engine;
82
+ return ENGINES[`${process.platform}-${process.arch}`];
86
83
  }
87
84
  const DOWNLOADS = 3;
88
85
  async function downloadedAgain(artifact, signal) {
@@ -129,7 +126,7 @@ async function install(artifacts, signal) {
129
126
  }
130
127
  }
131
128
  function reported(next) {
132
- const changed = next.installed !== readiness.installed || next.failure !== readiness.failure;
129
+ const changed = !isDeepStrictEqual(next, readiness);
133
130
  readiness = next;
134
131
  return changed;
135
132
  }
@@ -141,10 +138,12 @@ async function settle(transcribe) {
141
138
  await rm(directory(), { recursive: true, force: true });
142
139
  return reported({ installed: false, failure: null });
143
140
  }
141
+ const pinned = pinnedHere();
142
+ if (pinned === undefined)
143
+ return reported({ installed: false, failure: null, no_engine: true });
144
144
  const download = new AbortController();
145
145
  downloading = download;
146
146
  try {
147
- const pinned = pinnedHere();
148
147
  await install([pinned.decoder, pinned.engine, MODEL], download.signal);
149
148
  return reported({ installed: true, failure: null });
150
149
  }
package/dist/update.js CHANGED
@@ -93,7 +93,8 @@ export class KitUpdate {
93
93
  const failure = await this.place(release, 'named');
94
94
  if (failure !== null)
95
95
  return { refused: failure };
96
- process.stderr.write(`kit: Kit ${release} is placed; it starts once no turn is open\n`);
96
+ const starts = process.env.HOUSE_KIT_SANDBOX === '1' ? 'when the Sandbox starts again' : 'once no turn is open';
97
+ process.stderr.write(`kit: Kit ${release} is placed; it starts ${starts}\n`);
97
98
  return {};
98
99
  }
99
100
  async place(release, which) {
package/dist/wire.js CHANGED
@@ -1,8 +1,5 @@
1
- import { newerThanHouse, updateRequired } from './end.js';
2
- import { machine } from './placement.js';
1
+ import { updateRequired } from './end.js';
3
2
  import { refusalOf } from './refusals.js';
4
- export const KIT_WIRE = 6;
5
- export const KIT_WIRE_HEADER = 'x-house-kit-wire';
6
3
  let take = null;
7
4
  let taken = false;
8
5
  function unservedBy(text) {
@@ -13,10 +10,7 @@ function unservedBy(text) {
13
10
  catch {
14
11
  return null;
15
12
  }
16
- const error = body?.error;
17
- if (error?.code !== 'kit_update_required' && error?.code !== 'kit_newer_than_house')
18
- return null;
19
- return typeof error.release === 'string' ? error : null;
13
+ return body?.error?.code === 'kit_update_required' ? body.error : null;
20
14
  }
21
15
  export function takeUnservedRelease(taking) {
22
16
  take = taking;
@@ -35,6 +29,4 @@ export function endUnserved(text) {
35
29
  }
36
30
  if (refusalOf(text)?.code === 'kit_update_required')
37
31
  updateRequired();
38
- if (refused?.code === 'kit_newer_than_house')
39
- newerThanHouse(refused.release, refused.commands[machine()]);
40
32
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agentshouse/kit",
3
- "version": "0.2.1-ce8e5419af3f9",
3
+ "version": "0.2.1-ce9401bb7d372",
4
4
  "description": "Kit connects an Environment to agents.house.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -19,15 +19,16 @@
19
19
  "bootstrap-manifest": "node scripts/bootstrap-manifest.mjs",
20
20
  "build": "tsc -p tsconfig.build.json",
21
21
  "engine": "mkdir -p tmp/engine && docker run --rm -v \"$PWD:/kit\" -w /kit alpine:3.24@sha256:294b683cb724975bec92580e1e685676bd4b50bda910ddb8c51d4cabeaec77e6 sh scripts/engine.sh tmp/engine",
22
- "follow-skills": "node scripts/follow-skills.mjs",
22
+ "follow-skills-and-kit-wire": "node scripts/follow-skills-and-kit-wire.mjs",
23
23
  "release-files": "node scripts/release-files.mjs",
24
24
  "test": "tsc -p tsconfig.json && vitest run"
25
25
  },
26
26
  "dependencies": {
27
27
  "@agentclientprotocol/sdk": "2.4.0",
28
+ "@agentshouse/kit-wire": "0.1.0-ce39c80194ad4",
28
29
  "@agentshouse/mdmodel": "0.1.0-cd6a8e5bc7efc",
29
30
  "@agentshouse/session-content": "0.1.0-cad437697294e",
30
- "@agentshouse/skills": "0.1.0-c33c14a1acda2",
31
+ "@agentshouse/skills": "0.1.0-c094c13538a89",
31
32
  "@lydell/node-pty": "1.2.0-beta.15",
32
33
  "micromark": "4.0.2",
33
34
  "yaml": "2.9.1"
@@ -49,7 +50,8 @@
49
50
  "@types/ws": "8.18.2",
50
51
  "typescript": "7.0.2",
51
52
  "vitest": "5.0.5",
52
- "ws": "8.22.0"
53
+ "ws": "8.22.0",
54
+ "zod": "4.6.7"
53
55
  },
54
56
  "packageManager": "npm@11.19.1",
55
57
  "engines": {
@@ -1,10 +0,0 @@
1
- import { readFileSync } from 'node:fs';
2
- import { writeEnrolment } from './home.js';
3
- const [house, environment] = process.argv.slice(2);
4
- const relay = process.env.HOUSE_KIT_RELAY || undefined;
5
- await writeEnrolment({
6
- house: house,
7
- ...(relay === undefined ? {} : { relay }),
8
- environment: environment,
9
- credential: readFileSync(0, 'utf8').trim(),
10
- });