kdpa-agent-box 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/agent-box CHANGED
@@ -10,6 +10,8 @@ VOLUME=${BOX_VOLUME:-agent-box-data} # BOX_VOLUME, like BOX_NAME, only for tes
10
10
  HERE="$(cd "$(dirname "$(readlink -f "$0")")" && pwd)"
11
11
  OS=$(uname -s)
12
12
  CONF="${XDG_CONFIG_HOME:-$HOME/.config}/agent-box/config"
13
+ CACHE="${XDG_CACHE_HOME:-$HOME/.cache}/agent-box" # logs and locks
14
+ NET=agent-box # the box's own network, so other containers can't reach its ports
13
15
  CDP_PORT=${BOX_CDP_PORT:-9222}
14
16
  VIEW_PORT=${BOX_VIEW_PORT:-6080}
15
17
  CDP=http://127.0.0.1:$CDP_PORT
@@ -20,9 +22,11 @@ SKILL="$HERE/skills/agent-box"
20
22
  SKILL_DIRS=("${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills" "$HOME/.agents/skills") # Claude Code; Codex and other agents
21
23
 
22
24
  # The image tag is a checksum of the files it's built from, so an update rebuilds it.
23
- BUILD_FILES=(Containerfile entrypoint.sh box-quit-browser box-vault desktop/tint2rc desktop/agent-box-passwords.desktop desktop/keepassxc.ini)
25
+ BUILD_FILES=(Containerfile entrypoint.sh box-quit-browser box-vault box-type desktop/tint2rc desktop/agent-box-passwords.desktop desktop/keepassxc.ini)
24
26
  TAG=$(cd "$HERE" && cat "${BUILD_FILES[@]}" | cksum | cut -d' ' -f1)
25
27
  IMAGE="agent-box:$TAG"
28
+ STAMP="$CACHE/image-$TAG.built" # when this image was built, for the browser refresh
29
+ REFRESH_DAYS=${BOX_REFRESH_DAYS:-14}
26
30
 
27
31
  conf_get() { [ -f "$CONF" ] && sed -n "s/^$1=//p" "$CONF" | tail -n 1 || true; }
