@agentshouse/kit 0.0.1 → 0.1.0-alpha.2

package/src/inbound.js

@@ -0,0 +1,175 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import {
+  holdConversationFile,
+  retainConversationFile,
+  retryConversationFiles,
+  settleConversationFile,
+} from "./conversation-originals.js";
+import { heldControl, houseRequest } from "./house.js";
+import { KIT_CONTRACT_VERSION } from "./contract.js";
+import { KitRefusal } from "./refusal.js";
+
+const ROOT = "conversation-inbound";
+const MAX_BYTES = 32 * 1024 * 1024;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MEDIA = new Set(["document", "photo", "audio", "video", "voice", "video_note", "sticker", "animation"]);
+
+function segment(value) {
+  return typeof value === "string" && value !== "" && value !== "." && value !== ".." &&
+    Buffer.byteLength(value) <= 255 && !/[\\/\0]/.test(value);
+}
+
+async function cacheDirectory(directory, parts, create) {
+  let path = await realpath(directory);
+  for (const part of [ROOT, ...parts]) {
+    path = join(path, part);
+    if (create) await mkdir(path, { mode: 0o700 }).catch((error) => {
+      if (error.code !== "EEXIST") throw error;
+    });
+    const state = await lstat(path).catch((error) => {
+      if (error.code === "ENOENT" && !create) return null;
+      throw error;
+    });
+    if (state === null) return null;
+    if (!state.isDirectory() || state.isSymbolicLink()) throw new KitRefusal("kit_inbound_path_invalid");
+  }
+  return path;
+}
+
+function request(session, path, body = {}) {
+  return heldControl(session, session.signal).then((authorization) =>
+    houseRequest(session.house, authorization, `/kit/telegram/${path}`, body, session.dependencies, session.signal));
+}
+
+async function download(session, file) {
+  const signal = AbortSignal.any([AbortSignal.timeout(30_000), ...(session.signal ? [session.signal] : [])]);
+  const response = await (session.dependencies.fetch ?? fetch)(`${session.house}/kit/telegram/inbound/${file.id}/stream`, {
+    method: "POST", redirect: "error", signal,
+    headers: { authorization: await heldControl(session, signal), "content-type": "application/json", "x-house-kit-version": KIT_CONTRACT_VERSION },
+    body: "{}",
+  });
+  if (!response.ok || response.body === null) {
+    await response.body?.cancel();
+    throw new KitRefusal("kit_inbound_unavailable", file.id);
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      if (size > MAX_BYTES || (file.byte_size !== null && size > file.byte_size)) {
+        throw new KitRefusal("kit_inbound_size_mismatch", file.id);
+      }
+      chunks.push(chunk.value);
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+  if (file.byte_size !== null && size !== file.byte_size) throw new KitRefusal("kit_inbound_size_mismatch", file.id);
+  return Buffer.concat(chunks, size);
+}
+
+async function materialize(directory, session, file, outcome) {
+  const retention = { directory, session, signal: session.signal };
+  const parent = await cacheDirectory(directory, [file.run, file.id], true);
+  const path = join(parent, file.cache_name);
+  const incoming = { attachment: file.id, run: file.run, path };
+  let bytes;
+  try {
+    bytes = await download(session, file);
+  } catch (error) {
+    if (!session.signal?.aborted) outcome.originals.push(await retainConversationFile(retention, incoming, null));
+    throw error;
+  }
+  const temporary = join(parent, `${randomUUID()}.partial`);
+  try {
+    const opened = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try { await opened.writeFile(bytes); } finally { await opened.close(); }
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    outcome.originals.push(await retainConversationFile(retention, incoming, bytes));
+    throw error;
+  }
+  const { held, body } = await holdConversationFile(retention, incoming, bytes);
+  await request(session, `inbound/${file.id}/materialized`);
+  outcome.originals.push(await settleConversationFile(retention, held, body));
+  return path;
+}
+
+export async function reconcileInbound(directory, session) {
+  const outcome = { materialized: [], failures: [], originals: [] };
+  const attempted = new Set();
+  for (;;) {
+    const pending = await request(session, "inbound/acquire", { max: 10 });
+    if (!Array.isArray(pending?.files) || pending.files.length > 10) throw new KitRefusal("kit_inbound_response_invalid");
+    let progressed = false;
+    for (const file of pending.files) {
+      if (!UUID.test(file?.run) || !UUID.test(file?.id) || !segment(file?.cache_name) ||
+          !MEDIA.has(file?.media_kind) || (file.byte_size !== null && (!Number.isSafeInteger(file.byte_size) || file.byte_size < 0 || file.byte_size > MAX_BYTES))) {
+        throw new KitRefusal("kit_inbound_response_invalid");
+      }
+      if (attempted.has(file.id)) continue;
+      attempted.add(file.id);
+      try {
+        outcome.materialized.push(await materialize(directory, session, file, outcome));
+        progressed = true;
+      } catch (error) {
+        if (session.signal?.aborted) throw error;
+        outcome.failures.push({ id: file.id, run: file.run, code: error instanceof KitRefusal ? error.code : "kit_inbound_unavailable" });
+      }
+    }
+    if (pending.files.length < 10 || !progressed) break;
+  }
+  const retained = new Set(outcome.originals.map((original) => original.attachment));
+  outcome.originals.push(...(await retryConversationFiles({ directory, session, signal: session.signal }, retained)));
+  return outcome;
+}
+
+export async function localRequest(directory, run, request) {
+  const turn = request?.conversation?.turn ?? (request?.kind === "conversation" ? request.turn : null);
+  if (turn === null || turn === undefined) return request;
+  const result = structuredClone(request);
+  const localTurn = result.conversation?.turn ?? result.turn;
+  if (!Array.isArray(localTurn.messages)) throw new KitRefusal("kit_run_input_unreadable");
+  for (const message of localTurn.messages) {
+    if (!Array.isArray(message.files)) throw new KitRefusal("kit_run_input_unreadable");
+    for (const file of message.files) {
+      const parts = typeof file.path === "string" ? file.path.split("/") : [];
+      if (parts.length !== 4 || parts[0] !== ROOT || parts[1] !== run || !UUID.test(parts[1]) || !UUID.test(parts[2]) || !segment(parts[3])) {
+        throw new KitRefusal("kit_inbound_path_invalid");
+      }
+      const parent = await cacheDirectory(directory, [run, parts[2]], false);
+      if (parent === null) throw new KitRefusal("kit_inbound_unavailable");
+      const path = join(parent, parts[3]);
+      const opened = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW).catch(() => {
+        throw new KitRefusal("kit_inbound_unavailable");
+      });
+      try {
+        const state = await opened.stat();
+        if (!state.isFile() || state.size > MAX_BYTES || (file.bytes !== null && state.size !== file.bytes)) throw new KitRefusal("kit_inbound_size_mismatch");
+      } finally { await opened.close(); }
+      file.path = path;
+    }
+  }
+  return result;
+}
+
+export async function localReply(directory, run, frame, reply) {
+  if (frame.method !== "tools/call" || frame.params?.name !== "session_get_request" || reply.error || reply.result?.isError) return reply;
+  const result = structuredClone(reply);
+  for (const item of result.result?.content ?? []) {
+    if (item.type !== "text") continue;
+    let input;
+    try { input = JSON.parse(item.text); } catch { throw new KitRefusal("kit_run_input_unreadable"); }
+    item.text = JSON.stringify(await localRequest(directory, run, input));
+  }
+  return result;
+}

