@agentshouse/kit 0.1.0-alpha.36 → 0.1.0-alpha.37

package/bootstrap.json

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

package/docs/configuration.md

@@ -0,0 +1,104 @@
+# Configuration
+
+`kit.json` in Kit home is the one configuration file. Every section below is
+required; a file that omits one is refused.
+
+```json
+{
+  "availability": "continuous",
+  "execution_authority": "allow",
+  "migrators": [],
+  "instances": [
+    {
+      "id": "acme",
+      "preset": "custom",
+      "services": [
+        {
+          "service": "notes",
+          "source_ref": "src_acme_notes",
+          "rooms": ["work-room"],
+          "backfill": { "days": 30 },
+          "connector": {
+            "command": ["/usr/local/bin/acme-export", "--ndjson"],
+            "timeout_ms": 120000,
+            "environment": { "ACME_REGION": "eu" },
+            "secrets": {
+              "ACME_TOKEN": { "environment": "ACME_TOKEN_SOURCE" },
+              "ACME_KEY": { "file": "/run/secrets/acme-key" }
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "clients": [
+    {
+      "kind": "claude-code",
+      "settings": "/home/ada/.claude/settings.json"
+    }
+  ],
+  "host": null,
+  "skills": true
+}
+```
+
+- `availability`: `"continuous"` for a computer that stays online,
+  `"intermittent"` for a laptop.
+- `execution_authority`: `"allow"` or `"refuse"`, this computer's answer to
+  every permission request an agent makes.
+- `instances`: your own sources, each with a `custom` connector (below).
+- `clients`: agent clients outside Kit whose settings get House's session-start
+  hook. `claude-code` is the one supported kind; declare `[]` for none.
+- `migrators`: `[]` unless you run a migrator.
+- `host`: `null` unless this computer reports its capacity to House.
+- `skills`: `true` accepts the Skill set, `false` declines it. The connect
+  command sets it.
+
+Agents and agent CLIs are chosen in House, not here. Send your changes to
+House with:
+
+```sh
+kit apply
+```
+
+## Secrets
+
+Never write a secret into `kit.json`. Under `secrets`, name an environment
+variable (`{ "environment": "NAME" }`) or a file (`{ "file": "/path" }`); Kit
+passes its value to the connector only.
+
+## Custom connectors
+
+A connector is your own command. Kit runs it without a shell, with only `PATH`,
+`environment` and the resolved secrets, and never gives it a House credential.
+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 }
+```
+
+The command prints NDJSON: `item` lines, then at most one `cursor` line.
+`cursor` in the next request is the last one it printed.
+
+```
+{"type":"item","namespace":"acme/notes","native_object_id":"note-91","native_version":"7","observed_at":"2026-08-20T09:15:00.000Z","body":"the note","author":"ada","url":"https://acme.example/notes/91","attachments":[{"url":"https://acme.example/files/1","name":"plan.pdf"}]}
+{"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.
+
+`backfill` bounds the first capture: `{ "days": 30 }`, `{ "count": 500 }` or
+`{ "all": true }`.
+
+```sh
+kit source capture acme          # capture every service of an instance now
+kit source capture acme notes    # one service
+kit source status acme           # health, cursor, gaps and unsaved files
+kit source retry-files acme      # save files a capture could not save
+kit source reset acme notes      # start again from the backfill boundary
+```

package/docs/google.md

@@ -0,0 +1,33 @@
+# Google sources
+
+You add Gmail, Calendar and Drive sources in the House App: an account name you
+choose, the service, the Rooms it goes to, and how much history the first
+capture takes. Nothing is configured on this computer.
+
+Each service captures, read-only:
+
+- Gmail: every message except Spam and Trash.
+- Calendar: the account's primary calendar.
+- Drive: the files the account owns.
+
+## Signing in
+
+Kit ships no Google OAuth client. Each account signs in with your own:
+
+1. In your Google Cloud project, create an OAuth client of type **Desktop app**
+   and enable the API of each service you use.
+2. When House asks, enter the client id and secret on its page.
+3. Approve Google's consent. Google then sends the browser to a
+   `http://127.0.0.1:<port>/` address that does not load; copy that whole
+   address and paste it into the House page.
+
+Kit then captures each signed-in source every 15 minutes.
+
+```sh
+kit source capture work          # capture every source of the account now
+kit source capture work gmail    # one service
+kit source status work
+```
+
+If `kit source status` reports `api_disabled`, enable the API it names in your
+Google Cloud project.

package/docs/linux.md

@@ -0,0 +1,46 @@
+# Linux
+
+Run the Linux command from the [README](../README.md#connect-a-computer) in a
+terminal. It needs `bash`, `curl` and Docker Engine.
+
+## Docker Engine
+
+- A Docker Engine that already answers is used as it is, on any distribution.
+- On Ubuntu 22.04, 24.04 or 26.04 LTS, anything missing is installed from
+  Docker's own apt repository through `sudo`, which asks for your password.
+  The command starts the `docker` service and adds you to the `docker` group.
+- Ubuntu packages that conflict with Docker's (`docker.io`, `docker-compose`,
+  `docker-compose-v2`, `docker-doc`, `docker-buildx`, `podman-docker`,
+  `containerd`, `runc`) are not removed for you: remove them and run again.
+- On any other distribution, install Docker Engine first.
+
+A new `docker` group membership applies from your next sign-in. If a later run
+says so, sign out and back in, then run the command again.
+
+## What it creates
+
+- `~/.house-kit`: Kit home, with your credential and `kit.json`.
+- `~/AgentsHouse`: your workspace, mounted in the container as
+  `/agents/house`. Pass `--workspace /absolute/path` to use another directory.
+
+Both are readable only by you. The credential is never printed.
+
+## Updating
+
+Run a newer release's command. While an Agent session is still running, the
+update names it and leaves Kit as it is; run the command again once it ends.
+Your credential, Kit home and workspace are kept.
+
+## Pushing a working copy
+
+From a directory under your workspace, such as a Room copy under
+`working-copies/rooms/`, run:
+
+```sh
+bash <(curl -fsSL …/connect-linux.sh) house git push --owner
+```
+
+## A House on this computer
+
+`--house http://127.0.0.1:<port>` or `--house http://localhost:<port>` runs Kit
+on the host network so it can reach a House served on this computer.

package/docs/macos.md

@@ -0,0 +1,26 @@
+# macOS
+
+Run the Linux command from the [README](../README.md#connect-a-computer) in
+Terminal. It works on Apple silicon and Intel Macs, including from a terminal
+running under Rosetta.
+
+## Docker Desktop
+
+Kit on a Mac needs Docker Desktop.
+
+- A Docker Desktop that already answers is used as it is.
+- Other engines, such as Colima or OrbStack, are refused.
+- Without `/Applications/Docker.app`, the command downloads Docker Desktop for
+  your chip and installs it through `sudo`, which asks for your password.
+- The command opens Docker Desktop and waits up to five minutes while you
+  accept its terms or finish what its window asks. If it is still not ready,
+  run the command again.
+
+## Notes
+
+- A `--workspace` directory must be one Docker Desktop shares, such as one
+  under `/Users`.
+- A House on this computer (`--house http://127.0.0.1:<port>`) needs host
+  networking enabled in Docker Desktop's settings.
+
+Everything else works as on [Linux](linux.md).

package/docs/telegram.md

@@ -0,0 +1,29 @@
+# Telegram bot
+
+Kit can connect your own Telegram bot so your House conversations appear there.
+The bot token stays on this computer; House never receives it.
+
+1. Create a bot with BotFather and turn on its Threaded Mode.
+2. Send the bot one ordinary private message outside any topic, so Kit can
+   tell the bot is yours.
+3. Connect it, entering the token at the hidden prompt:
+
+   ```sh
+   kit telegram connect
+   ```
+
+4. Serve it; this keeps running until you stop it:
+
+   ```sh
+   kit telegram serve
+   ```
+
+To release the bot:
+
+```sh
+kit telegram disconnect
+```
+
+Run each command through the connect command as the
+[README](../README.md#run-a-kit-command) shows. Only one computer can serve a
+given bot.

package/docs/windows.md

@@ -0,0 +1,37 @@
+# Windows
+
+Run the Windows command from the [README](../README.md#connect-a-computer) in
+the 64-bit Windows PowerShell. It needs Windows 11 23H2 (build 22631) or later
+on `amd64`. Windows Server, Windows 10 and Windows on ARM are refused.
+
+## WSL 2 and Docker Desktop
+
+- A Docker Desktop that already runs Linux containers on WSL 2 is used as it is.
+- Without WSL, the command runs `wsl --install --no-distribution`. Approve the
+  administrator prompt, restart Windows, and run the command again. An old WSL
+  is updated the same way.
+- Without Docker Desktop, the command downloads it and installs it for your
+  account only, without administrator rights.
+- The command starts Docker Desktop and waits up to five minutes while you
+  accept its terms or finish what its window asks. If it is still not ready,
+  run the command again.
+- Windows containers, the Hyper-V engine and other Docker engines are refused.
+
+## What it creates
+
+- `%USERPROFILE%\.house-kit`: Kit home.
+- `%USERPROFILE%\AgentsHouse`: your workspace. Pass
+  `--workspace 'D:\Agents'` to use another directory.
+
+Both are restricted to your Windows account. A path containing a comma is
+refused.
+
+## Notes
+
+- Append `kit` and a command to run it, as on [Linux](linux.md). Each run
+  leaves its exit status in `$LASTEXITCODE`.
+- When a command asks for a secret, such as a Telegram bot token, keep its
+  output on the terminal: with output redirected, what you type is echoed.
+- A House on this computer needs host networking enabled in Docker Desktop's
+  settings.
+- This bootstrap has not yet been run on a real Windows computer.

package/package.json

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