28
32
  conf_set() {
@@ -89,6 +93,9 @@ ensure_system() {
89
93
  "$RT" info >/dev/null 2>&1 && return 0
90
94
  if colima_ctx; then colima start >/dev/null 2>&1 || true
91
95
  elif podman_vm; then podman machine start >/dev/null 2>&1 || true; fi
96
+ if "$RT" info 2>&1 | grep -i 'permission denied' >/dev/null; then
97
+ echo "agent-box: $RT says permission denied. Add yourself to its group: sudo usermod -aG docker \$USER, then log out and back in" >&2; exit 1
98
+ fi
92
99
  "$RT" info >/dev/null 2>&1 || {
93
100
  echo "agent-box: $RT isn't running. Start it (Docker Desktop, OrbStack, 'colima start' or 'podman machine start') and try again" >&2; exit 1; } ;;
94
101
  *)
@@ -114,9 +121,10 @@ stop_system() {
114
121
  }
115
122
 
116
123
  state() {
117
- local s
124
+ local s=""
118
125
  if [ "$RT" = container ]; then
119
- s=$(container inspect "$NAME" 2>/dev/null | python3 -c 'import json,sys; print(json.load(sys.stdin)[0]["status"]["state"])' 2>/dev/null) || true
126
+ if container list -q 2>/dev/null | grep -x "$NAME" >/dev/null; then s=running
127
+ elif container list -a -q 2>/dev/null | grep -x "$NAME" >/dev/null; then s=stopped; fi
120
128
  else
121
129
  s=$("$RT" inspect -f '{{.State.Status}}' "$NAME" 2>/dev/null) || true
122
130
  fi
@@ -134,8 +142,111 @@ image_tags() {
134
142
  return 0
135
143
  }
136
144
  image_rm() { if [ "$RT" = container ]; then container image delete "$1"; else "$RT" image rm "$1"; fi; }
137
- build_quiet() {
138
- "$0" build >/tmp/agent-box-build.log 2>&1 || { tail -n 20 /tmp/agent-box-build.log >&2; exit 1; }
145
+
146
+ # One start, and one image build, at a time: several agents may run `up` at once.
147
+ LOCKS=()
148
+ release_locks() { local l; for l in ${LOCKS[@]+"${LOCKS[@]}"}; do rm -rf "$l"; done; }
149
+ trap 'rc=$?; release_locks; exit "$rc"' EXIT # keep the command's own exit code
150
+ lock() {
151
+ local dir="$CACHE/$1.lock" i p
152
+ mkdir -p "$CACHE"
153
+ for i in $(seq 900); do
154
+ if mkdir "$dir" 2>/dev/null; then echo $$ > "$dir/pid"; LOCKS+=("$dir"); return 0; fi
155
+ p=$(cat "$dir/pid" 2>/dev/null || true)
156
+ if [ -n "$p" ] && ! kill -0 "$p" 2>/dev/null; then rm -rf "$dir"; continue; fi # its owner died
157
+ if [ -z "$p" ] && [ "$i" -gt 5 ]; then rm -rf "$dir"; continue; fi
158
+ sleep 1
159
+ done
160
+ echo "agent-box: waited 15 minutes for another agent-box command; if none is running, remove $dir" >&2
161
+ exit 1
162
+ }
163
+ unlock() { rm -rf "$CACHE/$1.lock"; }
164
+ locked() { [ -d "$CACHE/$1.lock" ]; }
165
+
166
+ # Run a command in its own session, so it outlives the agent's shell command.
167
+ detach() { python3 -c 'import os, sys; os.setsid(); os.execvp(sys.argv[1], sys.argv[1:])' "$@"; }
168
+
169
+ # Make sure the image exists. A build takes 1 to 3 minutes, longer than agents'
170
+ # commands may run, so it builds in the background and `up` waits a while for it.
171
+ # Returns 75 if it isn't ready yet.
172
+ prepare_image() {
173
+ image_ok && return 0
174
+ local wait=${BOX_PREPARE_WAIT:-100} i
175
+ [ -t 1 ] && wait=1800 # a person at a terminal: just wait
176
+ mkdir -p "$CACHE"
177
+ if ! locked build; then
178
+ echo "agent-box: preparing the box image (first run or after an update, 1 to 3 minutes)" >&2
179
+ detach "$0" build --if-missing >"$CACHE/build.log" 2>&1 </dev/null &
180
+ fi
181
+ for i in $(seq "$wait"); do image_ok && return 0; sleep 1; done
182
+ echo "agent-box: still preparing the image; run the same command again in a minute (progress: tail $CACHE/build.log)" >&2
183
+ return 75
184
+ }
185
+
186
+ # Rebuild, in the background, an image older than BOX_REFRESH_DAYS, so the
187
+ # browser gets security updates. The box uses it from its next start.
188
+ refresh_image() {
189
+ case $REFRESH_DAYS in ''|*[!0-9]*|0) return 0 ;; esac
190
+ mkdir -p "$CACHE"
191
+ [ -f "$STAMP" ] || { date +%s > "$STAMP"; return 0; }
192
+ local built; built=$(cat "$STAMP" 2>/dev/null || echo 0)
193
+ case $built in ''|*[!0-9]*) built=0 ;; esac
194
+ [ $(( $(date +%s) - built )) -ge $(( REFRESH_DAYS * 86400 )) ] || return 0
195
+ locked build && return 0
196
+ echo "agent-box: the browser image is over $REFRESH_DAYS days old; updating it in the background (used from the next start)" >&2
197
+ detach "$0" build >"$CACHE/build.log" 2>&1 </dev/null &
198
+ }
199
+
200
+ # The box's own network, where the container tool supports one.
201
+ network_opts() {
202
+ if "$RT" network inspect "$NET" >/dev/null 2>&1 || "$RT" network create "$NET" >/dev/null 2>&1; then
203
+ echo "--network $NET"
204
+ fi
205
+ }
206
+
207
+ # The host's time zone, so sites show local times.
208
+ host_tz() {
209
+ local z
210
+ for z in "${TZ:-}" "$(readlink /etc/localtime 2>/dev/null | sed -n 's#.*/zoneinfo/##p')" "$(cat /etc/timezone 2>/dev/null || true)"; do
211
+ case $z in ''|*[!A-Za-z0-9_+/-]*) ;; *) echo "$z"; return ;; esac
212
+ done
213
+ echo UTC
214
+ }
215
+
216
+ # True once the browser answers; false if the box stops while we wait.
217
+ wait_cdp() {
218
+ local i
219
+ for i in $(seq 120); do
220
+ curl -sf -m 1 "$CDP/json/version" >/dev/null && return 0
221
+ if [ $(( i % 10 )) -eq 0 ] && ! running; then return 1; fi
222
+ sleep 0.5
223
+ done
224
+ return 1
225
+ }
226
+
227
+ start_box() {
228
+ [ "$(state)" = absent ] || "$RT" rm -f "$NAME" >/dev/null 2>&1 || true # a stopped box blocks the name
229
+ prepare_image || exit 75
230
+ if ! "$RT" volume inspect "$VOLUME" >/dev/null 2>&1; then
231
+ if [ "$RT" = container ]; then container volume create -s 4G "$VOLUME" >/dev/null
232
+ else "$RT" volume create "$VOLUME" >/dev/null; fi
233
+ fi
234
+ # Apple's container runs each box in its own VM. Docker and Podman share one
235
+ # kernel and block the user namespaces Chromium's sandbox needs, so they get
236
+ # a seccomp profile: Docker's default plus clone, setns and unshare
237
+ # (scripts/update-seccomp.mjs regenerates it).
238
+ local extra net
239
+ if [ "$RT" = container ]; then extra=(-c "${BOX_CPUS:-2}")
240
+ else extra=(--cpus "${BOX_CPUS:-2}" --security-opt "seccomp=$HERE/chromium-seccomp.json"); fi
241
+ read -r -a net <<< "$(network_opts)"
242
+ mkdir -p "$CACHE"
243
+ "$RT" run -d --rm --name "$NAME" --init \
244
+ -m "${BOX_MEMORY:-2G}" "${extra[@]}" ${net[@]+"${net[@]}"} --shm-size 1G \
245
+ -e IDLE_MINUTES="${BOX_IDLE_MINUTES:-20}" -e TZ="$(host_tz)" \
246
+ -e SCREEN_WIDTH="${BOX_WIDTH:-1280}" -e SCREEN_HEIGHT="${BOX_HEIGHT:-800}" \
247
+ -v "$VOLUME":/data \
248
+ -p "127.0.0.1:$(viewer_port):6080" -p "127.0.0.1:$CDP_PORT:9223" \
249
+ "$IMAGE" >"$CACHE/run.log" 2>&1 || running || { cat "$CACHE/run.log" >&2; exit 1; }
139
250
  }
140
251
 
141
252
  # Phone viewer address, only once it's published on the tailnet (see README).
