@agentshouse/kit 0.0.1 → 0.1.0-alpha.2

package/src/custom/authorization.js

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

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

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

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

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

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