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

package/bin/connect-linux.sh

@@ -228,6 +228,8 @@ esac
 [[ "$WORKSPACE" == /* ]] || refuse 'workspace root must be an absolute path'
 if [[ "$RUNTIME" == 'Docker Desktop' ]]; then
   establish_docker_desktop "$CHIP"
+  DOCKER_SYSTEM=$(docker info --format '{{.OperatingSystem}}' 2>/dev/null) || refuse "Docker Desktop does not answer: $(docker_cause)"
+  [[ "$DOCKER_SYSTEM" == 'Docker Desktop' ]] || refuse "Docker answers from $DOCKER_SYSTEM, not Docker Desktop; stop that engine or switch Docker to Docker Desktop, then rerun this bootstrap"
 else
   establish_docker_engine
 fi

package/bin/connect-windows.ps1

@@ -0,0 +1,430 @@
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+
+$Image = 'ghcr.io/agentshouse/kit@sha256:__IMAGE_DIGEST__'
+$Name = 'house-kit'
+$BootstrapArguments = @($args | ForEach-Object { [string]$_ })
+$MinimumBuild = 22631
+$MinimumWsl = [version]'2.1.5'
+$DesktopInstaller = 'https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe'
+$DesktopWaitSeconds = 300
+
+function Stop-Bootstrap([string] $Cause) {
+  throw "kit_bootstrap_refused: $Cause"
+}
+
+function Exit-Bootstrap([int] $Status) {
+  throw "kit_bootstrap_exit: $Status"
+}
+
+function Invoke-Native([string] $Command, [string[]] $NativeArguments) {
+  $ErrorActionPreference = 'Continue'
+  $output = @(& $Command @NativeArguments 2>&1 | ForEach-Object { "$_" })
+  [pscustomobject]@{ Status = $LASTEXITCODE; Output = $output }
+}
+
+function ConvertTo-NativeArgument([string] $Value) {
+  if ((Get-Variable -Name PSNativeCommandArgumentPassing -ValueOnly -ErrorAction SilentlyContinue) -in @('Windows', 'Standard')) { return $Value }
+  if ($Value -eq '') { return '""' }
+  $escaped = $Value -replace '(\\*)"', '$1$1\"'
+  if ($PSVersionTable.PSEdition -eq 'Desktop' -and $Value -match '\s') { $escaped = $escaped -replace '(\\+)$', '$1$1' }
+  $escaped
+}
+
+function Invoke-Docker {
+  & docker @args
+  if ($LASTEXITCODE -ne 0) { Exit-Bootstrap $LASTEXITCODE }
+}
+
+function Read-Docker {
+  $read = [pscustomobject]@{ Answers = $false; Platform = ''; System = ''; Kernel = ''; Cause = 'the docker command is not installed' }
+  if (-not (Get-Command docker -CommandType Application -ErrorAction SilentlyContinue)) { return $read }
+  $result = Invoke-Native docker @('info', '--format', '{{.OSType}}/{{.Architecture}}|{{.OperatingSystem}}|{{.KernelVersion}}')
+  $line = @($result.Output | Where-Object { $_ -match '^[a-z]+/[a-z0-9_]+\|' })
+  if ($result.Status -ne 0 -or $line.Count -eq 0) {
+    $read.Cause = @($result.Output | Where-Object { $_ })[-1]
+    return $read
+  }
+  $fields = $line[0].Split('|')
+  $read.Answers = $true
+  $read.Platform = $fields[0]
+  $read.System = $fields[1]
+  $read.Kernel = $fields[2]
+  $read
+}
+
+function Invoke-Elevated([string] $FilePath, [string[]] $ElevatedArguments, [string] $Failure, [int[]] $Accepted = @(0)) {
+  try {
+    $process = Start-Process -FilePath $FilePath -ArgumentList $ElevatedArguments -Verb RunAs -Wait -PassThru
+  } catch {
+    Stop-Bootstrap "$Failure; Windows did not grant administrator rights: $($_.Exception.Message); rerun this bootstrap and approve the prompt"
+  }
+  if ($Accepted -notcontains $process.ExitCode) {
+    Stop-Bootstrap "$Failure (exit $($process.ExitCode)); rerun this bootstrap"
+  }
+}
+
+function Get-WslVersion {
+  if (-not (Get-Command wsl.exe -CommandType Application -ErrorAction SilentlyContinue)) { return $null }
+  $result = Invoke-Native wsl.exe @('--version')
+  if ($result.Status -ne 0) { return $null }
+  if ((($result.Output -join "`n") -replace "`0", '') -match '(\d+)\.(\d+)\.(\d+)') {
+    return [version]"$($Matches[1]).$($Matches[2]).$($Matches[3])"
+  }
+  $null
+}
+
+function Initialize-Wsl {
+  $version = Get-WslVersion
+  if ($null -eq $version) {
+    Write-Host 'Installing WSL through wsl --install --no-distribution; Windows asks you to approve administrator rights.'
+    Invoke-Elevated 'wsl.exe' @('--install', '--no-distribution') 'WSL could not be installed' @(0, 3010)
+    Stop-Bootstrap 'WSL is installed and needs a Windows restart; restart Windows, then rerun this bootstrap'
+  }
+  if ($version -lt $MinimumWsl) {
+    Write-Host "Updating WSL $version through wsl --update; Windows asks you to approve administrator rights."
+    Invoke-Elevated 'wsl.exe' @('--update') 'WSL could not be updated'
+  }
+}
+
+function Find-DockerDesktop {
+  foreach ($location in @((Join-Path $env:ProgramFiles 'Docker\Docker'), (Join-Path $env:LOCALAPPDATA 'Programs\DockerDesktop'))) {
+    if (Test-Path -LiteralPath (Join-Path $location 'Docker Desktop.exe') -PathType Leaf) { return $location }
+  }
+  $null
+}
+
+function Add-DockerPath([string] $Location) {
+  if (-not (Get-Command docker -CommandType Application -ErrorAction SilentlyContinue)) {
+    $env:PATH = "$env:PATH;$(Join-Path $Location 'resources\bin')"
+  }
+}
+
+function Install-DockerDesktop {
+  $download = Join-Path ([IO.Path]::GetTempPath()) ([IO.Path]::GetRandomFileName())
+  [void][IO.Directory]::CreateDirectory($download)
+  try {
+    $installer = Join-Path $download 'Docker Desktop Installer.exe'
+    Write-Host 'Downloading Docker Desktop for Windows from docker.com.'
+    try {
+      Invoke-WebRequest -UseBasicParsing -Uri $DesktopInstaller -OutFile $installer
+    } catch {
+      Stop-Bootstrap "Docker Desktop could not be downloaded: $($_.Exception.Message)"
+    }
+    Write-Host 'Installing Docker Desktop for this Windows account.'
+    try {
+      $process = Start-Process -FilePath $installer -ArgumentList @('install', '--user', '--quiet') -Wait -PassThru
+    } catch {
+      Stop-Bootstrap "the Docker Desktop installer could not be started: $($_.Exception.Message)"
+    }
+    if ($process.ExitCode -ne 0) { Stop-Bootstrap "the Docker Desktop installer did not finish (exit $($process.ExitCode))" }
+  } finally {
+    Remove-Item -LiteralPath $download -Recurse -Force -ErrorAction SilentlyContinue
+  }
+}
+
+function Initialize-DockerDesktop {
+  $location = Find-DockerDesktop
+  if ($location) { Add-DockerPath $location }
+  $docker = Read-Docker
+  if ($docker.Answers) { return $docker }
+  if ($Forwarding) {
+    if (-not $location) { Stop-Bootstrap 'House Kit is not installed; run this bootstrap without arguments first' }
+    Stop-Bootstrap "Docker Desktop does not answer: $($docker.Cause); start Docker Desktop, then rerun this command"
+  }
+  Initialize-Wsl
+  if (-not $location) {
+    Install-DockerDesktop
+    $location = Find-DockerDesktop
+    if (-not $location) { Stop-Bootstrap 'Docker Desktop is not where its installer puts it; rerun this bootstrap' }
+    Add-DockerPath $location
+  }
+  Write-Host 'Starting Docker Desktop; accept its terms or finish its setup if its window asks.'
+  try {
+    Start-Process -FilePath (Join-Path $location 'Docker Desktop.exe')
+  } catch {
+    Stop-Bootstrap "Docker Desktop could not be started: $($_.Exception.Message)"
+  }
+  $waited = 0
+  while (-not ($docker = Read-Docker).Answers) {
+    if ($waited -ge $DesktopWaitSeconds) {
+      Stop-Bootstrap "Docker Desktop is not ready: $($docker.Cause); finish what its window asks, then rerun this bootstrap"
+    }
+    Start-Sleep -Seconds 2
+    $waited += 2
+  }
+  $docker
+}
+
+function Protect-Directory([string] $Path) {
+  if ($Path.Contains(',')) { Stop-Bootstrap "$Path contains a comma, which this bootstrap cannot pass to a Docker mount from Windows PowerShell" }
+  $item = Get-Item -LiteralPath $Path -Force -ErrorAction SilentlyContinue
+  if ($item -and ($item.Attributes -band [IO.FileAttributes]::ReparsePoint)) { Stop-Bootstrap "$Path is a symbolic link" }
+  $created = -not $item
+  if ($created) {
+    try { [void][IO.Directory]::CreateDirectory($Path) } catch { Stop-Bootstrap "$Path could not be created" }
+    $item = Get-Item -LiteralPath $Path -Force
+  }
+  if (-not $item.PSIsContainer) { Stop-Bootstrap "$Path is not a directory" }
+  $owner = (Get-Acl -LiteralPath $Path).GetOwner([Security.Principal.SecurityIdentifier]).Value
+  if (-not $created -and $owner -ne $User.Value) { Stop-Bootstrap "$Path is not owned by this User" }
+  try {
+    $security = New-Object Security.AccessControl.DirectorySecurity
+    if ($owner -ne $User.Value) { $security.SetOwner($User) }
+    $security.SetAccessRuleProtection($true, $false)
+    $security.AddAccessRule((New-Object Security.AccessControl.FileSystemAccessRule($User, 'FullControl', 'ContainerInherit, ObjectInherit', 'None', 'Allow')))
+    $item.SetAccessControl($security)
+  } catch {
+    Stop-Bootstrap "$Path could not be owner-protected"
+  }
+  $item.FullName.TrimEnd('\')
+}
+
+function Write-Text([string] $Path, [string] $Text) {
+  [IO.File]::WriteAllText($Path, $Text, (New-Object Text.UTF8Encoding($false)))
+}
+
+function Read-Inspect([string] $Format) {
+  $value = & docker inspect --format $Format $Name
+  if ($LASTEXITCODE -ne 0) { Exit-Bootstrap $LASTEXITCODE }
+  "$value"
+}
+
+function Read-Source([string] $Destination) {
+  $source = Read-Inspect ('{{range .Mounts}}{{if eq .Destination `' + $Destination + '`}}{{.Source}}{{end}}{{end}}')
+  if ($source -match '^/run/desktop/mnt/host/([a-z])(/.*)?$') { $source = "$($Matches[1].ToUpper()):$($Matches[2] -replace '/', '\')" }
+  $source
+}
+
+function Test-Container {
+  (Invoke-Native docker @('container', 'inspect', $Name)).Status -eq 0
+}
+
+function Invoke-Login([string[]] $LoginArguments) {
+  if ($LoginArguments -contains '--manual') {
+    Invoke-Docker run -i --rm @Network @Common login @LoginArguments
+    return
+  }
+  & docker run @Published --rm @Network @Common login @LoginArguments --host-browser | ForEach-Object {
+    if ($_ -like 'Open *') {
+      Write-Host 'Opening House Login in the host browser.'
+      try { Start-Process -FilePath $_.Substring(5) } catch { Stop-Bootstrap 'host browser did not open; rerun with --manual' }
+    } else {
+      Write-Host $_
+    }
+  }
+  if ($LASTEXITCODE -ne 0) { Exit-Bootstrap $LASTEXITCODE }
+}
+
+function Start-Resident {
+  $resident = @()
+  if (-not $House.StartsWith('https://')) { $resident = @('--network', 'host') }
+  Invoke-Docker run -d --name $Name --restart unless-stopped @resident --mount $KitHomeMount --mount $WorkspaceMount --label "agentshouse.house=$House" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 $Image resident | Out-Null
+}
+
+function Connect-Kit {
+  $House = 'https://agents.house'
+  $Workspace = $null
+  $Manual = $false
+  $Skills = 'true'
+  $WorkspaceSelected = $false
+  $HouseSelected = $false
+  $Forwarding = $false
+  $Forwarded = 'kit'
+  $Forward = @()
+  $Arguments = $BootstrapArguments
+  if ($Arguments.Count -gt 0 -and ($Arguments[0] -ceq 'kit' -or $Arguments[0] -ceq 'house')) {
+    $Forwarding = $true
+    $Forwarded = $Arguments[0]
+    $Forward = @($Arguments | Select-Object -Skip 1 | ForEach-Object { ConvertTo-NativeArgument $_ })
+    $Arguments = @()
+  }
+  for ($index = 0; $index -lt $Arguments.Count; $index++) {
+    $argument = $Arguments[$index]
+    if ($argument -ceq '--workspace' -or $argument -ceq '--house') {
+      if ($index + 1 -ge $Arguments.Count) { Stop-Bootstrap "$argument requires one value" }
+      $index++
+      if ($argument -ceq '--workspace') {
+        if ($WorkspaceSelected) { Stop-Bootstrap 'supply exactly one workspace root' }
+        $Workspace = $Arguments[$index]
+        $WorkspaceSelected = $true
+      } else {
+        if ($HouseSelected) { Stop-Bootstrap 'supply exactly one House origin' }
+        $House = $Arguments[$index]
+        $HouseSelected = $true
+      }
+    } elseif ($argument -ceq '--manual') {
+      $Manual = $true
+    } elseif ($argument -ceq '--no-skills') {
+      $Skills = 'false'
+    } else {
+      Stop-Bootstrap "unknown argument $argument"
+    }
+  }
+
+  if ($Image -notmatch '^ghcr\.io/agentshouse/kit@sha256:[0-9a-f]{64}$') { Stop-Bootstrap 'this bootstrap has not been published with an immutable image digest' }
+  if ($env:OS -ne 'Windows_NT') { Stop-Bootstrap 'this bootstrap is for Windows 11; run connect-linux.sh on Linux and macOS' }
+  if (-not [Environment]::Is64BitProcess) { Stop-Bootstrap 'this is a 32-bit PowerShell; run this bootstrap from the 64-bit Windows PowerShell' }
+  $system = Get-CimInstance -ClassName Win32_OperatingSystem
+  if ([int]$system.ProductType -ne 1) { Stop-Bootstrap "$($system.Caption) is a Windows Server edition; this bootstrap supports Windows 11 on amd64" }
+  if ([int]$system.BuildNumber -lt 22000) { Stop-Bootstrap "$($system.Caption) is not Windows 11; this bootstrap supports Windows 11 on amd64" }
+  if ([int]$system.BuildNumber -lt $MinimumBuild) { Stop-Bootstrap "Docker Desktop needs Windows 11 23H2 (build $MinimumBuild) or later, not build $($system.BuildNumber); update Windows, then rerun this bootstrap" }
+  $processor = [int]@(Get-CimInstance -ClassName Win32_Processor)[0].Architecture
+  if ($processor -ne 9) {
+    $described = @{ 0 = 'x86'; 5 = 'ARM'; 12 = 'ARM64' }[$processor]
+    if (-not $described) { $described = "architecture $processor" }
+    Stop-Bootstrap "Windows on $described is not supported; this bootstrap supports Windows 11 on amd64"
+  }
+  if ($WorkspaceSelected -and $Workspace -notmatch '^[A-Za-z]:\\') { Stop-Bootstrap 'workspace root must be an absolute path' }
+
+  $docker = Initialize-DockerDesktop
+  if (-not $docker.Platform.StartsWith('linux/')) { Stop-Bootstrap "Docker runs $($docker.Platform.Split('/')[0]) containers; switch Docker Desktop to Linux containers, then rerun this bootstrap" }
+  if ($docker.System -ne 'Docker Desktop') { Stop-Bootstrap "Docker answers from $($docker.System), not Docker Desktop; stop that engine or switch Docker to Docker Desktop, then rerun this bootstrap" }
+  if ($docker.Kernel -notlike '*WSL2*') { Stop-Bootstrap "Docker Desktop does not use its WSL 2 engine; turn on Use the WSL 2 based engine in its settings, then rerun this bootstrap" }
+  if ($docker.Platform -ne 'linux/x86_64' -and $docker.Platform -ne 'linux/amd64') { Stop-Bootstrap "host linux/amd64 does not match Docker Desktop $($docker.Platform)" }
+  if ($Forwarding) {
+    if (-not (Test-Container)) { Stop-Bootstrap 'House Kit is not installed; run this bootstrap without arguments first' }
+    $Workspace = Read-Source '/agents/house'
+    if ($Workspace -notmatch '^[A-Za-z]:\\' -or -not (Test-Path -LiteralPath $Workspace -PathType Container)) {
+      Stop-Bootstrap "the installed Kit's workspace root $Workspace is not a directory on this computer; rerun this bootstrap without arguments"
+    }
+  }
+  if (-not $Workspace) { $Workspace = Join-Path $env:USERPROFILE 'AgentsHouse' }
+
+  $User = [Security.Principal.WindowsIdentity]::GetCurrent().User
+  $kitHome = Protect-Directory (Join-Path $env:USERPROFILE '.house-kit')
+  $Workspace = Protect-Directory $Workspace
+  $KitHomeMount = "type=bind,src=$kitHome,dst=/kit-home"
+  $WorkspaceMount = "type=bind,src=$Workspace,dst=/agents/house"
+  $credential = Join-Path $kitHome 'credential'
+  $environment = Join-Path $kitHome 'environment'
+  $bound = Join-Path $kitHome 'house'
+  $configuration = Join-Path $kitHome 'kit.json'
+  if (((Test-Path -LiteralPath $credential) -or (Test-Path -LiteralPath $environment)) -and -not (Test-Path -LiteralPath $bound)) {
+    Stop-Bootstrap 'stored House origin is missing for an enrolled Environment'
+  }
+  if (Test-Path -LiteralPath $bound) {
+    $boundHouse = @([IO.File]::ReadAllLines($bound))
+    if ($boundHouse.Count -eq 0) { Stop-Bootstrap 'stored House origin is unreadable' }
+    if ($HouseSelected -and $House -cne $boundHouse[0]) { Stop-Bootstrap 'this Environment is bound to another House origin' }
+    $House = $boundHouse[0]
+  }
+  if ($House -notmatch '^(https://|http://127\.0\.0\.1:|http://localhost:)') { Stop-Bootstrap 'House origin must use HTTPS or local loopback HTTP' }
+  if (-not $Forwarding) {
+    try {
+      if (-not (Test-Path -LiteralPath $configuration)) {
+        Write-Text $configuration "{`"availability`":`"intermittent`",`"execution_authority`":`"allow`",`"migrators`":[],`"instances`":[],`"clients`":[],`"host`":null,`"skills`":$Skills}`n"
+      } else {
+        $text = [IO.File]::ReadAllText($configuration)
+        if ($text -match '"skills"\s*:') {
+          $text = $text -replace '("skills"\s*:\s*)(true|false)', "`${1}$Skills"
+        } else {
+          $text = $text -replace '^(\s*)\{', "`${1}{`"skills`":$Skills,"
+        }
+        Write-Text $configuration $text
+      }
+    } catch {
+      Stop-Bootstrap 'kit.json could not be updated'
+    }
+    if ([IO.File]::ReadAllText($configuration) -notmatch "`"skills`"\s*:\s*$Skills") { Stop-Bootstrap 'kit.json could not be updated' }
+  }
+  $Network = @('--network', 'host')
+  $Published = @()
+  if ($House.StartsWith('https://')) {
+    $Network = @()
+    $port = Get-Random -Minimum 49152 -Maximum 65536
+    $Published = @('--publish', "127.0.0.1:${port}:$port", '--env', "HOUSE_KIT_LOGIN_PORT=$port")
+  }
+  $Common = @('--mount', $KitHomeMount, '--mount', $WorkspaceMount, '--env', 'HOME=/kit-home', '--env', 'HOUSE_KIT_HOME=/kit-home', '--env', 'HOUSE_KIT_CONTAINER=1', '--env', "HOUSE_KIT_HOSTNAME=$([Net.Dns]::GetHostName())", $Image)
+
+  if (Test-Container) {
+    $installed = Read-Inspect '{{.Config.Image}}'
+    if ($Forwarding -and $installed -cne $Image) { Stop-Bootstrap 'an installed Kit uses a different image; rerun this bootstrap without arguments to update it' }
+    if ((Read-Inspect '{{.HostConfig.RestartPolicy.Name}}') -cne 'unless-stopped') { Stop-Bootstrap 'the installed Kit has a different lifecycle' }
+    if ((Read-Inspect '{{len .Mounts}}') -cne '2') { Stop-Bootstrap 'the installed Kit has unexpected mounts' }
+    if ((Read-Source '/kit-home') -ine $kitHome) { Stop-Bootstrap 'the installed Kit uses another Kit home' }
+    if ((Read-Inspect '{{range .Mounts}}{{if eq .Destination `/kit-home`}}{{.Type}}/{{.RW}}{{end}}{{end}}') -cne 'bind/true') { Stop-Bootstrap 'the installed Kit home is not a writable bind mount' }
+    if ((Read-Source '/agents/house') -ine $Workspace) { Stop-Bootstrap 'the installed Kit uses another workspace root' }
+    if ((Read-Inspect '{{range .Mounts}}{{if eq .Destination `/agents/house`}}{{.Type}}/{{.RW}}{{end}}{{end}}') -cne 'bind/true') { Stop-Bootstrap 'the installed workspace is not a writable bind mount' }
+    if ((Read-Inspect '{{index .Config.Labels `agentshouse.house`}}') -cne $House) { Stop-Bootstrap 'the installed Kit uses another House origin' }
+    if (-not ((Test-Path -LiteralPath $credential) -and (Test-Path -LiteralPath $environment) -and (Test-Path -LiteralPath $bound))) { Stop-Bootstrap 'the installed Kit has no enrolled authority' }
+    if ($Forwarding) {
+      if ($Forwarded -ceq 'kit' -and $Forward.Count -gt 0 -and $Forward[0] -ceq 'login') {
+        Invoke-Login @($Forward | Select-Object -Skip 1)
+        return
+      }
+      $placed = @()
+      $entry = @()
+      if ($Forwarded -ceq 'house') {
+        $here = (Get-Location).ProviderPath.TrimEnd('\')
+        if ($here -ine $Workspace -and -not $here.StartsWith("$Workspace\", [StringComparison]::OrdinalIgnoreCase)) {
+          Stop-Bootstrap "the current directory is outside the workspace $Workspace"
+        }
+        $placed = @('--workdir', "/agents/house$($here.Substring($Workspace.Length).Replace('\', '/'))")
+        $entry = @('--entrypoint', 'house')
+      }
+      $terminal = @()
+      if (-not [Console]::IsInputRedirected -and -not [Console]::IsOutputRedirected) { $terminal = @('-t') }
+      if ((Read-Inspect '{{.State.Running}}') -ceq 'true') {
+        & docker exec -i @terminal @placed $Name $Forwarded @Forward
+      } else {
+        & docker run -i @terminal @placed @entry --rm @Network @Common @Forward
+      }
+      Exit-Bootstrap $LASTEXITCODE
+    }
+    if ($installed -cne $Image) {
+      Invoke-Docker pull --quiet --platform linux/amd64 $Image | Out-Null
+      if ((Read-Inspect '{{.State.Running}}') -ceq 'true') { Invoke-Docker exec $Name kit resident drain }
+      Invoke-Docker rm -f $Name | Out-Null
+      Remove-Item -LiteralPath (Join-Path $kitHome 'state\update-drain') -Force -ErrorAction SilentlyContinue
+      Start-Resident
+      Write-Host "House Kit updated for Environment $([IO.File]::ReadAllText($environment).Trim())."
+      return
+    }
+    Invoke-Docker run --rm @Network @Common credential check
+    if ((Read-Inspect '{{.State.Running}}') -ceq 'true') {
+      Write-Host "House Kit is already running for Environment $([IO.File]::ReadAllText($environment).Trim())."
+    } else {
+      Invoke-Docker start $Name | Out-Null
+      Write-Host "House Kit restarted for Environment $([IO.File]::ReadAllText($environment).Trim())."
+    }
+    return
+  }
+
+  Invoke-Docker pull --quiet --platform linux/amd64 $Image | Out-Null
+  if (Test-Path -LiteralPath $credential) {
+    Invoke-Docker run --rm @Network @Common credential check
+  } else {
+    $login = @()
+    if ($HouseSelected) { $login += @('--house', $House) }
+    if ($Manual) { $login += '--manual' }
+    Invoke-Login $login
+  }
+  Invoke-Docker run --rm @Network @Common apply
+  Start-Resident
+  Write-Host "House Kit connected for Environment $([IO.File]::ReadAllText($environment).Trim())."
+}
+
+$consoleEncoding = [Console]::OutputEncoding
+try {
+  try {
+    [Console]::OutputEncoding = New-Object Text.UTF8Encoding($false)
+  } catch {
+    Stop-Bootstrap 'this PowerShell has no console; run this bootstrap from a Windows PowerShell console window'
+  }
+  Connect-Kit
+  $global:LASTEXITCODE = 0
+} catch {
+  $message = "$($_.Exception.Message)"
+  if ($message -match '^kit_bootstrap_exit: (\d+)$') {
+    $global:LASTEXITCODE = [int]$Matches[1]
+  } elseif ($message.StartsWith('kit_bootstrap_refused: ')) {
+    [Console]::Error.WriteLine($message)
+    $global:LASTEXITCODE = 1
+  } else {
+    $global:LASTEXITCODE = 1
+    throw
+  }
+} finally {
+  try { [Console]::OutputEncoding = $consoleEncoding } catch { }
+}

package/bootstrap.json

@@ -1,17 +1,28 @@
 {
   "schemaVersion": 1,
-  "version": "0.1.0-alpha.35",
+  "version": "0.1.0-alpha.37",
   "hosts": {
     "linux": {
-      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.35/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.35/connect-linux.sh"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.37/connect-linux.sh"
       },
       "workspace": {
         "argument": "--workspace",
         "quoting": "posix"
       }
+    },
+    "windows": {
+      "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.37/connect-windows.ps1"
+      },
+      "workspace": {
+        "argument": "--workspace",
+        "quoting": "powershell"
+      }
     }
   }
 }

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.