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

package/README.md

@@ -4,12 +4,15 @@ House Kit is a public package repository. Product development is planned and
 coordinated in the [Agents House repository](https://github.com/trof3039/agents.house);
 this repository contains only the package source and its operator documentation.
 
+The Skill set Kit installs is Matt Pocock's
+[`mattpocock/skills`](https://github.com/mattpocock/skills); thank you, Matt.
+
 ## Connect a Linux computer
 
 On Linux `amd64` or `arm64`, run the published, versioned bootstrap once:
 
 ```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.25/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.27/connect-linux.sh)
 ```
 
 The bootstrap first establishes Docker Engine from what it observes on the
@@ -40,13 +43,18 @@ and starts the container with Docker's `unless-stopped` lifecycle. Pass
 `--workspace /absolute/path` for one other workspace root or `--manual` for
 the existing URL and one-time-code login route. `--house <origin>` selects
 another House and is retained in Kit home. A repeated invocation reuses the
-same container, credential and Environment.
+same container, credential and Environment. Every invocation that is not a
+forwarded command also sets `skills` in Kit's configuration: `--no-skills`
+declines [the Skill set](#the-skill-set) and an invocation without it accepts
+the set again.
 
 Running a newer release's bootstrap the same way is the only update. When the
 installed container runs another image, the bootstrap pulls this release's
 image and asks the running resident Kit to drain with `kit resident drain`. The
-resident stops acquiring Runs, resumptions, setup and agent CLI work, while the
-Sessions it supervises keep their renewal, owner stops, answers and reports.
+resident stops acquiring Runs, resumptions, setup, agent CLI work, Google
+sign-ins and scheduled Google captures, while the Sessions it supervises keep
+their renewal, owner stops, answers and reports and a capture already running
+finishes.
 While any Agent Session is still running or unreported, including one whose Run
 was being acquired when the drain began, the bootstrap names it and leaves the
 container as it is; rerun it once they end. Once nothing remains,
@@ -135,21 +143,17 @@ anything reaches House.
 
 ## Building the package
 
-The repository checkout is the development source. Build the package
-that can be published by supplying House's dedicated installed-application
-Google OAuth client, its id and its client secret:
+The repository checkout is the development source. Build the package that can
+be published:
 
 ```sh
-HOUSE_KIT_GOOGLE_OAUTH_CLIENT_ID=kit-client.apps.googleusercontent.com \
-HOUSE_KIT_GOOGLE_OAUTH_CLIENT_SECRET=GOCSPX-kit-installed-app \
 npm run build
 ```
 
-The command writes the publishable package to `dist/package`. Both values are
-public instance content fixed into that package at build time: Google issues an
-installed application's client secret without treating it as confidential, and
-still requires it in every token request. The installed Kit does not read either
-from its runtime environment and never requests them from House.
+The command writes the publishable package to `dist/package`. It reads no
+environment and ships no provider OAuth client: each Google account signs in
+with the User's own client, as [the Google preset](#the-google-preset)
+describes.
 
 Runtime dependencies stay minimal and exactly pinned in `package.json` and
 `package-lock.json`: House's own `@agentshouse/mdmodel`, `yaml`, which reads
@@ -227,7 +231,8 @@ never printed by Kit.
       "settings": "/home/ada/.claude/settings.json"
     }
   ],
-  "host": null
+  "host": null,
+  "skills": true
 }
 ```
 
@@ -247,13 +252,19 @@ mode: `"intermittent"` for a laptop or other normally offline placement,
 any other value refuses as `kit_configuration_invalid`; `kit apply` sends the
 declared mode with the rest of the desired state. An
 instance declares one or more services, and under the `custom` preset each
-service owns the command that produces it.
+service owns the command that produces it. The Kit reads only `custom` instances
+and passes over any other entry of `instances`.
 
 `host` declares the Linux host this installation measures for
 [host capacity reporting](#host-capacity). `null` declares that this Kit reports
 no capacity; the section is required like the others, so a host is measured only
 where the Environment owner says so.
 
+`skills` is this Environment's choice of [the Skill set](#the-skill-set):
+`true` accepts it and `false` declines it. A configuration that omits it
+accepts the set. The bootstrap writes it on every invocation that is not a
+forwarded command.
+
 `clients` is the local Agent client catalogue and never leaves the installation.
 Each entry names one client whose lifecycle hook configuration this Kit
 reconciles: `kind` is `claude-code`, the one client this Kit installs a hook
@@ -348,119 +359,81 @@ refuses as `kit_hook_rejected` instead of leaving whatever was installed before.
 
 ## The Google preset
 
-The published Kit is built with one House-owned Google installed-application
-OAuth client. Its id and client secret are public build-time instance content,
-not House secrets and not values served by House at run time. Google refresh
-and access tokens remain in the installation's local credential store.
-
-Each Google instance represents one Google account, and one Kit installation
-may declare as many as the User has. Each instance owns its own local Google
-authorization, selectors, Source references, Room routes, checkpoints and
-health under `state/<instance>/`; the installation's one `kit login` covers
-them all, and no instance can read another's provider credential.
+House holds this Environment's Google Sources, and its owner sets them in the
+App. Each entry names an account name the owner chooses, one service -
+`gmail`, `calendar` or `drive` - the Rooms it goes to, and what its first
+capture takes: `{ "new": true }` for new activity only, `{ "days": n }`,
+`{ "items": n }` or `{ "all": true }`. Neither the configuration file nor any
+command on this computer declares one.
+
+Each service captures a fixed corpus under its own read-only scope: Gmail every
+message but Spam and Trash, Calendar the account's primary calendar, and Drive
+the files the account owns.
+
+The resident reads the list from `/kit/sources/desired` each time its Kit
+control stream connects and each time House signals `sources` on it, then
+reconciles:
+
+- a new entry gets its local state and is captured once its account is signed
+  in for its service;
+- a changed entry's Rooms take effect on its next capture;
+- an entry House no longer lists stops, and its checkpoint, health, gaps,
+  dropped items and unsaved originals are deleted;
+- an account left with no entry has each of its grants revoked at Google's
+  revocation endpoint and its credentials, its OAuth client included, deleted.
+  Google's revocation ends every grant the Google user gave the client's
+  project, so when another listed account is signed in to the same Google user,
+  the Kit deletes the local credentials and revokes nothing.
+
+It then reports every entry to `/kit/sources/report`, and reports an entry
+again after each sign-in and each capture: `signed_out` while its
+account holds no grant for its service, `failed` with its cause code when its
+last capture failed, and `ready` otherwise, each with the account's signed-in
+email once the Kit knows it.
+
+The Kit ships no Google OAuth client. Each account signs in with the User's
+own: an OAuth client of type Desktop app in the User's Google Cloud project,
+with the service's API enabled there. An entry whose account holds no grant for
+its service opens a login renewal for integration `google`, instance the
+account name and service the entry's service, and presents its ceremony on
+House's owner-authenticated page, so the owner's browser never has to reach
+this Environment. When the account has no client yet, the page first collects
+the client id and secret. It then links to Google's consent for that service's
+scope only; Google sends the browser to a `http://127.0.0.1:<port>/` address
+that nothing answers, and the owner pastes that whole address into the page.
+The Kit accepts it only when it carries the state its own consent issued,
+exchanges the code with its PKCE verifier and the account's client, and stores
+the grant beside the client in `state/google/credentials/<account>.json`. The
+collected values pass through House's live relay only; neither they nor any
+token enter a report, a log or anything House stores. Adding a
+service to a signed-in account asks only for that service's consent, and each
+service keeps its own grant. An address that answers another consent, or a code
+Google refuses to exchange, stores nothing; a declined consent or a ceremony
+that outlives its ten-minute bound cancels the sign-in, and the Kit tries again
+at the next reconciliation.
+
+The resident captures each signed-in entry every 15 minutes, with no command.
+An occurrence never overlaps its entry's previous one, and one missed while the
+resident was stopped is not replayed: the next resumes from the checkpoint. The
+first capture fixes the initial choice's boundary, so `new` captures nothing
+that existed then and everything that arrives after.
 
