@agentshouse/kit 0.0.1 → 0.1.0-alpha.2

package/src/setup.js

@@ -0,0 +1,185 @@
+import { compiledContract } from "./adapter.js";
+import {
+  agentReadiness,
+  agentSignedIn,
+  guidedAgentLogin,
+  updateDeclaredAgent,
+} from "./agents.js";
+import { readConfiguration } from "./configuration.js";
+import { connectorLogin } from "./connector-login.js";
+import { GUIDED_LOGIN_TIMEOUT_MS } from "./contract.js";
+import { launchBase, prepareLaunchBase } from "./directory.js";
+import {
+  acquireSetup,
+  awaitSecretInput,
+  desiredAgents,
+  maintainControl,
+  openSession,
+  reportAgentCapabilities,
+  reportLogin,
+  reportSetup,
+} from "./house.js";
+import { KitRefusal } from "./refusal.js";
+
+function cancelled(error) {
+  return error instanceof KitRefusal && error.code === "kit_command_cancelled";
+}
+
+function agentModule(context, kind) {
+  const recipe = compiledContract(kind).guidedLogin;
+  return {
+    category: "agent",
+    name: kind,
+    login: { integration: kind, instance: kind, service: kind },
+    install: async () => {
+      const updated = await updateDeclaredAgent(
+        { directory: context.directory, at: context.dependencies.now?.() },
+        kind,
+        context.dependencies,
+      );
+      if (updated.release === null) throw new KitRefusal("kit_agent_not_installed", kind);
+    },
+    signedIn: () => agentSignedIn(context.directory, kind, context.dependencies),
+    guided: recipe === null ? null : guidedAgentLogin(context.directory, kind, recipe),
+  };
+}
+
+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,
+            }),
+  };
+}
+
+async function present(context, episode, ceremony, signal) {
+  for (;;) {
+    const relayed = await awaitSecretInput(context.session, episode, ceremony, signal);
+    if (relayed.collected !== null) return relayed.collected;
+  }
+}
+
+async function guidedLogin(context, module) {
+  let opened;
+  try {
+    opened = await reportLogin(context.session, module.login, "renewal_required", context.signal);
+  } catch (error) {
+    if (error instanceof KitRefusal && error.code === "kit_login_renewal_unsupported") {
+      return "unavailable";
+    }
+    throw error;
+  }
+  if (opened.episode === null) throw new KitRefusal("kit_login_rejected", module.name);
+  const bound = AbortSignal.any([
+    context.signal,
+    AbortSignal.timeout(context.dependencies.guidedLoginTimeoutMs ?? GUIDED_LOGIN_TIMEOUT_MS),
+  ]);
+  const outcome = await module.guided({
+    present: (ceremony, signal) => present(context, opened.episode, ceremony, signal),
+    signal: bound,
+  });
+  if (context.signal.aborted) throw new KitRefusal("kit_command_cancelled");
+  return outcome;
+}
+
+async function settleLogin(context, module) {
+  try {
+    await reportLogin(context.session, module.login, "authenticated", context.signal);
+  } catch (error) {
+    if (error instanceof KitRefusal && error.code === "kit_login_renewal_unsupported") return;
+    throw error;
+  }
+}
+
+async function signedIn(module) {
+  try {
+    return await module.signedIn();
+  } catch (error) {
+    if (cancelled(error)) throw error;
+    return false;
+  }
+}
+
+async function setUpModule(context, module) {
+  const summary = (status, reason = null) => ({
+    category: module.category,
+    name: module.name,
+    status,
+    reason,
+  });
+  if (module.install !== null) {
+    try {
+      await module.install();
+    } catch (error) {
+      if (cancelled(error)) throw error;
+      return summary("needs_attention", "install_failed");
+    }
+  }
+  if (await signedIn(module)) {
+    await settleLogin(context, module);
+    return summary("skipped");
+  }
+  if (module.guided === null) return summary("needs_attention", "login_unavailable");
+  const outcome = await guidedLogin(context, module);
+  if (outcome === "unavailable") return summary("needs_attention", "login_unavailable");
+  if (outcome === "cancelled") return summary("needs_attention", "login_cancelled");
+  if (outcome !== "ready" || !(await signedIn(module))) {
+    return summary("needs_attention", "login_failed");
+  }
+  await settleLogin(context, module);
+  return summary("ready");
+}
+
+export async function runSetup(context, request) {
+  await prepareLaunchBase(launchBase(context.dependencies));
+  const modules = [];
+  for (const kind of context.configuration.agents) {
+    modules.push(await setUpModule(context, agentModule(context, kind)));
+  }
+  for (const instance of context.configuration.instances) {
+    modules.push(await setUpModule(context, connectorModule(context, instance)));
+  }
+  const readiness = await agentReadiness(
+    { directory: context.directory },
+    context.configuration,
+    context.dependencies,
+  );
+  await reportAgentCapabilities(context.session, readiness.agents, context.signal);
+  await reportSetup(context.session, request, modules, context.signal);
+  return modules;
+}
+
+export async function setupEnvironment(options, dependencies = {}) {
+  const configuration = await readConfiguration(options.configuration);
+  const session = await openSession(options, dependencies);
+  return maintainControl(
+    session,
+    async (signal) => {
+      const pending = await acquireSetup(session, signal);
+      if (pending === null) return null;
+      const context = {
+        session,
+        configuration: { ...configuration, agents: await desiredAgents(session, signal) },
+        directory: options.directory,
+        dependencies,
+        signal,
+      };
+      return { request: pending.request, modules: await runSetup(context, pending.request) };
+    },
+    options.signal,
+  );
+}