@@ -153,7 +264,12 @@ info() {
153
264
  local t
154
265
  if t=$(view_tailnet); then echo " viewer from phone: $t (Tailscale)"
155
266
  else echo " viewer from phone: not published (see $HERE/README.md)"; fi
156
- echo " stops after ${BOX_IDLE_MINUTES:-20} min idle; 'agent-box down' stops it now"
267
+ local idle hold
268
+ idle=$(in_box "$NAME" printenv IDLE_MINUTES 2>/dev/null || echo "${BOX_IDLE_MINUTES:-20}")
269
+ hold=$(in_box "$NAME" sh -c 'h=$(cat /tmp/box-hold-until 2>/dev/null || echo 0); n=$(date +%s); [ "$h" -gt "$n" ] && echo $(( (h - n + 59) / 60 ))' 2>/dev/null || true)
270
+ if [ "$idle" = 0 ]; then echo " never stops by itself; 'agent-box down' stops it"
271
+ else echo " stops after $idle min idle${hold:+ (kept awake for $hold more min)}; 'agent-box down' stops it now"; fi
272
+ echo " downloads: 'agent-box files' lists them, 'agent-box get <name>' copies one here"
157
273
  }
158
274
 
159
275
  case "${1:-help}" in
@@ -213,7 +329,10 @@ case "${1:-help}" in
213
329
  fi
214
330
  if ! command -v playwright-cli >/dev/null; then
215
331
  echo "agent-box: installing playwright-cli (npm)"
216
- npm install -g @playwright/cli@latest
332
+ npm install -g @playwright/cli@latest || {
333
+ echo "agent-box: npm couldn't install playwright-cli for everyone. If it needs sudo, give npm a folder of your own:" >&2
334
+ echo " npm config set prefix ~/.npm-global, add ~/.npm-global/bin to PATH, then run agent-box setup again" >&2
335
+ exit 1; }
217
336
  fi
218
337
  if [ "$RT" = container ]; then
219
338
  container system status >/dev/null 2>&1 || container system start --enable-kernel-install
@@ -222,10 +341,8 @@ case "${1:-help}" in
222
341
  fi
223
342
  conf_set runtime "$RT"
224
343
  if [ "$RT" = docker ] && [ "$(docker context show 2>/dev/null)" = colima ]; then conf_set vm colima; else conf_set vm none; fi
225
- if ! image_ok; then
226
- echo "agent-box: building the box image with $RT (about 3 minutes; log in /tmp/agent-box-build.log)"
227
- build_quiet
228
- fi
344
+ prepared=1; prepare_image || prepared=0
345
+ if [ "$skills" = 1 ]; then conf_set skill_dirs "$(IFS=:; echo "${dirs[*]}")"; else conf_set skill_dirs none; fi
229
346
  if [ "$skills" = 1 ]; then
230
347
  for d in "${dirs[@]}"; do
231
348
  if [ -e "$d/agent-box" ] && [ ! -L "$d/agent-box" ]; then
@@ -238,7 +355,8 @@ case "${1:-help}" in
238
355
  else
239
356
  echo "agent-box: ready, using $RT, without the skill: point agents at $SKILL/SKILL.md. Watch the box at $VIEW_LOCAL"
240
357
  fi
241
- echo " For the phone viewer and password vault, see $HERE/README.md" ;;
358
+ [ "$prepared" = 1 ] || echo " The box image is still being prepared in the background; the first 'agent-box up' finishes it."
359
+ echo " For the phone viewer and password vault, see $HERE/README.md. To check everything: agent-box doctor" ;;
242
360
  uninstall)
243
361
  # Undo setup. --all also deletes the image and the box's storage (logins and password vault).
244
362
  shift; all=0; dirs=("${SKILL_DIRS[@]}")
@@ -265,33 +383,18 @@ case "${1:-help}" in
265
383
  echo "agent-box: uninstalled. Finish with: npm rm -g kdpa-agent-box" ;;
266
384
  up)
267
385
  ensure_system
268
- if ! running; then
269
- # A stopped box that was not cleaned up yet would block the name.
270
- if [ "$(state)" != absent ]; then "$RT" rm "$NAME" >/dev/null 2>&1 || true; fi
271
- if ! image_ok; then
272
- echo "agent-box: building the image first (first run or update, about 3 minutes)" >&2
273
- build_quiet
386
+ for attempt in 1 2 3; do
387
+ if ! running; then
388
+ lock "start-$NAME"
389
+ running || start_box
390
+ unlock "start-$NAME"
274
391
  fi