package/src/instance/google.js

@@ -0,0 +1 @@
+export const GOOGLE_OAUTH_CLIENT = Object.freeze({"id":"911965338518-867gdvuddb7kdkjo3qvpv6gds369alb7.apps.googleusercontent.com","secret":"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"});

package/src/launcher-main.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { launchWorkerSession } from "./launcher.js";
+import { BRIDGE_NONCE_ENVIRONMENT, BRIDGE_SOCKET_ENVIRONMENT } from "./contract.js";
+
+const socket = process.env[BRIDGE_SOCKET_ENVIRONMENT];
+const nonce = process.env[BRIDGE_NONCE_ENVIRONMENT];
+
+if (socket === undefined || nonce === undefined) {
+  process.stderr.write("kit_bridge_unavailable\n");
+  process.exit(1);
+}
+
+launchWorkerSession({ socket, nonce }).then(
+  () => process.exit(0),
+  (refusal) => {
+    process.stderr.write(`${refusal instanceof Error ? refusal.message : "kit_launcher_failed"}\n`);
+    process.exit(1);
+  },
+);

package/src/launcher.js

@@ -0,0 +1,276 @@
+import { randomUUID } from "node:crypto";
+import { commandHouseInstructions, commandHouseRequest } from "./adapter-mcp.js";
+import {
+  compiledContract,
+  initializeCommandAdapter,
+  openedSession,
+  startCommandAdapter,
+  stopCommandAdapter,
+} from "./adapter.js";
+import { PERMISSION_OPTION_KINDS, SESSION_SET_CONFIG_OPTION } from "./contract.js";
+import { observedAssistantDrafts } from "./draft.js";
+import { observedPlans } from "./plan.js";
+import { bridgePeer } from "./peer.js";
+import {
+  elicitationResponse,
+  elicitedForm,
+  elicitedVisit,
+  grokForm,
+  grokResponse,
+} from "./question.js";
+import { KitRefusal } from "./refusal.js";
+
+export function resolvedPermission(request, authority) {
+  const wanted = PERMISSION_OPTION_KINDS[authority];
+  if (wanted === undefined) return { outcome: { outcome: "cancelled" } };
+  const options = Array.isArray(request?.options) ? request.options : [];
+  const selected = options.find(
+    (option) =>
+      option?.kind === wanted &&
+      typeof option?.optionId === "string" &&
+      option.optionId.length > 0,
+  );
+  if (selected === undefined) return { outcome: { outcome: "cancelled" } };
+  return { outcome: { outcome: "selected", optionId: selected.optionId } };
+}
+
+function queuedOwner(channel, turn, frame, elicited, answer, cancel) {
+  const correlation = `${turn.providerTurn}:${frame.id}`;
+  if (elicited === null) return { action: "cancel" };
+  return new Promise((resolve) => {
+    turn.questions.set(correlation, { correlation, answer, cancel, resolve });
+    channel.send({
+      type: "question",
+      delivery: correlation,
+      form: elicited.form,
+      ...(elicited.ceremony === undefined ? {} : { ceremony: elicited.ceremony }),
+    });
+  });
+}
+
+export function askedOwner(channel, turn, frame) {
+  const correlation = `${turn.providerTurn}:${frame.id}`;
+  const bound = { correlation, providerTurn: turn.providerTurn };
+  const elicited = elicitedForm(frame.params, bound) ?? elicitedVisit(frame.params, bound);
+  return queuedOwner(
+    channel,
+    turn,
+    frame,
+    elicited,
+    (response) => elicitationResponse(elicited?.convention ?? {}, response),
+    () => ({ action: "cancel" }),
+  );
+}
+
+export function askedGrokOwner(channel, turn, frame) {
+  const correlation = `${turn.providerTurn}:${frame.id}`;
+  const elicited = grokForm(frame.params, {
+    correlation,
+    providerTurn: turn.providerTurn,
+  });
+  if (elicited === null) return { outcome: "cancelled" };
+  return queuedOwner(
+    channel,
+    turn,
+    frame,
+    elicited,
+    (response) => grokResponse(elicited?.convention ?? {}, response),
+    () => ({ outcome: "cancelled" }),
+  );
+}
+
+export function answeredOwner(channel, turn, frame) {
+  const pending = turn.questions.get(frame.delivery);
+  if (pending === undefined) return;
+  if (
+    frame.unsupported !== true &&
+    (frame.provider_turn !== turn.providerTurn || frame.correlation !== pending.correlation)
+  ) {
+    return;
+  }
+  turn.questions.delete(frame.delivery);
+  pending.resolve(frame.unsupported === true ? pending.cancel() : pending.answer(frame.response));
+  channel.send({ type: "question_applied", delivery: frame.delivery, outcome: "resolved" });
+}
+
+function abandonQuestions(channel, turn) {
+  for (const [delivery, pending] of turn.questions) {
+    turn.questions.delete(delivery);
+    pending.resolve(pending.cancel());
+    channel.send({ type: "question_applied", delivery, outcome: "expired" });
+  }
+}
+
+function turnOutcome(contract, stopReason) {
+  const named =
+    typeof stopReason === "string" &&
+    Object.hasOwn(contract.capabilities.stop_reasons, stopReason);
+  if (!named) {
+    throw new KitRefusal(
+      "kit_adapter_contract_mismatch",
+      `session/prompt stop reason ${JSON.stringify(stopReason ?? null)}`,
+    );
+  }
+  return contract.capabilities.stop_reasons[stopReason];
+}
+
+async function configureSession(acp, contract, sessionId, adapter) {
+  for (const field of ["model", "effort"]) {
+    const value = adapter[field];
+    if (value === null) continue;
+    const configId = contract.sessionConfig[field];
+    if (configId === null) {
+      throw new KitRefusal(
+        "kit_adapter_failed",
+        `${contract.kind} contract ${contract.version} offers no ${field} option`,
+      );
+    }
+    await acp.request(SESSION_SET_CONFIG_OPTION, { sessionId, configId, value });
+  }
+}
+
+async function runTurn(channel, start, bridge, turn) {
+  const contract = compiledContract(start.adapter?.kind);
+  const adapter = startCommandAdapter(
+    { ...start.adapter, workingDirectory: start.working_directory },
+    bridge,
+  );
+  const said = [];
+  const message = { text: "" };
+  const drafts = observedAssistantDrafts({ send: (text) => channel.send({ type: "draft", text }) });
+  const plans = observedPlans({
+    send: (snapshot) =>
+      channel.send({ type: "plan", provider_turn: turn.providerTurn, ...snapshot }),
+  });
+  const wholeSoFar = () => [...said, message.text].filter((text) => text !== "").join("\n\n");
+  let loading = false;
+  const flush = () => {
+    if (message.text === "") return;
+    channel.send({ type: "assistant", text: message.text });
+    said.push(message.text);
+    message.text = "";
+    drafts.complete(wholeSoFar());
+  };
+  const handlers = {
+    onPermission: (params) => resolvedPermission(params, start.execution_authority),
+    onElicitation: (request) => askedOwner(channel, turn, request),
+    onNativeQuestion: (request) => askedGrokOwner(channel, turn, request),
+    onUpdate: (params) => {
+      if (loading) return;
+      const update = params?.update;
+      if (update?.sessionUpdate === "agent_message_chunk") {
+        if (update.content?.type === "text" && typeof update.content.text === "string") {
+          message.text += update.content.text;
+          drafts.observe(wholeSoFar());
+        }
+        return;
+      }
+      if (update?.sessionUpdate === "plan") plans.observe(update.entries);
+      flush();
+    },
+  };
+  try {
+    const { acp } = await initializeCommandAdapter(adapter, contract, handlers);
+    const instructions = await commandHouseInstructions(bridge);
+    let providerSessionId = start.provider_session ?? null;
+    const setup = { cwd: start.working_directory, mcpServers: [] };
+    if (providerSessionId === null) {
+      providerSessionId = openedSession(await acp.request("session/new", setup));
+      if (providerSessionId === null) {
+        throw new KitRefusal("kit_adapter_contract_mismatch", "session/new");
+      }
+    } else {
+      loading = true;
+      await acp.request("session/load", { ...setup, sessionId: providerSessionId });
+      loading = false;
+    }
+    await configureSession(acp, contract, providerSessionId, start.adapter);
+    const request = start.request === null ? await commandHouseRequest(bridge) : start.request;
+    turn.adapterSession = true;
+    turn.cancel = () => acp.cancel({ sessionId: providerSessionId });
+    const prompted = await acp.request("session/prompt", {
+      sessionId: providerSessionId,
+      prompt: [
+        { type: "text", text: JSON.stringify(request) },
+        { type: "text", text: instructions },
+      ],
+    });
+    await new Promise((resolve) => setImmediate(resolve));
+    flush();
+    plans.complete();
+    channel.send({
+      type: "turn_ended",
+      stop_outcome: turnOutcome(contract, prompted?.stopReason),
+      provider_continuation: contract.sessionLoad,
+      provider_session_id: providerSessionId,
+    });
+  } finally {
+    turn.cancel = null;
+    plans.complete();
+    abandonQuestions(channel, turn);
+    drafts.close();
+    stopCommandAdapter(adapter);
+  }
+}
+
+export async function launchWorkerSession(bridge) {
+  const turn = {
+    adapterSession: false,
+    providerTurn: randomUUID(),
+    questions: new Map(),
+    cancel: null,
+  };
+  const peer = bridgePeer({
+    socket: bridge.socket,
+    nonce: bridge.nonce,
+    role: "launcher",
+    hello: () => ({ adapter_session: turn.adapterSession }),
+    greeted: (frame) => frame.type === "resumed" || frame.type === "start",
+    onFrame: (frame) => {
+      if (frame.type === "answered" && typeof frame.delivery === "string") {
+        answeredOwner(peer, turn, frame);
+      }
+      if (frame.type === "interrupt" && typeof frame.interrupt === "string") {
+        const cancel = turn.cancel;
+        if (cancel === null) {
+          peer.send({
+            type: "interrupt_applied",
+            interrupt: frame.interrupt,
+            outcome: "nothing_to_interrupt",
+          });
+          return;
+        }
+        void cancel().then(
+          () =>
+            peer.send({
+              type: "interrupt_applied",
+              interrupt: frame.interrupt,
+              outcome: "interrupted",
+            }),
+          () =>
+            peer.send({
+              type: "interrupt_applied",
+              interrupt: frame.interrupt,
+              outcome: "nothing_to_interrupt",
+            }),
+        );
+      }
+    },
+  });
+  const start = await peer.open();
+  if (start.type !== "start") {
+    throw new KitRefusal("kit_bridge_refused", start.code ?? null);
+  }
+  try {
+    await Promise.race([runTurn(peer, start, bridge, turn), peer.refused]);
+  } catch (refusal) {
+    peer.send({
+      type: "failed",
+      code: refusal instanceof KitRefusal ? refusal.code : "kit_adapter_failed",
+      detail: refusal instanceof Error ? refusal.message : null,
+    });
+  }
+  peer.send({ type: "exiting" });
+  await Promise.race([peer.drained(), peer.refused.catch(() => undefined)]);
+  await peer.end();
+}

