@agentshouse/kit 0.0.1 → 0.1.0-alpha.1

package/src/terminal.js

@@ -0,0 +1,57 @@
+import {
+  EXECUTION_FAILURE_CAUSE_MAX,
+  EXECUTION_OUTCOMES,
+  PROVIDER_CAPACITY_EXHAUSTED,
+  PROVIDER_CONTINUATION_UNAVAILABLE,
+  PROVIDER_REFUSED,
+} from "./contract.js";
+
+export function reportedCause(failure) {
+  const named =
+    failure.detail === null || failure.detail === undefined
+      ? failure.code
+      : `${failure.code}: ${failure.detail}`;
+  return named.slice(0, EXECUTION_FAILURE_CAUSE_MAX);
+}
+
+export function failedReport(failure) {
+  return { outcome: "failed", cause: reportedCause(failure) };
+}
+
+export function terminalReport(observed) {
+  if (observed.capacityExhausted) {
+    return { outcome: "failed", cause: PROVIDER_CAPACITY_EXHAUSTED };
+  }
+  if (observed.providerRefused) {
+    return { outcome: "failed", cause: PROVIDER_REFUSED };
+  }
+  if (observed.failure !== null && observed.failure !== undefined) {
+    return failedReport(observed.failure);
+  }
+  if (observed.turnCompleted && !observed.conversation) return { outcome: "completed", cause: null };
+  if (observed.continuable) return null;
+  return { outcome: "failed", cause: PROVIDER_CONTINUATION_UNAVAILABLE };
+}
+
+export function reportedNote(reported) {
+  return { operation: reported.operation, outcome: reported.outcome, cause: reported.cause };
+}
+
+export function retainedReport(stored) {
+  if (stored === null || stored === undefined) return null;
+  if (typeof stored !== "object" || Array.isArray(stored)) return undefined;
+  if (typeof stored.operation !== "string" || stored.operation.length === 0) return undefined;
+  if (!EXECUTION_OUTCOMES.includes(stored.outcome)) return undefined;
+  if (stored.outcome === "completed") {
+    if (stored.cause !== null) return undefined;
+    return { operation: stored.operation, outcome: stored.outcome, cause: null };
+  }
+  if (
+    typeof stored.cause !== "string" ||
+    stored.cause.length === 0 ||
+    stored.cause.length > EXECUTION_FAILURE_CAUSE_MAX
+  ) {
+    return undefined;
+  }
+  return { operation: stored.operation, outcome: stored.outcome, cause: stored.cause };
+}

package/src/tmux.js

@@ -0,0 +1,119 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { runCommand, withoutHouseCredentials } from "./command.js";
+import { TMUX_COMMAND_TIMEOUT_MS, TMUX_SUPPORTED_MINIMUM } from "./contract.js";
+import { KitRefusal } from "./refusal.js";
+
+const VERSION_LINE = /^tmux (?:next-)?(\d+)\.(\d+)/;
+const SESSION_NAME = /^[a-f0-9]{16}$/;
+
+const PREREQUISITE =
+  `the Environment owner must install tmux ${TMUX_SUPPORTED_MINIMUM} or newer and make it reachable on PATH; ` +
+  "House Kit never installs, upgrades, or replaces tmux";
+
+function parsedVersion(line) {
+  const found = VERSION_LINE.exec(line.trim());
+  return found === null ? null : [Number(found[1]), Number(found[2])];
+}
+
+const REQUIRED_VERSION = parsedVersion(`tmux ${TMUX_SUPPORTED_MINIMUM}`);
+
+const NAMESPACE_CONFIGURATION = "set-option -g -w remain-on-exit off\n";
+
+export function tmuxNamespace(directory) {
+  return `house-kit-${createHash("sha256").update(directory).digest("hex").slice(0, 16)}`;
+}
+
+export function workerRuntime(directory, tmux) {
+  return {
+    tmux,
+    namespace: tmuxNamespace(directory),
+    configuration: join(directory, "tmux", "namespace.conf"),
+  };
+}
+
+export function workerSessionName() {
+  return randomBytes(8).toString("hex");
+}
+
+function namespaced(runtime, args) {
+  return runCommand({
+    command: [runtime.tmux, "-L", runtime.namespace, "-f", runtime.configuration, ...args],
+    environment: {},
+    stdin: "",
+    timeoutMs: TMUX_COMMAND_TIMEOUT_MS,
+  });
+}
+
+export async function readyTmux(runtime) {
+  let reported;
+  try {
+    reported = await runCommand({
+      command: [runtime.tmux, "-V"],
+      environment: {},
+      stdin: "",
+      timeoutMs: TMUX_COMMAND_TIMEOUT_MS,
+    });
+  } catch (refusal) {
+    if (refusal instanceof KitRefusal && refusal.code === "kit_command_unavailable") {
+      throw new KitRefusal("kit_tmux_unavailable", PREREQUISITE);
+    }
+    throw refusal;
+  }
+  if (reported.status !== 0) throw new KitRefusal("kit_tmux_unavailable", PREREQUISITE);
+  const found = parsedVersion(reported.stdout);
+  if (found === null) {
+    throw new KitRefusal(
+      "kit_tmux_unsupported",
+      `this Environment reports "${reported.stdout.trim()}"; ${PREREQUISITE}`,
+    );
+  }
+  if (found[0] < REQUIRED_VERSION[0] || (found[0] === REQUIRED_VERSION[0] && found[1] < REQUIRED_VERSION[1])) {
+    throw new KitRefusal(
+      "kit_tmux_unsupported",
+      `this Environment has tmux ${found[0]}.${found[1]}; ${PREREQUISITE}`,
+    );
+  }
+  await mkdir(join(runtime.configuration, ".."), { recursive: true, mode: 0o700 });
+  await writeFile(runtime.configuration, NAMESPACE_CONFIGURATION, { mode: 0o600 });
+  return `${found[0]}.${found[1]}`;
+}
+
+export async function createSession(runtime, options) {
+  if (!SESSION_NAME.test(options.session)) {
+    throw new KitRefusal("kit_tmux_session_invalid", options.session);
+  }
+  const environment = Object.entries(withoutHouseCredentials(options.environment)).flatMap(
+    ([name, value]) => ["-e", `${name}=${value}`],
+  );
+  const created = await namespaced(runtime, [
+    "new-session",
+    "-d",
+    "-s",
+    options.session,
+    "-c",
+    options.workingDirectory,
+    ...environment,
+    "--",
+    ...options.command,
+  ]);
+  if (created.status !== 0) {
+    throw new KitRefusal("kit_tmux_session_refused", created.stderr.trim() || null);
+  }
+  return options.session;
+}
+
+export async function sessionPresent(runtime, session) {
+  const asked = await namespaced(runtime, ["has-session", "-t", `=${session}`]);
+  return asked.status === 0;
+}
+
+export async function destroySession(runtime, session) {
+  const killed = await namespaced(runtime, ["kill-session", "-t", `=${session}`]);
+  if (killed.status === 0) return true;
+  if (await sessionPresent(runtime, session)) {
+    throw new KitRefusal("kit_tmux_session_persistent", session);
+  }
+  return false;
+}