275
- if ! "$RT" volume inspect "$VOLUME" >/dev/null 2>&1; then
276
- if [ "$RT" = container ]; then container volume create -s 4G "$VOLUME" >/dev/null
277
- else "$RT" volume create "$VOLUME" >/dev/null; fi
278
- fi
279
- # Apple's container runs each box in its own VM. Docker and Podman share one
280
- # kernel and block the user namespaces Chromium's sandbox needs, so they get
281
- # a seccomp profile: Docker's default plus clone, setns and unshare
282
- # (scripts/update-seccomp.mjs regenerates it).
283
- if [ "$RT" = container ]; then extra=(-c "${BOX_CPUS:-2}")
284
- else extra=(--cpus "${BOX_CPUS:-2}" --security-opt "seccomp=$HERE/chromium-seccomp.json"); fi
285
- "$RT" run -d --rm --name "$NAME" --init \
286
- -m "${BOX_MEMORY:-2G}" "${extra[@]}" --shm-size 1G \
287
- -e IDLE_MINUTES="${BOX_IDLE_MINUTES:-20}" \
288
- -e SCREEN_WIDTH="${BOX_WIDTH:-1280}" -e SCREEN_HEIGHT="${BOX_HEIGHT:-800}" \
289
- -v "$VOLUME":/data \
290
- -p "127.0.0.1:$(viewer_port):6080" -p "127.0.0.1:$CDP_PORT:9223" \
291
- "$IMAGE" >/tmp/agent-box-run.log 2>&1 || { cat /tmp/agent-box-run.log >&2; exit 1; }
292
- fi
293
- for _ in $(seq 120); do curl -sf -m 1 "$CDP/json/version" >/dev/null && break; sleep 0.5; done
294
- curl -sf -m 2 "$CDP/json/version" >/dev/null || { echo "agent-box: browser did not come up; see 'agent-box logs'" >&2; exit 1; }
392
+ wait_cdp && break
393
+ if running; then echo "agent-box: the box runs but its browser doesn't answer; see 'agent-box logs'" >&2; exit 1; fi
394
+ # It stopped while we waited, for example an idle stop that was under way: start it again.
395
+ [ "$attempt" -lt 3 ] || { echo "agent-box: the box keeps stopping while it starts; see 'agent-box doctor'" >&2; exit 1; }
396
+ done
397
+ refresh_image
295
398
  info ;;
296
399
  down)
297
400
  if running; then
@@ -302,15 +405,21 @@ case "${1:-help}" in
302
405
  for _ in $(seq 20); do [ "$(state)" = absent ] && break; sleep 0.5; done
303
406
  echo "agent-box: stopped" ;;
304
407
  status)
305
- if running; then info; "$RT" stats --no-stream "$NAME" 2>/dev/null || true
408
+ if running; then
409
+ info
410
+ browser=$(curl -s -m 2 "$CDP/json/version" | sed -n 's/.*"Browser": *"\([^"]*\)".*/\1/p')
411
+ age=""; [ -f "$STAMP" ] && age=$(( ( $(date +%s) - $(cat "$STAMP") ) / 86400 ))
412
+ echo " browser: ${browser:-not answering}${age:+, image built $age days ago}"
413
+ "$RT" stats --no-stream "$NAME" 2>/dev/null || true
306
414
  else echo "agent-box: stopped (run 'agent-box up'); container tool: $RT"; fi ;;
307
415
  url)
308
416
  echo "$VIEW_LOCAL"; view_tailnet || true ;;
309
417
  shot)
310
418
  # Screenshot of the whole desktop, for when the page alone is not enough.
311
- out="${2:-/tmp/agent-box-$(date +%Y%m%d-%H%M%S).png}"
312
- in_box "$NAME" sh -c 'DISPLAY=:1 scrot -o /tmp/shot.png'
313
- in_box "$NAME" cat /tmp/shot.png > "$out"; echo "$out" ;;
419
+ need_box
420
+ out="${2:-/tmp/agent-box-$(date +%Y%m%d-%H%M%S)-$$.png}"
421
+ in_box "$NAME" sh -c "DISPLAY=:1 scrot -o /tmp/shot-$$.png"
422
+ in_box "$NAME" cat "/tmp/shot-$$.png" > "$out"; in_box "$NAME" rm -f "/tmp/shot-$$.png"; echo "$out" ;;
314
423
  x)
315
424
  # Raw mouse/keyboard on the desktop, e.g. `agent-box x mousemove 640 400 click 1`.
316
425
  shift; in_box "$NAME" env DISPLAY=:1 xdotool "$@" ;;
@@ -319,8 +428,14 @@ case "${1:-help}" in
319
428
  logs)
320
429
  "$RT" logs "$NAME" ;;
321
430
  build)
431
+ # Always with current packages (--pull --no-cache), so the browser gets its
432
+ # security updates. --if-missing: only if this version's image isn't there yet.
433
+ [ "${2:-}" = --if-missing ] && if_missing=1 || if_missing=0
322
434
  ensure_system
323
- "$RT" build -t "$IMAGE" -f "$HERE/Containerfile" "$HERE"
435
+ lock build
436
+ if [ "$if_missing" = 1 ] && image_ok; then exit 0; fi
437
+ "$RT" build --pull --no-cache -t "$IMAGE" -f "$HERE/Containerfile" "$HERE"
438
+ mkdir -p "$CACHE"; date +%s > "$STAMP"
324
439
  # Drop the build cache (about 4.5 GB with Apple's container), older builds and unused layers.
325
440
  if [ "$RT" = container ]; then
326
441
  container builder stop >/dev/null 2>&1 || true
@@ -379,53 +494,149 @@ case "${1:-help}" in
379
494
  *) echo "usage: agent-box secret save <name> --from-file <path> [--user U] [--url URL] | list | rm <name> | open" >&2; exit 2 ;;
380
495
  esac ;;
381
496
  type-secret)
382
- # Type a vault entry into the focused field in the box, without printing it.
383
- # agent-box type-secret <name> [--username | --totp] [--no-enter]
384
- # agent-box type-secret --from-file <path> [--no-enter] (one-time use)
385
- # For passwords it presses Enter, then clears any password still left in a
386
- # field (e.g. a failed login): page snapshots show password values.
497
+ # Type a vault entry into the field the agent focused, without printing it.
498
+ # agent-box type-secret <name> [--username | --totp] [--no-enter] [--page <text>] [--keyboard]
499
+ # agent-box type-secret --from-file <path> [--url <site>] [...] (one-time use)
500
+ # It types into the one page whose focused field is the right kind (a password
501
+ # field for passwords), on the entry's site, whatever tab is in front. For
502
+ # passwords it presses Enter, then clears password fields on that page:
503
+ # page snapshots show their text.
387
504
  shift; need_box
