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

package/src/custom/authorization.js

@@ -1,63 +0,0 @@
-import { resolveEnvironment, runCommand } from "../command.js";
-import { AUTHORIZATION_OUTPUT_MAX_BYTES, KIT_CONTRACT_VERSION } from "../contract.js";
-import { KitRefusal } from "../refusal.js";
-
-function authorizationRequest(instance, mode) {
-  return `${JSON.stringify({
-    contract: KIT_CONTRACT_VERSION,
-    action: "authorization",
-    mode,
-    instance: instance.id,
-  })}\n`;
-}
-
-function authorizationAnswer(stdout) {
-  let answer;
-  try {
-    answer = JSON.parse(stdout);
-  } catch {
-    throw new KitRefusal("kit_connector_authorization_invalid");
-  }
-  if (
-    typeof answer !== "object" ||
-    answer === null ||
-    Array.isArray(answer) ||
-    Object.keys(answer).length !== 1 ||
-    typeof answer.authorized !== "boolean"
-  ) {
-    throw new KitRefusal("kit_connector_authorization_invalid");
-  }
-  return answer.authorized;
-}
-
-async function serviceAuthorization(instance, service, mode, context) {
-  const connector = service.connector;
-  const run = await runCommand({
-    command: connector.command,
-    environment: await resolveEnvironment(connector),
-    stdin: authorizationRequest(instance, mode),
-    timeoutMs: connector.timeoutMs,
-    outputMaxBytes: AUTHORIZATION_OUTPUT_MAX_BYTES,
-    signal: context.signal,
-  });
-  if (run.status !== 0) {
-    if (mode === "status") return false;
-    throw new KitRefusal("kit_connector_authorization_failed", `${run.status}`);
-  }
-  return authorizationAnswer(run.stdout);
-}
-
-export async function customAuthorizationStatus(instance, context) {
-  for (const service of instance.services) {
-    if (!(await serviceAuthorization(instance, service, "status", context))) return false;
-  }
-  return true;
-}
-
-export async function authorizeCustom(instance, context) {
-  for (const service of instance.services) {
-    if (await serviceAuthorization(instance, service, "status", context)) continue;
-    if (!(await serviceAuthorization(instance, service, "login", context))) return false;
-  }
-  return true;
-}

package/src/declaration.js

@@ -1,35 +0,0 @@
-import { KitRefusal } from "./refusal.js";
-
-export function declarationReader(code) {
-  const refuse = (declaration) => {
-    throw new KitRefusal(code, declaration);
-  };
-  const plain = (value, declaration) => {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) refuse(declaration);
-    return value;
-  };
-  const closed = (value, fields, declaration) => {
-    plain(value, declaration);
-    for (const field of Object.keys(value)) {
-      if (!fields.includes(field)) refuse(`${declaration}.${field}`);
-    }
-    return value;
-  };
-  const text = (value, declaration, maximum) => {
-    if (typeof value !== "string" || value.length === 0 || value.length > maximum) {
-      refuse(declaration);
-    }
-    return value;
-  };
-  const optionalText = (value, declaration, maximum) =>
-    value === undefined ? null : text(value, declaration, maximum);
-  const positiveCount = (value, declaration, maximum = Number.MAX_SAFE_INTEGER) => {
-    if (!Number.isInteger(value) || value < 1 || value > maximum) refuse(declaration);
-    return value;
-  };
-  const filled = (value, declaration) => {
-    if (!Array.isArray(value) || value.length === 0) refuse(declaration);
-    return value;
-  };
-  return { refuse, plain, closed, text, optionalText, positiveCount, filled };
-}

package/src/delivery.js