package/src/local-files.js

@@ -0,0 +1,113 @@
+import { isAbsolute } from "node:path";
+import { parse, stringify } from "yaml";
+import { AGENT_OPERATION_META, ATTACHMENT_FILE_META } from "./contract.js";
+import { derivedOperationId } from "./operation.js";
+import { localAttachment, sendLocalConversationFile, uploadLocalAttachment } from "./original.js";
+import { KitRefusal } from "./refusal.js";
+
+class HouseRefused extends Error {
+  constructor(frame) {
+    super("kit_house_refused");
+    this.frame = frame;
+  }
+}
+
+function parsed(text) {
+  try {
+    return parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function answerOf(frame) {
+  if (frame.error !== undefined || frame.result?.isError === true) throw new HouseRefused(frame);
+  const text = (frame.result?.content ?? []).filter((item) => item.type === "text").map((item) => item.text).join("\n");
+  const answer = parsed(text);
+  if (answer === null || typeof answer !== "object") throw new KitRefusal("kit_house_answer_unreadable");
+  return answer;
+}
+
+function answered(frame, value) {
+  const text = stringify(value, { aliasDuplicateObjects: false, lineWidth: 0 });
+  return { jsonrpc: "2.0", id: frame.id, result: { content: [{ type: "text", text }] } };
+}
+
+function declaring(frame, meta) {
+  return { ...frame, params: { ...frame.params, _meta: { ...frame.params._meta, ...meta } } };
+}
+
+function saved(answer) {
+  if (answer.save.status !== "saved") {
+    throw new KitRefusal("attachment_upload_failed", answer.upload_failure ?? answer.save.failure ?? answer.save.status);
+  }
+  return answer;
+}
+
+async function declaredFile(frame) {
+  const path = frame.params.arguments?.path;
+  if (typeof path !== "string" || !isAbsolute(path)) throw new KitRefusal("kit_house_arguments_invalid", "path");
+  const local = await localAttachment(path, derivedOperationId(frame.params._meta[AGENT_OPERATION_META], "version"));
+  return { local, declared: declaring(frame, { [ATTACHMENT_FILE_META]: local.file }) };
+}
+
+async function stored(frame, call, dependencies, signal) {
+  const { local, declared } = await declaredFile(frame);
+  const requested = async () => answerOf(await call(declared));
+  return saved(await uploadLocalAttachment(requested, local, dependencies, signal));
+}
+
+async function sent(frame, call, dependencies, signal) {
+  const { local, declared } = await declaredFile(frame);
+  const admitted = await call(declared);
+  const answer = answerOf(admitted);
+  if (answer.save === undefined) return admitted;
+  saved(await sendLocalConversationFile(async () => answer, local, dependencies, signal));
+  const operation = derivedOperationId(frame.params._meta[AGENT_OPERATION_META], "send");
+  return call(declaring(declared, { [AGENT_OPERATION_META]: operation }));
+}
+
+async function appended(frame, call, dependencies, signal) {
+  const args = frame.params.arguments;
+  const operation = frame.params._meta[AGENT_OPERATION_META];
+  const attachments = [];
+  for (const [position, path] of args.attachments.entries()) {
+    const upload = {
+      ...frame,
+      params: {
+        name: "upload_attachment",
+        arguments: { path, room_ref: args.room_ref },
+        _meta: { ...frame.params._meta, [AGENT_OPERATION_META]: derivedOperationId(operation, `attachment/${position}`) },
+      },
+    };
+    attachments.push((await stored(upload, call, dependencies, signal)).attachment);
+  }
+  return call({ ...frame, params: { ...frame.params, arguments: { ...args, attachments } } });
+}
+
+function operated(frame) {
+  return typeof frame.params?._meta?.[AGENT_OPERATION_META] === "string";
+}
+
+function attaches(frame) {
+  const args = frame.params?.arguments;
+  return frame.params?.name === "append_record" && Array.isArray(args?.attachments) && typeof args.room_ref === "string";
+}
+
+export function localFiles(call, dependencies, signal) {
+  return async (frame) => {
+    if (frame.method !== "tools/call" || !operated(frame)) return call(frame);
+    try {
+      if (frame.params.name === "upload_attachment") {
+        return frame.params.arguments?.conversation === true
+          ? await sent(frame, call, dependencies, signal)
+          : answered(frame, await stored(frame, call, dependencies, signal));
+      }
+      if (attaches(frame)) return await appended(frame, call, dependencies, signal);
+    } catch (refusal) {
+      if (refusal instanceof HouseRefused) return refusal.frame;
+      throw refusal;
+    }
+    return call(frame);
+  };
+}