388
- field=password; enter=1; name=""; file=""
505
+ field=password; enter=1; name=""; file=""; url=""; opts=()
389
506
  while [ $# -gt 0 ]; do
390
507
  case "$1" in
391
508
  --username) field=username; enter=0; shift ;;
392
509
  --totp) field=totp; shift ;;
393
510
  --no-enter) enter=0; shift ;;
394
511
  --from-file) file="${2:-}"; shift 2 ;;
512
+ --url) url="${2:-}"; shift 2 ;;
513
+ --page) opts+=(--page "${2:?--page needs part of the page address or title}"); shift 2 ;;
514
+ --keyboard) opts+=(--keyboard); shift ;;
515
+ -*) echo "agent-box: unknown option $1" >&2; exit 2 ;;
395
516
  *) name="$1"; shift ;;
396
517
  esac
397
518
  done
519
+ [ "$enter" = 1 ] && opts+=(--enter)
520
+ [ "$enter" = 1 ] && [ "$field" = password ] && opts+=(--clear-after 3)
521
+ rc=0
398
522
  if [ -n "$file" ]; then
399
523
  [ -f "$file" ] || { echo "agent-box: no such file" >&2; exit 2; }
400
- in_box "$NAME" env DISPLAY=:1 xdotool search --onlyvisible --class chromium windowactivate --sync %1 >/dev/null 2>&1 || true
401
- tr -d '\r\n' < "$file" | in_box -i "$NAME" env DISPLAY=:1 xdotool type --clearmodifiers --delay 15 --file -
524
+ tr -d '\r\n' < "$file" | in_box -i -u agent "$NAME" env DISPLAY=:1 box-type --kind "$field" --url "$url" ${opts[@]+"${opts[@]}"} || rc=$?
402
525
  else