@@ -1,191 +0,0 @@
-import { createHash } from "node:crypto";
-import { KIT_CAPTURE_BATCH_MAX } from "./contract.js";
-
-const DAY_MS = 24 * 60 * 60 * 1000;
-
-const RETRY_CODES = new Set([
-  "kit_house_unavailable",
-  "environment_control_lease_active",
-  "rate_limited",
-  "service_mode_write_halted",
-]);
-
-const FAILURE_CATEGORIES = {
-  kit_command_timeout: "provider",
-  kit_command_cancelled: "provider",
-  kit_command_output_exceeded: "provider",
-  kit_command_unavailable: "provider",
-  kit_connector_failed: "provider",
-  kit_connector_line_invalid: "provider",
-  kit_connector_limit_exceeded: "provider",
-  kit_item_invalid: "provider",
-  kit_bound_exceeded: "provider",
-  dedup_key_conflict: "provider",
-  kit_secret_unresolved: "config",
-  kit_house_credential_refused: "config",
-  kit_configuration_invalid: "config",
-  kit_instance_unknown: "config",
-  kit_state_name_invalid: "config",
-  kit_upgrade_required: "config",
-  kit_declaration_invalid: "config",
-  kit_source_not_found: "config",
-  kit_source_mismatch: "config",
-  kit_route_unknown: "config",
-  room_archived: "config",
-  room_deleting: "config",
-  kit_room_not_writable: "authority",
-  operation_denied: "authority",
-  kit_credential_rejected: "authority",
-  rate_limited: "house",
-  service_mode_write_halted: "house",
-  storage_full: "house",
-  kit_capture_rejected: "house",
-  kit_lease_rejected: "house",
-  environment_control_lease_active: "house",
-  environment_control_lease_rejected: "authority",
-  kit_apply_rejected: "house",
-  kit_house_unavailable: "network",
-  google_authorization_required: "authority",
-  google_authority_revoked: "authority",
-  google_scope_revoked: "authority",
-  google_authorization_rejected: "authority",
-  google_authorization_cancelled: "authority",
-  google_authorization_unreadable: "config",
-  google_provider_unavailable: "provider",
-  google_provider_response_invalid: "provider",
-  google_checkpoint_invalid: "provider",
-  google_service_unsupported: "config",
-  google_oauth_client_unconfigured: "config",
-  google_drive_selection_exceeded: "config",
-  google_drive_item_missing: "provider",
-};
-
-export function fileDescriptor(file) {
-  const { path: _path, ...descriptor } = file;
-  return descriptor;
-}
-
-function revisionAttachments(attachments) {
-  return attachments.map((attachment) =>
-    attachment.file === undefined ? attachment : { ...attachment, file: fileDescriptor(attachment.file) },
-  );
-}
-
-export function acceptedVersion(key, position, file) {
-  const identity = createHash("sha256")
-    .update(JSON.stringify([key, position, file.bytes, file.sha256, file.media_type ?? null]))
-    .digest();
-  identity[6] = (identity[6] & 0x0f) | 0x80;
-  identity[8] = (identity[8] & 0x3f) | 0x80;
-  const hex = identity.subarray(0, 16).toString("hex");
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
-
-function deliveredAttachments(key, attachments) {
-  return attachments.map((attachment, position) => {
-    if (attachment.file === undefined) return attachment;
-    const descriptor = fileDescriptor(attachment.file);
-    return {
-      original: { version: acceptedVersion(key, position, descriptor), ...descriptor },
-      ...(attachment.name === undefined ? {} : { name: attachment.name }),
-    };
-  });
-}
-
-export function deliveryKey(binding, item) {
-  const revisionIdentity =
-    item.nativeVersion ??
-    (item.providerModifiedAt === null || item.providerModifiedAt === undefined
-      ? null
-      : [
-          item.providerModifiedAt,
-          createHash("sha256")
-            .update(
-              JSON.stringify([
-                item.container ?? null,
-                item.body,
-                item.author,
-                item.url,
-                revisionAttachments(item.attachments),
-              ]),
-            )
-            .digest("hex"),
-        ]);
-  return createHash("sha256")
-    .update(
-      JSON.stringify([
-        binding.sourceRef,
-        binding.service,
-        item.namespace,
-        item.nativeObjectId,
-        revisionIdentity,
-      ]),
-    )
-    .digest("hex");
-}
-
-export function deliveredItem(binding, item) {
-  const key = deliveryKey(binding, item);
-  return {
-    dedup_key: key,
-    observed_at: item.observedAt,
-    provider: item.namespace,
-    container: item.container ?? `${item.namespace}/${item.nativeObjectId}`,
-    native_object_id: item.nativeObjectId,
-    ...(item.nativeVersion === null ? {} : { native_version: item.nativeVersion }),
-    ...(item.providerModifiedAt === null || item.providerModifiedAt === undefined
-      ? {}
-      : { provider_modified: item.providerModifiedAt }),
-    body: item.body,
-    ...(item.author === null ? {} : { author: item.author }),
-    ...(item.url === null ? {} : { url: item.url }),
-    ...(item.attachments.length === 0
-      ? {}
-      : { attachments: deliveredAttachments(key, item.attachments) }),
-  };
-}
-
-export function newCheckpoint(backfill, now) {
-  if (backfill.kind === "all") return { cursor: null, backfill: null };
-  if (backfill.kind === "days") {
-    return {
-      cursor: null,
-      backfill: {
-        kind: "days",
-        floor: new Date(now.getTime() - backfill.bound * DAY_MS).toISOString(),
-      },
-    };
-  }
-  return { cursor: null, backfill: { kind: "count", remaining: backfill.bound } };
-}
-
-export function itemLimit(checkpoint) {
-  return checkpoint.backfill?.kind === "count"
-    ? Math.min(KIT_CAPTURE_BATCH_MAX, checkpoint.backfill.remaining)
-    : KIT_CAPTURE_BATCH_MAX;
-}
-
-export function admittedItems(checkpoint, items) {
-  if (checkpoint.backfill?.kind !== "days") return items;
-  const floor = Date.parse(checkpoint.backfill.floor);
-  return items.filter((item) => Date.parse(item.observedAt) >= floor);
-}
-
-export function advancedCheckpoint(checkpoint, cursor, delivered) {
-  if (checkpoint.backfill?.kind !== "count") return { cursor, backfill: checkpoint.backfill };
-  const remaining = Math.max(0, checkpoint.backfill.remaining - delivered);
-  return { cursor, backfill: remaining === 0 ? null : { kind: "count", remaining } };
-}
-
-export function stallOf(code, houseRetry = null) {
-  if (houseRetry !== null) return { code, disposition: houseRetry ? "retry" : "blocked", category: "house" };
-  return { code, disposition: RETRY_CODES.has(code) ? "retry" : "blocked" };
-}
-
-export function healthOfRun(stall) {
-  if (stall === null) return { state: "ok", category: null };
-  return {
-    state: stall.disposition === "retry" ? "retrying" : "failed",
-    category: stall.category ?? FAILURE_CATEGORIES[stall.code] ?? "internal",
-  };
-}

package/src/directory.js

@@ -1,102 +0,0 @@
-import { constants } from "node:fs";
-import { access, mkdir, realpath, rename, rm, stat } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { LAUNCH_DIRECTORY_BASE } from "./contract.js";
-import { KitRefusal } from "./refusal.js";
-import { seedStarterSet } from "./starter-set.js";
-
-export function launchBase(dependencies = {}) {
-  return dependencies.launchBase ?? LAUNCH_DIRECTORY_BASE;
-}
-
-function defaultDirectory(base, agentId) {
-  if (typeof agentId !== "string" || agentId.length === 0) return null;
-  const expected = resolve(base, agentId);
-  return dirname(expected) === resolve(base) ? expected : null;
-}
-
-async function made(path) {
-  try {
-    await mkdir(path, { recursive: true });
-    return null;
-  } catch (error) {
-    return error.code ?? "unknown";
-  }
-}
-
-export async function prepareLaunchBase(base) {
-  const refused = await made(base);
-  if (refused !== null) {
-    throw new KitRefusal(
-      "kit_launch_base_unprepared",
-      `${base} could not be created (${refused}); create that absolute directory and give this installation write access to it`,
-    );
-  }
-}
-
-function unavailable(path, cause) {
-  return new KitRefusal("kit_launch_directory_unavailable", `${path} ${cause}`);
-}
-
-async function isDirectory(path) {
-  try {
-    return (await stat(path)).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-async function seedDefaultDirectory(selected, base, path) {
-  const staging = join(base, `.${randomUUID()}.staging`);
-  try {
-    await seedStarterSet(staging);
-    await rename(staging, path);
-  } catch (error) {
-    await rm(staging, { recursive: true, force: true }).catch(() => undefined);
-    if (!(await isDirectory(path))) {
-      throw unavailable(selected, `could not be prepared (${error.code ?? "unknown"})`);
-    }
-  }
-}
-
-function within(base, selected) {
-  const path = relative(base, selected);
-  return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
-}
-
-export async function readyLaunchDirectory(selected, base, agentId = null, options = {}) {
-  if (typeof selected !== "string" || !isAbsolute(selected)) {
-    throw unavailable(selected, "is not an absolute directory path");
-  }
-  const path = resolve(selected);
-  if (options.container && !within(resolve(base), path)) {
-    throw unavailable(selected, `resolves outside ${base}`);
-  }
-  if (path === defaultDirectory(base, agentId) && !(await isDirectory(path))) {
-    await seedDefaultDirectory(selected, base, path);
-  }
-  let described;
-  try {
-    described = await stat(path);
-  } catch (error) {
-    throw unavailable(selected, `is unavailable (${error.code ?? "unknown"})`);
-  }
-  if (!described.isDirectory()) throw unavailable(selected, "is not a directory");
-  try {
-    await access(path, constants.R_OK | constants.X_OK);
-  } catch (error) {
-    throw unavailable(selected, `is not accessible (${error.code ?? "unknown"})`);
-  }
-  if (options.container) {
-    let mounted;
-    let actual;
-    try {
-      mounted = await realpath(base);
-      actual = await realpath(path);
-    } catch (error) {
-      throw unavailable(selected, `could not be resolved (${error.code ?? "unknown"})`);
-    }
-    if (!within(mounted, actual)) throw unavailable(selected, `resolves outside ${base}`);
-  }
-}

package/src/draft.js

@@ -1,89 +0,0 @@
-import { assistantBlocks, blocksText, withinAssistantBound } from "./blocks.js";
-
-const DRAFT_INTERVAL_MS = 500;
-
-export function observedAssistantDrafts(options) {
-  const intervalMs = options.intervalMs ?? DRAFT_INTERVAL_MS;
-  const now = options.now ?? (() => Date.now());
-  let timer = null;
-  let sentAt = null;
-  let sent = null;
-  let latest = null;
-
-  function write() {
-    timer = null;
-    if (latest === null || latest === sent) return;
-    sent = latest;
-    sentAt = now();
-    options.send(sent);
-  }
-
-  function cancel() {
-    if (timer === null) return;
-    clearTimeout(timer);
-    timer = null;
-  }
-
-  return {
-    observe(view) {
-      if (typeof view !== "string" || view === "") return;
-      latest = view;
-      if (timer !== null) return;
-      const wait = sentAt === null ? 0 : sentAt + intervalMs - now();
-      if (wait <= 0) {
-        write();
-        return;
-      }
-      timer = setTimeout(write, wait);
-      timer.unref?.();
-    },
-    complete(view) {
-      if (typeof view !== "string" || view === "") return;
-      latest = view;
-      cancel();
-      write();
-    },
-    close: cancel,
-  };
-}
-
-export function openAssistantDrafts(options) {
-  let pending = null;
-  let sending = null;
-  let sent = null;
-  let closed = false;
-
-  function pump() {
-    if (sending !== null || pending === null) return;
-    const view = pending;
-    pending = null;
-    sent = view.text;
-    let started;
-    try {
-      started = Promise.resolve(options.send(view.blocks));
-    } catch {
-      started = Promise.resolve();
-    }
-    sending = started
-      .catch(() => undefined)
-      .finally(() => {
-        sending = null;
-        pump();
-      });
-  }
-
-  return {
-    update(text) {
-      if (closed || typeof text !== "string" || text === "") return;
-      if (text === sent || text === pending?.text) return;
-      const blocks = assistantBlocks(text);
-      if (blocks === null || !withinAssistantBound(blocksText(blocks))) return;
-      pending = { text, blocks };
-      pump();
-    },
-    close() {
-      closed = true;
-      pump();
-    },
-  };
-}

package/src/google/calendar.js

@@ -1,177 +0,0 @@
-import { ITEM_BODY_MAX_BYTES } from "../contract.js";
-import { KitRefusal } from "../refusal.js";
-import { googleJson } from "./gateway.js";
-import { GOOGLE_SCOPES } from "./oauth.js";
-
-const CALENDAR_ORIGIN = "https://www.googleapis.com";
-
-function cursorOf(value, calendars) {
-  if (value === null) return { calendar: 0, pageToken: null, syncTokens: {} };
-  let cursor;
-  try {
-    cursor = JSON.parse(value);
-  } catch {
-    throw new KitRefusal("google_checkpoint_invalid", "calendar");
-  }
-  if (
-    typeof cursor !== "object" ||
-    cursor === null ||
-    !Number.isInteger(cursor.calendar) ||
-    cursor.calendar < 0 ||
-    cursor.calendar >= calendars.length ||
-    (cursor.pageToken !== null && typeof cursor.pageToken !== "string") ||
-    typeof cursor.syncTokens !== "object" ||
-    cursor.syncTokens === null ||
-    Array.isArray(cursor.syncTokens) ||
-    Object.entries(cursor.syncTokens).some(
-      ([calendar, token]) => !calendars.includes(calendar) || typeof token !== "string",
-    )
-  ) {
-    throw new KitRefusal("google_checkpoint_invalid", "calendar");
-  }
-  return cursor;
-}
-
-function eventBody(event) {
-  return [event.summary, event.description, event.location]
-    .filter((value) => typeof value === "string" && value.length > 0)
-    .join("\n\n");
-}
-
-function authorOf(event) {
-  if (typeof event.organizer?.email !== "string") return null;
-  return typeof event.organizer.displayName === "string"
-    ? `${event.organizer.displayName} <${event.organizer.email}>`
-    : event.organizer.email;
-}
-
-function normalizedEvent(event, calendar) {
-  if (
-    typeof event?.id !== "string" ||
-    typeof event.etag !== "string" ||
-    typeof event.updated !== "string" ||
-    Number.isNaN(Date.parse(event.updated)) ||
-    (event.status !== undefined && typeof event.status !== "string") ||
-    (event.htmlLink !== undefined && typeof event.htmlLink !== "string")
-  ) {
-    throw new KitRefusal("google_provider_response_invalid", "calendar event");
-  }
-  if (event.status === "cancelled") throw new KitRefusal("google_calendar_item_cancelled");
-  const body = eventBody(event);
-  if (Buffer.byteLength(body, "utf8") > ITEM_BODY_MAX_BYTES) {
-    throw new KitRefusal("google_calendar_content_exceeded");
-  }
-  return {
-    namespace: "google/calendar",
-    nativeObjectId: event.id,
-    nativeVersion: event.etag,
-    providerModifiedAt: new Date(event.updated).toISOString(),
-    observedAt: new Date(event.updated).toISOString(),
-    body,
-    author: authorOf(event),
-    url: event.htmlLink ?? null,
-    attachments: [],
-    container: `google/calendar/${calendar}`,
-  };
-}
-
-function pageUrl(calendar, cursor, limit, backfillFloor) {
-  const url = new URL(
-    `/calendar/v3/calendars/${encodeURIComponent(calendar)}/events`,
-    CALENDAR_ORIGIN,
-  );
-  url.searchParams.set("maxResults", `${limit}`);
-  url.searchParams.set("singleEvents", "true");
-  url.searchParams.set("showDeleted", "true");
-  if (cursor.pageToken !== null) url.searchParams.set("pageToken", cursor.pageToken);
-  const syncToken = cursor.syncTokens[calendar];
-  if (syncToken !== undefined) url.searchParams.set("syncToken", syncToken);
-  else if (backfillFloor !== null && backfillFloor !== undefined) {
-    url.searchParams.set("timeMin", backfillFloor);
-  }
-  return url.toString();
-}
-
-export async function calendarPage(options, dependencies = {}) {
-  const calendars = options.selection.calendars;
-  let cursor = cursorOf(options.cursor, calendars);
-  const calendar = calendars[cursor.calendar];
-  const common = {
-    directory: options.directory,
-    instance: options.instance,
-    client: options.client,
-    requiredScopes: [GOOGLE_SCOPES.calendar],
-    signal: options.signal,
-  };
-  let answer;
-  try {
-    answer = await googleJson(
-      {
-        ...common,
-        goneCode: "google_calendar_cursor_expired",
-        url: pageUrl(calendar, cursor, options.limit, options.backfillFloor),
-      },
-      dependencies,
-    );
-  } catch (error) {
-    if (!(error instanceof KitRefusal) || error.code !== "google_calendar_cursor_expired") {
-      throw error;
-    }
-    const syncTokens = { ...cursor.syncTokens };
-    delete syncTokens[calendar];
-    cursor = { calendar: cursor.calendar, pageToken: null, syncTokens };
-    answer = await googleJson(
-      { ...common, url: pageUrl(calendar, cursor, options.limit, options.backfillFloor) },
-      dependencies,
-    );
-  }
-  const items = answer.items ?? [];
-  if (
-    !Array.isArray(items) ||
-    (answer.nextPageToken !== undefined && typeof answer.nextPageToken !== "string") ||
-    (answer.nextSyncToken !== undefined && typeof answer.nextSyncToken !== "string")
-  ) {
-    throw new KitRefusal("google_provider_response_invalid", "calendar page");
-  }
-  let next;
-  if (answer.nextPageToken !== undefined) {
-    next = { calendar: cursor.calendar, pageToken: answer.nextPageToken, syncTokens: cursor.syncTokens };
-  } else {
-    if (typeof answer.nextSyncToken !== "string") {
-      throw new KitRefusal("google_provider_response_invalid", "calendar sync token");
-    }
-    const syncTokens = { ...cursor.syncTokens, [calendar]: answer.nextSyncToken };
-    next = {
-      calendar: cursor.calendar + 1 === calendars.length ? 0 : cursor.calendar + 1,
-      pageToken: null,
-      syncTokens,
-    };
-  }
-  const normalized = [];
-  const dropped = [];
-  for (const event of items) {
-    try {
-      normalized.push(normalizedEvent(event, calendar));
-    } catch (error) {
-      if (
-        error instanceof KitRefusal &&
-        ["google_calendar_item_cancelled", "google_calendar_content_exceeded"].includes(error.code)
-      ) {
-        dropped.push({
-          namespace: "google/calendar",
-          nativeObjectId: event.id,
-          nativeVersion: event.etag,
-          code: error.code,
-        });
-      } else {
-        throw error;
-      }
-    }
-  }
-  return {
-    items: normalized,
-    dropped,
-    cursor: JSON.stringify(next),
-    more: answer.nextPageToken !== undefined || cursor.calendar + 1 < calendars.length,
-  };
-}