@agentshouse/kit 0.1.0-alpha.9 → 0.2.1-alpha.1

package/src/google/source.js

@@ -1,25 +0,0 @@
-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

@@ -1,376 +0,0 @@
-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

@@ -1,121 +0,0 @@
-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

@@ -1,79 +0,0 @@
-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;
-  },
-);