403
- [ -n "$name" ] || { echo "usage: agent-box type-secret <name> [--username|--totp] [--no-enter]" >&2; exit 2; }
404
- vault type "$name" "$field" || exit 1
526
+ [ -n "$name" ] || { echo "usage: agent-box type-secret <name> [--username|--totp] [--no-enter] [--page <text>]" >&2; exit 2; }
527
+ vault type "$name" "$field" ${opts[@]+"${opts[@]}"} || rc=$?
528
+ fi
529
+ [ "$rc" = 0 ] || exit "$rc"
530
+ if [ "$enter" = 0 ] && [ "$field" = password ]; then
531
+ echo "agent-box: submit the form before any snapshot (snapshots show password fields)"
532
+ fi ;;
533
+ files)
534
+ # Downloads the box saved, newest first.
535
+ need_box
536
+ list=$(in_box "$NAME" find /data/Downloads -maxdepth 1 -type f -printf '%T@\t%TY-%Tm-%Td %TH:%TM\t%s\t%f\n' 2>/dev/null | sort -rn || true)
537
+ if [ -z "$list" ]; then echo "agent-box: no downloads yet"; exit 0; fi
538
+ printf '%s\n' "$list" | awk -F'\t' '{ n = $4; note = "";
539
+ if (n ~ /\.crdownload$/) { sub(/\.crdownload$/, "", n); note = " (still downloading)" }
540
+ printf "%s %10s %s%s\n", $2, $3, n, note }' ;;
541
+ get)
542
+ # agent-box get <name>|--latest [destination]: copy a download out of the box.
543
+ need_box
544
+ name="${2:-}"; dest="${3:-.}"
545
+ if [ "$name" = --latest ]; then
546
+ name=$(in_box "$NAME" sh -c 'ls -1t /data/Downloads 2>/dev/null | grep -v "\.crdownload$" | head -n 1' || true)
547
+ [ -n "$name" ] || { echo "agent-box: no finished downloads yet" >&2; exit 1; }
548
+ fi
549
+ case "$name" in ''|*/*|.|..) echo "usage: agent-box get <name>|--latest [destination] (names from agent-box files)" >&2; exit 2 ;; esac
550
+ if in_box "$NAME" test -f "/data/Downloads/$name.crdownload"; then
551
+ echo "agent-box: '$name' is still downloading; try again shortly" >&2; exit 1
405
552
  fi
406
- if [ "$enter" = 0 ]; then
407
- [ "$field" = password ] && echo "agent-box: typed it; submit the form before any snapshot (snapshots show password fields)" || echo "agent-box: typed it"
553
+ in_box "$NAME" test -f "/data/Downloads/$name" || { echo "agent-box: no download named '$name'; see agent-box files" >&2; exit 1; }
554
+ [ -d "$dest" ] && dest="${dest%/}/$name"
555
+ in_box "$NAME" cat "/data/Downloads/$name" > "$dest.part" && mv "$dest.part" "$dest"
556
+ echo "$dest" ;;
557
+ hold)
558
+ # Keep the box awake while you work elsewhere: agent-box hold <minutes> (0 ends it).
559
+ need_box
560
+ m="${2:-}"
561
+ case "$m" in ''|*[!0-9]*) echo "usage: agent-box hold <minutes> (at most 1440; 0 ends the hold)" >&2; exit 2 ;; esac
562
+ [ "$m" -le 1440 ] || { echo "agent-box: hold for at most 1440 minutes (a day)" >&2; exit 2; }
563
+ if [ "$m" = 0 ]; then
564
+ in_box "$NAME" rm -f /tmp/box-hold-until
565
+ echo "agent-box: hold ended; the box stops after the usual idle time"
408
566
  else
409
- in_box "$NAME" env DISPLAY=:1 xdotool key Return
410
- if [ "$field" = password ]; then
411
- sleep 3
412
- in_box -i "$NAME" python3 - <<'PY' 2>/dev/null || true
413
- import json, urllib.request, websocket
414
- js = ("document.querySelectorAll('input[type=password]').forEach(i => { if (i.value) {"
415
- " i.value = ''; i.dispatchEvent(new Event('input', {bubbles: true})); } })")
416
- for t in json.load(urllib.request.urlopen("http://127.0.0.1:9222/json/list", timeout=2)):
417
- if t.get("type") != "page":
418
- continue
419
- try:
420
- ws = websocket.create_connection(t["webSocketDebuggerUrl"], timeout=3)
421
- ws.send(json.dumps({"id": 1, "method": "Runtime.evaluate", "params": {"expression": js}}))
422
- ws.recv(); ws.close()
423
- except Exception:
424
- pass
425
- PY
426
- fi
427
- echo "agent-box: typed it and pressed Enter"
567
+ in_box "$NAME" sh -c 'echo $(( $(date +%s) + '"$m"' * 60 )) > /tmp/box-hold-until'
568
+ echo "agent-box: kept awake for $m minutes, even with nothing connected"
428
569
  fi ;;
570
+ doctor)
571
+ # Check the setup and say how to fix what's wrong.
572
+ bad=0
573
+ pass() { printf ' ok %s\n' "$1"; }
574
+ note() { printf ' -- %s\n' "$1"; }
575
+ fail() { printf ' FAIL %s\n fix: %s\n' "$1" "$2"; bad=1; }
576
+ port_busy() { (exec 3<>"/dev/tcp/127.0.0.1/$1") 2>/dev/null; }
577
+ echo "agent-box $(sed -n 's/^ *"version": *"\(.*\)".*/\1/p' "$HERE/package.json") on $OS $(uname -m), container tool: $RT"
578
+ if command -v python3 >/dev/null && python3 -c 1 >/dev/null 2>&1; then pass "python3"
579
+ else fail "python3 is missing (or is macOS's install stub)" "install the Command Line Tools (xcode-select --install) or Python 3"; fi
580
+ command -v curl >/dev/null && pass "curl" || fail "curl is missing" "install curl"
581
+ usable=0
582
+ case "$RT" in
583
+ container)
584
+ if ! command -v container >/dev/null; then fail "Apple's container isn't installed" "agent-box setup (or brew install container)"
585
+ elif container system status >/dev/null 2>&1; then pass "Apple's container is running"; usable=1
586
+ else note "Apple's container service is stopped; agent-box up starts it"; fi ;;
587
+ docker|podman)
588
+ if ! command -v "$RT" >/dev/null; then fail "$RT isn't installed" "install it, or run agent-box setup --runtime <tool>"
589
+ elif out=$("$RT" info 2>&1); then pass "$RT is running"; usable=1
590
+ elif echo "$out" | grep -i 'permission denied' >/dev/null; then fail "$RT says permission denied" "sudo usermod -aG docker \$USER, then log out and back in"
591
+ elif colima_ctx; then note "Colima is stopped; agent-box up starts it"
592
+ else fail "$RT isn't running" "start Docker Desktop or OrbStack, or run colima start or podman machine start"; fi ;;
593
+ *) fail "no container tool chosen" "agent-box setup" ;;
594
+ esac
595
+ if [ "$usable" = 1 ]; then
596
+ if image_ok; then
597
+ age=""; [ -f "$STAMP" ] && age=" ($(( ( $(date +%s) - $(cat "$STAMP") ) / 86400 )) days old)"
598
+ pass "box image for this version is ready$age"
599
+ elif locked build; then note "box image is being prepared now (progress: tail $CACHE/build.log)"
600
+ else note "box image isn't built yet; the next agent-box up prepares it (1 to 3 minutes)"; fi
601
+ if running; then
602
+ pass "box is running"
603
+ if browser=$(curl -sf -m 2 "$CDP/json/version"); then
604
+ pass "browser answers on $CDP ($(printf '%s' "$browser" | sed -n 's/.*"Browser": *"\([^"]*\)".*/\1/p'))"
605
+ else fail "browser doesn't answer on $CDP" "agent-box logs; then agent-box down && agent-box up"; fi
606
+ curl -sf -m 2 -o /dev/null "http://127.0.0.1:$(viewer_port)/vnc.html" && pass "viewer answers" || fail "viewer doesn't answer" "agent-box logs"
607
+ else
608
+ note "box is stopped; agent-box up starts it"
609
+ port_busy "$CDP_PORT" && fail "port $CDP_PORT is taken by something else" "stop it, or set BOX_CDP_PORT to a free port"
610
+ port_busy "$(viewer_port)" && fail "port $(viewer_port) is taken by something else" "stop it, or set BOX_VIEW_PORT to a free port"
611
+ fi
612
+ fi
613
+ command -v playwright-cli >/dev/null && pass "playwright-cli is installed" || fail "playwright-cli isn't installed" "npm install -g @playwright/cli@latest"
614
+ skill_dirs=$(conf_get skill_dirs); [ -n "$skill_dirs" ] || skill_dirs=$(IFS=:; echo "${SKILL_DIRS[*]}")
615
+ if [ "$skill_dirs" = none ]; then note "the agent skill isn't linked (setup ran with --no-skills)"
616
+ else
617
+ IFS=: read -r -a sdirs <<< "$skill_dirs"; linked=0
618
+ for d in "${sdirs[@]}"; do
619
+ if [ -f "$d/agent-box/SKILL.md" ]; then pass "agent skill linked in $d"; linked=1
620
+ elif [ -L "$d/agent-box" ]; then fail "the skill link in $d is broken" "agent-box setup"; linked=1; fi
621
+ done
622
+ [ "$linked" = 1 ] || fail "the agent skill isn't linked, so agents won't know the box" "agent-box setup"
623
+ fi
624
+ prefix=$(npm prefix -g 2>/dev/null || true)
625
+ if [ -n "$prefix" ] && { [ -w "$prefix/lib/node_modules" ] || [ -w "$prefix/lib" ]; }; then pass "npm can update agent-box without sudo"
626
+ elif [ -n "$prefix" ]; then note "npm's global folder needs sudo, so updates do too"; fi
627
+ if command -v "$TS" >/dev/null 2>&1 || [ -x "$TS" ]; then
628
+ if t=$(view_tailnet); then pass "phone viewer published at $t"
629
+ else note "phone viewer not published (optional; see the README)"; fi
630
+ fi
631
+ if [ "$OS" = Darwin ] && door_on; then
632
+ script=$(door_plists | head -n 1 | xargs grep -o '/[^<]*box-door\.py' 2>/dev/null | head -n 1)
633
+ if [ -n "$script" ] && [ -f "$script" ]; then pass "front door is on"
634
+ else fail "the front door points to an install that's gone" "agent-box door on"; fi
635
+ fi
636
+ free=$(df -Pk "$HOME" | awk 'NR == 2 { print int($4 / 1048576) }')
637
+ if [ "$free" -ge 6 ]; then pass "$free GB free on disk"
638
+ else fail "only $free GB free on disk" "free some space: the image needs about 2 GB, and a build up to 5 GB more for a while"; fi
639
+ exit "$bad" ;;
429
640
  off)
430
641
  # Stop the box, and the container service or VM when nothing else uses it.
431
642
  if running; then "$0" down >/dev/null; fi
@@ -445,8 +656,12 @@ agent-box shot [file.png] screenshot of the whole desktop
445
656
  agent-box x <xdotool args> mouse and keyboard on the desktop
446
657
  agent-box exec <cmd> run a command inside the box
447
658
  agent-box logs the box's log
659
+ agent-box files downloads the box saved, newest first
660
+ agent-box get <name>|--latest [dest] copy a download out of the box
661
+ agent-box hold <minutes> keep the box awake that long even when idle (0 ends it)
662
+ agent-box doctor check the setup and say how to fix what's wrong
448
663
  agent-box runtime the container tool in use (container, docker or podman)
449
- agent-box build rebuild the image
664
+ agent-box build rebuild the image with current packages
450
665
  agent-box off stop the box, and the container service or VM if nothing else uses it
451
666
  agent-box door on|off (macOS) always-on helper so the viewer address starts the box itself
452
667
  agent-box setup [--runtime container|docker|podman] [--skills-dir DIR]... [--no-skills]
@@ -459,14 +674,15 @@ agent-box secret save <name> --from-file <path> [--user U] [--url URL]
459
674
  add one (file from a private secret prompt)
460
675
  agent-box secret rm <name> delete one
461
676
  agent-box secret open open the password manager on the box's screen
462
- agent-box type-secret <name> [--username | --totp] [--no-enter]
463
- click the field first; types it there. For passwords it presses
464
- Enter, then clears leftover password fields.
677
+ agent-box type-secret <name> [--username | --totp] [--no-enter] [--page <text>]
678
+ click the field first; it types into that field, on the entry's
679
+ site only. For passwords it presses Enter, then clears password
680
+ fields on that page.
465
681
 
466
682
  Agents: read the agent-box skill. In short: `agent-box up`, then
467
683
  `playwright-cli -s=<your-session> attach --cdp=<the browser control address it printed>`,
468
- drive the page (tab-new, find, click, screenshot) and finish with
469
- `playwright-cli -s=<your-session> detach`.
684
+ drive the page (tab-new, find, click, screenshot), close your tab with
685
+ `playwright-cli -s=<your-session> tab-close` and finish with `detach`.
470
686
  Never put a password in a command, file or chat: use agent-box type-secret.
471
687
  EOF
472
688
  ;;
package/box-door.py CHANGED
@@ -4,31 +4,49 @@
4
4
  Tailscale Serve points the phone address here. If the box is running, each
5
5
  connection passes straight through to the box's viewer (HTTP and WebSocket
6
6
  alike). If the box is off, the door starts it and answers with a small page
