@agentshouse/kit 0.0.1 → 0.1.0-alpha.1

package/src/connector.js

@@ -0,0 +1,107 @@
+import { isAbsolute } from "node:path";
+import {
+  ITEM_ATTACHMENTS_MAX,
+  ITEM_BODY_MAX_BYTES,
+  KIT_CONTRACT_VERSION,
+  ORIGINAL_NAME_MAX,
+} from "./contract.js";
+import { declarationReader } from "./declaration.js";
+import { originalDescriptor } from "./original.js";
+import { KitRefusal } from "./refusal.js";
+
+const NAMESPACE = /^[a-z0-9][a-z0-9._-]*(\/[a-z0-9][a-z0-9._-]*)*$/;
+const OBSERVED_AT = /^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d{1,6})?Z$/;
+const ITEM_FIELDS = [
+  "type",
+  "namespace",
+  "native_object_id",
+  "native_version",
+  "observed_at",
+  "body",
+  "author",
+  "url",
+  "attachments",
+];
+const ATTACHMENT_FIELDS = ["url", "file", "name"];
+const FILE_FIELDS = ["path", "bytes", "sha256", "media_type"];
+
+const { refuse, closed, text, optionalText } = declarationReader("kit_connector_line_invalid");
+
+function attachmentsOf(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > ITEM_ATTACHMENTS_MAX) refuse("attachments");
+  return value.map((entry) => {
+    const attachment = closed(entry, ATTACHMENT_FIELDS, "attachments");
+    const name = optionalText(attachment.name, "attachments.name", 512);
+    const named = name === null ? {} : { name };
+    if (attachment.file === undefined) {
+      return { url: text(attachment.url, "attachments.url", 2048), ...named };
+    }
+    if (attachment.url !== undefined) refuse("attachments");
+    if (name !== null && name.length > ORIGINAL_NAME_MAX) refuse("attachments.name");
+    const file = closed(attachment.file, FILE_FIELDS, "attachments.file");
+    const path = text(file.path, "attachments.file.path", 4096);
+    if (!isAbsolute(path)) refuse("attachments.file.path");
+    let descriptor;
+    try {
+      descriptor = originalDescriptor(file);
+    } catch {
+      refuse("attachments.file");
+    }
+    return { file: { path, ...descriptor }, ...named };
+  });
+}
+
+function itemOf(line) {
+  const namespace = text(line.namespace, "namespace", 128);
+  if (!NAMESPACE.test(namespace)) refuse("namespace");
+  const observedAt = text(line.observed_at, "observed_at", 64);
+  if (!OBSERVED_AT.test(observedAt) || Number.isNaN(Date.parse(observedAt))) refuse("observed_at");
+  if (typeof line.body !== "string" || Buffer.byteLength(line.body, "utf8") > ITEM_BODY_MAX_BYTES) {
+    refuse("body");
+  }
+  return {
+    namespace,
+    nativeObjectId: text(line.native_object_id, "native_object_id", 512),
+    nativeVersion: optionalText(line.native_version, "native_version", 256),
+    observedAt,
+    body: line.body,
+    author: optionalText(line.author, "author", 512),
+    url: optionalText(line.url, "url", 2048),
+    attachments: attachmentsOf(line.attachments),
+  };
+}
+
+export function connectorRequest(request) {
+  return `${JSON.stringify({
+    contract: KIT_CONTRACT_VERSION,
+    instance: request.instance,
+    cursor: request.cursor,
+    limit: request.limit,
+  })}\n`;
+}
+
+export function parseConnectorRun(stdout, limit) {
+  const lines = stdout.split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  const items = [];
+  let cursor = null;
+  for (const line of lines) {
+    if (cursor !== null) refuse("line after the terminal cursor");
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      refuse("line is not JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) refuse("line");
+    if (parsed.type === "cursor") {
+      cursor = text(closed(parsed, ["type", "cursor"], "cursor").cursor, "cursor", 2048);
+      continue;
+    }
+    if (parsed.type !== "item") refuse("type");
+    items.push(itemOf(closed(parsed, ITEM_FIELDS, "item")));
+  }
+  if (items.length > limit) throw new KitRefusal("kit_connector_limit_exceeded", `${items.length}`);
+  return { items, dropped: [], cursor, more: cursor !== null && items.length > 0 };
+}

package/src/continuation.js

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { KitRefusal } from "./refusal.js";
+import { readNote, writeNote } from "./state.js";
+
+function continuationDirectory(directory) {
+  return join(directory, "state", "continuations");
+}
+
+function continuationName(run) {
+  return `${createHash("sha256").update(run).digest("hex")}.json`;
+}
+
+function path(directory, run) {
+  return join(continuationDirectory(directory), continuationName(run));
+}
+
+export async function writeContinuation(directory, continuation) {
+  await writeNote(path(directory, continuation.run), { installation: directory, ...continuation });
+}
+
+export async function readContinuation(directory, run) {
+  const stored = await readNote(path(directory, run), null);
+  if (stored === null) return null;
+  if (stored.installation !== directory || stored.run !== run ||
+      typeof stored.conversation !== "boolean" ||
+      [stored.agentId, stored.workingDirectory, stored.routeId].some((value) => typeof value !== "string" || value.length === 0) ||
+      (stored.providerSessionId !== null && (typeof stored.providerSessionId !== "string" || stored.providerSessionId.length === 0 || stored.providerSessionId.length > 512))) {
+    throw new KitRefusal("kit_continuation_unreadable", run);
+  }
+  return stored;
+}
+
+export async function readContinuationRuns(directory) {
+  let present;
+  try {
+    present = await readdir(continuationDirectory(directory));
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw new KitRefusal("kit_state_unreadable", continuationDirectory(directory));
+  }
+  const runs = [];
+  for (const name of present.filter((entry) => entry.endsWith(".json")).sort()) {
+    let stored;
+    try {
+      stored = await readNote(join(continuationDirectory(directory), name), null);
+    } catch (refusal) {
+      if (!(refusal instanceof KitRefusal)) throw refusal;
+      continue;
+    }
+    if (stored?.installation !== directory || typeof stored.run !== "string") continue;
+    if (continuationName(stored.run) !== name) continue;
+    runs.push(stored.run);
+  }
+  return runs;
+}
+
+export async function removeContinuation(directory, run) {
+  await rm(path(directory, run), { force: true });
+}

package/src/contract.js

@@ -0,0 +1,363 @@
+import { CLAUDE_PASTED_CODE, CODEX_DEVICE_CODE, GROK_DEVICE_CODE } from "./agent-logins.js";
+
+export const KIT_CONTRACT_VERSION = "2026-09-26-house-agent-kinds";
+export const KIT_CAPTURE_BATCH_MAX = 100;
+export const COMMAND_INPUT_MAX_BYTES = 4 * 1024;
+export const AUTHORIZATION_OUTPUT_MAX_BYTES = 4 * 1024;
+export const CONNECTOR_OUTPUT_MAX_BYTES = 8 * 1024 * 1024;
+export const CONNECTOR_TIMEOUT_MS = 120_000;
+export const ITEM_BODY_MAX_BYTES = 1024 * 1024;
+export const ITEM_ATTACHMENTS_MAX = 32;
+export const DROPPED_ITEM_NOTES_MAX = 100;
+export const LEASE_RENEWAL_MARGIN_MS = CONNECTOR_TIMEOUT_MS + 60_000;
+export const KIT_CREDENTIAL = /^ahk_[A-Za-z0-9_-]+$/;
+export const DECLARED_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+export const TMUX_SUPPORTED_MINIMUM = "3.2";
+export const TMUX_COMMAND_TIMEOUT_MS = 10_000;
+export const COMMAND_ADAPTER_INITIALIZE_TIMEOUT_MS = 10_000;
+export const COMMAND_ADAPTER_SESSION_TIMEOUT_MS = 30_000;
+
+export const WORKER_EXIT_GRACE_MS = 5_000;
+export const WORKER_EXIT_POLL_MS = 100;
+export const WORKER_SUPERVISION_POLL_MS = 2_000;
+export const WORKER_COMMAND_POLL_MS = 2_000;
+export const WORKER_HEARTBEAT_MS = 30_000;
+export const WORKER_COMMAND_BATCH_MAX = 10;
+export const WORKER_RUN_TOKEN_MARGIN_MS = 60_000;
+export const TELEGRAM_IMAGE_UPLOAD_CEILING_BYTES = 10 * 1024 * 1024;
+export const CONVERSATION_FILE_TRANSFER_TIMEOUT_MS = 30_000;
+export const WORKER_INHERITED_ENVIRONMENT = ["PATH", "HOME"];
+export const WORKER_ATTACH_ENVIRONMENT = ["PATH", "HOME", "TERM"];
+
+export const EXECUTION_OUTCOMES = ["completed", "failed"];
+export const EXECUTION_FAILURE_CAUSE_MAX = 200;
+export const PROVIDER_CAPACITY_EXHAUSTED = "provider_capacity_exhausted";
+export const PROVIDER_REFUSED = "provider_refused";
+export const PROVIDER_CONTINUATION_UNAVAILABLE = "kit_provider_continuation_unavailable";
+
+export function runOutcomePath(run) {
+  return `/kit/runs/${encodeURIComponent(run)}/outcome`;
+}
+
+export const KIT_SESSIONS_REPORT_PATH = "/kit/sessions/report";
+export const KIT_SESSIONS_REPORT_MAX = 256;
+
+export const ASSISTANT_TEXT_MAX_BYTES = 4096;
+export const ASSISTANT_BLOCKS_MAX = 500;
+export const ASSISTANT_TABLE_COLUMNS_MAX = 20;
+
+export function assistantDraftsPath(workerSession) {
+  return `/kit/sessions/${encodeURIComponent(workerSession)}/drafts`;
+}
+
+export function assistantTextPath(workerSession) {
+  return `/kit/sessions/${encodeURIComponent(workerSession)}/assistant-messages`;
+}
+
+export const TELEGRAM_API_ORIGIN = "https://api.telegram.org";
+export const TELEGRAM_INGRESS_BATCH_MAX = 100;
+export const TELEGRAM_DELIVERY_BATCH_MAX = 10;
+export const TELEGRAM_DOWNLOAD_CEILING_BYTES = 20 * 1024 * 1024;
+export const TELEGRAM_BOT_API_TIMEOUT_MS = 30_000;
+export const TELEGRAM_GATEWAY_POLL_MS = 2_000;
+export const TELEGRAM_CONTROL_KEYBOARD_COMMANDS = ["/stop", "/kill"];
+export const TELEGRAM_MEDIA_KINDS = [
+  "document",
+  "photo",
+  "audio",
+  "video",
+  "voice",
+  "video_note",
+  "sticker",
+  "animation",
+];
+export const TELEGRAM_UNSUPPORTED_MEDIA_FIELDS = [
+  "contact",
+  "location",
+  "venue",
+  "poll",
+  "dice",
+  "game",
+  "invoice",
+  "successful_payment",
+];
+export const TELEGRAM_UPDATE_OUTCOMES = ["accepted", "duplicate", "refused"];
+export const TELEGRAM_DELIVERY_KINDS = [
+  "agent_choice",
+  "final_text",
+  "refusal",
+  "conversation_closed",
+  "control_reply",
+  "fresh_session_boundary",
+  "control_keyboard",
+  "interaction_card",
+  "plan",
+  "conversation_topic",
+  "conversation_file_link",
+];
+export const PERSONAL_BOT_TOKEN_RELATIVE_PATH = "secrets/personal-telegram-bot.token";
+export const PERSONAL_BOT_OFFSET_RELATIVE_PATH = "state/telegram/get-updates-offset.json";
+export const PERSONAL_BOT_DISCONNECT_RELATIVE_PATH = "state/telegram/disconnecting.json";
+
+export function telegramApiUrl(token, method) {
+  return `${TELEGRAM_API_ORIGIN}/bot${token}/${method}`;
+}
+
+export function telegramFileUrl(token, path) {
+  return `${TELEGRAM_API_ORIGIN}/file/bot${token}/${path}`;
+}
+
+export const BRIDGE_LINE_MAX_BYTES = 4 * 1024 * 1024;
+export const BRIDGE_SOCKET_ENVIRONMENT = "HOUSE_KIT_BRIDGE";
+export const BRIDGE_NONCE_ENVIRONMENT = "HOUSE_KIT_BRIDGE_NONCE";
+export const BRIDGE_RECONNECT_MS = 200;
+export const BRIDGE_RECONNECT_MAX_MS = 5_000;
+
+export const ACP_PROTOCOL = 1;
+export const ACP_AUTH_REQUIRED = -32000;
+export const ADAPTER_EXIT_GRACE_MS = 2_000;
+export const ELICITATION_FIELD_KINDS = Object.freeze([
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "array",
+]);
+export const TURN_OUTCOMES = Object.freeze(["completed", "interrupted", "refused", "exhausted"]);
+
+const PROTOCOL_STOP_REASONS = Object.freeze({
+  end_turn: "completed",
+  cancelled: "interrupted",
+  refusal: "refused",
+  max_tokens: "exhausted",
+  max_turn_requests: "exhausted",
+});
+
+export const ACP_CLIENT_INFO = Object.freeze({
+  name: "@agentshouse/kit",
+  version: KIT_CONTRACT_VERSION,
+});
+
+export const ACP_CLIENT_CAPABILITIES = Object.freeze({
+  fs: Object.freeze({ readTextFile: false, writeTextFile: false }),
+  terminal: false,
+  elicitation: Object.freeze({ form: Object.freeze({}) }),
+});
+
+export const ADAPTER_CONTRACTS = Object.freeze({
+  "codex-acp": Object.freeze({
+    kind: "codex-acp",
+    version: "2",
+    protocol: ACP_PROTOCOL,
+    release: Object.freeze({
+      package: "@agentclientprotocol/codex-acp",
+      minimum: "1.12.0",
+    }),
+    binary: "codex-acp",
+    arguments: Object.freeze([]),
+    settings: Object.freeze([
+      Object.freeze({
+        file: ".codex/config.toml",
+        setting: "tools.experimental_request_user_input.enabled",
+        value: "true",
+      }),
+    ]),
+    signIn: Object.freeze(["cli", "login", "--device-auth"]),
+    signedIn: Object.freeze(["cli", "login", "status"]),
+    guidedLogin: CODEX_DEVICE_CODE,
+    identity: Object.freeze({ agentInfo: "@agentclientprotocol/codex-acp" }),
+    nativeQuestion: null,
+    sessionLoad: true,
+    sessionConfig: Object.freeze({ model: "model", effort: "reasoning_effort" }),
+    capabilities: Object.freeze({
+      field_kinds: ELICITATION_FIELD_KINDS,
+      decline: true,
+      stop_reasons: Object.freeze({
+        ...PROTOCOL_STOP_REASONS,
+        [PROVIDER_CAPACITY_EXHAUSTED]: "exhausted",
+      }),
+    }),
+  }),
+  "claude-agent-acp": Object.freeze({
+    kind: "claude-agent-acp",
+    version: "1",
+    protocol: ACP_PROTOCOL,
+    release: Object.freeze({
+      package: "@agentclientprotocol/claude-agent-acp",
+      minimum: "0.79.0",
+    }),
+    binary: "claude-agent-acp",
+    arguments: Object.freeze([]),
+    settings: Object.freeze([]),
+    signIn: Object.freeze(["--cli", "auth", "login", "--claudeai"]),
+    signedIn: Object.freeze(["--cli", "auth", "status"]),
+    guidedLogin: CLAUDE_PASTED_CODE,
+    identity: Object.freeze({ agentInfo: "@agentclientprotocol/claude-agent-acp" }),
+    nativeQuestion: null,
+    sessionLoad: false,
+    sessionConfig: Object.freeze({ model: "model", effort: "effort" }),
+    capabilities: Object.freeze({
+      field_kinds: ELICITATION_FIELD_KINDS,
+      decline: true,
+      stop_reasons: PROTOCOL_STOP_REASONS,
+    }),
+  }),
+  "grok-build": Object.freeze({
+    kind: "grok-build",
+    version: "1",
+    protocol: ACP_PROTOCOL,
+    release: Object.freeze({
+      package: "@xai-official/grok",
+      minimum: "1.0.41",
+    }),
+    binary: "grok",
+    arguments: Object.freeze(["agent", "--no-leader", "stdio"]),
+    settings: Object.freeze([]),
+    signIn: Object.freeze(["login", "--device-auth"]),
+    signedIn: Object.freeze({ initializeMeta: "defaultAuthMethodId" }),
+    guidedLogin: GROK_DEVICE_CODE,
+    identity: Object.freeze({ initializeMeta: "grokShell", versionMeta: "agentVersion" }),
+    nativeQuestion: "x.ai/ask_user_question",
+    sessionLoad: true,
+    sessionConfig: Object.freeze({ model: "model", effort: "reasoning_effort" }),
+    capabilities: Object.freeze({
+      field_kinds: Object.freeze(["string", "array"]),
+      decline: false,
+      stop_reasons: Object.freeze({
+        end_turn: "completed",
+        cancelled: "interrupted",
+      }),
+    }),
+  }),
+});
+
+export const ADAPTER_KINDS = Object.freeze(Object.keys(ADAPTER_CONTRACTS));
+
+export const KIT_AGENTS_REPORT_PATH = "/kit/agents/report";
+export const KIT_AGENTS_DESIRED_PATH = "/kit/agents/desired";
+export const AGENT_HOME = "agents";
+export const AGENT_STATE_FILE = "state.json";
+export const AGENT_RELEASES_HOME = "releases";
+export const AGENT_UPDATE_INTERVAL_MS = 6 * 60 * 60 * 1000;
+export const AGENT_INSTALL_TIMEOUT_MS = 15 * 60 * 1000;
+export const AGENT_SIGNED_IN_TIMEOUT_MS = 30_000;
+
+export const LAUNCH_DIRECTORY_BASE = "/agents/house";
+
+export const KIT_SETUP_ACQUIRE_PATH = "/kit/setup/acquire";
+export const KIT_SETUP_REPORT_PATH = "/kit/setup/report";
+export const KIT_LOGIN_REPORT_PATH = "/kit/logins/report";
+export const GUIDED_LOGIN_TIMEOUT_MS = 10 * 60 * 1000;
+export const GUIDED_LOGIN_OUTPUT_MAX_BYTES = 64 * 1024;
+
+export const EXECUTION_AUTHORITIES = ["allow", "refuse"];
+
+export const PERMISSION_OPTION_KINDS = Object.freeze({
+  allow: "allow_once",
+  refuse: "reject_once",
+});
+
+export const KIT_HOST_CAPACITY_PATH = "/kit/host-capacity";
+export const HOST_CPU_SAMPLE_MS = 1_000;
+
+export const KIT_WORKSPACES_ACQUIRE_PATH = "/kit/workspaces/acquire";
+export const WORKSPACE_ACQUIRE_MAX = 10;
+export const WORKSPACE_POLL_MS = 2_000;
+export const WORKSPACE_LABEL = "house-kit.workspace";
+export const WORKSPACE_MOUNT = "/workspace";
+export const WORKSPACE_KIT_HOME = "/workspace/.house-kit";
+export const WORKSPACE_DISK_IMAGE = "disk.img";
+export const WORKSPACE_DISK_MOUNT = "mnt";
+export const WORKSPACE_MOUNT_OPTIONS = "loop,nosuid,nodev";
+export const HOST_MOUNT_INFO = "/proc/self/mountinfo";
+export const WORKSPACE_SYSTEM_RESERVE_BYTES = 512 * 1024 * 1024;
+export const WORKSPACE_COMMAND_TIMEOUT_MS = 120_000;
+export const WORKSPACE_READY_ATTEMPTS = 60;
+export const WORKSPACE_READY_POLL_MS = 1_000;
+export const WORKSPACE_STOP_TIMEOUT_SECONDS = 10;
+export const WORKSPACE_OPERATION_WITHDRAWN = "hosted_environment_operation_not_found";
+export const CGROUP_CONTROLLERS = "/sys/fs/cgroup/cgroup.controllers";
+export const LOOP_CONTROL = "/dev/loop-control";
+
+export function workspaceOutcomePath(operation) {
+  return `/kit/workspaces/${operation}/outcome`;
+}
+
+export const KIT_DOOR_DISCOVER_PATH = "/kit/door/discover";
+export const KIT_DOOR_BOOTSTRAP_PATH = "/kit/door/bootstrap";
+export const KIT_DOOR_ENUMERATE_PATH = "/kit/door/enumerate";
+export const KIT_DOOR_BATCH_PATH = "/kit/door/batch";
+export const EXPLICIT_SYNC_VERSION = "explicit-sync/1";
+export const KIT_DOOR_UNMOUNT_PATH = "/kit/door/unmount";
+
+export const MIGRATOR_CONTRACT = "kit-migrator/1";
+export const MIGRATOR_CATEGORY = "migrator";
+export const MIGRATOR_MANIFEST = "migrator.json";
+export const MIGRATOR_CONTENT_HOME = "content";
+export const MIGRATOR_ATTACHMENTS_HOME = "attachments";
+export const MIGRATOR_MODEL_HOME = "model";
+export const MIGRATOR_DOWNLOAD_OUTCOMES = ["downloaded", "unavailable", "skipped"];
+export const MIGRATOR_TIMEOUT_MS = 60 * 60 * 1000;
+export const MIGRATOR_OUTPUT_MAX_BYTES = 64 * 1024;
+export const MIGRATOR_ATTACHMENTS_MAX = 256;
+export const MOUNT_REPORT_NAME = "MIGRATION.md";
+
+export const KIT_ATTACHMENTS_UPLOAD_PATH = "/kit/attachments/upload";
+export const KIT_ATTACHMENTS_GET_PATH = "/kit/attachments/get";
+export const ATTACHMENT_REFERENCE = /^at_[1-9a-z][0-9a-z]*\.[0-9a-z]$/;
+export const ATTACHMENT_TRANSFER_CONTRACT = "attachment-transfer/1";
+export const ATTACHMENT_FILE_META = "agents.house/file";
+export const KIT_CAPTURE_ORIGINALS_SAVE_PATH = "/kit/capture/originals/save";
+export const KIT_CAPTURE_ORIGINALS_GET_PATH = "/kit/capture/originals/get";
+export const KIT_CONVERSATION_ORIGINALS_SAVE_PATH = "/kit/conversation/originals/save";
+export const KIT_CONVERSATION_ORIGINALS_GET_PATH = "/kit/conversation/originals/get";
+export const BYTE_GRANT_OPERATION_HEADER = "x-house-byte-operation";
+export const BYTE_GRANT_POST_BYTES_MAX = 32 * 1024 * 1024;
+export const ORIGINAL_NAME_MAX = 255;
+export const ORIGINAL_MEDIA_TYPE_MAX = 255;
+export const SHA256_DIGEST = /^[a-f0-9]{64}$/;
+export const ORIGINAL_UUID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export const MCP_PROTOCOL_VERSION = "2026-07-28";
+export const MCP_PROTOCOL_VERSION_META = "io.modelcontextprotocol/protocolVersion";
+export const MCP_CLIENT_INFO_META = "io.modelcontextprotocol/clientInfo";
+export const MCP_CLIENT_CAPABILITIES_META = "io.modelcontextprotocol/clientCapabilities";
+export const AGENT_OPERATION_META = "agents.house/agent-operation";
+
+export const ELICITATION_CREATE = "elicitation/create";
+export const REQUEST_PERMISSION = "session/request_permission";
+export const SESSION_UPDATE = "session/update";
+export const SESSION_SET_CONFIG_OPTION = "session/set_config_option";
+export const ELICITATION_SECRET_META = "agents.house/secret";
+export const ELICITATION_FREE_TEXT_META = "agents.house/free-text";
+export const NATIVE_CUSTOM_ANSWER_META = "_askUserQuestionCustomAnswer";
+export const NATIVE_CODEX_META = "codex";
+export const NATIVE_USER_NOTE_ROLE = "user_note";
+export const NATIVE_OTHER_OPTION = "None of the above";
+export const INTERACTION_OUTCOMES = ["resolved", "expired"];
+export const INTERACTION_CORRELATION_MAX = 64;
+export const INTERACTION_PROPERTY_MAX = 64;
+export const INTERACTION_VALUE_MAX = 4096;
+export const INTERACTION_OPTIONS_MAX = 32;
+export const INTERACTION_VALUES_MAX = INTERACTION_OPTIONS_MAX + 1;
+
+export function sessionInteractionsPath(workerSession) {
+  return `/kit/sessions/${encodeURIComponent(workerSession)}/interactions`;
+}
+
+export function interactionOutcomePath(interaction) {
+  return `/kit/interactions/${encodeURIComponent(interaction)}/outcome`;
+}
+
+export const ELICITATION_FORM_MODE = "form";
+export const ELICITATION_URL_MODE = "url";
+export const SECRET_CEREMONY_STEPS_MAX = 8;
+export const SECRET_STEP_LABEL_MAX = 200;
+export const SECRET_STEP_TEXT_MAX = 4096;
+export const SECRET_VALUE_MAX = 4096;
+
+export function secretInputPath(subject) {
+  return `/kit/secret-input/${encodeURIComponent(subject)}`;
+}

package/src/conversation-originals.js

@@ -0,0 +1,143 @@
+import { createHash } from "node:crypto";
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { BYTE_GRANT_POST_BYTES_MAX } from "./contract.js";
+import { describedBytes, readOriginalFile, saveConversationOriginal } from "./original.js";
+import { KitRefusal } from "./refusal.js";
+import { readNote, writeNote } from "./state.js";
+
+const SETTLED_ASSOCIATION = new Set(["conversation_original_not_found"]);
+
+function stateDirectory(directory) {
+  return join(directory, "state", "conversation-originals");
+}
+
+function statePath(directory, held) {
+  const identity = `attachment:${held.attachment}`;
+  return join(stateDirectory(directory), `${createHash("sha256").update(identity).digest("hex")}.json`);
+}
+
+function report(held) {
+  return {
+    attachment: held.attachment,
+    run: held.run,
+    original: held.original,
+    version: held.version,
+    save: held.save,
+    error: held.error,
+  };
+}
+
+function sameDescriptor(held, observed) {
+  return (
+    held !== null &&
+    observed !== null &&
+    held.bytes === observed.bytes &&
+    held.sha256 === observed.sha256
+  );
+}
+
+export async function holdConversationFile(context, file, bytes) {
+  const oversized = bytes !== null && bytes.length > BYTE_GRANT_POST_BYTES_MAX;
+  const identity = { attachment: file.attachment };
+  const path = statePath(context.directory, identity);
+  const noted = await readNote(path, null);
+  const observed = bytes === null || oversized ? null : describedBytes(bytes);
+  // House fixes a version's descriptor the first time one is declared and refuses
+  // every later one, so a file held again keeps the descriptor its note carries.
+  // Bytes that no longer answer that descriptor are not this original's bytes.
+  const descriptor = noted?.descriptor ?? observed;
+  const beyondBound = descriptor === null && (oversized || noted?.exceeded === true);
+  const held = {
+    ...identity,
+    run: file.run,
+    path: file.path ?? noted?.path ?? null,
+    descriptor,
+    exceeded: beyondBound,
+    original: null,
+    version: null,
+    save: { status: "pending", failure: null },
+    error: beyondBound ? "original_bytes_exceeded" : null,
+  };
+  await writeNote(path, held, context.signal);
+  return { held, body: sameDescriptor(descriptor, observed) ? bytes : null };
+}
+
+export async function settleConversationFile(context, held, body) {
+  let settled;
+  let answered = false;
+  try {
+    const saved = await saveConversationOriginal(context.session, {
+      attachment: held.attachment,
+      descriptor: held.descriptor,
+      body: held.exceeded ? null : body,
+      signal: context.signal,
+    });
+    answered = true;
+    settled = {
+      ...held,
+      original: saved.original,
+      version: saved.version,
+      save: saved.save,
+      error: held.exceeded ? "original_bytes_exceeded" : null,
+    };
+  } catch (refusal) {
+    if (!(refusal instanceof KitRefusal) || refusal.code === "kit_command_cancelled") throw refusal;
+    settled = { ...held, error: refusal.code };
+  }
+  const path = statePath(context.directory, settled);
+  if (settled.save.status === "saved" || (held.exceeded && answered) || SETTLED_ASSOCIATION.has(settled.error)) {
+    await rm(path, { force: true });
+  } else {
+    await writeNote(path, settled, context.signal);
+  }
+  return report(settled);
+}
+
+export async function retainConversationFile(context, file, bytes) {
+  const { held, body } = await holdConversationFile(context, file, bytes);
+  return settleConversationFile(context, held, body);
+}
+
+async function heldFiles(directory) {
+  let names;
+  try {
+    names = await readdir(stateDirectory(directory));
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw new KitRefusal("kit_state_unreadable", stateDirectory(directory));
+  }
+  const held = [];
+  for (const name of names.filter((entry) => /^[a-f0-9]{64}\.json$/.test(entry)).sort()) {
+    held.push(await readNote(join(stateDirectory(directory), name), null));
+  }
+  return held.filter((note) => note !== null);
+}
+
+async function localBytes(held) {
+  if (held.path === null) return { bytes: null, exceeded: false };
+  try {
+    return { bytes: await readOriginalFile(held.path, held.descriptor?.bytes ?? null), exceeded: false };
+  } catch (refusal) {
+    if (!(refusal instanceof KitRefusal) || refusal.code !== "original_bytes_exceeded") throw refusal;
+    return { bytes: null, exceeded: true };
+  }
+}
+
+export async function retryConversationFiles(context, settled = new Set()) {
+  const reported = [];
+  for (const held of await heldFiles(context.directory)) {
+    if (settled.has(held.attachment)) continue;
+    const local = held.exceeded ? { bytes: null, exceeded: true } : await localBytes(held);
+    const descriptor = held.descriptor ?? (local.bytes === null ? null : describedBytes(local.bytes));
+    const exceeded = held.exceeded || (held.descriptor === null && local.exceeded);
+    reported.push(
+      await settleConversationFile(
+        context,
+        { ...held, descriptor, exceeded, error: exceeded ? "original_bytes_exceeded" : held.error },
+        local.bytes,
+      ),
+    );
+  }
+  return reported;
+}