-```json
-{
-  "availability": "intermittent",
-  "execution_authority": "refuse",
-  "migrators": [],
-  "instances": [
-    {
-      "id": "google-account",
-      "preset": "google",
-      "scopes": ["https://www.googleapis.com/auth/contacts.readonly"],
-      "services": [
-        {
-          "service": "gmail",
-          "source_ref": "src_google_mail",
-          "rooms": ["work-room"],
-          "backfill": { "days": 30 },
-          "selection": { "labels": ["INBOX"] }
-        },
-        {
-          "service": "calendar",
-          "source_ref": "src_google_calendar",
-          "rooms": ["work-room"],
-          "backfill": { "all": true },
-          "selection": { "calendars": ["primary"] }
-        },
-        {
-          "service": "drive",
-          "source_ref": "src_google_drive",
-          "rooms": ["work-room"],
-          "backfill": { "count": 500 },
-          "selection": { "files": ["file-id"], "folders": ["folder-id"] }
-        }
-      ]
-    }
-  ],
-  "clients": [],
-  "host": null
-}
+```sh
+kit source capture work        # one occurrence of every entry of the account now
+kit source capture work gmail  # one occurrence of one entry now
+kit source status work
 ```
 
-Google authorization is incremental. Enabling Gmail requests only Gmail's
-read-only scope; Calendar and Drive request their own read-only scopes only
-when enabled. Each service scope set has its own local provider grant, so a
-later authorization never widens or replaces a sibling service's grant.
-Additional Google API scopes are declared once on the preset instance and
-remain local; a declared service names only scopes that instance already
-holds. Drive requires at least one explicit file or folder selection and never
-defaults to the whole account.
-
-A Google API outside the three curated services may use the closed declared
-service schema. The declaration is data only: no script or executable transform
-is loaded. Its host must be a Google API domain and it runs under scopes the
-instance already holds.
-
-```json
-{
-  "service": "people",
-  "source_ref": "src_google_people",
-  "rooms": ["work-room"],
-  "backfill": { "all": true },
-  "declaration": {
-    "host": "people.googleapis.com",
-    "path": "/v1/people/me/connections",
-    "query": { "personFields": "names,emailAddresses,metadata" },
-    "page_size": "pageSize",
-    "scopes": ["https://www.googleapis.com/auth/contacts.readonly"],
-    "page_token": {
-      "request": "pageToken",
-      "response": "nextPageToken",
-      "checkpoint_request": "syncToken",
-      "checkpoint_response": "nextSyncToken"
-    },
-    "items": "connections",
-    "fields": {
-      "native_id": "resourceName",
-      "native_version": "etag",
-      "provider_modified_at": "metadata.sources.0.updateTime",
-      "observed_at": "metadata.sources.0.updateTime",
-      "body": ["names.0.displayName", "emailAddresses.0.value"],
-      "container": "metadata.sources.0.type"
-    }
-  }
-}
-```
+`kit source capture` and `kit source status` take the account name where a
+custom connector takes its instance; a name House lists as an account is read
+as the account. While the resident runs, it performs the requested occurrence
+itself, after any occurrence of that entry already running.
 
-A Google instance signs in only through [Environment setup](#environment-setup),
-on House's owner-authenticated page, so the owner's browser never has to reach
-this Environment. For each enabled service whose scopes the instance does not
-hold yet, the page links to Google's consent for exactly that service's scopes.
-Google then sends the browser to a `http://127.0.0.1:<port>/` address that
-nothing answers: the owner copies that whole address from the address bar and
-pastes it into the page. The Kit accepts it only when it carries the state its
-own consent issued, exchanges the code with its PKCE verifier and the built
-client, and stores the grant locally. An address that answers another consent,
-or a code Google refuses to exchange, fails the login and stores nothing; a
-declined consent cancels it. Grants already completed for earlier services stay.
-
-`kit source sign-in <instance>` signs in a custom connector instance through
-its own command, described below. It skips an instance whose local
-authorization is already valid and answers `ready`, `skipped`, or
-`needs_attention`. A Google instance refuses it as `kit_connector_login_guided`
-and names House setup.
+A failed occurrence records its cause. A Google 403 for an API disabled in the
+client's project fails as `api_disabled`, and `kit source status` names the API
+to enable; a revoked scope (`google_scope_revoked`), an expired or revoked grant
+(`google_authority_revoked`) and a provider failure
+(`google_provider_unavailable`) keep their own codes.
 
 ## Environment setup
 