7
- that reloads itself until the viewer is up. Uses about 15 MB of memory.
7
+ that reloads itself until the viewer is up, or shows why the start failed.
8
+ It starts the box only for a page someone opened, not for a request a web page
9
+ makes in the background. Uses about 15 MB of memory.
8
10
  """
9
11
  import asyncio
12
+ import html
10
13
  import os
14
+ import re
11
15
  import subprocess
16
+ import time
12
17
 
13
18
  LISTEN = ("127.0.0.1", int(os.environ.get("DOOR_PORT", 6080)))
14
19
  BOX_VIEWER = ("127.0.0.1", int(os.environ.get("DOOR_BOX_PORT", 6090))) # where `agent-box up` publishes the viewer
15
20
  BOX_CMD = os.path.join(os.path.dirname(os.path.realpath(__file__)), "agent-box")
21
+ LOG = os.path.join(os.environ.get("XDG_CACHE_HOME") or os.path.expanduser("~/.cache"), "agent-box", "door-up.log")
22
+ RETRY_AFTER = 30 # seconds before trying again after a failed start
16
23
 
17
- PAGE = """<!doctype html>
24
+ starting = None # the running `agent-box up`, if any
25
+ last_failure = 0.0 # when the last start failed
26
+
27
+
28
+ def box_starting():
29
+ return starting is not None and starting.poll() is None
30
+
31
+
32
+ def page(title, body, refresh):
33
+ return f"""<!doctype html>
18
34
  <meta name="viewport" content="width=device-width, initial-scale=1">
19
- <meta http-equiv="refresh" content="3">
35
+ <meta http-equiv="refresh" content="{refresh}">
20
36
  <title>Agent box</title>
21
37
  <body style="font:17px -apple-system,system-ui,sans-serif;padding:2em;line-height:1.4">
22
- <p><b>Starting the agent box&hellip;</b></p>
23
- <p>This page reloads by itself and opens the box in about 10 seconds.</p>
38
+ <p><b>{title}</b></p>
39
+ {body}
24
40
  </body>
25
41
  """.encode()
