@agentshouse/kit 0.0.1 → 0.1.0-alpha.1

package/src/google/source.js

@@ -0,0 +1,25 @@
+import { KitRefusal } from "../refusal.js";
+import { gmailPage } from "./gmail.js";
+import { calendarPage } from "./calendar.js";
+import { drivePage } from "./drive.js";
+import { declaredPage } from "./declared.js";
+
+export async function googlePage(options, dependencies = {}) {
+  const common = {
+    directory: options.directory,
+    instance: options.instance,
+    client: options.client,
+    selection: options.service.selection,
+    cursor: options.cursor,
+    limit: options.limit,
+    backfillFloor: options.backfillFloor,
+    signal: options.signal,
+  };
+  if (options.service.service === "gmail") return gmailPage(common, dependencies);
+  if (options.service.service === "calendar") return calendarPage(common, dependencies);
+  if (options.service.service === "drive") return drivePage(common, dependencies);
+  if (options.service.declaration !== null) {
+    return declaredPage({ ...common, service: options.service }, dependencies);
+  }
+  throw new KitRefusal("google_service_unsupported", options.service.service);
+}

package/src/hook.js

@@ -0,0 +1,376 @@
+import { readFile, readdir, readlink, rm, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { DECLARED_ID } from "./contract.js";
+import { declarationReader } from "./declaration.js";
+import { KitRefusal } from "./refusal.js";
+import { readNote, writeNote, writeText } from "./state.js";
+
+const SESSION_START_EVENT = "SessionStart";
+const HOOK_INSTRUCTION_MAX = 16 * 1024;
+const SETTINGS_MODE = 0o600;
+const LINK_BUDGET = 32;
+
+const { refuse, closed, text } = declarationReader("kit_hook_rejected");
+
+function servedSessionStartHook(value) {
+  const served = closed(value, ["id", "version", "event", "instruction"], "session_start_hook");
+  const id = text(served.id, "session_start_hook.id", 128);
+  if (!DECLARED_ID.test(id)) refuse("session_start_hook.id");
+  if (served.event !== SESSION_START_EVENT) refuse("session_start_hook.event");
+  return {
+    id,
+    version: text(served.version, "session_start_hook.version", 64),
+    event: SESSION_START_EVENT,
+    instruction: text(served.instruction, "session_start_hook.instruction", HOOK_INSTRUCTION_MAX),
+  };
+}
+
+function hooksNamespace(directory) {
+  return join(directory, "state", "hooks");
+}
+
+function recordPath(directory) {
+  return join(directory, "state", "hooks.json");
+}
+
+function shellQuoted(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function instructionCommand(path) {
+  return `cat ${shellQuoted(path)}`;
+}
+
+function active(signal) {
+  if (signal?.aborted === true) throw new KitRefusal("kit_command_cancelled");
+}
+
+function plainDocument(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function pathSegments(path) {
+  return path.split(sep).filter((segment) => segment.length > 0);
+}
+
+async function linkTarget(path, declared) {
+  try {
+    return await readlink(path);
+  } catch (error) {
+    if (error.code === "EINVAL" || error.code === "ENOENT" || error.code === "ENOTDIR") return null;
+    throw new KitRefusal("kit_client_settings_unreadable", declared);
+  }
+}
+
+async function canonicalPath(declared) {
+  let remaining = pathSegments(resolve(declared));
+  let resolved = sep;
+  let links = LINK_BUDGET;
+  while (remaining.length > 0) {
+    const segment = remaining.shift();
+    if (segment === ".") continue;
+    if (segment === "..") {
+      resolved = dirname(resolved);
+      continue;
+    }
+    const candidate = join(resolved, segment);
+    const target = await linkTarget(candidate, declared);
+    if (target === null) {
+      resolved = candidate;
+      continue;
+    }
+    links -= 1;
+    if (links < 0) throw new KitRefusal("kit_client_settings_refused", declared);
+    remaining = [...pathSegments(target), ...remaining];
+    if (isAbsolute(target)) resolved = sep;
+  }
+  return resolved;
+}
+
+function within(path, root) {
+  return path === root || path.startsWith(`${root}${sep}`);
+}
+
+async function declaredDestination(installation, client, taken) {
+  const path = await canonicalPath(client.settings);
+  if (within(path, installation.home) || path === installation.configuration || taken.has(path)) {
+    throw new KitRefusal("kit_client_settings_refused", client.settings);
+  }
+  taken.add(path);
+  return { kind: client.kind, declared: client.settings, path, desired: true };
+}
+
+async function recordedDestination(installation, recorded) {
+  const path = await canonicalPath(recorded.path);
+  if (path !== recorded.path || within(path, installation.home)) {
+    throw new KitRefusal("kit_client_settings_refused", recorded.path);
+  }
+  return { kind: null, declared: recorded.path, path, desired: false };
+}
+
+function hookSections(document, declared) {
+  const hooks = document.hooks === undefined ? {} : document.hooks;
+  if (!plainDocument(hooks)) throw new KitRefusal("kit_client_settings_unreadable", declared);
+  const groups = hooks[SESSION_START_EVENT] === undefined ? [] : hooks[SESSION_START_EVENT];
+  if (!Array.isArray(groups)) throw new KitRefusal("kit_client_settings_unreadable", declared);
+  return { hooks, groups };
+}
+
+function identityOf(status) {
+  return { device: status.dev, node: status.ino };
+}
+
+async function readSettings(destination) {
+  let status;
+  try {
+    status = await stat(destination.path);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { document: {}, contents: null, mode: SETTINGS_MODE, identity: null, present: false };
+    }
+    throw new KitRefusal("kit_client_settings_unreadable", destination.declared);
+  }
+  if (!status.isFile()) throw new KitRefusal("kit_client_settings_refused", destination.declared);
+  let stored;
+  try {
+    stored = await readFile(destination.path, "utf8");
+  } catch {
+    throw new KitRefusal("kit_client_settings_unreadable", destination.declared);
+  }
+  let document;
+  try {
+    document = JSON.parse(stored);
+  } catch {
+    throw new KitRefusal("kit_client_settings_unreadable", destination.declared);
+  }
+  if (!plainDocument(document)) {
+    throw new KitRefusal("kit_client_settings_unreadable", destination.declared);
+  }
+  hookSections(document, destination.declared);
+  return {
+    document,
+    contents: stored,
+    mode: status.mode & 0o777,
+    identity: identityOf(status),
+    present: true,
+  };
+}
+
+async function prepared(destination, guard) {
+  const path = await canonicalPath(destination.declared);
+  if (path !== destination.path || within(path, guard.home) || path === guard.configuration) {
+    return false;
+  }
+  let status = null;
+  try {
+    status = await stat(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") return false;
+  }
+  if (status === null) return !destination.present;
+  return (
+    destination.present &&
+    status.isFile() &&
+    status.dev === destination.identity.device &&
+    status.ino === destination.identity.node
+  );
+}
+
+async function readRecord(directory) {
+  const path = recordPath(directory);
+  const stored = await readNote(path, null);
+  if (stored === null) return [];
+  const unreadable = () => {
+    throw new KitRefusal("kit_state_unreadable", path);
+  };
+  if (!plainDocument(stored) || !Array.isArray(stored.destinations)) unreadable();
+  return stored.destinations.map((entry) => {
+    if (!plainDocument(entry) || typeof entry.settings !== "string") unreadable();
+    if (!Array.isArray(entry.commands)) unreadable();
+    if (entry.commands.some((command) => typeof command !== "string")) unreadable();
+    return { path: entry.settings, commands: entry.commands };
+  });
+}
+
+function recordOf(destinations) {
+  return {
+    destinations: destinations.map((destination) => ({
+      settings: destination.path,
+      commands: [...destination.commands],
+    })),
+  };
+}
+
+function sameRecord(one, other) {
+  return JSON.stringify(one) === JSON.stringify(other);
+}
+
+function ownedEntry(entry, commands) {
+  return (
+    plainDocument(entry) &&
+    entry.type === "command" &&
+    typeof entry.command === "string" &&
+    commands.has(entry.command)
+  );
+}
+
+function keptGroup(group, commands) {
+  if (!plainDocument(group) || !Array.isArray(group.hooks)) return group;
+  const kept = group.hooks.filter((entry) => !ownedEntry(entry, commands));
+  if (kept.length === group.hooks.length) return group;
+  if (kept.length === 0) return null;
+  return { ...group, hooks: kept };
+}
+
+function reconciledSettings(destination, command) {
+  const settings = destination.document;
+  const { hooks, groups: declared } = hookSections(settings, destination.declared);
+  const kept = declared
+    .map((group) => keptGroup(group, destination.commands))
+    .filter((group) => group !== null);
+  const groups =
+    command === null ? kept : [...kept, { hooks: [{ type: "command", command }] }];
+  if (groups.length > 0) {
+    return { ...settings, hooks: { ...hooks, [SESSION_START_EVENT]: groups } };
+  }
+  const { [SESSION_START_EVENT]: _sessionStart, ...remaining } = hooks;
+  if (Object.keys(remaining).length > 0) return { ...settings, hooks: remaining };
+  const { hooks: _hooks, ...document } = settings;
+  return document;
+}
+
+function instructionPath(directory, id) {
+  return join(hooksNamespace(directory), `${id}.txt`);
+}
+
+async function pruneInstructions(directory, hook, signal) {
+  active(signal);
+  const namespace = hooksNamespace(directory);
+  if (hook === null) {
+    await rm(namespace, { recursive: true, force: true });
+    return;
+  }
+  const current = `${hook.id}.txt`;
+  for (const present of await readdir(namespace)) {
+    if (present !== current) await rm(join(namespace, present), { recursive: true });
+  }
+}
+
+async function restored(written) {
+  const unrestored = [];
+  for (const target of [...written].reverse()) {
+    try {
+      if (target.present) await writeText(target.path, target.contents, undefined, target.mode);
+      else await rm(target.path, { force: true });
+    } catch {
+      unrestored.push(target.path);
+    }
+  }
+  if (unrestored.length > 0) {
+    throw new KitRefusal("kit_client_settings_unrestored", unrestored.join(" "));
+  }
+}
+
+async function writeSettings(targets, guard, signal) {
+  const written = [];
+  try {
+    for (const target of targets) {
+      if (!target.desired && !target.present) continue;
+      active(signal);
+      if (!(await prepared(target, guard))) {
+        throw new KitRefusal("kit_client_settings_refused", target.declared);
+      }
+      await writeNote(target.path, target.next, signal, target.mode);
+      written.push(target);
+    }
+  } catch (error) {
+    await restored(written);
+    throw error;
+  }
+}
+
+async function writeReconciliation(plan, targets, hook, command, signal) {
+  const { directory, recorded, guard } = plan;
+  const intent = recordOf(targets);
+  if (!sameRecord(intent, recordOf(recorded))) {
+    active(signal);
+    await writeNote(recordPath(directory), intent, signal);
+  }
+  if (hook !== null) {
+    active(signal);
+    await writeText(instructionPath(directory, hook.id), `${hook.instruction}\n`, signal);
+  }
+  await writeSettings(targets, guard, signal);
+  const desired = targets.filter((target) => target.desired);
+  active(signal);
+  if (desired.length === 0) {
+    await rm(recordPath(directory), { force: true });
+  } else {
+    await writeNote(
+      recordPath(directory),
+      recordOf(desired.map((target) => ({ path: target.path, commands: new Set([command]) }))),
+      signal,
+    );
+  }
+  await pruneInstructions(directory, hook, signal);
+}
+
+export async function planSessionStartHook(installation, clients, signal) {
+  const recorded = await readRecord(installation.directory);
+  const plan = {
+    directory: installation.directory,
+    declared: clients.length,
+    recorded,
+    targets: [],
+    guard: null,
+  };
+  if (clients.length === 0 && recorded.length === 0) return plan;
+  const home = await canonicalPath(installation.directory);
+  const configuration = await canonicalPath(installation.configuration);
+  plan.guard = { home, configuration };
+  const taken = new Set();
+  const destinations = new Map();
+  for (const client of clients) {
+    active(signal);
+    const destination = await declaredDestination({ home, configuration }, client, taken);
+    destinations.set(destination.path, { ...destination, commands: new Set() });
+  }
+  for (const entry of recorded) {
+    active(signal);
+    if (!destinations.has(entry.path)) {
+      const destination = await recordedDestination({ home }, entry);
+      destinations.set(destination.path, { ...destination, commands: new Set() });
+    }
+    const known = destinations.get(entry.path);
+    for (const previous of entry.commands) known.commands.add(previous);
+  }
+  plan.targets = [...destinations.values()];
+  for (const target of plan.targets) {
+    active(signal);
+    Object.assign(target, await readSettings(target));
+  }
+  return plan;
+}
+
+export async function commitSessionStartHook(plan, served, signal) {
+  if (plan.declared === 0 && plan.recorded.length === 0) return { installed: [], removed: [] };
+  const hook = plan.declared === 0 ? null : servedSessionStartHook(served);
+  const command =
+    hook === null ? null : instructionCommand(instructionPath(plan.directory, hook.id));
+  for (const target of plan.targets) {
+    if (target.desired && command !== null) target.commands.add(command);
+    target.next = reconciledSettings(target, target.desired ? command : null);
+  }
+  await writeReconciliation(plan, plan.targets, hook, command, signal);
+  return {
+    installed: plan.targets
+      .filter((target) => target.desired)
+      .map((target) => ({
+        kind: target.kind,
+        settings: target.declared,
+        id: hook.id,
+        version: hook.version,
+      })),
+    removed: plan.targets.filter((target) => !target.desired).map((target) => target.path),
+  };
+}

package/src/host.js

@@ -0,0 +1,121 @@
+import { readFile, statfs } from "node:fs/promises";
+import { readConfiguration } from "./configuration.js";
+import { HOST_CPU_SAMPLE_MS } from "./contract.js";
+import { openSession, reportHostCapacity } from "./house.js";
+import { KitRefusal } from "./refusal.js";
+
+const PROC_STAT = "/proc/stat";
+const PROC_MEMINFO = "/proc/meminfo";
+const PROCESSOR_LINE = /^cpu[0-9]+\s/;
+const AGGREGATE_LINE = /^cpu\s+(.*)$/;
+const MEMINFO_LINE = /^(\w+):\s+(\d+)\s+kB$/;
+
+function unmeasurable(source) {
+  throw new KitRefusal("kit_host_unmeasurable", source);
+}
+
+async function readSource(read, path) {
+  try {
+    return await read(path);
+  } catch {
+    return unmeasurable(path);
+  }
+}
+
+function processorTime(document) {
+  const lines = document.split("\n");
+  const aggregate = lines.map((line) => AGGREGATE_LINE.exec(line)).find((match) => match !== null);
+  if (aggregate === null || aggregate === undefined) unmeasurable(PROC_STAT);
+  const fields = aggregate[1].trim().split(/\s+/).slice(0, 8).map(Number);
+  if (fields.length < 5 || fields.some((field) => !Number.isFinite(field))) {
+    unmeasurable(PROC_STAT);
+  }
+  const processors = lines.filter((line) => PROCESSOR_LINE.test(line)).length;
+  if (processors === 0) unmeasurable(PROC_STAT);
+  return {
+    processors,
+    busy: fields.reduce((total, field) => total + field, 0) - fields[3] - fields[4],
+    idle: fields[3] + fields[4],
+  };
+}
+
+async function processors(read, wait) {
+  const first = processorTime(await readSource(read, PROC_STAT));
+  await wait(HOST_CPU_SAMPLE_MS);
+  const second = processorTime(await readSource(read, PROC_STAT));
+  const elapsed = second.busy + second.idle - first.busy - first.idle;
+  if (elapsed <= 0 || second.processors !== first.processors) unmeasurable(PROC_STAT);
+  const total = second.processors * 1000;
+  const used = Math.min(total, Math.round(((second.busy - first.busy) / elapsed) * total));
+  return { total, used, available: total - used };
+}
+
+function memory(document) {
+  const named = new Map(
+    document
+      .split("\n")
+      .map((line) => MEMINFO_LINE.exec(line))
+      .filter((match) => match !== null)
+      .map((match) => [match[1], Number(match[2]) * 1024]),
+  );
+  const total = named.get("MemTotal");
+  const available = named.get("MemAvailable");
+  if (total === undefined || available === undefined || total < 1 || available > total) {
+    unmeasurable(PROC_MEMINFO);
+  }
+  return { total, used: total - available, available };
+}
+
+function workspaceDisk(path, statistics) {
+  const total = statistics.blocks * statistics.bsize;
+  const used = (statistics.blocks - statistics.bfree) * statistics.bsize;
+  const available = statistics.bavail * statistics.bsize;
+  if (!Number.isSafeInteger(total) || total < 1 || used < 0 || available > total) {
+    unmeasurable(path);
+  }
+  return { path, total, used, available };
+}
+
+export async function measureHost(workspace, dependencies = {}) {
+  const read = dependencies.readFile ?? ((path) => readFile(path, "utf8"));
+  const statistics = dependencies.statfs ?? statfs;
+  const wait = dependencies.wait ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = dependencies.now ?? (() => new Date());
+  const cpu = await processors(read, wait);
+  const ram = memory(await readSource(read, PROC_MEMINFO));
+  let filesystem;
+  try {
+    filesystem = await statistics(workspace);
+  } catch {
+    return unmeasurable(workspace);
+  }
+  return {
+    observed_at: now().toISOString(),
+    cpu,
+    memory: ram,
+    disk: workspaceDisk(workspace, filesystem),
+  };
+}
+
+function declaredMaxima(maxima) {
+  return {
+    ...(maxima.cpuMillicores === null ? {} : { cpu_millicores: maxima.cpuMillicores }),
+    ...(maxima.memoryBytes === null ? {} : { memory_bytes: maxima.memoryBytes }),
+    ...(maxima.diskBytes === null ? {} : { disk_bytes: maxima.diskBytes }),
+  };
+}
+
+export async function reportHost(options, dependencies = {}) {
+  const configuration = await readConfiguration(options.configuration);
+  if (configuration.host === null) {
+    throw new KitRefusal("kit_host_unconfigured", options.configuration);
+  }
+  const observed = await measureHost(configuration.host.workspace, dependencies);
+  const declaration =
+    configuration.host.maxima === null
+      ? observed
+      : { ...observed, maxima: declaredMaxima(configuration.host.maxima) };
+  const session = await openSession(options, dependencies);
+  await reportHostCapacity(session, declaration);
+  return declaration;
+}

package/src/house-main.js

@@ -0,0 +1,79 @@
+import { resolve } from "node:path";
+import { BRIDGE_NONCE_ENVIRONMENT, BRIDGE_SOCKET_ENVIRONMENT } from "./contract.js";
+import { bridgeCall } from "./mcp.js";
+import { KitRefusal } from "./refusal.js";
+
+const HELP = ["--help", "-h"];
+const usage = (verb) => `usage: house ${verb} ['<arguments as one JSON object>' | - for standard input]`;
+
+async function answered(method, params) {
+  const socket = process.env[BRIDGE_SOCKET_ENVIRONMENT];
+  const nonce = process.env[BRIDGE_NONCE_ENVIRONMENT];
+  if (socket === undefined || nonce === undefined) throw new KitRefusal("kit_bridge_unavailable");
+  const frame = await bridgeCall({ socket, nonce }, { method, params });
+  if (frame.error !== undefined) throw new KitRefusal(frame.error.message ?? "kit_house_refused");
+  return frame.result;
+}
+
+async function listed() {
+  const tools = (await answered("tools/list", {}))?.tools;
+  if (!Array.isArray(tools)) throw new KitRefusal("kit_house_listing_unreadable");
+  return tools;
+}
+
+async function standardInput() {
+  let text = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) text += chunk;
+  return text;
+}
+
+async function argumentsOf(verb, text) {
+  if (text === undefined) return {};
+  let parsed = null;
+  try {
+    parsed = JSON.parse(text === "-" ? await standardInput() : text);
+  } catch {}
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new KitRefusal("kit_house_arguments_invalid", usage(verb));
+  }
+  return parsed;
+}
+
+function located(verb, args) {
+  const local = (path) => (typeof path === "string" ? resolve(path) : path);
+  if (verb === "upload_attachment") return { ...args, path: local(args.path) };
+  if (verb === "append_record" && Array.isArray(args.attachments)) {
+    return { ...args, attachments: args.attachments.map(local) };
+  }
+  return args;
+}
+
+async function house([verb, argument, ...rest]) {
+  if (verb === undefined || HELP.includes(verb)) {
+    const tools = await listed();
+    return { out: [usage("<verb>"), ...tools.map((tool) => `${tool.name}\n${tool.description}`)].join("\n\n") };
+  }
+  if (HELP.includes(argument)) {
+    const tool = (await listed()).find((one) => one.name === verb);
+    if (tool === undefined) throw new KitRefusal("kit_house_verb_unknown", verb);
+    return { out: [usage(verb), tool.description, JSON.stringify(tool.inputSchema, null, 2)].join("\n\n") };
+  }
+  if (rest.length > 0) throw new KitRefusal("kit_house_arguments_invalid", usage(verb));
+  const args = located(verb, await argumentsOf(verb, argument));
+  const result = await answered("tools/call", { name: verb, arguments: args });
+  const text = (result?.content ?? []).filter((item) => item.type === "text").map((item) => item.text).join("\n");
+  return result?.isError === true ? { err: text, status: 1 } : { out: text };
+}
+
+house(process.argv.slice(2)).then(
+  ({ out, err, status = 0 }) => {
+    if (out !== undefined) process.stdout.write(`${out}\n`);
+    if (err !== undefined) process.stderr.write(`${err}\n`);
+    process.exitCode = status;
+  },
+  (refusal) => {
+    process.stderr.write(`${refusal instanceof Error ? refusal.message : "kit_house_failed"}\n`);
+    process.exitCode = 1;
+  },
+);