package/src/source-originals.js

@@ -0,0 +1,116 @@
+import { acceptedVersion, deliveryKey, fileDescriptor } from "./delivery.js";
+import { readOriginalFile, saveCapturedOriginal } from "./original.js";
+import { KitRefusal } from "./refusal.js";
+import { readSourceOriginals, writeSourceOriginals } from "./state.js";
+
+const SETTLED_ASSOCIATION = new Set(["captured_original_not_found"]);
+
+export function sameReference(left, right) {
+  return left.room === right.room && left.record === right.record && left.position === right.position;
+}
+
+export function acceptedOriginals(binding, items, outcome) {
+  const references = [];
+  for (const [index, result] of outcome.items.entries()) {
+    if (result.outcome === "rejected") continue;
+    const item = items[index];
+    const key = deliveryKey(binding, item);
+    for (const [position, attachment] of item.attachments.entries()) {
+      if (attachment.file === undefined) continue;
+      const descriptor = fileDescriptor(attachment.file);
+      for (const room of result.rooms) {
+        references.push({
+          room: room.room,
+          record: room.record,
+          position,
+          accepted_version: acceptedVersion(key, position, descriptor),
+          path: attachment.file.path,
+          descriptor,
+          native_object_id: item.nativeObjectId,
+          original: null,
+          version: null,
+          save: { status: "pending", failure: null },
+          error: null,
+        });
+      }
+    }
+  }
+  return references;
+}
+
+export async function recordAcceptedOriginals(context, binding, items, outcome) {
+  const accepted = acceptedOriginals(binding, items, outcome);
+  if (accepted.length === 0) return accepted;
+  const held = await readSourceOriginals(context.directory, binding.instance, binding.service);
+  const merged = held.map((known) => {
+    const offered = accepted.find((reference) => sameReference(known, reference));
+    return offered === undefined ? known : { ...known, path: offered.path };
+  });
+  merged.push(...accepted.filter((reference) => !held.some((known) => sameReference(known, reference))));
+  await writeSourceOriginals(context.directory, binding.instance, binding.service, merged, context.signal);
+  return accepted;
+}
+
+async function declaredBytes(reference) {
+  try {
+    return await readOriginalFile(reference.path, reference.descriptor.bytes);
+  } catch (refusal) {
+    if (refusal instanceof KitRefusal && refusal.code === "original_bytes_exceeded") return null;
+    throw refusal;
+  }
+}
+
+async function saveReference(context, reference) {
+  const body = await declaredBytes(reference);
+  try {
+    const saved = await saveCapturedOriginal(context.session, {
+      room_ref: reference.room,
+      record: reference.record,
+      position: reference.position,
+      accepted_version: reference.accepted_version,
+      descriptor: reference.descriptor,
+      body,
+      signal: context.signal,
+    });
+    return { ...reference, original: saved.original, version: saved.version, save: saved.save, error: null };
+  } catch (refusal) {
+    if (!(refusal instanceof KitRefusal) || refusal.code === "kit_command_cancelled") throw refusal;
+    return { ...reference, error: refusal.code };
+  }
+}
+
+export async function saveSourceOriginals(context, binding, chosen = () => true) {
+  const held = await readSourceOriginals(context.directory, binding.instance, binding.service);
+  const reported = [];
+  const outstanding = [];
+  for (const reference of held) {
+    if (!chosen(reference)) {
+      outstanding.push(reference);
+      continue;
+    }
+    const settled = await saveReference(context, reference);
+    reported.push(settled);
+    if (settled.save.status !== "saved" && !SETTLED_ASSOCIATION.has(settled.error)) {
+      outstanding.push(settled);
+    }
+  }
+  if (reported.length > 0) {
+    await writeSourceOriginals(
+      context.directory,
+      binding.instance,
+      binding.service,
+      outstanding,
+      context.signal,
+    );
+  }
+  return reported.map((reference) => ({
+    room: reference.room,
+    record: reference.record,
+    position: reference.position,
+    native_object_id: reference.native_object_id,
+    original: reference.original,
+    version: reference.version,
+    save: reference.save,
+    error: reference.error,
+  }));
+}

