@agentshouse/kit 0.1.0-alpha.42 → 0.1.0-alpha.44

package/README.md

@@ -13,13 +13,13 @@ The Skill set Kit installs is Matt Pocock's
 Linux (`amd64`, `arm64`) or macOS (Apple silicon, Intel):
 
 ```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.42/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.44/connect-linux.sh)
 ```
 
 Windows 11 (`amd64`), in PowerShell:
 
 ```powershell
-& ([scriptblock]::Create((irm https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.42/connect-windows.ps1)))
+& ([scriptblock]::Create((irm https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.44/connect-windows.ps1)))
 ```
 
 The command sets up Docker if it is missing, creates `~/.house-kit` (Kit home;

package/bootstrap.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "version": "0.1.0-alpha.42",
+  "version": "0.1.0-alpha.44",
   "hosts": {
     "linux": {
-      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.42/connect-linux.sh)",
+      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.44/connect-linux.sh)",
       "asset": {
         "name": "connect-linux.sh",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.42/connect-linux.sh"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.44/connect-linux.sh"
       },
       "workspace": {
         "argument": "--workspace",
@@ -14,10 +14,10 @@
       }
     },
     "windows": {
-      "command": "& ([scriptblock]::Create((irm https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.42/connect-windows.ps1)))",
+      "command": "& ([scriptblock]::Create((irm https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.44/connect-windows.ps1)))",
       "asset": {
         "name": "connect-windows.ps1",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.42/connect-windows.ps1"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.44/connect-windows.ps1"
       },
       "workspace": {
         "argument": "--workspace",

package/docs/configuration.md

@@ -76,7 +76,7 @@ It must finish within `timeout_ms` (at most 120000).
 Kit writes one request line to its standard input:
 
 ```json
-{ "contract": "2026-08-22", "instance": "acme", "cursor": null, "limit": 100 }
+{ "contract": "4", "instance": "acme", "cursor": null, "limit": 100 }
 ```
 
 The command prints NDJSON: `item` lines, then at most one `cursor` line.
@@ -87,10 +87,12 @@ The command prints NDJSON: `item` lines, then at most one `cursor` line.
 {"type":"cursor","cursor":"page-2"}
 ```
 
-`namespace`, `native_object_id`, `observed_at` and `body` are required. An
-attachment is a `url`, or a local `file` with its exact `path`, `bytes`,
-`sha256` and optional `media_type`. A malformed line, a non-zero exit or a
-timeout rejects the whole run and nothing is delivered.
+`namespace`, `native_object_id`, `observed_at` and `body` are required. The
+optional `container` and `name` are the folder path and file name the item
+reads at below its Source in House. An attachment is a `url`, or a local `file`
+with its exact `path`, `bytes`, `sha256` and optional `media_type`. A malformed
+line, a non-zero exit or a timeout rejects the whole run and nothing is
+delivered.
 
 `backfill` bounds the first capture: `{ "days": 30 }`, `{ "count": 500 }` or
 `{ "all": true }`.

package/docs/google.md

@@ -10,6 +10,15 @@ Each service captures, read-only:
 - Calendar: the account's primary calendar.
 - Drive: the files the account owns.
 
+Each capture is a file below its Source in House:
+
+- Gmail: `<label>/<thread subject>/<YYYY-MM-DD>-<subject>.md`. The label is the
+  message's first own label by name, else `INBOX`, `SENT` or `DRAFT`, else
+  `All Mail`.
+- Drive: `<folder path>/<title>.md`.
+- Calendar: `<calendar>/<YYYY-MM>/<YYYY-MM-DD>-<event title>.md`, by the
+  event's start day.
+
 ## Signing in
 
 Kit ships no Google OAuth client. Each account signs in with your own:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/kit",
-  "version": "0.1.0-alpha.42",
+  "version": "0.1.0-alpha.44",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/connector.js

@@ -21,6 +21,8 @@ const ITEM_FIELDS = [
   "author",
   "url",
   "attachments",
+  "container",
+  "name",
 ];
 const ATTACHMENT_FIELDS = ["url", "file", "name"];
 const FILE_FIELDS = ["path", "bytes", "sha256", "media_type"];
@@ -60,6 +62,7 @@ function itemOf(line) {
   if (typeof line.body !== "string" || Buffer.byteLength(line.body, "utf8") > ITEM_BODY_MAX_BYTES) {
     refuse("body");
   }
+  const name = optionalText(line.name, "name", Number.MAX_SAFE_INTEGER);
   return {
     namespace,
     nativeObjectId: text(line.native_object_id, "native_object_id", 512),
@@ -69,6 +72,8 @@ function itemOf(line) {
     author: optionalText(line.author, "author", 512),
     url: optionalText(line.url, "url", 2048),
     attachments: attachmentsOf(line.attachments),
+    container: optionalText(line.container, "container", Number.MAX_SAFE_INTEGER),
+    claimed: name === null ? {} : { name },
   };
 }
 

package/src/contract.js

@@ -1,6 +1,6 @@
 import { CLAUDE_PASTED_CODE, CODEX_DEVICE_CODE, GROK_DEVICE_CODE } from "./agent-logins.js";
 
-export const KIT_CONTRACT_VERSION = "3";
+export const KIT_CONTRACT_VERSION = "4";
 export const KIT_CAPTURE_BATCH_MAX = 100;
 export const COMMAND_INPUT_MAX_BYTES = 4 * 1024;
 export const AUTHORIZATION_OUTPUT_MAX_BYTES = 4 * 1024;

package/src/delivery.js

@@ -128,7 +128,8 @@ export function deliveredItem(binding, item) {
     dedup_key: key,
     observed_at: item.observedAt,
     provider: item.namespace,
-    container: item.container ?? `${item.namespace}/${item.nativeObjectId}`,
+    ...(item.container === null ? {} : { container: item.container }),
+    ...(Object.keys(item.claimed).length === 0 ? {} : { claimed: item.claimed }),
     native_object_id: item.nativeObjectId,
     ...(item.nativeVersion === null ? {} : { native_version: item.nativeVersion }),
     ...(item.providerModifiedAt === null || item.providerModifiedAt === undefined

package/src/google/calendar.js

@@ -5,6 +5,7 @@ import { GOOGLE_SCOPES } from "./oauth.js";
 
 const CALENDAR_ORIGIN = "https://www.googleapis.com";
 const CALENDAR = "primary";
+const DAY = /^\d{4}-\d{2}-\d{2}/;
 
 function cursorOf(value) {
   if (value === null) return { pageToken: null, syncToken: null };
@@ -31,29 +32,56 @@ function eventBody(event) {
     .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 person(entry) {
+  if (typeof entry?.email !== "string") return null;
+  return typeof entry.displayName === "string" ? `${entry.displayName} <${entry.email}>` : entry.email;
 }
 
-function normalizedEvent(event) {
+function momentOf(value) {
+  if (typeof value?.dateTime === "string") return value.dateTime;
+  return typeof value?.date === "string" ? value.date : null;
+}
+
+function claimedEvent(event, start) {
+  const day = start.slice(0, 10);
+  const end = momentOf(event.end);
+  const attendees = (event.attendees ?? []).map(person).filter((attendee) => attendee !== null);
+  const titled = typeof event.summary === "string" && event.summary.length > 0;
+  return {
+    name: titled ? `${day}-${event.summary}.md` : `${day}.md`,
+    start,
+    ...(end === null ? {} : { end }),
+    ...(attendees.length === 0 ? {} : { attendees }),
+    ...(typeof event.location === "string" && event.location.length > 0
+      ? { location: event.location }
+      : {}),
+  };
+}
+
+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")
+    (event.htmlLink !== undefined && typeof event.htmlLink !== "string") ||
+    (event.attendees !== undefined && !Array.isArray(event.attendees))
   ) {
     throw new KitRefusal("google_provider_response_invalid", "calendar event");
   }
   if (event.status === "cancelled") throw new KitRefusal("google_calendar_item_cancelled");
+  const start = momentOf(event.start);
+  if (start === null || !DAY.test(start)) {
+    throw new KitRefusal("google_provider_response_invalid", "calendar event start");
+  }
   const body = eventBody(event);
   if (Buffer.byteLength(body, "utf8") > ITEM_BODY_MAX_BYTES) {
     throw new KitRefusal("google_calendar_content_exceeded");
   }
+  if (typeof calendar !== "string") {
+    throw new KitRefusal("google_provider_response_invalid", "calendar summary");
+  }
   return {
     namespace: "google/calendar",
     nativeObjectId: event.id,
@@ -61,10 +89,11 @@ function normalizedEvent(event) {
     providerModifiedAt: new Date(event.updated).toISOString(),
     observedAt: new Date(event.updated).toISOString(),
     body,
-    author: authorOf(event),
+    author: person(event.organizer),
     url: event.htmlLink ?? null,
     attachments: [],
-    container: `google/calendar/${CALENDAR}`,
+    container: `${calendar}/${start.slice(0, 7)}`,
+    claimed: claimedEvent(event, start),
   };
 }
 
@@ -145,7 +174,7 @@ export async function calendarPage(options, dependencies = {}) {
   const dropped = [];
   for (const event of items) {
     try {
-      normalized.push(normalizedEvent(event));
+      normalized.push(normalizedEvent(event, answer.summary));
     } catch (error) {
       if (
         error instanceof KitRefusal &&

package/src/google/drive.js

@@ -67,34 +67,51 @@ function fileMetadata(value) {
   return value;
 }
 
-async function parentPath(options, file, dependencies, cache) {
-  const names = [];
-  const seen = new Set();
-  let parent = file.parents?.[0] ?? null;
-  while (parent !== null && parent !== "root") {
-    if (seen.has(parent)) throw new KitRefusal("google_provider_response_invalid", "drive parents");
-    seen.add(parent);
-    let metadata = cache.get(parent);
-    if (metadata === undefined) {
-      metadata = fileMetadata(
-        await googleJson(
-          {
-            ...common(options),
-            url: fileUrl(parent, { fields: FILE_FIELDS }),
-            notFoundCode: "google_drive_item_missing",
-          },
-          dependencies,
-        ),
-      );
-      cache.set(parent, metadata);
-    }
-    if (metadata.mimeType !== FOLDER_MIME) {
-      throw new KitRefusal("google_provider_response_invalid", "drive parent");
-    }
-    names.unshift(metadata.name);
-    parent = metadata.parents?.[0] ?? null;
+async function rootId(options, dependencies) {
+  const root = await googleJson(
+    { ...common(options), url: fileUrl("root", { fields: "id" }) },
+    dependencies,
+  );
+  if (typeof root.id !== "string") {
+    throw new KitRefusal("google_provider_response_invalid", "drive root");
   }
-  return names;
+  return root.id;
+}
+
+function folderPaths(options, dependencies) {
+  const folders = new Map();
+  let root = null;
+  return async (file) => {
+    const names = [];
+    const seen = new Set();
+    let parent = file.parents?.[0] ?? null;
+    if (parent === null || parent === "root") return names;
+    root ??= await rootId(options, dependencies);
+    while (parent !== null && parent !== "root" && parent !== root) {
+      if (seen.has(parent)) throw new KitRefusal("google_provider_response_invalid", "drive parents");
+      seen.add(parent);
+      let metadata = folders.get(parent);
+      if (metadata === undefined) {
+        metadata = fileMetadata(
+          await googleJson(
+            {
+              ...common(options),
+              url: fileUrl(parent, { fields: FILE_FIELDS }),
+              notFoundCode: "google_drive_item_missing",
+            },
+            dependencies,
+          ),
+        );
+        folders.set(parent, metadata);
+      }
+      if (metadata.mimeType !== FOLDER_MIME) {
+        throw new KitRefusal("google_provider_response_invalid", "drive parent");
+      }
+      names.unshift(metadata.name);
+      parent = metadata.parents?.[0] ?? null;
+    }
+    return names;
+  };
 }
 
 async function contentOf(options, file, dependencies) {
@@ -132,7 +149,7 @@ function authorOf(file) {
     : owner.emailAddress;
 }
 
-async function normalizedFile(options, file, dependencies, cache) {
+async function normalizedFile(options, file, dependencies, pathOf) {
   const metadata = fileMetadata(file);
   if (
     metadata.mimeType === FOLDER_MIME ||
@@ -144,7 +161,7 @@ async function normalizedFile(options, file, dependencies, cache) {
     throw new KitRefusal("google_provider_response_invalid", "drive content");
   }
   const body = await contentOf(options, metadata, dependencies);
-  const folders = await parentPath(options, metadata, dependencies, cache);
+  const folders = await pathOf(metadata);
   return {
     namespace: "google/drive",
     nativeObjectId: metadata.id,
@@ -155,7 +172,8 @@ async function normalizedFile(options, file, dependencies, cache) {
     author: authorOf(metadata),
     url: metadata.webViewLink ?? null,
     attachments: [],
-    container: `google/drive${folders.length === 0 ? "" : `/${folders.join("/")}`}`,
+    container: folders.length === 0 ? null : folders.join("/"),
+    claimed: { name: `${metadata.name}.md` },
   };
 }
 
@@ -168,13 +186,14 @@ function droppedFile(file, code) {
   };
 }
 
-async function normalizeFiles(options, files, dependencies, cache) {
+async function normalizeFiles(options, files, dependencies) {
+  const pathOf = folderPaths(options, dependencies);
   const items = [];
   const dropped = [];
   for (const file of files) {
     if (file.mimeType === FOLDER_MIME) continue;
     try {
-      items.push(await normalizedFile(options, file, dependencies, cache));
+      items.push(await normalizedFile(options, file, dependencies, pathOf));
     } catch (error) {
       if (
         error instanceof KitRefusal &&
@@ -225,12 +244,7 @@ async function snapshotPage(options, cursor, dependencies) {
   ) {
     throw new KitRefusal("google_provider_response_invalid", "drive files");
   }
-  const normalized = await normalizeFiles(
-    options,
-    answer.files.map(fileMetadata),
-    dependencies,
-    new Map(),
-  );
+  const normalized = await normalizeFiles(options, answer.files.map(fileMetadata), dependencies);
   const next =
     answer.nextPageToken === undefined
       ? { phase: "changes", pageToken: cursor.changeToken }
@@ -268,7 +282,7 @@ async function changesPage(options, cursor, dependencies) {
     .filter((change) => change?.removed !== true && change?.file !== undefined)
     .map((change) => fileMetadata(change.file))
     .filter((file) => file.ownedByMe === true && file.trashed !== true);
-  const normalized = await normalizeFiles(options, files, dependencies, new Map());
+  const normalized = await normalizeFiles(options, files, dependencies);
   const pageToken = answer.nextPageToken ?? answer.newStartPageToken;
   if (typeof pageToken !== "string") {
     throw new KitRefusal("google_provider_response_invalid", "drive change token");

package/src/google/gmail.js

@@ -5,6 +5,9 @@ import { GOOGLE_SCOPES } from "./oauth.js";
 
 const GMAIL_ORIGIN = "https://gmail.googleapis.com";
 const EXCLUDED_LABELS = ["SPAM", "TRASH"];
+const PLACES = ["INBOX", "SENT", "DRAFT"];
+const ARCHIVED = "All Mail";
+const CLAIMED_HEADERS = ["from", "to", "cc", "subject"];
 
 function cursorOf(value) {
   if (value === null) return { mode: "messages", pageToken: null, historyId: null };
@@ -54,6 +57,7 @@ function header(message, name) {
 function normalizedMessage(message) {
   if (
     typeof message?.id !== "string" ||
+    typeof message.threadId !== "string" ||
     typeof message.historyId !== "string" ||
     !/^\d+$/.test(message.historyId) ||
     typeof message.internalDate !== "string" ||
@@ -85,7 +89,87 @@ function normalizedMessage(message) {
     author,
     url: `https://mail.google.com/mail/u/0/#all/${encodeURIComponent(message.id)}`,
     attachments: [],
-    container: `google/gmail/${message.labelIds[0] ?? "mail"}`,
+  };
+}
+
+function claimedMessage(message, observedAt) {
+  const day = observedAt.slice(0, 10);
+  const subject = header(message, "subject");
+  const claimed = { name: subject === null || subject === "" ? `${day}.md` : `${day}-${subject}.md` };
+  for (const field of CLAIMED_HEADERS) {
+    const value = header(message, field);
+    if (value !== null) claimed[field] = value;
+  }
+  return claimed;
+}
+
+function labelOf(labelIds, labels) {
+  const [user] = labelIds
+    .map((id) => labels.get(id))
+    .filter((label) => label?.type === "user")
+    .map((label) => label.name)
+    .sort();
+  return user ?? PLACES.find((id) => labelIds.includes(id)) ?? ARCHIVED;
+}
+
+async function labelsOf(shared, dependencies) {
+  const answer = await googleJson(
+    { ...shared, url: `${GMAIL_ORIGIN}/gmail/v1/users/me/labels` },
+    dependencies,
+  );
+  if (
+    !Array.isArray(answer.labels) ||
+    answer.labels.some(
+      (label) =>
+        typeof label?.id !== "string" ||
+        typeof label.name !== "string" ||
+        typeof label.type !== "string",
+    )
+  ) {
+    throw new KitRefusal("google_provider_response_invalid", "gmail labels");
+  }
+  return new Map(answer.labels.map((label) => [label.id, label]));
+}
+
+async function threadSubject(shared, threadId, dependencies) {
+  const url = new URL(`/gmail/v1/users/me/threads/${encodeURIComponent(threadId)}`, GMAIL_ORIGIN);
+  url.searchParams.set("format", "metadata");
+  url.searchParams.set("metadataHeaders", "Subject");
+  const thread = await googleJson(
+    { ...shared, url: url.toString(), notFoundCode: "google_gmail_item_missing" },
+    dependencies,
+  );
+  if (
+    !Array.isArray(thread.messages) ||
+    thread.messages.length === 0 ||
+    thread.messages.some(
+      (message) => typeof message?.internalDate !== "string" || !/^\d+$/.test(message.internalDate),
+    )
+  ) {
+    throw new KitRefusal("google_provider_response_invalid", "gmail thread");
+  }
+  const [opening] = [...thread.messages].sort(
+    (left, right) => Number(left.internalDate) - Number(right.internalDate),
+  );
+  const subject = header(opening, "subject");
+  return subject === "" ? null : subject;
+}
+
+function placement(shared, dependencies) {
+  let labels = null;
+  const subjects = new Map();
+  return async (message, item) => {
+    labels ??= await labelsOf(shared, dependencies);
+    if (!subjects.has(message.threadId)) {
+      subjects.set(message.threadId, await threadSubject(shared, message.threadId, dependencies));
+    }
+    const label = labelOf(message.labelIds, labels);
+    const subject = subjects.get(message.threadId);
+    return {
+      ...item,
+      container: subject === null ? label : `${label}/${subject}`,
+      claimed: claimedMessage(message, item.observedAt),
+    };
   };
 }
 