26
42
 
27
- starting = None # the running `box up`, if any
28
43
 
29
-
30
- def box_starting():
31
- return starting is not None and starting.poll() is None
44
+ def respond(writer, status, body):
45
+ writer.write(
46
+ b"HTTP/1.1 %s\r\nContent-Type: text/html; charset=utf-8\r\n"
47
+ b"Cache-Control: no-store\r\nConnection: close\r\n"
48
+ b"Content-Length: %d\r\n\r\n" % (status.encode(), len(body)) + body
49
+ )
32
50
 
33
51
 
34
52
  async def pipe(reader, writer):
@@ -43,7 +61,7 @@ async def pipe(reader, writer):
43
61
 
44
62
 
45
63
  async def handle(client_r, client_w):
46
- global starting
64
+ global starting, last_failure
47
65
  if not box_starting():
48
66
  try:
49
67
  box_r, box_w = await asyncio.wait_for(asyncio.open_connection(*BOX_VIEWER), 1)
@@ -52,16 +70,42 @@ async def handle(client_r, client_w):
52
70
  else:
53
71
  await asyncio.gather(pipe(client_r, box_w), pipe(box_r, client_w))
54
72
  return
55
- starting = subprocess.Popen([BOX_CMD, "up"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
73
+ # The box is off or starting. Read the request to see what asked for it.
56
74
  try:
57
- await asyncio.wait_for(client_r.read(65536), 2) # the request; its content doesn't matter
75
+ request = await asyncio.wait_for(client_r.read(65536), 2)
58
76
  except (OSError, asyncio.TimeoutError):
59
- pass
60
- client_w.write(
61
- b"HTTP/1.1 200 OK\r\nContent-Type: text/html; charset=utf-8\r\n"
62
- b"Cache-Control: no-store\r\nConnection: close\r\n"
63
- b"Content-Length: %d\r\n\r\n" % len(PAGE) + PAGE
64
- )
77
+ request = b""
78
+ mode = re.search(rb"^sec-fetch-mode:\s*([a-z-]+)", request, re.I | re.M)
79
+ if mode and mode.group(1).lower() != b"navigate":
80
+ # Something a web page fetched in the background, not a page someone
81
+ # opened: don't start the box for it.
82
+ respond(client_w, "403 Forbidden", page("Not started", "<p>Open this address in its own tab.</p>", 3600))
83
+ else:
84
+ if starting is not None and not box_starting(): # the last start finished
85
+ if starting.returncode not in (0, 75): # 75: still preparing the image
86
+ last_failure = time.time()
87
+ starting = None
88
+ if not box_starting() and time.time() - last_failure > RETRY_AFTER:
89
+ last_failure = 0.0
90
+ os.makedirs(os.path.dirname(LOG), exist_ok=True)
91
+ with open(LOG, "w") as log:
92
+ starting = subprocess.Popen([BOX_CMD, "up"], stdin=subprocess.DEVNULL,
93
+ stdout=subprocess.DEVNULL, stderr=log)
94
+ if last_failure:
95
+ try:
96
+ with open(LOG) as log:
97
+ detail = "".join(log.readlines()[-15:])
98
+ except OSError:
99
+ detail = ""
100
+ body = (f"<pre style='white-space:pre-wrap'>{html.escape(detail)}</pre>"
101
+ f"<p>It tries again in {RETRY_AFTER} seconds. On the computer, "
102
+ "<code>agent-box doctor</code> shows what's wrong.</p>")
103
+ respond(client_w, "200 OK", page("The agent box didn't start", body, 10))
104
+ else:
105
+ respond(client_w, "200 OK", page(
106
+ "Starting the agent box&hellip;",
107
+ "<p>This page reloads by itself and opens the box in about 10 seconds. "
108
+ "The first start after an install or update takes a few minutes.</p>", 3))
65
109
  try:
66
110
  await client_w.drain()
67
111
  finally:
package/box-quit-browser CHANGED
@@ -11,3 +11,5 @@ ws.send(json.dumps({"id": 1, "method": "Browser.close"}))
11
11
  PY
12
12
  for _ in $(seq 100); do pgrep -f "^$CHROME_BIN" >/dev/null || exit 0; sleep 0.1; done
13
13
  pkill -TERM -f "^$CHROME_BIN"
14
+ # Give it a moment to write its files before the box itself stops.
15
+ for _ in $(seq 30); do pgrep -f "^$CHROME_BIN" >/dev/null || exit 0; sleep 0.1; done