@agentshouse/kit 0.1.0-alpha.26 → 0.1.0-alpha.27

package/src/google/gateway.js

@@ -84,7 +84,7 @@ async function googleResponse(options, dependencies) {
         attempt -= 1;
         continue;
       }
-      await revokeGoogleAuthorization(options.directory, options.instance, options.requiredScopes);
+      await revokeGoogleAuthorization(options.directory, options.account, options.requiredScopes);
       throw new KitRefusal("google_authority_revoked");
     }
     if (response.status === 403) {
@@ -98,13 +98,10 @@ async function googleResponse(options, dependencies) {
         throw new KitRefusal("google_provider_unavailable");
       }
       if (reasons.includes("insufficientPermissions")) {
-        await revokeGoogleAuthorization(
-          options.directory,
-          options.instance,
-          options.requiredScopes,
-        );
+        await revokeGoogleAuthorization(options.directory, options.account, options.requiredScopes);
         throw new KitRefusal("google_scope_revoked");
       }
+      if (reasons.includes("accessNotConfigured")) throw new KitRefusal("api_disabled");
       throw new KitRefusal("google_provider_unavailable");
     }
     if (RETRYABLE_STATUS.has(response.status) && attempt + 1 < RETRY_LIMIT) {

package/src/google/gmail.js

@@ -4,6 +4,7 @@ import { googleJson } from "./gateway.js";
 import { GOOGLE_SCOPES } from "./oauth.js";
 
 const GMAIL_ORIGIN = "https://gmail.googleapis.com";
+const EXCLUDED_LABELS = ["SPAM", "TRASH"];
 
 function cursorOf(value) {
   if (value === null) return { mode: "messages", pageToken: null, historyId: null };
@@ -88,18 +89,36 @@ function normalizedMessage(message) {
   };
 }
 
-async function currentHistoryId(common, dependencies) {
-  const profile = await googleJson(
-    { ...common, url: `${GMAIL_ORIGIN}/gmail/v1/users/me/profile` },
-    dependencies,
-  );
+function common(options) {
+  return {
+    directory: options.directory,
+    account: options.account,
+    requiredScopes: [GOOGLE_SCOPES.gmail],
+    signal: options.signal,
+  };
+}
+
+async function profileOf(shared, dependencies) {
+  return googleJson({ ...shared, url: `${GMAIL_ORIGIN}/gmail/v1/users/me/profile` }, dependencies);
+}
+
+async function currentHistoryId(shared, dependencies) {
+  const profile = await profileOf(shared, dependencies);
   if (typeof profile.historyId !== "string" || !/^\d+$/.test(profile.historyId)) {
     throw new KitRefusal("google_provider_response_invalid", "gmail profile");
   }
   return profile.historyId;
 }
 
-function listUrl(selection, cursor, limit, backfillFloor) {
+export async function gmailEmail(options, dependencies = {}) {
+  const profile = await profileOf(common(options), dependencies);
+  if (typeof profile.emailAddress !== "string") {
+    throw new KitRefusal("google_provider_response_invalid", "gmail profile");
+  }
+  return profile.emailAddress;
+}
+
+function listUrl(cursor, limit, backfillFloor) {
   const url = new URL(
     cursor.mode === "messages"
       ? "/gmail/v1/users/me/messages"
@@ -109,7 +128,6 @@ function listUrl(selection, cursor, limit, backfillFloor) {
   url.searchParams.set("maxResults", `${limit}`);
   if (cursor.pageToken !== null) url.searchParams.set("pageToken", cursor.pageToken);
   if (cursor.mode === "messages") {
-    for (const label of selection.labels) url.searchParams.append("labelIds", label);
     if (backfillFloor !== null && backfillFloor !== undefined) {
       url.searchParams.set("q", `after:${Math.floor(Date.parse(backfillFloor) / 1000)}`);
     }
@@ -151,22 +169,16 @@ function referencesOf(answer, mode) {
 
 export async function gmailPage(options, dependencies = {}) {
   let cursor = cursorOf(options.cursor);
-  const common = {
-    directory: options.directory,
-    instance: options.instance,
-    client: options.client,
-    requiredScopes: [GOOGLE_SCOPES.gmail],
-    signal: options.signal,
-  };
+  const shared = common(options);
   if (cursor.mode === "messages" && cursor.historyId === null) {
-    cursor = { ...cursor, historyId: await currentHistoryId(common, dependencies) };
+    cursor = { ...cursor, historyId: await currentHistoryId(shared, dependencies) };
   }
   let answer;
   try {
     answer = await googleJson(
       {
-        ...common,
-        url: listUrl(options.selection, cursor, options.limit, options.backfillFloor),
+        ...shared,
+        url: listUrl(cursor, options.limit, options.backfillFloor),
         ...(cursor.mode === "history" ? { notFoundCode: "google_history_expired" } : {}),
       },
       dependencies,
@@ -176,10 +188,10 @@ export async function gmailPage(options, dependencies = {}) {
     cursor = {
       mode: "messages",
       pageToken: null,
-      historyId: await currentHistoryId(common, dependencies),
+      historyId: await currentHistoryId(shared, dependencies),
     };
     answer = await googleJson(
-      { ...common, url: listUrl(options.selection, cursor, options.limit, options.backfillFloor) },
+      { ...shared, url: listUrl(cursor, options.limit, options.backfillFloor) },
       dependencies,
     );
   }
@@ -197,16 +209,14 @@ export async function gmailPage(options, dependencies = {}) {
     try {
       detail = await googleJson(
         {
-          ...common,
+          ...shared,
           notFoundCode: "google_gmail_item_missing",
           url: `${GMAIL_ORIGIN}/gmail/v1/users/me/messages/${encodeURIComponent(identifier)}?format=full`,
         },
         dependencies,
       );
       const normalized = normalizedMessage(detail);
-      if (options.selection.labels.every((label) => detail.labelIds.includes(label))) {
-        items.push(normalized);
-      }
+      if (!detail.labelIds.some((label) => EXCLUDED_LABELS.includes(label))) items.push(normalized);
     } catch (error) {
       if (
         error instanceof KitRefusal &&

package/src/google/oauth.js

@@ -1,8 +1,10 @@
 import { createHash, randomBytes, randomInt } from "node:crypto";
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { readFile, rm } from "node:fs/promises";
 import { KitRefusal } from "../refusal.js";
-import { writeNote } from "../state.js";
+import { notePath, writeNote } from "../state.js";
+import { exclusively } from "../tasks.js";
+
+export const GOOGLE_SOURCES = "google";
 
 export const GOOGLE_SCOPES = Object.freeze({
   gmail: "https://www.googleapis.com/auth/gmail.readonly",
@@ -12,26 +14,30 @@ export const GOOGLE_SCOPES = Object.freeze({
 
 const AUTHORIZATION_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth";
 const TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+const REVOCATION_ENDPOINT = "https://oauth2.googleapis.com/revoke";
 const REFRESH_MARGIN_MS = 60_000;
 const LOOPBACK_PORT_FLOOR = 49152;
 const LOOPBACK_PORT_SPAN = 16384;
 
-function credentialPath(directory, instance) {
-  return join(directory, "state", instance, "credentials", "google.json");
+function credentialPath(directory, account) {
+  return notePath(directory, GOOGLE_SOURCES, account, "credentials");
 }
 
-async function rawAuthorization(directory, instance) {
-  const path = credentialPath(directory, instance);
+async function rawAccount(directory, account) {
+  const path = credentialPath(directory, account);
   let document;
   try {
     document = JSON.parse(await readFile(path, "utf8"));
   } catch (error) {
     if (error.code === "ENOENT") return null;
-    throw new KitRefusal("google_authorization_unreadable", instance);
+    throw new KitRefusal("google_authorization_unreadable", account);
   }
   if (
     typeof document !== "object" ||
     document === null ||
+    typeof document.client?.id !== "string" ||
+    typeof document.client.secret !== "string" ||
+    (document.email !== null && typeof document.email !== "string") ||
     !Array.isArray(document.grants) ||
     document.grants.some(
       (grant) =>
@@ -46,21 +52,27 @@ async function rawAuthorization(directory, instance) {
         grant.scopes.some((scope) => typeof scope !== "string"),
     )
   ) {
-    throw new KitRefusal("google_authorization_unreadable", instance);
+    throw new KitRefusal("google_authorization_unreadable", account);
   }
   return document;
 }
 
-async function writeAuthorization(directory, instance, authorization) {
-  await writeNote(credentialPath(directory, instance), authorization);
+function updateAccount(directory, account, change) {
+  return exclusively(credentialPath(directory, account), async () => {
+    const stored = await rawAccount(directory, account);
+    const changed = change(stored);
+    if (changed !== null) await writeNote(credentialPath(directory, account), changed);
+  });
 }
 
-export async function googleAuthorization(directory, instance) {
-  const authorization = await rawAuthorization(directory, instance);
-  if (authorization === null || authorization.grants.length === 0) return null;
+export async function googleAccount(directory, account) {
+  const stored = await rawAccount(directory, account);
+  if (stored === null) return null;
   return {
-    scopes: [...new Set(authorization.grants.flatMap((grant) => grant.scopes))].sort(),
-    grants: authorization.grants.map((grant) => ({
+    client: { id: stored.client.id, secret: stored.client.secret },
+    email: stored.email,
+    scopes: [...new Set(stored.grants.flatMap((grant) => grant.scopes))].sort(),
+    grants: stored.grants.map((grant) => ({
       accessToken: grant.access_token,
       refreshToken: grant.refresh_token,
       expiresAt: grant.expires_at,
@@ -69,6 +81,15 @@ export async function googleAuthorization(directory, instance) {
   };
 }
 
+export async function googleSignedIn(directory, account, service) {
+  const stored = await rawAccount(directory, account);
+  return stored?.grants.some((grant) => grant.scopes.includes(GOOGLE_SCOPES[service])) === true;
+}
+
+export function recordGoogleEmail(directory, account, email) {
+  return updateAccount(directory, account, (stored) => (stored === null ? null : { ...stored, email }));
+}
+
 function requiredScopesOf(value) {
   if (
     !Array.isArray(value) ||
@@ -80,19 +101,51 @@ function requiredScopesOf(value) {
   return value;
 }
 
-export async function revokeGoogleAuthorization(directory, instance, scopes) {
+export async function revokeGoogleAuthorization(directory, account, scopes) {
   const requiredScopes = requiredScopesOf(scopes);
-  const authorization = await rawAuthorization(directory, instance);
-  if (authorization !== null) {
-    await writeAuthorization(directory, instance, {
-      grants: authorization.grants
-        .map((grant) => ({
-          ...grant,
-          scopes: grant.scopes.filter((scope) => !requiredScopes.includes(scope)),
-        }))
-        .filter((grant) => grant.scopes.length > 0),
+  await updateAccount(directory, account, (stored) =>
+    stored === null
+      ? null
+      : {
+          ...stored,
+          grants: stored.grants
+            .map((grant) => ({
+              ...grant,
+              scopes: grant.scopes.filter((scope) => !requiredScopes.includes(scope)),
+            }))
+            .filter((grant) => grant.scopes.length > 0),
+        },
+  );
+}
+
+async function revokedAtProvider(fetcher, token) {
+  let response;
+  try {
+    response = await fetcher(REVOCATION_ENDPOINT, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ token }).toString(),
     });
+  } catch {
+    throw new KitRefusal("google_provider_unavailable");
   }
+  if (response.status !== 200 && response.status !== 400) {
+    throw new KitRefusal("google_provider_unavailable");
+  }
+}
+
+export async function forgetGoogleAccount(directory, account, kept, dependencies = {}) {
+  const stored = await rawAccount(directory, account);
+  if (stored === null) return;
+  const others = await Promise.all(kept.map((other) => rawAccount(directory, other)));
+  if (stored.email === null || !others.some((held) => held?.email === stored.email)) {
+    for (const grant of stored.grants) {
+      await revokedAtProvider(dependencies.fetch ?? fetch, grant.refresh_token);
+    }
+  }
+  await exclusively(credentialPath(directory, account), () =>
+    rm(credentialPath(directory, account), { force: true }),
+  );
 }
 
 function oauthValue() {
@@ -167,26 +220,9 @@ async function tokenRequest(fetcher, body) {
   return answer;
 }
 
-function configuredClient(client) {
-  if (
-    typeof client?.id !== "string" ||
-    client.id.length === 0 ||
-    typeof client.secret !== "string" ||
-    client.secret.length === 0
-  ) {
-    throw new KitRefusal("google_oauth_client_unconfigured");
-  }
-  return client;
-}
-
 export async function authorizeGoogle(options, dependencies = {}) {
-  const client = configuredClient(options.client);
-  const stored = await rawAuthorization(options.directory, options.instance);
+  const { client } = options;
   const scopes = [...new Set(options.scopes)];
-  const covered = stored?.grants.some((grant) =>
-    scopes.every((scope) => grant.scopes.includes(scope)),
-  );
-  if (covered === true) return { status: "skipped", requestedScopes: [] };
   const verifier = oauthValue();
   const state = oauthValue();
   const redirectUri = loopbackRedirect(dependencies.loopbackPort);
@@ -215,10 +251,11 @@ export async function authorizeGoogle(options, dependencies = {}) {
   }
   const grantedScopes = [...new Set(returnedScopes.length === 0 ? scopes : returnedScopes)].sort();
   const key = grantedScopes.join("\n");
-  const grants = (stored?.grants ?? []).filter((grant) => [...grant.scopes].sort().join("\n") !== key);
-  await writeAuthorization(options.directory, options.instance, {
+  await updateAccount(options.directory, options.account, (stored) => ({
+    client: { id: client.id, secret: client.secret },
+    email: stored?.email ?? null,
     grants: [
-      ...grants,
+      ...(stored?.grants ?? []).filter((grant) => [...grant.scopes].sort().join("\n") !== key),
       {
         access_token: token.access_token,
         refresh_token: refreshToken,
@@ -226,48 +263,51 @@ export async function authorizeGoogle(options, dependencies = {}) {
         scopes: grantedScopes,
       },
     ],
-  });
-  return { status: "ready", requestedScopes: scopes };
+  }));
 }
 
 export async function googleAccessToken(options, dependencies = {}) {
-  const stored = await rawAuthorization(options.directory, options.instance);
+  const stored = await rawAccount(options.directory, options.account);
   const requiredScopes = requiredScopesOf(options.requiredScopes);
   const grant = stored?.grants
     .filter((candidate) => requiredScopes.every((scope) => candidate.scopes.includes(scope)))
     .sort((left, right) => left.scopes.length - right.scopes.length)[0];
   if (grant === undefined) {
-    throw new KitRefusal("google_authorization_required", options.instance);
+    throw new KitRefusal("google_authorization_required", options.account);
   }
   const now = dependencies.now?.() ?? new Date();
   if (options.forceRefresh !== true && Date.parse(grant.expires_at) - now.getTime() > REFRESH_MARGIN_MS) {
     return grant.access_token;
   }
-  const client = configuredClient(options.client);
   let token;
   try {
     token = await tokenRequest(dependencies.fetch ?? fetch, {
-      client_id: client.id,
-      client_secret: client.secret,
+      client_id: stored.client.id,
+      client_secret: stored.client.secret,
       refresh_token: grant.refresh_token,
       grant_type: "refresh_token",
     });
   } catch (error) {
     if (error instanceof KitRefusal && error.code === "google_authority_revoked") {
-      await revokeGoogleAuthorization(options.directory, options.instance, grant.scopes);
+      await revokeGoogleAuthorization(options.directory, options.account, grant.scopes);
     }
     throw error;
   }
-  await writeAuthorization(options.directory, options.instance, {
-    grants: stored.grants.map((candidate) =>
-      candidate === grant
-        ? {
-            ...candidate,
-            access_token: token.access_token,
-            expires_at: new Date(now.getTime() + token.expires_in * 1000).toISOString(),
-          }
-        : candidate,
-    ),
-  });
+  await updateAccount(options.directory, options.account, (current) =>
+    current === null
+      ? null
+      : {
+          ...current,
+          grants: current.grants.map((candidate) =>
+            candidate.refresh_token === grant.refresh_token
+              ? {
+                  ...candidate,
+                  access_token: token.access_token,
+                  expires_at: new Date(now.getTime() + token.expires_in * 1000).toISOString(),
+                }
+              : candidate,
+          ),
+        },
+  );
   return token.access_token;
 }

package/src/google/source.js

@@ -1,25 +1,23 @@
-import { KitRefusal } from "../refusal.js";
-import { gmailPage } from "./gmail.js";
-import { calendarPage } from "./calendar.js";
-import { drivePage } from "./drive.js";
-import { declaredPage } from "./declared.js";
+import { calendarEmail, calendarPage } from "./calendar.js";
+import { driveEmail, drivePage } from "./drive.js";
+import { gmailEmail, gmailPage } from "./gmail.js";
+import { googleAccount, recordGoogleEmail } from "./oauth.js";
 
-export async function googlePage(options, dependencies = {}) {
-  const common = {
-    directory: options.directory,
-    instance: options.instance,
-    client: options.client,
-    selection: options.service.selection,
-    cursor: options.cursor,
-    limit: options.limit,
-    backfillFloor: options.backfillFloor,
-    signal: options.signal,
-  };
-  if (options.service.service === "gmail") return gmailPage(common, dependencies);
-  if (options.service.service === "calendar") return calendarPage(common, dependencies);
-  if (options.service.service === "drive") return drivePage(common, dependencies);
-  if (options.service.declaration !== null) {
-    return declaredPage({ ...common, service: options.service }, dependencies);
-  }
-  throw new KitRefusal("google_service_unsupported", options.service.service);
+const SERVICES = {
+  gmail: { page: gmailPage, email: gmailEmail },
+  calendar: { page: calendarPage, email: calendarEmail },
+  drive: { page: drivePage, email: driveEmail },
+};
+
+export function googlePage(options, dependencies = {}) {
+  return SERVICES[options.service].page(options, dependencies);
+}
+
+export async function recordAccountEmail(context, google) {
+  if ((await googleAccount(context.directory, google.account))?.email !== null) return;
+  const email = await SERVICES[google.service].email(
+    { directory: context.directory, account: google.account, signal: context.signal },
+    context.dependencies,
+  );
+  await recordGoogleEmail(context.directory, google.account, email);
 }

package/src/house.js

@@ -24,6 +24,8 @@ import {
   KIT_SESSIONS_REPORT_PATH,
   KIT_SETUP_ACQUIRE_PATH,
   KIT_SETUP_REPORT_PATH,
+  KIT_SOURCES_DESIRED_PATH,
+  KIT_SOURCES_REPORT_PATH,
   KIT_WORKSPACES_ACQUIRE_PATH,
   LEASE_RENEWAL_MARGIN_MS,
   MCP_PROTOCOL_VERSION,
@@ -172,7 +174,7 @@ async function residentRelay(session, request, signal, draining) {
   }
 }
 
-export async function serveResident(session, directory, signal, drain, push) {
+export async function serveResident(session, directory, signal, drain, push, capture) {
   const socket = residentSocket(directory);
   await mkdir(dirname(socket), { recursive: true, mode: 0o700 });
   await rm(socket, { force: true });
@@ -231,9 +233,14 @@ export async function serveResident(session, directory, signal, drain, push) {
         relayed.set(request.id, cancelled);
         const relaySignal = AbortSignal.any([signal, cancelled.signal]);
         const answered =
-          request.push === undefined
-            ? residentRelay(session, request, relaySignal, draining)
-            : push(request.push, relaySignal).then((pushed) => ({ pushed }));
+          request.push !== undefined
+            ? push(request.push, relaySignal).then((pushed) => ({ pushed }))
+            : request.capture !== undefined
+              ? capture(request.capture, relaySignal).then(
+                  (captured) => ({ captured }),
+                  (error) => ({ refused: error?.code ?? "kit_resident_unavailable" }),
+                )
+              : residentRelay(session, request, relaySignal, draining);
         void answered.then((answer) => {
           relayed.delete(request.id);
           if (!connection.destroyed) writeFrame(connection, { id: request.id, ...answer });
@@ -330,6 +337,12 @@ async function residentDelegation(directory, fetcher) {
     if (answer.pushed === undefined) throw new KitRefusal("kit_resident_unavailable");
     return answer.pushed;
   }
+  async function capture(source, signal) {
+    const answer = await exchange({ capture: source }, signal);
+    if (answer.refused !== undefined) throw new KitRefusal(answer.refused);
+    if (answer.captured === undefined) throw new KitRefusal("kit_resident_unavailable");
+    return answer.captured;
+  }
   async function delegated(url, init = {}) {
     const { authorization, ...headers } = init.headers ?? {};
     if (authorization !== RESIDENT) return fetcher(url, init);
@@ -352,7 +365,7 @@ async function residentDelegation(directory, fetcher) {
       headers: answer.type === null ? {} : { "content-type": answer.type },
     });
   }
-  return { connection, fetch: delegated, push };
+  return { connection, fetch: delegated, push, capture };
 }
 
 export async function openSession(options, dependencies = {}) {
@@ -372,6 +385,7 @@ export async function openSession(options, dependencies = {}) {
   if (resident !== null) {
     session.resident = resident.connection;
     session.push = resident.push;
+    session.capture = resident.capture;
     session.dependencies = { ...dependencies, fetch: resident.fetch };
     return session;
   }
@@ -695,6 +709,30 @@ export async function desiredAgents(session, signal = session.signal) {
   return answer.agents;
 }
 
+export async function desiredSources(session, signal = session.signal) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    KIT_SOURCES_DESIRED_PATH,
+    {},
+    session.dependencies,
+    signal,
+  );
+  if (!Array.isArray(answer?.sources)) throw new KitRefusal("kit_sources_rejected");
+  return answer.sources;
+}
+
+export async function reportSources(session, sources, signal = session.signal) {
+  return houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    KIT_SOURCES_REPORT_PATH,
+    { sources },
+    session.dependencies,
+    signal,
+  );
+}
+
 const HOUSE_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 export async function acquireSetup(session, signal = session.signal) {

package/src/kit-work-stream.js

@@ -5,7 +5,7 @@ import { heldControl } from "./house.js";
 import { KitRefusal } from "./refusal.js";
 
 const PROTOCOL = "house.kit.stream.1";
-const WATCHED_SUBJECTS = ["agents", "working_copy"];
+const WATCHED_SUBJECTS = ["agents", "working_copy", "sources"];
 
 function streamAddress(house) {
   const url = new URL("/kit/stream", house);

package/src/setup.js

@@ -6,7 +6,7 @@ import {
   updateDeclaredAgent,
 } from "./agents.js";
 import { readConfiguration } from "./configuration.js";
-import { connectorLogin } from "./connector-login.js";
+import { customAuthorizationStatus } from "./custom/authorization.js";
 import { GUIDED_LOGIN_TIMEOUT_MS } from "./contract.js";
 import { launchBase, prepareLaunchBase } from "./directory.js";
 import {
@@ -45,24 +45,14 @@ function agentModule(context, kind) {
 }
 
 function connectorModule(context, instance) {
-  const gateway = connectorLogin(instance, context.dependencies);
   return {
     category: "connector",
     name: instance.id,
     login: { integration: instance.preset, instance: instance.id, service: instance.id },
     install: null,
     signedIn: () =>
-      gateway.status(instance, { directory: context.directory, signal: context.signal }),
-    guided:
-      gateway.guided === undefined
-        ? null
-        : ({ present, signal }) =>
-            gateway.guided(instance, {
-              directory: context.directory,
-              dependencies: context.dependencies,
-              present,
-              signal,
-            }),
+      customAuthorizationStatus(instance, { directory: context.directory, signal: context.signal }),
+    guided: null,
   };
 }
 
@@ -144,8 +134,12 @@ async function setUpModule(context, module, install = true) {
   return summary("ready");
 }
 
+export function signInModule(context, module) {
+  return setUpModule(context, module, false);
+}
+
 export function signInWantedAgent(context, kind) {
-  return setUpModule(context, agentModule(context, kind), false);
+  return signInModule(context, agentModule(context, kind));
 }
 
 export async function runSetup(context, request) {