@@ -577,8 +550,10 @@ An object whose content changes without its native version changing keeps its
 key and is refused by House as a delivery-key conflict rather than silently
 overwriting the earlier Record.
 
-The same command owns its module authorization. `kit source sign-in` and the
-setup walk's status check send one JSON line
+The same command owns its module authorization. `kit source sign-in <instance>`
+skips an instance whose local authorization is already valid and answers
+`ready`, `skipped`, or `needs_attention`. It and the setup walk's status check
+send one JSON line
 with `action: "authorization"` and `mode: "status"` or `mode: "login"`; the
 command returns exactly one JSON object such as `{ "authorized": true }`.
 
@@ -653,27 +628,12 @@ inside `/agents/house` is somebody else's default or an owner's own workspace,
 never this Agent's. Every path that is not this exact equality, one deeper
 inside `/agents/house` included, must
 already exist in this Environment as a directory the installation can enter;
-Kit never creates or seeds it.
-
-When the Agent's own default directory is absent, Kit builds the starter set in
-a temporary directory beneath the base and renames it into place as one atomic
-step, so a partly seeded directory is never visible at the default path. Two
-concurrent first launches race that rename; the loser discards its temporary
-directory and uses the directory the winner put there, so the pair still leaves
-one complete directory and nothing partial. A present default directory -
-including one whose starter files the owner edited or removed - launches
-exactly as it is, and a deleted default directory is recreated with a fresh
-starter set on its next launch.
-
-The starter set is `AGENTS.md` with the single line ``The agents.house `house`
-CLI is available: run `house --help`.``, `CLAUDE.md` as a relative symbolic link to it, `.agents/skills/grilling/`
-vendored from [`mattpocock/skills`](https://github.com/mattpocock/skills)
-`skills/productivity/grilling` at a pinned commit with its MIT license and a
-provenance header naming that commit, and `.claude/skills` as a relative
-symbolic link to `.agents/skills`. Once seeded the files belong to the owner:
-Kit never syncs, refreshes, or restores them, and refreshing the vendored skill
-for new Agents is an ordinary Kit release that never touches an already seeded
-directory.
+Kit never creates it.
+
+When the Agent's own default directory is absent, Kit creates it empty; two
+concurrent first launches create the same directory. A present default
+directory launches exactly as it is, and a deleted one is created empty again
+on its next launch. Kit writes no file into any working directory.
 
 A relative, missing, inaccessible, or non-directory working directory refuses
 with `kit_launch_directory_unavailable` before any provider process starts. Kit falls back to no other location - not the
@@ -681,6 +641,52 @@ base, not `$HOUSE_KIT_HOME`, and not its own current directory - and neither
 connecting an installation nor launching a session moves, copies, overwrites,
 or removes anything a working directory holds.
 
+## The Skill set
+
+The Skill set is every skill the `mattpocock/skills` plugin manifest names at
+one pinned commit but `setup-matt-pocock-skills`, `triage` and `wizard`. Each
+is vendored under `src/skill-set/<name>/` with every file it ships, the
+upstream MIT `LICENSE` and a provenance header in `SKILL.md` naming the commit
+and upstream path. Nothing else is edited but two lines: a
+`disable-model-invocation: true` frontmatter line in `SKILL.md` and an
+`allow_implicit_invocation: false` line in `agents/openai.yaml` are removed, so
+an agent reaches every skill without being told its name.
+
+Kit installs the Skill set once for the Environment, for every Agent whatever
+its working directory, under the home it launches agent CLIs with: each skill
+as the directory `$HOME/.agents/skills/<name>`, which Codex and Grok Build
+read, and a relative symbolic link `$HOME/.claude/skills/<name>` to it, which
+Claude Code reads; when `$HOME/.claude/skills` already resolves to
+`$HOME/.agents/skills`, Claude Code reads the directory there and Kit makes no
+link. In a container that home is Kit home, so the set survives
+container recreation; on a native host it is the host user's home.
+
+`$HOUSE_KIT_HOME/state/skill-set.json` records the names Kit installed and the
+Kit version that installed them, and Kit owns exactly those names: the
+directory and the link of each. At start and on every resident pass, when
+the set is accepted and the record names another version or none, Kit deletes
+every recorded name, installs the current Skill set and rewrites the record. A
+name whose directory or link exists without being recorded is the owner's: Kit
+leaves it untouched and installs nothing under it. Kit never compares, merges
+or restores a file, so an edit to an installed skill is lost at the next
+release and a copy under another name is kept. When `skills` is `false`, Kit
+deletes every recorded name and the record and installs nothing.
+
+After Kit first installs the Skill set, the first Session it launches whose
+Profile ceiling lets it write the owner's How-we-work document
+`/private/library/how-we-work.md` creates it, when it is absent, with the text
+Kit ships in `src/how-we-work.md`, over the Session's own bridge before its
+first prompt is built. Kit then notes in `$HOUSE_KIT_HOME/state/how-we-work`,
+apart from the record, that the document exists, and a present document is
+noted the same way without being touched. Nothing ever creates it again: a
+release, a declined Skill set and a later acceptance leave the note, so an
+owner's edit stands and a deleted document stays deleted. A Session whose
+ceiling cannot write the document launches without it and leaves it for the
+next one; any other refused creation refuses the attempt as
+`kit_how_we_work_unwritable` with House's answer before a prompt is sent. A
+Skill set Kit cannot install or remove refuses the pass as
+`kit_skill_set_unavailable` and names the path.
+
 ## The declared agent CLIs
 
 The Environment owner installs no adapter binary by hand. `kit agents update`
@@ -1165,8 +1171,8 @@ on the door's own deduplication. When House stops a batch early, its answer
 settles only the prefix it reached, and the unsettled tail is reoffered with the
 rest. The loop repeats while the connector still returns items and no Room
 destination is blocked, and every run ends by writing the service's health into
-this installation's own state. House holds no preset, service, route, checkpoint
-or health of yours.
+this installation's own state. House holds no custom connector's service, route,
+checkpoint or health, and no Google entry's checkpoint or health.
 
 A Capture item that declares a `file` attachment answers one Record per Room
 destination: Rooms of one owner share that owner's Record, and a Room of another
@@ -1708,8 +1714,16 @@ $HOUSE_KIT_HOME/
   state/conversation-originals/<attachment identity>.json
   state/sessions/<tmux session>.json
   state/update-drain
+  state/skill-set.json
+  state/how-we-work
   state/continuations/<run identity>.json
-  state/<instance>/credentials/google.json
+  state/google/entries/<source>.json
+  state/google/credentials/<account>.json
+  state/google/checkpoints/<source>.json
+  state/google/health/<source>.json
+  state/google/gaps/<source>.json
+  state/google/dropped/<source>.json
+  state/google/originals/<source>.json
   state/<instance>/checkpoints/<service>.json
   state/<instance>/health/<service>.json
   state/<instance>/gaps/<service>.json
@@ -1719,15 +1733,18 @@ $HOUSE_KIT_HOME/
 
 Every file is written atomically and readable only by its owner. A file the Kit
 cannot read is refused rather than treated as a service that never captured.
-Disabling a service or an instance leaves its state in place, so re-enabling
-resumes from the stored cursor instead of importing again.
+A Google entry's state is keyed by its Source reference and lives only while
+House lists the entry. Disabling a custom service or instance leaves its state
+in place, so re-enabling resumes from the stored cursor instead of importing
+again.
 
 ```sh
 kit source reset acme        # every service
 kit source reset acme notes  # one service
 ```
 
-Reset is the only deletion of captured state. It removes the named checkpoints
+Reset serves custom connectors, and is the only deletion of their captured
+state. It removes the named checkpoints
 and their outstanding retained references so the next capture restarts exactly at
 the configured backfill boundary. It takes the same
 Environment control lease a capture takes, so it cannot delete a checkpoint a
@@ -1947,10 +1964,7 @@ workspaces.
 ```sh
 docker compose -f test/compose.yaml build kit
 docker compose -f test/compose.yaml run --rm kit npm test
-docker compose -f test/compose.yaml run --rm \
-  -e HOUSE_KIT_GOOGLE_OAUTH_CLIENT_ID=kit-client.apps.googleusercontent.com \
-  -e HOUSE_KIT_GOOGLE_OAUTH_CLIENT_SECRET=GOCSPX-kit-installed-app \
-  kit npm run build
+docker compose -f test/compose.yaml run --rm kit npm run build
 ```
 
 `test/pair/run.sh` boots real Core, Auth and PostgreSQL and runs the installed

package/bin/connect-linux.sh

@@ -6,6 +6,7 @@ NAME='house-kit'
 HOUSE='https://agents.house'
 WORKSPACE="$HOME/AgentsHouse"
 MANUAL=0
+SKILLS=true
 WORKSPACE_SELECTED=0
 HOUSE_SELECTED=0
 FORWARDING=0
@@ -160,6 +161,10 @@ while (($#)); do
       MANUAL=1
       shift
       ;;
+    --no-skills)
+      SKILLS=false
+      shift
+      ;;
     *) refuse "unknown argument $1" ;;
   esac
 done
@@ -208,6 +213,16 @@ if [[ -f "$KIT_HOME/house" ]]; then
   HOUSE="$BOUND_HOUSE"
 fi
 [[ "$HOUSE" == https://* || "$HOUSE" == http://127.0.0.1:* || "$HOUSE" == http://localhost:* ]] || refuse 'House origin must use HTTPS or local loopback HTTP'
+if ((FORWARDING == 0)); then
+  if [[ ! -f "$KIT_HOME/kit.json" ]]; then
+    printf '{"availability":"intermittent","execution_authority":"allow","migrators":[],"instances":[],"clients":[],"host":null,"skills":%s}\n' "$SKILLS" > "$KIT_HOME/kit.json"
+  elif grep -Eq '"skills"[[:space:]]*:' "$KIT_HOME/kit.json"; then
+    sed -E -i "s/(\"skills\"[[:space:]]*:[[:space:]]*)(true|false)/\\1$SKILLS/" "$KIT_HOME/kit.json" || refuse 'kit.json could not be updated'
+  else
+    sed -E -i "1s/^([[:space:]]*)\\{/\\1{\"skills\":$SKILLS,/" "$KIT_HOME/kit.json" || refuse 'kit.json could not be updated'
+  fi
+  grep -Eq "\"skills\"[[:space:]]*:[[:space:]]*$SKILLS" "$KIT_HOME/kit.json" || refuse 'kit.json could not be updated'
+fi
 DOCKER_RUN=(docker run --rm --network host --user "$(id -u):$(id -g)" --mount "$KIT_HOME_MOUNT" --mount "$WORKSPACE_MOUNT" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 --env "HOUSE_KIT_HOSTNAME=$(hostname)" "$IMAGE")
 
 if docker container inspect "$NAME" >/dev/null 2>&1; then
@@ -271,10 +286,6 @@ fi
 
 docker pull --quiet --platform "linux/$ARCH" "$IMAGE" >/dev/null
 
-if [[ ! -f "$KIT_HOME/kit.json" ]]; then
-  printf '{"availability":"intermittent","execution_authority":"allow","migrators":[],"instances":[],"clients":[],"host":null}\n' > "$KIT_HOME/kit.json"
-fi
-
 if [[ -f "$KIT_HOME/credential" ]]; then
   "${DOCKER_RUN[@]}" credential check
 else