package/src/source.js

@@ -0,0 +1,286 @@
+import { resolveEnvironment, runCommand } from "./command.js";
+import { declaredServices, readConfiguration, sourceInstance } from "./configuration.js";
+import { connectorRequest, parseConnectorRun } from "./connector.js";
+import { CONNECTOR_OUTPUT_MAX_BYTES } from "./contract.js";
+import {
+  admittedItems,
+  advancedCheckpoint,
+  deliveredItem,
+  deliveryKey,
+  healthOfRun,
+  itemLimit,
+  newCheckpoint,
+  stallOf,
+} from "./delivery.js";
+import { captureBatch, openSession } from "./house.js";
+import { googlePage } from "./google/source.js";
+import { houseAnswered, houseAnsweredFailure, houseFailed, KitRefusal } from "./refusal.js";
+import { recordAcceptedOriginals, sameReference, saveSourceOriginals } from "./source-originals.js";
+import {
+  readCheckpoint,
+  readCoverageGaps,
+  readDroppedItems,
+  readHealth,
+  readSourceOriginals,
+  recordDroppedItems,
+  recordHealth,
+  resetCheckpoints,
+  recordCoverageGaps,
+  writeCheckpoint,
+} from "./state.js";
+
+async function acquire(context, service, checkpoint, limit) {
+  if (context.instance.preset === "google") {
+    return googlePage(
+      {
+        directory: context.directory,
+        instance: context.instance.id,
+        client: context.googleOAuthClient,
+        service,
+        cursor: checkpoint.cursor,
+        limit,
+        backfillFloor:
+          checkpoint.backfill?.kind === "days" ? checkpoint.backfill.floor : null,
+        signal: context.signal,
+      },
+      context.dependencies,
+    );
+  }
+  const run = await runCommand({
+    command: service.connector.command,
+    environment: context.environment,
+    stdin: connectorRequest({ instance: context.instance.id, cursor: checkpoint.cursor, limit }),
+    timeoutMs: service.connector.timeoutMs,
+    outputMaxBytes: CONNECTOR_OUTPUT_MAX_BYTES,
+    signal: context.signal,
+  });
+  if (run.status !== 0) throw new KitRefusal("kit_connector_failed", `${run.status}`);
+  return parseConnectorRun(run.stdout, limit);
+}
+
+async function noteRefusals(context, binding, checkpoint, admitted, outcome) {
+  if (outcome.blocked_routes.length > 0) {
+    await recordCoverageGaps(
+      context.directory,
+      binding.instance,
+      binding.service,
+      outcome.blocked_routes.map((route) => ({
+        room: route.room,
+        code: route.code,
+        gap: route.gap,
+        cursor: checkpoint.cursor,
+      })),
+    );
+  }
+  const dropped = outcome.items.flatMap((result, position) =>
+    result.outcome === "rejected" && result.scope === "item" && result.disposition === "blocked"
+      ? [
+          {
+            delivery_key: deliveryKey(binding, admitted[position]),
+            namespace: admitted[position].namespace,
+            native_object_id: admitted[position].nativeObjectId,
+            code: result.code,
+            dropped_at: context.now().toISOString(),
+          },
+        ]
+      : [],
+  );
+  await recordDroppedItems(context.directory, binding.instance, binding.service, dropped);
+}
+
+async function noteProviderDrops(context, binding, dropped) {
+  if (dropped.length === 0) return;
+  await recordDroppedItems(
+    context.directory,
+    binding.instance,
+    binding.service,
+    dropped.map((item) => ({
+      delivery_key: deliveryKey(binding, item),
+      namespace: item.namespace,
+      native_object_id: item.nativeObjectId,
+      code: item.code,
+      dropped_at: context.now().toISOString(),
+    })),
+  );
+}
+
+async function openCheckpoint(context, service, binding) {
+  const stored = await readCheckpoint(context.directory, binding.instance, binding.service);
+  if (stored !== null) return stored;
+  const opened = newCheckpoint(service.backfill, context.now());
+  await writeCheckpoint(context.directory, binding.instance, binding.service, opened);
+  return opened;
+}
+
+async function runDeliveryLoop(context, service, progress) {
+  const binding = serviceBinding(context, service);
+  let checkpoint = await openCheckpoint(context, service, binding);
+  for (;;) {
+    const limit = itemLimit(checkpoint);
+    const run = await acquire(context, service, checkpoint, limit);
+    await noteProviderDrops(context, binding, run.dropped);
+    const admitted = admittedItems(checkpoint, run.items);
+    let outcome = { items: [], blocked_routes: [] };
+    if (admitted.length > 0) {
+      outcome = await captureBatch(context.session, {
+        sourceRef: service.sourceRef,
+        rooms: service.rooms,
+        items: admitted.map((item) => deliveredItem(binding, item)),
+      });
+      progress.batches += 1;
+      const accepted = await recordAcceptedOriginals(context, binding, admitted, outcome);
+      progress.attempted.push(...accepted);
+      progress.originals.push(
+        ...(await saveSourceOriginals(context, binding, (reference) =>
+          accepted.some((offered) => sameReference(offered, reference)),
+        )),
+      );
+    }
+    await noteRefusals(context, binding, checkpoint, admitted, outcome);
+    const refused = outcome.items.find((result) => result.outcome === "rejected");
+    if (refused !== undefined) {
+      progress.stall = { code: refused.code, disposition: refused.disposition };
+      return;
+    }
+    progress.delivered += admitted.length;
+    if (run.cursor === null) return;
+    const advanced = advancedCheckpoint(checkpoint, run.cursor, admitted.length);
+    await writeCheckpoint(context.directory, binding.instance, binding.service, advanced);
+    const darkened = outcome.blocked_routes.at(-1);
+    if (darkened !== undefined) {
+      progress.stall = stallOf(darkened.code);
+      return;
+    }
+    if (advanced.cursor === checkpoint.cursor) return;
+    if (checkpoint.backfill?.kind === "count" && advanced.backfill === null) return;
+    if (!run.more) return;
+    checkpoint = advanced;
+  }
+}
+
+function serviceBinding(context, service) {
+  return { instance: context.instance.id, service: service.service, sourceRef: service.sourceRef };
+}
+
+async function deliverService(context, service) {
+  const progress = { delivered: 0, batches: 0, stall: null, refused: null, attempted: [], originals: [] };
+  try {
+    const resolved =
+      context.instance.preset === "custom"
+        ? { ...context, environment: await resolveEnvironment(service.connector) }
+        : context;
+    await runDeliveryLoop(resolved, service, progress);
+  } catch (refusal) {
+    if (!(refusal instanceof KitRefusal) || refusal.code === "kit_command_cancelled") throw refusal;
+    progress.stall = stallOf(refusal.code, houseAnsweredFailure(refusal) ? houseFailed(refusal) : null);
+    if (houseAnswered(refusal)) progress.refused = { code: refusal.code, payload: refusal.payload };
+  }
+  const health = healthOfRun(progress.stall);
+  await recordHealth(context.directory, context.instance.id, service.service, {
+    ...health,
+    observed_at: context.now().toISOString(),
+  });
+  return {
+    service: service.service,
+    delivered: progress.delivered,
+    batches: progress.batches,
+    health,
+    refused: progress.refused,
+    originals: [
+      ...progress.originals,
+      ...(await saveSourceOriginals(
+        context,
+        serviceBinding(context, service),
+        (reference) => !progress.attempted.some((attempted) => sameReference(attempted, reference)),
+      )),
+    ],
+  };
+}
+
+export async function captureSource(options, dependencies = {}) {
+  const configuration = await readConfiguration(options.configuration);
+  const instance = sourceInstance(configuration, options.instance);
+  const services = declaredServices(instance, options.service ?? null);
+  const googleOAuthClient =
+    instance.preset === "google" ? dependencies.googleOAuthClient() : null;
+  const session = await openSession(options, dependencies);
+  const context = {
+    instance,
+    session,
+    directory: options.directory,
+    signal: options.signal,
+    now: session.now,
+    dependencies,
+    googleOAuthClient,
+  };
+  const delivered = [];
+  for (const service of services) delivered.push(await deliverService(context, service));
+  return { instance: instance.id, services: delivered };
+}
+
+export async function sourceStatus(options) {
+  const configuration = await readConfiguration(options.configuration);
+  const instance = sourceInstance(configuration, options.instance);
+  const services = declaredServices(instance, options.service ?? null);
+  const reported = [];
+  for (const service of services) {
+    reported.push({
+      service: service.service,
+      source_ref: service.sourceRef,
+      rooms: service.rooms,
+      health: (await readHealth(options.directory, instance.id, service.service)) ?? {
+        state: "pending",
+        category: null,
+        observed_at: null,
+      },
+      checkpoint: await readCheckpoint(options.directory, instance.id, service.service),
+      gaps: await readCoverageGaps(options.directory, instance.id, service.service),
+      dropped: await readDroppedItems(options.directory, instance.id, service.service),
+      originals: (await readSourceOriginals(options.directory, instance.id, service.service)).map(
+        (reference) => ({
+          room: reference.room,
+          record: reference.record,
+          position: reference.position,
+          native_object_id: reference.native_object_id,
+          save: reference.save,
+          error: reference.error,
+        }),
+      ),
+    });
+  }
+  return { instance: instance.id, preset: instance.preset, services: reported };
+}
+
+export async function retrySourceOriginals(options, dependencies = {}) {
+  const configuration = await readConfiguration(options.configuration);
+  const instance = sourceInstance(configuration, options.instance);
+  const services = declaredServices(instance, options.service ?? null);
+  const context = { instance, directory: options.directory, signal: options.signal };
+  const outstanding = [];
+  for (const service of services) {
+    outstanding.push((await readSourceOriginals(options.directory, instance.id, service.service)).length);
+  }
+  if (outstanding.some((count) => count > 0)) context.session = await openSession(options, dependencies);
+  const retried = [];
+  for (const [position, service] of services.entries()) {
+    retried.push({
+      service: service.service,
+      originals:
+        outstanding[position] === 0
+          ? []
+          : await saveSourceOriginals(context, serviceBinding(context, service)),
+    });
+  }
+  return { instance: instance.id, services: retried };
+}
+
+export async function resetSource(options, dependencies = {}) {
+  const configuration = await readConfiguration(options.configuration);
+  const instance = sourceInstance(configuration, options.instance);
+  declaredServices(instance, options.service);
+  await openSession(options, dependencies);
+  return {
+    instance: instance.id,
+    services: await resetCheckpoints(options.directory, instance.id, options.service),
+  };
+}