@@ -202,6 +286,7 @@ export async function gmailPage(options, dependencies = {}) {
     throw new KitRefusal("google_provider_response_invalid", "gmail cursor");
   }
   const identifiers = referencesOf(answer, cursor.mode);
+  const placed = placement(shared, dependencies);
   const items = [];
   const dropped = [];
   for (const identifier of identifiers) {
@@ -216,7 +301,9 @@ export async function gmailPage(options, dependencies = {}) {
         dependencies,
       );
       const normalized = normalizedMessage(detail);
-      if (!detail.labelIds.some((label) => EXCLUDED_LABELS.includes(label))) items.push(normalized);
+      if (!detail.labelIds.some((label) => EXCLUDED_LABELS.includes(label))) {
+        items.push(await placed(detail, normalized));
+      }
     } catch (error) {
       if (
         error instanceof KitRefusal &&

package/src/workspace.js

@@ -201,6 +201,13 @@ export async function workspacePrerequisites(host, image) {
   if (version.status !== 0 || version.stdout.trim() === "") {
     return { supported: false, refusal: "the container runtime daemon did not answer a version" };
   }
+  const swap = await docker(host, ["info", "--format", "{{.SwapLimit}}"]);
+  if (swap.status !== 0 || swap.stdout.trim() !== "true") {
+    return {
+      supported: false,
+      refusal: "the container runtime cannot enforce the workspace memory and swap ceiling",
+    };
+  }
   const formatter = await docker(host, [
     "run",
     "--rm",