package/src/starter-set/grilling/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/starter-set/grilling/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+---
+
+<!-- Vendored from mattpocock/skills at commit 6654f6b60cd9d5be8b54c6fafe44346dabeb3b76 (skills/productivity/grilling). MIT licensed — see LICENSE in this directory. -->
+
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

package/src/starter-set/grilling/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Grilling"
+  short_description: "Stress-test thinking a round of questions at a time"

package/src/starter-set.js

@@ -0,0 +1,17 @@
+import { cp, mkdir, symlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const AGENTS_INSTRUCTION = "The agents.house `house` CLI is available: run `house --help`.\n";
+const GRILLING_SOURCE = fileURLToPath(new URL("starter-set/grilling/", import.meta.url));
+
+export async function seedStarterSet(target) {
+  await mkdir(target, { recursive: true });
+  await writeFile(join(target, "AGENTS.md"), AGENTS_INSTRUCTION);
+  await symlink("AGENTS.md", join(target, "CLAUDE.md"));
+  const skills = join(target, ".agents", "skills");
+  await mkdir(skills, { recursive: true });
+  await cp(GRILLING_SOURCE, join(skills, "grilling"), { recursive: true });
+  await mkdir(join(target, ".claude"), { recursive: true });
+  await symlink(join("..", ".agents", "skills"), join(target, ".claude", "skills"));
+}